The Readable Programming Language - Handbook

Getting Started

Availability

Lisilogic, its development environment, and tutorials are not yet available online, but a presentation including a live demonstration can be organized. Please send an email to info@lisilogic.com!

Requirements

The development environment of Lisilogic is programmed in Java and needs a JRE to execute. If it isn't yet installed on your computer, you can download and install it from here.
As for now, a JDK (javac compiler) is not required.

The purpose of Lisilogic is to program web applications, so you'll need a web server installed locally on your development machine to test what you've programmed.

As for now, the only available translator (see Translators) generates applications in PHP + MySQL, so it is required that your web server supports PHP and MySQL. Xampp is recommended, you can download it from here.

During the installation of your web server, please remember the following informations:

  • The directory that it serves (the place where the web pages are stored). With Xampp, it will be the "htdocs" directory in the installation directory of Xampp (/opt/lampp/htdocs for Linux, C:\xampp\htdocs or C:\Applications\Apachefriends\Xampp\htdocs under Windows).
  • The address of your MySQL server. With Xampp, it will be "localhost".
  • The username and password of your MySQL server. The user must have the permission to modify the structure of the database of your application. With Xampp, the easiest is to use the user "root" and the passwort you've given to it at installation time.

In the future, Lisilogic will support further execution environments.

A Lisilogic plugin for Eclipse is planned too.

Development Environment

Starting

Once downloaded and installed, you'll start the Lisilogic development environment by double-clicking on lisilogic.jar or with the following command line:
java -jar lisilogic.jar

The development environment shows

  • At the left, the list of chapters (see below) and important buttons (save, generate, ...),
  • In the middle, the chapters and configurations open for editing,
  • At the right, the structures, roles, pages, procedures etc. of the application.

Saving and Loading

Lisilogic saves each project in a single, zip-compressed file.
You can open a project when starting the development environment by providing its filename on the command line:
java -jar lisilogic.jar test.lisilo

It is recommended to associate Lisilogic and its development environment with a filename extension in order to be able to double-click on a project to open it. The recommended filename extension is .lisilo. Please refer to the manual of your system to find out how to achieve this association.

Chapters

A Lisilogic application is made up of chapters.
Each chapter has a title and a content.
The title is free, it has no effect on the application, it only helps to organize and understand the code.

You find the list of chapters at the left of the development environment. Click on

  • + to add a new chapter (you'll be prompted for a title),
  • r to change the title of the chapter selected in the list (there must be just one selected chapter),
  • - to delete the chapters selected in the list.

Double-click on a chapter in the list to open it for edition.

See also Basic Syntax: Chapters, Sentences, Whitespace.

Sentences

A Lisilogic chapter is made up of sentences.
Click on the chapter editor outside the available sentences to add a new one. You'll be prompted for the sentence type.

There are two kinds of sentence editors: a free text editor and a guided editor.
When creating a sentence, choose "free text editor" to get a free text editor, or the kind of sentence you whish to obtain a guided editor.

Once a sentence is created, it can be displayed either in its editor or as a normalized text for easier reading. Click in the margin at the left of the sentence and choose "edit" or "stop edit" to toggle.

Normalized display
Guided editor
 Free text editor

The normalized display shows how the sentence will look for non-programmers. The aim of Lisilogic is to make code readable even by non-programmers, remember? The normalized display happens to be better readable even for programmers, so you'll probably leave the sentences in this form as long as you don't need to edit them.

The guided editor helps building sentences down to the level of an expression (see Expressions). It prevents many typos, indents automatically, and gives more detailed information about eventual syntax errors, but it might be unusual and it is not as readable as the others, because it displays clickable and editable areas with different background colors (white for editable areas, light gray for clickable ones).

The free text editor is more usual, but it won't indent automatically, it won't make suggestions and it won't help you find eventual syntax errors. It has the advantage that it allows copy and paste (in the future, the guided editor will allow copy and paste too), and a series of variations in the way you write the sentences, for instance:
click on "Logout" to logout
click "Logout" to logout
Each submission has a short string called its title.
Each submission has a title, which is a short string.

You can convert a sentence from the guided editor to the text editor at any time (click in the margin at its left, choose "edit as text" and confim). A sentence edited as free text can only be converted to a guided editor if it doesn't contain any syntax errors. The "guided edit" choice appears in its margin menu after parsing, see below.

It is strongly recommended to use the guided editor at least until you are able to write error free.

Parsing and Compiling

Once you have added sentences and filled in their editors, click on "save, parse, compile" at the top left of the development environment to save, check the syntax of the sentences and create the pages, structures, roles, etc. that they define. Syntax errors appear in red and the created elements appear in the tables at the right of the programming environment.

Clicking on an error will select the concerned part of the sentence.

Selecting a created object will display its content at the bottom right of the development environment: the values of an enumeration, the attributes of a structure, the UI elements of a page, the actions a role can take. Double-clicking on them will open their definition.

Lisilogic tries to calculate automatically and associate plurals and singulars, for instance, the sentence
Each user has a list of addresses.
will create a structure called "address".
This is a heuristic, it might lead to incorrect results in some cases. Try not to use irregular words like "mice" and "men".

Deploying

Once you've parsed and compiled your application, you may deploy it to your test web server.

Configurations

Click on "configurations" at the top left of the development environment to open the deployment configuration editor.

This is also the place where you define the title of your application, that will appear on each page.

Click on "create configuration" to define a new deployment target. You'll be prompted to select the kind of execution environment; for now only "PHP + MySQL" is available.

Fill in the new configuration. For PHP + MySQL, you'll have to select:

  • The directory to which your application will be deployed. It must be inside the directory that your web server serves (htdocs), for instance <installation directory of Xampp>/htdocs/MyFirstLisilogicApplication/.
    Lisilogic must have the permission to write into this directory and to delete its content.
  • The address of your MySQL database server. If you use Xampp without further configuration, it will probably be "localhost".
    The development environment of Lisilogic doesn't access the database directly, it only generates PHP scripts that will do so.
  • The username and password that your application will use to connect to the database. This user must be able to modify the structure of the database (add and remove tables, columns, etc.). With Xampp, the easiest is to use "root" and the password you've given during the installation.
  • The name of the database of your application, for instance "MyFirstLisilogicApplication".
    The init script that Lisilogic generates will attempt to create this database if it isn't present, but not all web servers allow any PHP script to create databases (the default installation of Xampp doesn't), so it is probably a good idea to create it by other means, for instance with PHPMyAdmin. If the database already exists, the init script of your Lisilogic application will reset it (drop all tables).
  • An optional prefix that will be used for every table name of your application, for instance "lisilo_".

After choosing the deployment directory, please check that the URL of your application is correct. Lisilogic tries to guess it from the deployment directory - there might be cases where this guess fails. Lisilogic and your application will work even in this case, only the "browse"-buttons of the development environment won't (see below).

Generating

Click on "generate" in the configuration editor or on the corresponding "gen" button that has been created just under "save, parse, compile" at the top left of the development environment. Lisilogic generates the files of your application into the directory you've configured, and deletes any other content of it.

Note that for now, this will also delete any files or images that have been uploaded during previous tests.
An edit and deployment procedure suited for already deployed applications is in development.

Note that deploying doesn't reset or change the database: Lisilogic doesn't access it directly, only the init script does.

Initializing the Application

Now open a browser and navigate to the init script of your application:
http://localhost/<your application's directory>/amin/init.php
for instance
http://localhost/MyFirstLisilogicApplication/amin/init.php
If the URL that Lisilogic guessed for your application is correct (depending on your web server and on the deployment directory you choosed), you may use the "browse to init" button in the configuration editor or the corresponding "ini" button just under "save, parse, compile" at the top left of the development environment.

The init script resets the database, creates the tables of your application, and inserts a test user for each role (see Roles).

Note that the init script deletes (drops) every table of the database whose name starts with the prefix chosen in the configuration. If you have left empty the prefix, all tables of the database will be deleted. Any data saved during previous tests is lost.
An edit and deploy procedure suited for already deployed applications will be available in the future.

During development, the init script must be executed only if the changes in the code lead to modifications of the database structure (if an attribute has been added or removed, a new type defined, etc.), not if only the user interface and business logic (procedures) have been modified.

When the application goes productive, it is highly recommended not to upload the "admin" directory to the final server, or at least not the init script (init.php), or at least to protect it with a .htaccess. Lisilogic will soon do the latter automatically.

Testing

In a browser, navigate to your application:
http://localhost/<your application's directory/>
for instance
http://localhost/MyFirstLisilogicApplication/
If the URL that Lisilogic guessed for your application is correct (depending on your web server and on the deployment directory you choosed), you may use the "browse to application" button in the configuration editor or the corresponding "app" button just under "save, parse, compile" at the top left of the development environment.

You'll see a login form along with what you have programmed on the "Home" page for the "visitor" role, corresponding to somebody who looks at the application without being logged in (see Roles and User Interface).

The init script has created a test user for each role, with username, password and role all identical. So you can log in with "user" as username and "user" as password, or with "admin" as username and "admin" as password.

If you have omitted to provide the user with a possibility to log out, you'll ave to close your browser or to run the init script again to log out. It is recommended to add a sentence like
In the menu of any page, the user can click "Logout" to logout.
in every Lisilogic application. The login form is available automatically, but this sentence is left to the programmer as a first exercise and as a possibility to place the logout button wherever he whishes.

Documentation

Along with the application, Lisilogic generates its code in HTML for documentation purposes. It comes in the "doc" directory in the application's main directory:
http://localhost/<your application's directory/>/doc
for instance
http://localhost/MyFirstLisilogicApplication/doc/
If the URL that Lisilogic guessed for your application is correct (depending on your web server and on the deployment directory you choosed), you may use the "browse to doc" button in the configuration editor or the corresponding "doc" button just under "save, parse, compile" at the top left of the development environment.

Tools to explore the documentation (search, additional summary pages corresponding to the lists at the right of the development environment, ...) are in development.