Ubuntu Manpage: statements - Golf documentation (language)

NAME

       statements - Golf documentation (language)

DESCRIPTION

       STATEMENTS

       Golf statements generally have three components separated by space(s):

           • a name,

           • an object,

           • clauses.

       A statement starts with a name, which designates its main purpose.

       An object denotes what is referenced by a statement.

       Each  clause that follows consist of a clause name followed either with no arguments, or with one or more
       arguments. A clause may have subclauses immediately afterwards, which follow  the  same  structure.  Most
       clauses  are separated by space(s), however some (like "=" or "@") may not need space(s) before any data;
       the statement's documentation would clearly specify this.

       An object must immediately follow the statement's name, while clauses may be specified in any order.

       For example, in the following Golf code:

           encrypt-data orig_data input-length 6 password "mypass" salt newsalt to res binary

       encrypt-data is the statement's name, and "orig_data" is its object. The clauses are:

           • input-length 6

           • password "mypass"

           • salt newsalt

           • to res

           • binary

       The clauses can be in any order, so the above can be restated as:

           encrypt-data orig_data to res password "mypass" salt newsalt binary input-length 6

       Golf documentation provides a concise BNF-like notation of how each statement works,  which  in  case  of
       encrypt-data is (backslash simply allows continuing to multiple lines):

           encrypt-data <data> to <result> \
               [ input-length <input length> ] \
               [ binary [ <binary> ] ] \
               ( password <password> \
                   [ salt <salt> [ salt-length <salt length> ] ] \
                   [ iterations <iterations> ] \
                   [ cipher <cipher algorithm> ] \
                   [ digest <digest algorithm> ]
                   [ cache ]
                   [ clear-cache <clear cache> ) \
               [ init-vector <init vector> ]

       Note the color scheme: clauses with input data are in blue, and with output data in green.

       Optional clauses are enclosed with angle brackets (i.e between "[" and "]").

       Arguments (in general variables and constants) are stated between "<" and ">".

       If only one of a number of clauses may appear, such clauses are separated by "|".

       A group of clauses that cannot be separated, or to remove ambiguity, are enclosed with "(" and ")".

       Keywords  (other  than  statement  names  such  as  encrypt-data  above)  are  generally specific to each
       statement. So, keyword "salt", for example, has meaning only within encrypt-data and a few other  related
       statements.  In  order to have the freedom to choose your variable names, you can simply surround them in
       parenthesis (i.e. "(" and ")") and use any names you want, even keywords, for example:

           set-string password = "some password"
           set-string salt = "0123456789012345"
           encrypt-data "some data" password (password) salt (salt) to enc_data
           print-out enc_data

       In this example, keywords "password" and "salt" are used as variable names as well.

       Note that while you can use tab characters at the beginning of the line (such  as  for  indentation),  as
       well  as  in  string literals, do not use tabs in Golf statements otherwise as they are not supported for
       lack of readability - use plain spaces.

       SPLITTING STATEMENT INTO MULTIPLE LINES, SPACE TRIMMING

       To split a statement into multiple lines (including string  continuations),  use  a  backslash  (\),  for
       instance:

           encrypt-data orig_data input-length 6 \
               password "my\
               pass" salt \
               newsalt to res binary

       Note that all statements are always left-trimmed for whitespace. Thus the resulting string literal in the
       above example is "mypass", and not "my   pass", as the whitespaces prior to line starting with "pass" are
       trimmed first. Also, all statements are right-trimmed for white space, except if backslash is used at the
       end,  in  which  case  any spaces prior to backslash are conserved. For that reason, in the above example
       there is a space prior to a backslash where clauses need to be separated.

       Note that begin-handler statement cannot be split with backsplash, i.e. it must always  be  on  a  single
       line for readability.

       COMMENTS

       You  can  use  both  C  style  (i.e.  /*  ...  */) and C++ style (i.e. //) comments with Golf statements,
       including within statements (with the exception of /*..*/ before statement  name  for  readability),  for
       example:

           run-query @db = \
               "select firstName, lastName from employee where yearOfHire>='%s'" \
               output /* comment within */ firstName, lastName : "2015" // other comment

       ERROR HANDLING

       A  statement  that  fails for reasons that are generally irrecoverable will error out, for example out of
       memory or disk space, bad input parameters etc.

       Golf philosophy is to minimize the need to check for such  conditions  by  preventing  the  program  from
       continuing.  This  is  preferable,  as  forgetting to check usually results in unforeseen bugs and safety
       issues, and the program should have stopped anyway.

       Errors that are correctable programmatically are reported and  you  can  check  them,  for  example  when
       opening a file that may or may not exist.

       Overall,  the  goal  is to stop execution when necessary and to offer the ability to handle an issue when
       warranted, in order to increase run-time safety and provide instant clues about conditions that  must  be
       corrected.

NAME

DESCRIPTION

SEE ALSO