The Readable Programming Language - Handbook

Structures

Definition

A structure (class) is usually defined by declaring its attributes in a "has", "owns", "is made up of" or "knows" sentence.
An address is made up of: - a street, which is a short string, - a house_number, which is a short string, - a city, which is a short string, - a zip_code, which is a short string.

There are no methods and no class inheritance (extends). Lisilogic is user oriented, not object oriented.

Attributes

Each attribute (member variable) of a structure has a name and a type. They may be identical.
Each user has: - an address, - an image called his avatar, - an age, which is a whole number of years.

Several sentences may add attributes to the same structure.

Two attributes may not have the same name, even if one of them is a list (plural name) and the other one a single value (singular name).
Each user has images called his avatars. Redefining attribute avatar with a different cardinality.

An attribute of a structure instance may always be empty (null), but in some cases null works like a particular value (boolean false, empty string, number 0).

If no definition is found for the type of an attribute, it will be interpreted as an empty structure (without attributes).
Instances of this structure can still be created, saved, compared etc., but not displayed.

Relationships

Attributes whose type is a structure may be owned (composition, defined in a "has", "owns" or "is made up of" sentence) or known (reference, defined in a "knows" sentence).
Each user knows a list of users called his friends.

An instance of a structure may belong to (be owned by) at most one other structure.

When a structure instance gets deleted:

  • Everything it owns gets deleted too,
  • It is removed from all reference attributes (lists lose this element, single value attributes are set to null).

Basic Types

Here's the list of the available basic types in Lisilogic.

The eventual parameters of basic types (unit of numbers, max length of strings, etc.) are not mandatory.

It is not possible to make lists of basic types, except email addresses. If you need a list of, say, short strings, then define a structure with a short string attribute and make a list of this structure.

Conversions between basic types are automatic when they can be reasonably expected.

boolean

Constants: true, false

Null values (inaccessible or empty) and empty lists will be interpreted as false when put into boolean attributes or combined to booleans (with and, or, equals, ...).

UI: a boolean will be edited using a checkbox, displayed as a check mark (✓) for true and a dash (-) for false in table columns, and as a disabled checkbox otherwise.

whole number

Parameter: unit
Each user has an age, which is a whole number of years.

Examples of constants: 42, 18 years, 0xFF
See also Basic Syntax: Numbers.

Null will be interpreted as 0.

UI: a whole number will be edited using a text field and right-justified.

number

Parameters: number of decimals and unit
Each article has a price, which is a number in € with 2 decimals.

Examples of constants: 3.5, 40.00 €, -1.3e-5
See also Basic Syntax: Numbers.

Null will be interpreted as 0.0e0 (0 without a unit and without a number of decimals).

UI: a number will be edited using a text field and right-justified.

short string

Parameter: maximum length in characters.
Each address has a street, which is a short string (max 20 characters).
The length of short strings is limited 30 characters in the database and the max length parameter can only make it smaller.
When a too long string is written into a short string attribute, it will be cut off, issueing a warning in the ui.

Null will be interpreted as an empty string ("").

Example of constant: the text "Main st."
String constants introduced by "the text" will be considered short strings if their length is less than 30 characters and if they contain no line breaks, as texts otherwise.
Double quoted constants without "the text" will be considered enumeration values and converted to short strings, texts, email addresses, etc. when needed.

Short string constants may contain calculated parts in braces ({}): the text "Hello {the user's username}!"
See also Basic Syntax: Character Strings.

UI: a short string will be edited using a text field.

text

Parameter: maximum length in characters.
Each submission has a description, which is a text (max 2000 characters).

Null will be interpreted as an empty string ("").

Example of constant:
the text "Please describe your project here. Please be precise and don't repeat informations provided otherwise."
String constants introduced by "the text" will be considered short strings if their length is less than 30 characters and if they contain no line breaks, as texts otherwise.
Double quoted constants without "the text" will be considered enumeration values and converted to short strings, texts, email addresses, dates etc. when needed.

Text constants may contain calculated parts in braces ({}).
See also Basic Syntax: Character Strings.

UI: a text will be edited using a text area.

In the future, Lisilogic may allow rich texts (with bold, italics etc.), edited using a WYSIWYG editor. The exact possibilities will be adapted to the experience in pioneer projects.

password

Example of attribute: Each user has a signature, which is a password.

A password is just like a short string, except that it is never displayed, checked using a password field and edited using two password fields (the user must repeat the new password identically).

email address

Example of attribute: Each user has an email address.

Unlike all other basic types, it is possible to make lists of email addresses:
Each gallery has a list of email addresses called its subscribers.

Examples of constants: info@lisilogic.com, "kontakt@webware-nach-mass.de,remy@webware-nach-mass.de"
See also Basic Syntax: Email Addresses.

Email addresses are checked for syntax before they are stored into variables, so you may rely on the fact that email address attributes are syntactically valid.

UI:

  • a single email address will be displayed as a mailto: link and edited using a text field.
  • a list of email addresses will be displayed as a mailto: link with several recipients and edited using a text area.

url

Example of attribute: Each user has a home_page, which is a url.

Example of constant: http://www.webware-nach-mass.de/lisilogic
See also Basic Syntax: URLs.

Conversions: mailto: urls can be converted to email addresses and reciprocally.

UI: Urls are displayed as links and edited using a text field. Only http://, https:// and mailto: urls are allowed, http:// will be added automatically if needed.

date

Example of attribute: Each user has a birthday, which is a date.

Constants:today, 12/16/2017, "Dec 16th, 2017"
See also Basic Syntax: Date and Time Constants.

Arithmetic operations between dates and strings and dates and numbers are calculated within reasonable possibilities, see Basic Syntax: Numbers.

UI: A date is displayed in English format (MM/DD/YYYY) and edited with a text field that allows also other formats (DD.MM.YYYY, YYYY-MM-DD, and different textual representations). A popup calendar is in development.

timestamp

Example of attribute: Each submission has a timestamp called its modified_at.

Constants:now, 12/16/2017 04:31:49, today at 20:00, "Dec 16th, 2017 4:31am"
See also Basic Syntax: Date and Time Constants.

Arithmetic operations between timestamps and strings and timestamps and numbers are calculated within reasonable possibilities, see Basic Syntax: Numbers.

UI: A timestamp is displayed in English format (MM/DD/YYYY hh:mm:ss) and edited with a text field that allows also other formats (DD.MM.YYYY hh:mm:ss, YYYY-MM-DD hh:mm:ss, and different textual representations). A popup calendar is in development.

Enumerations

See the corresponding chapter: Enumerations.

Double quoted constants without "the text" will be considered enumeration values and converted to short strings, texts, email addresses, dates etc. when needed.

role

Is a predefined enumeration, see Roles.

Predefined Structures

user

The predefined structure user has:

  • a username, which is a short string,
  • a password,
  • a list of roles.

You may add attributes to it.

The list of roles will automatically contain the value "user" and it may not contain the value "visitor", which is reserved for people who visit the application without logging in.

If you define a structure with the same name as a role, an instance of it (a role object) will be created automatically each time the role is added to a user's role list.

See Roles.

file

The predefined structure file has:

  • a filename, which is a string with up to 255 characters,
  • a type, which is a short string calculated as the filename's extension (after the last dot),
  • a size, which is a whole number of bytes, calculated automatically when the file gets uploaded,
  • an upload_time, which is a timestamp saved automatically when the file gets uploaded.

You may add attributes to it.

It is not possible to create a file or to set its type, size or upload_time programmatically. Files can only be uploaded.

Setting the filename of a file means renaming it. The name may be corrected automatically if it contains forbidden characters or if it is already in use; a warning will be issued.
Renaming a file may change its type. This is not recommended, except to normalize the type (jpg instead of jpeg for instance).

Attribute parameter: the allowed types (filename extensions)
Each submission has a description_document, which is a pdf, odt or doc file.
Uppercase or lowercase doesn't make a difference for filename extensions.

UI: files are normally displayed as a download link and edited using a file input (upload) and a "delete" checkbox.
To display also their attributes, use the word "download" instead of "see".
The normal editor also displays the files, use the word "upload" instead of "edit" to show only the file input. This is useful when the files are already visible or editable somewhere else, for instance in a table.

Conversions between files and images are only made (if possible) when copying one of them. So it is possible to add an image to a list of files if this list is an owned attribute, but not if it is a known (reference) attribute. The same applies to single value attributes.

image

The predefined structure image has:

  • a filename, which is a string with up to 255 characters,
  • a width, which is a whole number of px calculated automatically when the image gets uploaded,
  • a height, which is a whole number of px calculated automatically when the image gets uploaded,
  • a size, which is a whole number of px calculated automatically as the maximum of its width or height,
  • an upload_time, which is a timestamp saved automatically when the image gets uploaded.

You may add attributes to it.

It is not possible to create an image or to set its width, height, size or upload_time programmatically. Images can only be uploaded.
In the future, Lisilogic may allow to scale images programmatically by setting their width, height or size.

Setting the filename of an image means renaming it. The name may be corrected automatically if it contains forbidden characters or if it is already in use; a warning will be issued.

Attribute parameters: min size, max size, thumbnail size, min width, max width, thumbnail width, min height, max height, thumbnail height, all in px.
Each user has an avatar, which is an image (min size 64px, max size 640px, thumbnail size 128px).
If defined, the mins and maxes are checked and the thumbnail is calculated automatically when the image is uploaded and when it gets copied to another attribute. The default thumbnail size is 150px, meaning that the thumbnail is produced by scaling the image so that its width and height are both smaller or equal to 150px.
For now, images that don't fit in the defined mins and maxes are rejected (an error is issued). In the future, Lisilogic will support automatic scaling (with a corresponding warning).

UI: images are normally displayed as their thumbnail with a download link, and edited using a file input (upload) and a "delete" checkbox.
To display also their attributes, use the word "download" instead of "see".
The normal editor also displays the images, use the word "upload" instead of "edit" to show only the file input. This is useful when the images are already visible or editable somewhere else, for instance in a table.

Conversions between files and images are only made (if possible) when copying one of them. So it is possible to add an image to a list of files if this list is an owned attribute, but not if it is a known (reference) attribute. The same applies to single value attributes.

application

The application is a predefined structure that has only one instance (singleton pattern).

It has no predefined attributes, you may extend it to store global data.
The application has a list of european_recommendations, which are pdf files.

It is not possible to create or delete an application or to store it in an attribute that owns its content.

session

An instance of the session is created and destroyed automatically with each web session. It will be destroyed if the user logs out, but not upon login.

It has no predefined attributes, you may extend it to store temporary data, for instance to perform checks on edited values before storing them in the database.
The session has a temporary_end_date, which is a date.