This page describes macros available both for thalassa (the static content generator) and thalcgi.cgi (the CGI program).

Please note that the colon char ``:'' is used hereinafter as the delimiter, but in fact any ASCII punctuation char (except for ``_'' and ``*'') can be used in this role.

• Conditionals
• The if macro
• The ifeq macro
• The ifbelongs macro
• The or macro
• The switch macro
• The mapper
• The foreach macro
• How to use it
• String manipulation
• The trim macro
• The collapsews macro: collapse whitespace
• The rmlf macro: remove linefeeds
• The ltgt macro: HTML protection
• The urlenc macro: URL-encoding
• The q macro: quote string as HTML attribute
• Accessing files
• The iffile macro
• The filesize macro
• The readfile macro
• The imgdim macro: dimensions for img tag
• Time and date
• The now macro: current time
• The rfcdate macro
• Indices in file names

Conditionals

This section describes macros that allow to choose one of the two (or more) alternatives depending on certain conditions.

WARNING: Please make sure you read and understood the section devoted to eager computational model and its consequences. It is important to understand that all arguments of any nesting macro call are always computed (unconditionally), and conditional macros only choose one of the results of these computations, simply dropping the results that aren't choosen.

The if macro

Synopsis: %[if:condition:then_text:else_text]

The first argument (condition) is trimmed off any leading and trailing whitespace; in case the result of this trimming is not empty, the condition is assumed true, and then_text is returned; otherwise, else_text is returned.

The third argument may be omitted; in this case, if the condition is empty (false), the macro call expands to an empty string.

The ifeq macro

Synopsis: %[ifeq:str1:str2:then_text:else_text]

The first two arguments (str1 and str2) are trimmed off any leading and trailing whitespace, and the results are compared; in case they are equal, then_text is returned; otherwise, else_text is returned.

The fourth argument may be omitted; in this case, if the strings are not equal, the macro call expands to an empty string.

The ifbelongs macro

Synopsis: %[ifbelongs:str1:list:then_text:else_text]

The first argument (str) is trimmed off any leading and trailing whitespace. The second argument (list) is broken down to words (that is, using whitespace as separators); then, check is performed whether str equals any of the words. In case the word is found, then_text is returned; otherwise, else_text is returned.

The fourth argument may be omitted; in this case, if the given word isn't found in the list, the macro call expands to an empty string.

The or macro

Synopsis: %[or:str1:str2: ... ]

The arguments (str1, str2 etc.) are checked one by one, whether they turn into an empty string after trimming off leading and trailing whitespace. The first argument that doesn't become empty (which effectively means it contains any non-whitespace characters) is returned as it was in the call, before trimming.

If no suitable argument is found, an empty string is returned.

The switch macro

Synopsis: %[switch:expr:v1:r1:v2:r2 ... ]

The first argument, expr, after stripping off all leading and trainling whitespace, is compared, one by one, with values v1, v2 etc., also with spaces stripped off; in case one of them equals to the expr, the work is immediately finished and the corresponding result (r1, r2...) is returned. In case none of the values match, an empty string is returned.

The mapper

In the present version of Thalassa CMS, there's only one macro resembling a loop construct. In reality it is not a loop, it is a mapper. It might look somewhat bad practice to provide anything loop-like in such an environment; unfortunately, it seems hard to invent anything else to build, e.g., a list of <option> items for the <select> HTML form input — and, generally speaking, having an arbitrary list of items, to build an HTML representation for it.

Anyway, the mapper is not intended to be used as a general purpose loop construct, and it definitely should not be abused this way. Remember, all these Thalassa CMS ini files are not programs. If you feel you need a general purpose loop, it means you're doing something wrong.

The foreach macro

Synopsis: %[foreach:list:name:a1:a2: ... ]

The first argument (list) is broken down to words (using whitespace for delimiting). Then for each word, the macro named name is invoked with arguments a1, a2, ..., and with the word as the last argument.

The results of all invocations are concatenated (with no chars inserted in between the items — that is, a real concatenation is done), and the concatenated string is returned.

For example, consider the following call:

  %[foreach:alpha beta gamma:m1:pp:qq:rr]

The result will be precisely the same as if we did

  %[m1:pp:qq:rr:alpha]%[m1:pp:qq:rr:beta]%[m1:pp:qq:rr:gamma]

How to use it

In most cases, the html macro is used as the second argument to foreach, and the HTML snippet name is passed as the third argument.

Consider, for example, you've got a list of certain words and you want to create an HTML enumerated list out of them. The following two snippets will do the thing:

  [html]
  words2ol   = <ol>%[foreach:%0%:html:li_enclose]</ol>
  li_enclose = <li>%0%</li>

Having these two snippets, it is sufficient to write %[html:words2ol:put your list here] to get the HTML list.

String manipulation

In the present version, the set of string manipulation functions doesn't look very powerful. However, once again, this macro system is not a programming language, so we shouldn't ever want things like indexing a string, getting substrings and the like.

The trim macro

Synopsis: %[trim:string]

The argument is stripped off any leading and trailing whitespace; the result is returned.

The collapsews macro: collapse whitespace

Synopsis: %[collapsews:string]

The argument is stripped off any leading and trailing whitespace; within the rest, any non-empty sequence of whitespace chars (space, tab, carriage return and newline) is replaced with exactly one space. The result is returned.

The rmlf macro: remove linefeeds

Synopsis: %[rmlf:string]

All carriage return and newline chars are removed from the argument, the result is returned.

Please note the argument is not stripped nor modified in any other way, only the CR and LF chars are removed.

The ltgt macro: HTML protection

Synopsis: %[ltgt:string]

Within the argument, HTML active characters — namely ``<'', ``>'' and ``&'' — are replaced with, respectively, ``<'', ``>'' and ``&'', making the text safe to be included into an HTML document.

The urlenc macro: URL-encoding

Synopsis: %[urlenc:string]

The argument is URL-encoded and returned.

Precisely speaking, ASCII alphanumeric characters as well as punctuation chars -_~. are left as they are, spaces are replaced with +, and any other byte is percent-encoded, that is, replaced with the percent char and the 2-digit hexadecimal code. Upper-case chars are uses as hexadecimal digits.

The macro is codepage-agnostic, just like almost all Thalassa CMS.

The q macro: quote string as HTML attribute

Synopsis: %[q:string]

If the argument contains no doublequote char, it is returned being surrounded by doublequotes. If it contains doublequotes but doesn't contain apostrophes, it is returned surrounded by apostrophes. In case it contains both apostrophes and doublequotes, it is returned surrounded by doublequotes, with each doublequote char inside the argument replaced with ``"''.

The macro is useful when you need to give an attrubute to an HTML tag, and you're not sure it will not contain doublequote chars at the generation time. Actually, it seems to be a good practice to use this macro for all attribute values that contain any macro calls.

Accessing files

The iffile macro

Synopsis: %[iffile:filename:then_text:else_text]

The first argument (filename) is trimmed off any leading and trailing whitespace, and the result is used as a file name; if the file with given name exists, then_text is returned; otherwise, else_text is returned.

The third argument may be omitted; in this case, if the file doesn't exist, the call expands to an empty string.

The filesize macro

Synopsis: %[filesize:filename]

The first argument (filename) is trimmed off any leading and trailing whitespace, and the result is used as a file name; if the file with given name exists and is a regular file, its size (in bytes, as a decimal number) is returned; otherwise, the macro returns an empty string.

The readfile macro

Synopsis: %[readfile:filename]

The first argument (filename) is trimmed off any leading and trailing whitespace, and the result is used as a file name; if the file with given name exists and is readable, the macro returns the whole contents of the file (as a string, so you probably shouldn't apply this macro to binary files). In case of any error, an empty string is returned.

In case the argument is empty or becomes empty after trimming, no attempts will be made to open any files or to do anything else; the macro will immediately return the empty string. This property can be used for conditional reading of files: instead of placing the readfile call in one of branches of any conditional checkers (in which case the reading attempt will be performed regardless of the condition), better check for the condition within the readfile's argument and return an empty string in case the file is not to be read.

The imgdim macro: dimensions for img tag

Synopsis: %[imgdim:filename]

The first argument (filename) is trimmed off any leading and trailing whitespace, and the result is used as a file name; the file should contain a valid image in PNG, JPEG or GIF format. In case the file doesn't exist, not readable or its format is not recognized, the macro returns an empty string.

In case of successful image parsing, a string with HTML attributes, suitable for use within the img HTML tag, is returned. The string looks like this:

  width="305" height="500" 

The file format is detected by its content, not by its name.

Time and date

The now macro: current time

Synopsis: %now%

No arguments are accepted. Macro call is replaced with the current time as a Unix datetime value (a decimal integer equal to the amount of seconds passed since Jan 01, 1970).

The rfcdate macro

Synopsis: %[rfcdate:unix_datetime]

The first argument (unix_datetime) is trimmed off any leading and trailing whitespace; the result, which must be a decimal number, is taken as a Unix date/time value. The macro returns the same date in a human-readable form as defined by rfc2822, something like ``29 Mar 2023 19:15:00 +0000''.

Indices in file names

Sometimes it becomes necessary to provide a template for file names that form a kind of an array with a main page and some numbered additional pages. For such cases, Thalassa provides a family of index macros; being used within a file name template, they are replaced with the indicies as necessary, thus forming file name series containing numbers.

The ``main'' page is always meant to have zero as its index; however, there's often no page with index 1 (it is not present in lists that have a native order, while is present in reversed lists).

The following macros are used in ``indexed'' file name templates:

• %idx% is substituted with the index number, but empty string for zero;
• %_idx% is substituted with the underscore char and the index number (like ``_12'', but empty string for zero;
• %idx0% is substituted with the index number, even if it is zero.

Please note these macros are not universally available, they only work for file name templates where numbered additional pages are involved. Parameters using these macros are explicitly declared as such.