Quick start guide

This guide uses simple HTML code in the examples, and requires some basic knowledge of it.

Before you read any further, you should obtain and install a copy of the P* interpreter from the download page.

P* programs are run as scripts. This means that you can simply write a program into a text file, and tell the P* interpreter to run it.

Your first program!

To create your first program, paste this into a text file called hello_world.pstar:

#!/usr/bin/wpl -f
SCENE main {
	echo "Hello World!\n";
}

Running the program will look something like this:

$ chmod +x hello_world.pstar
$ ./hello_world.pstar
Hello World!
$ 

P*, like many other languages, supports values and expressions. Expressions are an important part of P*. The program above contains an expression with one operator, echo, and one operand, a string with the contents Hello world!.

In P*, we say that values, like strings and integer, are alive. In an expression, you tell values to do stuff. In the example above, we tell the string to echo its value to standard output.

Variables

P* can store values in named variables. A variable can hold a value of a specific type, for instance an int or a string. Please check the reference manual for a complete list of all types.

Some types are special and do stuff under the hood. One example is the ENV type, which reads environment variables.

We can make P* retrieve an environment variable from the shell, store it in a variable and print it out. Example:

#!/usr/bin/wpl -f
SCENE main {
	/* Create a variable named 'env' of special type 'ENV' */
	ENV env;

	/* Create a variable named 'path' of type 'string' */
	string path;

	/* Tell the env variable to retrieve the environment
	   variable PATH and put the result into our 'path' variable */
	path = env->PATH;

	/* Put the variable 'path' into a text string and then print it out */
	echo "My shell looks for programs in these directories: $path\n";
}

What is a SCENE?

A SCENE in P* is like a function that does not take arguments. Programs may have multiple scenes, but they have to define one scene named main. This scene is always the first one to run. All code must be inside scenes.

Here is a program with two scenes where the main scene calls the other scene named number_printer:

#!/usr/bin/wpl -f
SCENE number_printer {
	echo "My number is: $my_number\n";
}

SCENE main {
	int my_number = 55;
	#SCENE number_printer;
}

You can call a scene using the #SCENE-pragma. When you do, all available variables from the location of the call is made available in the other scene. In the example above the variable my_number is made available in the scene number_printer.

TEXT blocks

P* has a special syntax for text blocks with variables and values interpolated into them. The reason for this is that P* focuses on web development, which is much about generating dynamic HTML code.

A plain text box joins strings together and prints them out. Other types of text boxes have the same syntax, but they might do other stuff than just printing (see the next section).

A P* Hello World program using a text block looks like this:

#!/usr/bin/wpl -f
SCENE main {
	TEXT {
Hello World!
	}
}

Note that you don't have to use \n to get a newline, everything you put in between the two curly brackets are printed out literally.

HTML_TEMPLATE

The text blocks are not very useful on their own, but when we use them in templates, we can see why they are benefitial. A template is used to separate program code and HTML markup to make your programs tidy. To do this, we need to have an efficient method to move variables from the code section of our program to the template section.

Let's do the example with the environment variable again, but now we use an HTML template:

#!/usr/bin/wpl -f
HTML_TEMPLATE my_first_template {
	<p>
		My shell looks for programs in the following directories:
		<b>{@path}</b>
	</p>
}

SCENE main {
	ENV env;
	string path = env->PATH;

	/* Call the template */
	#HTML_TEMPLATE my_first_template;
}

In text blocks and templates, as you might have noticed, you can join in an expression with the syntax {@EXP}. All sequences starting with the open curly bracket directly followed by the @-sign will make P* parse the enclosed text as an expression. A joined-in expression ends with a close curly bracket.

When you tell the template to print itself using the #HTML_TEMPLATE-pragma, the template inherits all variables from where you call it. The two variables we have defined, env and path, can therefore be used in the template.

If you have JavaScript code inside text blocks, you need to have equal amounts of open brackets and close brackets. This is to make P* able to figure out which end bracket is the one ending the text block.

If you need to use curly brackets which are not matching pairs of open brackets and close brackets, you have to use HTML etity code. &#123; is for the open bracket and &#125; is for the close bracket.

Programs with multiple files

A web page doesn't have to be very large before the source file gets difficult to navigate through. You can split your program into multiple files and use the #INCLUDE-pragma to join them. It is common to have templates, at least, in separate files.

Here is an example of a small web site consisting of multiple files and pages:

The file layout

HTML_TEMPLATE head {
	<!DOCTYPE html>
	<head>
	<title>My P* site</title>
	</head>
	<body>
}
HTML_TEMPLATE foot {
	</body>
	</html>
}

The file first_page

#!/usr/bin/wpl -f
#INCLUDE layout;

HTML_TEMPLATE body {
	<p>
		This is the first page. You can also take
		a look at <a href="second_page">the second page</a>.
	</p>
}

SCENE main {
	#HTML_TEMPLATE head;
	#HTML_TEMPLATE body;
	#HTML_TEMPLATE foot;
}

The file second_page

#!/usr/bin/wpl -f
#INCLUDE layout;

HTML_TEMPLATE body {
	<p>
		This is the first page. If you want to, you can go
		back to <a href="first_page">the first page</a>.
	</p>
}

SCENE main {
	#HTML_TEMPLATE head;
	#HTML_TEMPLATE body;
	#HTML_TEMPLATE foot;
}

Notice that you don't need the #!/usr/bin/wpl -f-line at the top in files you include.

More resources

Please take a look at The reference manual for more in-depth documentation.

You can also find example programs in the source directory under /tests/