Introduction
The language has a number of functions built-in which are always available. These are described below in the following groups:-
| Group | Functions |
|---|---|
| General purpose | @if, @quote, @read, @filesys, @version, @global |
| Type conversion | @error, @string, @field, @range, @rlist, @number, @float |
| Value properties | @type, @low, @high, @span, @size, @envelope, @object |
| Manage blobs | @load:blob |
Additional mathematical functions will be added in the future.
General Purpose
| Function | Description |
|---|---|
| @if( comp, t, f ) | Acts as a comparison operator. |
| @quote( value ) | Stringize the value and enclose in " quotes. |
| @read.input( prompt ) | Obtain text from file or console. |
| @filesys | Examine and control the file system. |
| @version | Return the current Glich version. |
| @global | Select the global variable if both global and local exist. |
Function: @if( comp, t, f )
The @if function behaves similar to the C language ? : tertiary operator. If the comp argument is true the result is the t argument, otherwise the result is the f argument. The function is equivalent to the following statement.
| function if( comp, t, f ) { if comp result = t; else result = f; endif } |
Function @quote( value )
The quote function is identical to the string function below, except the resulting text is enclosed in " double quotes
| Example | Result |
|---|---|
| @quote( 1 = 2 ) | "false" |
| @quote( 345f ) | "345" |
| @quote( 50 | 5 .. 10 ) | "5..10 | 50" |
| @quote( "Text" ) | "Text" |
| @quote( "say ""hello""" ) | "say ""hello""" |
Function: @read.filecode( prompt = "" )
Provide external text input. If the function is not qualified, the nature of the input will depend upon program running the script. An optional prompt may be supplied. How this is used will also depend on the running program.
If the function is qualified with a file code then the function will return the next line of text from the file, starting at the first line. The file code must have been successfully defined using the file statement first.
Function: @filesys
The filesys function and its qualifiers give limited control over the underlying file system.
| Function | Description |
|---|---|
| @filesys | Return the current working directory. |
| @filesys.cd( path ) | Change the current working directory. |
| @filesys.dir | Return object listing all files in the current directory. |
| @filesys.exists( path ) | Return true if the path exists. |
| @filesys.exists.file( path ) | Return true if the file exists. |
| @filesys.exists.dir( path ) | Return true if the directory exists. |
The @filesys function without any qualifiers or arguments will return a string value holding the current working directory. If the script creates or opens any files, this is where they will be located.
Function: @filesys.cd( path )
The @filesys.cd( path ) qualified function will change the current working directory to the given (absolute or relative) path. It will return the new current working directory if successful. If the change fails, an error value is returned.
Function: @filesys.dir
The @filesys.dir qualified function will return a general object containing the current directory as its first value followed by a list of all directories and files it contains. Directories will have the prefix "D: " and the files "F: ".
Function: @filesys.exists( path )
The @filesys.dir qualified function will return the boolean value true if the (absolute or relative) path is a valid directory or file, and false otherwise.
The "file" or "dir" additional qualifiers are used to specify which type of path we are testing for.
Function: @version
Return the current version string or version number (in string form).
| Function | Description |
|---|---|
| @version | Return the version number and configuration. |
| @version.number | Return just the version number. |
Function: @global
If a variable name is used for a local and a global variable, just the name will give the local value. The @global.name function will give the global value.
| Example | Result |
|---|---|
| let value = 100; global value = "hundred"; write value, @global.value; | 100, hundred |
Type Conversion
| Function | Description |
|---|---|
| @error( message ) | Create an error value. |
| @string( value ) | Stringize the value. |
| @field( value, default = ? ) | Convert value to a field type. |
| @range( value, default = 0..0 ) | Convert value to a range type. |
| @rlist( value, default = empty ) | Convert value to a rlist type. |
| @number( value, default = 0 ) | Convert value to a number type. |
| @float( value, default = nan ) | Convert value to a float type. |
Function @error( message )
The error function converts a string message into an error value. This can be used to signal an unusable value in a calculation or function.
The prefix "Error ("line"): " is added to message, where line is the line number of the the error function.
| Example | Result |
|---|---|
| @error( "Age is negative." ) | Error (10): Age is negative. |
| @error( "Age of " + age + " is too high." ) | Error (10): Age of 150 is too high. |
Function @string( value )
The string function converts any value type (including error types) to a string value. The conversion follows the same rules as the write statement uses.
| Example | Result |
|---|---|
| @string( null ) | null |
| @string( 1 = 2 ) | false |
| @string( 123n ) | 123 |
| @string( 345f ) | 345 |
| @string( 1.2 ) | 1.2 |
| @string( 10 .. 20 ) | 10..20 |
| @string( 50 | 5 .. 10 ) | 5..10 | 50 |
| @string( {:,11} ) | {: null, 11} |
| @string( @error( "Test" ) ) | Error (1): Test |
| @string( "Text" ) | Text |
| @string( "say ""hello""" ) | say "hello" |
Function @field( value, default )
The field function converts the value, where possible, to a field. If the conversion is not possible then the optional default value is used. If the default is not given or cannot be used, the function returns the unknown '?' value.
Conversion of the float type rounds the value to the nearest integer and tests for limits.
| Example | Result |
|---|---|
| @field( null ) | ? |
| @field( null, 0 ) | 0 |
| @field( 1 = 2 ) | ? |
| @field( 123n, 0 ) | 123 |
| @field( 345f ) | 345 |
| @field( 1.7 ) | 2 |
| @field( 1.7, 10 ) | 2 |
| @field( 10 .. 20 ) | ? |
| @field( 50 | 5 .. 10, 0 ) | 0 |
| @field( {:,11} ) | ? |
| @field( @error( "Test" ), 0 ) | 0 |
| @field( "-50" ) | -50 |
| @field( "10 + 2" ) | 12 |
Function @range( value, default )
The range function converts the value, where possible, to a range. If the conversion is not possible then the optional default value is used. If the default is not given or cannot be used, the function returns the 0..0 range value (which normally gets demoted to the field 0).
| Example | Result |
|---|---|
| @range( 123n, 0 ) | 123..123 |
| @range( 345f ) | 345..345 |
| @range( 1.7 ) | 0..0 |
| @range( 1.7, 10..12 ) | 10..12 |
| @range( 10 .. 20 ) | 10..20 |
| @field( 50 | 5 .. 10 ) | 0..0 |
| @field( "50 .. 55" ) | 50..55 |
Function @rlist( value, default )
The rlist function converts the value, where possible, to an rlist. If the conversion is not possible then the optional default value is used. If the default is not given or cannot be used, the function returns the empty rlist value.
| Example | Result |
|---|---|
| @rlist( 123n, 0 ) | 123..123 |
| @rlist( 345f ) | 345..345 |
| @rlist( 1.7 ) | empty |
| @rlist( 1.7, past..future ) | past..future |
| @rlist( 10 .. 20 ) | 10..20 |
| @rlist( 50 | 5 .. 10 ) | 5..10 | 50 |
| @rlist( "50 .. 55|10" ) | 10 | 50..55 |
| @rlist( "!0" ) | -infinity..-1 | 1..+infinity |
| The output of the range limit names will depend on the script context setting. | |
Function @number( value, default )
The number function converts the value, where possible, to a number. If the conversion is not possible then the optional default value is used. If the default is not given or cannot be used, the function returns 0.
Conversion of the float type rounds the value to the nearest integer.
| Example | Result |
|---|---|
| @number( 123n, 100 ) | 123 |
| @number( 345f ) | 345 |
| @number( 1.7 ) | 2 |
| @number( 1.7, 10 ) | 2 |
| @number( 10 .. 20 ) | 0 |
| @number( 50 | 5 .. 10, 50 ) | 50 |
| @number( "-50" ) | -50 |
| @number( "10 + 2" ) | 12 |
Function @float( value, default )
The float function converts the value, where possible, to a float. If the conversion is not possible then the optional default value is used. If the default is not given or cannot be used, the function returns nan (not a number).
| Example | Result |
|---|---|
| @float( 123n, 100 ) | 123.0 |
| @float( 345f ) | 345.0 |
| @float( 1.7 ) | 1.7 |
| @float( 10 .. 10 ) | 10.0 |
| @float( 50 | 5 .. 10, 50 ) | 50.0 |
| @float( {:,11} ) | nan |
| @float( "-50" ) | -50.0 |
| @float( "10 + 2" ) | 12.0 |
Value Properties
| Function | Description |
|---|---|
| @type( value ) | Return the type of value as a string. |
| @low( value ) | Return the lower bound of a range or rlist. |
| @high( value ) | Return the upper bound of a range or rlist. |
| @span( value ) | Return the inclusive count between upper and lower bounds of a range or rlist. |
| @size( value ) | Return the number of elements in a rlist, object or string |
| @envelope( value ) | Return the enclosing range af an rlist. |
| @object( value ) | Return the object code name. |
Function: @type( value )
The function returns a string type with the name of the value type, as shown in the table below.
An error value is not passed through, but the value type "error" is returned instead.
| Example | Result |
|---|---|
| @type( 123n ) | number |
| @type( 456f ) | field |
| @type( 10.5 ) | float |
| @type( "text" ) | string |
| @type( 5..10 ) | range |
| @type( 4..8 | 10..18 ) | rlist |
| @type( {: 10, 20, 30} ) | object |
| @type( true ) | bool |
| @type( null ) | null |
| @type( @error( "Whoops" ) ) | error |
Function: @low( value )
If value is of type range, the function returns the lower field value. If value is of type rlist, the function returns the lower field of the first range in the rlist.
If the value is a numeric_type, then the value is returned unchanged. An error value will also be returned unchanged. All other values will return the field value ? (invalid).
| Example | Result |
|---|---|
| @low( 123n ) | 123 |
| @low( 456f ) | 456 |
| @low( 10.5 ) | 10.5 |
| @low( "text" ) | ? |
| @low( 5..10 ) | 5 |
| @low( 4..8 | 10..18 ) | 4 |
| @low( {: 10, 20, 30} ) | ? |
| @low( true ) | ? |
| @low( null ) | ? |
| @low( @error( "Whoops" ) ) | Error (12): Whoops |
Function: @high( value )
If value is of type range, the function returns the higher field value. If value is of type rlist, the function returns the higher field of the last range in the rlist.
If the value is a numeric_type, then the value is returned unchanged. An error value will also be returned unchanged. All other values will return the field value ? (invalid).
| Example | Result |
|---|---|
| @high( 123n ) | 123 |
| @high( 456f ) | 456 |
| @high( 10.5 ) | 10.5 |
| @high( "text" ) | ? |
| @high( 5..10 ) | 10 |
| @high( 4..8 | 10..18 ) | 18 |
| @high( {: 10, 20, 30} ) | ? |
| @high( true ) | ? |
| @high( null ) | ? |
| @high( @error( "Whoops" ) ) | Error (12): Whoops |
Function: @span( value )
If the value is an integer_type, then the function returns the field value 1. If value is of type range or rlist, the function returns the inclusive count between upper and lower bounds of the range or rlist.
An error value will be returned unchanged. All other values will return the field value ? (invalid).
| Example | Result |
|---|---|
| @span( 123n ) | 1 |
| @span( 456f ) | 1 |
| @span( 10.5 ) | ? |
| @span( "text" ) | ? |
| @span( 5..10 ) | 6 |
| @span( 4..8 | 10..18 ) | 15 |
| @span( {: 10, 20, 30} ) | ? |
| @span( true ) | ? |
| @span( null ) | ? |
| @span( @error( "Whoops" ) ) | Error (12): Whoops |
Function: @size( value )
If value is of type text, the function returns the number of characters in the string. If value is of type rlist, the function returns the number of ranges in the rlist. If value is of type object, the function returns the number of elements in the object.
An error value will be returned unchanged. All other values will return the number 0.
| Example | Result |
|---|---|
| @size( 123n ) | 0 |
| @size( 456f ) | 0 |
| @size( 10.5 ) | 0 |
| @size( "text" ) | 4 |
| @size( 5..10 ) | 0 |
| @size( 4..8 | 10..18 ) | 2 |
| @size( {: 10, 20, 30} ) | 3 |
| @size( true ) | 0 |
| @size( null ) | 0 |
| @size( @error( "Whoops" ) ) | Error (12): Whoops |
Function: @envelope( value )
The @envelope function is only intended to be used with an rlist value, when it returns the enclosing range value.
An error value will be returned unchanged. All other values will return the field value ? (invalid).
| Example | Result |
|---|---|
| @envelope( 123n ) | ? |
| @envelope( 456f ) | ? |
| @envelope( 10.5 ) | ? |
| @envelope( "text" ) | ? |
| @envelope( 5..10 ) | ? |
| @envelope( 4..8 | 10..18 ) | 4..18 |
| @envelope( {: 10, 20, 30} ) | ? |
| @envelope( true ) | ? |
| @envelope( null ) | ? |
| @envelope( @error( "Whoops" ) ) | Error (12): Whoops |
Function: @object( value )
The @object function is only intended to be used with an object value, when it returns the objects code name string value.
An error value will be returned unchanged. All other values will return an empty string value "".
| Example | Result |
|---|---|
| @object( 123n ) | "" |
| @object( 456f ) | "" |
| @object( 10.5 ) | "" |
| @object( "text" ) | "" |
| @object( 5..10 ) | "" |
| @object( 4..8 | 10..18 ) | "" |
| @object( {: 10, 20, 30} ) | ":" |
| @object( true ) | "" |
| @object( null ) | "" |
| @object( @error( "Whoops" ) ) | Error (12): Whoops |
Manage Blobs
Blob values are created using the @load:blob function. They are saved using the save:blob command.
| Function | Description |
|---|---|
| @load:blob( filename ) | Load a blob from a file. |
Function: @load:blob( filename )
If the file exists and can be opened, the function returns a blob with the files binary data. Otherwise, the function returns an error value. The blob type is determined by the file extension where possible.
| Example | Result |
|---|---|
| @load:blob( "glich32.png" ) | blob:png:1999 |
