The Readable Programming Language - Handbook

Basic Syntax

Chapters, Sentences, Whitespace

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.

The content of a chapter is code, made up of sentences.
Each sentence ends with a dot (.) followed by a space, a line break, or the end of the chapter.

The sentences may contain tabs and line breaks. They will be treated like spaces by the compiler, but they can improve the readability.
Several spaces will be treated as one space by the compiler. They may be used to indent lists if tabs are unwanted.
There may be only whitespace (spaces, tabs, line breaks and empty lines) between the sentences.

The ordering of chapters and sentences and the repartition of the sentences among chapters has only an influence if several parts of a webpage are defined in several sentences. The parts will be translated in the order of the sentences and will appear in this order in the UI of the application.
Reordering the chapters or the sentences or moving sentences from a chapter to another has no other consequences than the order of the UI elements, in particular, it can't make the code valid or invalid. It might cause the error messages to change in certain cases of invalid code (when faultily redefining an identifier).

In the future, Lisilogic may allow to group the chapters in directories and/or the sentences in paragraphs with a title.

Comments

At this stage, there is no possibility to write comments in the code of a Lisilogic application.
The aim of Lisilogic is to write readable and understandable code, and thus to suppress the need for comments.

If explanations of the code seem needed (purpose of a function or structure, overview of a procedure, external references to norms, warnings and legal notes, ...), it is recommended to display them in the user interface, next to the concerned UI elements or on a "Help" or "Reference" page.

Future developments of the programming environment may allow several kinds of informations attached to the code, corresponding to different uses of comments, tags and annotations in other programming languages:

  • Striked through code, corresponding to disabling ("commenting out") code parts,
  • To-do notices, attached to a task management system and eventually associated with an output in the application (eg. "to be defined", "not implemented yet", ...),
  • "Deprecated" notices for programmers, with mandatory replacement suggestions,
  • Only if absolutely indispensable, specific informations for the different deployment platforms (translators). A common, readable form will be looked for preferentially.

If whished by many users, explanatory comments might be made possible at some point, when the available specialized code enrichment possibilities appear to be developed enough to prevent the tendency of programmers to encode things in comments, or to rely on comments as an excuse for unclear code. These explanatory comments could be implemented in form of side notes attached to a position in the code.

Character Strings

Character strings in Lisilogic are enclosed in double quotes (").

They find various utilizations:

  • String or text constants
    the text "Hello world!"
  • Enumeration elements
    A gender is one of: "female","male","I'd rather not say".
  • Title (and name) of webpages
    On the "Home" page, the user can...
  • Labels of UI elements, headers of table columns
    On the "Manage users" page, the admin can see all users under the label "Users" as a table showing: - a "Street" column containing their street, - ...


Character strings may contain line breaks, tabs, and any character. Line breaks are preserved when displaying webpages, but not tabs or multiple spaces.

String and text constants may contain calculated parts in braces ({})
At the top of any page, the user can see the text "Welcome {his username}!".

Double quotes and opening braces inside character strings must be preceded with a backslash (\)
the text "please say \"hello\" and smile under your moustache \{"

Identifiers

Identifiers in Lisilogic must start with a letter and must not contain any whitespace or punctuation.
Digits (0 to 9) and the underscore character (_) are allowed.
Diacritics and "special characters" (like ü, é, ç, ñ, ø, Ł, đ etc.) are allowed but not recommended. Lisilogic applications are written in English. Future internationalization tools will manage these characters properly.

Uppercase and lowercase don't make a difference, but it is recommended that you write normally, that is, capitalizing only the first letter of each sentence.

Identifiers are used to name

  • Enumerations
    A gender is one of...
  • Structures
    An address is made up of...
  • Attributes of structures
    ... a street, which is a short string.
  • Roles
    On the "Review" page, the reviewer can...
  • Widgets (page parts to be included in other web pages)
    On the address_editor, the user can...
  • Procedures
    To validate an address, ...


Some words are reserved and cannot be used as identifiers (is, a, and, or, in, equal, open, see, edit, save, etc.).
Some predefined identifiers (structures or roles) can be extended (user, admin, file, image, ...), others (mostly operations and functions like and, or, edit, see, save, etc.) can't.

Lists

Lists with more than one element must start with a colon (:), may use a dash (minus sign, -) or an asterisk (*) to introduce each element, and must use a comma (,) or a semicolon (;) to separate their elements.
A gender is one of: - "female", - "male", - "I'd rather not say".

If there is an introducing character (- or *), it must be present for all elements of the list and must be the same throughout.
The element separator (, or ;) must be the same through the whole list.

Lists in lists are recognized using their introducing character and their separator. It is recommended to add a line break before each element and to use indentation for better readability.
On the "Home" page, the user can: - see his address using an address_viewer; - see his files as a table showing: * a column containing their filename, * a column where the user can click "delete" to delete them, * a column where the user can upload them; - click "Save" to save.
(List using asterisk and comma inside of a list using dash and semicolon. The third level could use dash and comma, the fourth level asterisk and semicolon, etc. in a cycle. It is not recommended to write deep level lists of lists though, consider splitting the sentence instead.)

Numbers

In Lisilogic, numbers can be associated with a unit, indicated after them.
add 3 points to the given player's life

A unit may contain any character except dot, comma, colon or semicolon (.,:;), it may not contain whitespace (space, tab, or line break) and it may not start with a plus, a minus, an asterisk or a slash (+-*/).

Units will be combined correctly, but there will be no automatic conversion:
On the "Home" page, the user can: - see 3m + 5kg, - see 50km/h * 3h, - see today - 3 days, - see 3 days + 5 hours, Can't calculate m + kg. 150km 10/19/2017 Can't calculate days + hours.

The % "unit" is handled according to its signification:
- see 50 points + 10%, - see 50.00€ * 19%, 55points 9.50€

Decimal numbers carry along their precision:
- see 40€ + 11%, - see 40.00€ + 11%, 44€ 44.40€

Hint for conversions: provide the unit ratio along with the conversion factor:
- see 3" * 2.5 cm/" 7.5cm

Email Addresses

Explicit email addresses are written without quotes:
send an email to info@lisilogic.com with ...

They must not contain any whitespaces.

Character strings will be converted automatically to email addresses if needed, for instance if they are added to a list of email addresses. In the future, Lisilogic may allow explicit conversion ("the email address ...").

URLs

Explicit URLs are written without quotes and must begin with http://, https:// or mailto:.
open http://www.webware-nach-mass.de/lisilogic in a new window

They must not contain any whitespaces, use %20 instead.

Character strings will be converted automatically to urls if needed. In the future, Lisilogic may allow explicit conversion ("the url ...").

Date and Time Constants

Date and time constants are written without quotes.
Allowed formats for dates are MM/DD/YYYY (English), DD.MM.YYYY (German) and YYYY-MM-DD (database). The word today is available.
Allowed formats for times are hh:mm:ss and hh:mm. The word now is available. The word "at" may be present between date and time.

At the top of any page, the visitor can see today.

set the given document's last_update to now

set the user's respond_before to today at 12:00 + 7 days

set the application's last_controlled to 06/25/2015 17:00:00

Character strings will be converted to dates or timestamps in reasonable cases (for instance when writing them into a date or timestamp attribute). Depending on the execution environment, more formats might be allowed, for instance, PHP is able to convert "Jun. 25th, 2015" to a date. In the future, Lisilogic may allow explicit conversion ("the date ...", "the timestamp ..."), and to use the word "at" as an operator ("the user's birthday at 12:00").