.TH GOLF 2gg $VERSION $DATE Development Tools
.SH NAME
statements \- Golf documentation (language)
.SH DESCRIPTION

.LP
.B STATEMENTS
.LP

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

.RS 4
\[bu]    
a name,

.RE

.RS 4
\[bu]    
an object,

.RE

.RS 4
\[bu]    
clauses.
.RE

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:

.RS 4
.EX

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

.EE
.RE

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

.RS 4
\[bu]    
input-length 6

.RE

.RS 4
\[bu]    
password "mypass"

.RE

.RS 4
\[bu]    
salt newsalt

.RE

.RS 4
\[bu]    
to res 

.RE

.RS 4
\[bu]    
binary
.RE

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

.RS 4
.EX

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

.EE
.RE

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

.RS 4
.EX

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> ]

.EE
.RE

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:

.RS 4
.EX

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

.EE
.RE

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.

.LP
.B SPLITTING STATEMENT INTO MULTIPLE LINES, SPACE TRIMMING
.LP

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

.RS 4
.EX

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

.EE
.RE

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 \fBbegin-handler\fP statement cannot be split with backsplash, i.e. it must always be on a single line for readability.

.LP
.B COMMENTS
.LP

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:

.RS 4
.EX

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

.EE
.RE


.LP
.B ERROR HANDLING
.LP

A statement that fails for reasons that are generally irrecoverable will \fBerror out\fP, 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.
.SH SEE ALSO
 Language

\fBinline-code\fP  
\fBstatements\fP  
\fBsyntax-highlighting\fP  
\fBunused-var\fP  
\fBvariable-scope\fP   
See all 
\fBdocumentation\fP