Introduction

The aim of this "How to …​" guide is to illustrate common tasks when programming in PPL.

This manual is a stub. Future chapters will explain how to work with strings, collections, streams, directories and files, etc.

If you can’t find what you need or if you have any suggestions then please write an email to contact {at} practical-programming {dot} org. Thank you.

Writing and Executing Code

Three Ways to Write Code

There are three ways you can write and execute PPL/Java code:

  1. Script file

    Used to execute a small set of instructions contained in a single text file.

  2. Program file:

    A program file is a single text file that can contain any number of functions and other PPL software components (e.g. types, factories, services). It is used to write small applications.

  3. PPL project:

    Used to write large applications composed of hundreds or thousands of source code files hierarchically organized in a directory tree

The following chapters explain how to use each method.

Script File

You can put PPL source code instructions into a single text file and then execute them immediately.

Scripting is typically used for testing out source code snippets or for writing small command line utilities.

"Hello World" Example

To create and execute a simple script file proceed as follows:

  • Use your preferred text editor and create a file named hello.ppl in any directory and with the following content:

    File hello.ppl
    write_line ( "Hello world" )
  • Execute the script by typing the following command in a system terminal:

    ppl hello.ppl
    Note
    If your current directory is different from the directory of the script file then you must specify a relative or absolute path to the script file, for example:
    ppl ../tests/hello.ppl
  • Executing the above script writes to the standard OS out device:

    Hello world

Program File

A PPL script file (which we introduced in the previous chapter) can only contain a single set of instructions. You can think of it as a single function.

A PPL program file, on the other hand, can contain any number of functions and other software components, such as types, factories and services. Thus, a program file is very convenient if you want to write small executable applications contained in a single text file.

A program file starts with the program keyword in the first line, and ends with a dot (.) on the last line. Between these lines it must at least contain one function called start. This function is executed when the program is launched.

Let’s look at a simple example.

"Hello World" Example
  • Create file hello.ppl with the following content:

    File hello.ppl
    program
    
        function start
            write_line ( "Hello World" )
        .
    .
  • Launch the program with the OS command

    ppl hello.ppl
  • Output displayed in the terminal:

    Hello World
Book Example

Here is another (hopefully more exciting) example:

File book_program.ppl
program

    data type book                                  (1)

        att id pos_32
        att title string
        att top_seller yes_no default:no
    .

    function create_book -> book                    (2)

        return book.create (
            id = 123
            title = "How to write beautiful code"
            top_seller = yes )
    .

    function start                                  (3)

        const book = create_book
        show ( book )
        OS.console?.ask_press_Enter
    .
.
  1. type book defines a data structure with 3 attributes: id, title and top_seller

  2. a function that creates and returns a book object

  3. the start function that executes first when the program is launched

Executing this program with …​

ppl book_program.ppl

... will display the book object in a new window like this:

PPL Book GUI

PPL Project

Note
In this context the term 'PPL project' is used to denote any application that runs on a machine with a Java Virtual Machine (JVM) installed. For example: a desktop PC with Linux, Mac OS X, Unix or Windows, a server, a tablet PC, a mobile device or any other device that supports Java.

A PPL project can contain hundreds or thousands of source code files and libraries hierarchically organized in directories.

"Hello World" Example

To create, compile and run an application do the following:

  • Open a terminal window and go to any directory in which you want to create the project.

  • Create a new project named hello by entering the following command:

    ppl create_project id=hello

    PPL creates a sub-directory named hello.

    Moreover, a number of subdirectories and files are created under hello. To get more information about them please have a look at the README file in the project’s root directory.

    An important file is se_hello_starter.ppl which has been created under hello/work/ppl/source_code/hello/. This file contains the entry code that will be executed when the application starts.

  • Open file hello/work/ppl/source_code/hello/se_hello_starter.ppl with your preferred text editor, and change the source code so that it looks like this:

    service hello_starter
    
        function start
            write_line ( "Hello world" )
        .
    .
  • Save the file.

  • Compile and build your project by executing the compile_and_build system file which is located in your project’s root directory (i.e. compile_and_build.sh on Linux/Unix and compile_and_build.bat on Windows).

    Alternatively you can also execute the following two OS commands in a terminal (while being in the project’s root directory):

    ppl compile_project
    ppl build_project

    Or you can use shortcuts for compile_project and build_project and simply type:

    ppl cp
    ppl bp
  • Now run your application by executing the run system file in your project’s root directory (i.e. run.sh on Linux/Unix systems and run.bat on Windows systems).

    Alternatively, you can also execute the OS command ppl run_project, or simply ppl rp.

    The application’s output is displayed in the terminal:

    Hello world
Deploying an Application

To package your application into a single file for deployment on other computers and devices:

  • Execute the package system file in your projects root directory (i.e. package.sh on Linux/Unix systems and package.bat on Windows systems). Or type ppl package_project or ppl pp in a terminal.

    This command creates a single compressed file in your project’s distribute subdirectory. The file contains everything needed to execute your application on another PC that has Java installed. There are two version of this file:

    • a file with extension .tar.gz: use this file to deploy on a Linux/Unix machine

    • a file with extension .zip: use this file to deploy on a Windows machine

To install your application on another PC:

  • Ensure that the correct Java version is installed on the PC. If it isn’t, you must first install or upgrade Java.

  • Copy the compressed file created in the previous step to the PC (use the .tar.gz file on a Linux/Mac/Unix machine or the .zip file on a Windows machine). You can use any directory, but you should of course consider the operating system’s standards and permissions.

  • Unzip the file.

  • Run the application by executing the system command file located in the application’s root directory (e.g. hello.sh on Linux/Unix and hello.bat on Windows).

Note
Instead of the above procedure, you can of course also use any Java deployment tool for more flexibility and totally automated distribution.

OS Command Line Arguments

Within any script you can access input arguments provided on the OS command line. The command line arguments are available as a list of strings. You can get this list with the expression OS_process.command_line_arguments. The following script (stored in file list_arguments.java) shows how the command line arguments can be handled:

File list_arguments.ppl
// Note: The inferred type of constant 'command_line_arguments' is:
// indexed_list<string or null> or null

const command_line_arguments = OS_process.command_line_arguments

if command_line_arguments is null then
    write_line ( "There are no command line arguments." )
    return
.

write_line ( """Number of command line arguments: {{command_line_arguments.size}}""" )
write_new_line

// classic loop with if instruction
repeat for each argument in command_line_arguments
    if argument is not null then
        write_line ( argument )
    else
        write_line ( "null" )
    .
.
write_new_line

///
    The above loop can also be written in a functional style
    using a stream, a closure, and the 'if_null:' operator
.///

command_line_arguments.stream.for_each ( arg => { write_line ( arg if_null: "null" ) } )

Executing the above script with command …​

ppl list_arguments.ppl a1 "" "arg with spaces"

... will produce the following output:

Number of command line arguments: 4

list_arguments.ppl
a1
null
arg with spaces

list_arguments.ppl
a1
null
arg with spaces

Note that the first argument is the script’s file name.

Embedding Java Source Code

Besides PPL source code, any script can also contain Java source code.

To embed Java source code in a script, simply insert the Java statements between a java line and an end java line, as in the following example:

File hello_java.ppl
java
    System.out.println ( "Hello world from Java" );
end java

Typing ppl hello_java.ppl in the terminal will display:

Hello world from Java

You can also mix PPL and Java code in a script like this:

File PPL_Java_mix.ppl
// loop with PPL; display with Java
repeat 3 times
    java
        System.out.println ( "Hello world from Java" );
    end java
.

// loop with Java; display with PPL
java
    for ( int i = 1; i <= 2; i++ ) {
end java
        write_line ( "Hello world from PPL" )
java
    }
end java

Output:

Hello world from Java
Hello world from Java
Hello world from Java
Hello world from PPL
Hello world from PPL

First Class Executable Script or Program Files

If you use Linux/Unix, you can turn a PPL script or program file into a first class executable, by using the so-called shebang syntax.

To do this, insert a first line as shown below in your script file:

File hello.ppl
#!/usr/bin/env ppl

write_line ( "Hello world" )

Note: You might need to adapt #!/usr/bin/env to your specific OS environment.

Make your file executable with the following command:

chmod a+x hello.ppl

Now you can execute hello.ppl by simply typing:

./hello.ppl

Result displayed in your terminal:

Hello world