Types.HasValue( Value )

Determine if a variable contains a value or or not.

Returns: boolean - True if Value actually contains a value.

Parameters

Description

Tests the provided Value parameter and returns false if it does not represent a value. More specifically, if Value is undefined or null, then false is returned. if Value is a zero length string "" or an empty object {}, false is also returned. In all other cases, this function returns true.

Types.Coerce( Value, Loud )

Returns a Coercion object which is used to coerce values to different types.

Returns: object - A Coercion object.

Parameters

Description

The returned Coercion object has a single member Coercion.value and a number of coercion functions:

• ToBoolean( Default = false ) : Returns the boolean value of Coercion.value. Anything can be coerced to a boolean. If value is a string, then 'false' and '0' will return false while 'true' will return true.

• ToNumber( Default = 0 ) : Returns the numeric value of Coercion.value. Booleans, other numbers, and numeric strings can be coerced to a number.

• ToString( Default = '' ) : Returns the string value of Coercion.value. Anything can be coerced to a string. If value is an object, then it is JSON stringified and returned.

• ToObject( Default = null ) : Returns the object value of Coercion.value. Only JSON strings and other objects can be coerced to an object. If value is a JSON string, then it is JSON parsed and returned.

Coercion.value is set to the Value parameter.

Usage

There are two ways to use the Coercion object.

One way is to immediately call one of the coercion functions after obtaining the Coercion object:

let number_42 = Liquicode.Types.Coerce( '42' ).ToNumber();

Another way is to reuse the Coercion object and alter the Coercion.value property yourself:

let coercion = Liquicode.Types.Coerce();
coercion.value = '42';
let number_42 = coercion.ToNumber();

Examples

// Coercing to boolean
Schema.Coerce( null ).ToBoolean()           // = false
Schema.Coerce( 0 ).ToBoolean()              // = false
Schema.Coerce( 'true' ).ToBoolean()         // = true

// Coercing to number
Schema.Coerce( null ).ToNumber()            // = 0
Schema.Coerce( '3.14' ).ToNumber()          // = 3.14
Schema.Coerce( 'foo' ).ToNumber()           // = 0

// Coercing to string
Schema.Coerce( null ).ToString()            // = ''
Schema.Coerce( '3.14' ).ToString()          // = '3.14'
Schema.Coerce( { foo: 'bar' } ).ToString()  // = '{"foo":"bar"}'

// Coercing to object
Schema.Coerce( null ).ToObject()            // = null
Schema.Coerce( 3.14 ).ToObject()            // = null
Schema.Coerce( '{"foo":"bar"}' ).ToObject() // = { foo: 'bar' }

// Coercing with a Default
Schema.Coerce( 'Hello' ).ToNumber( -1 )     // = -1
Schema.Coerce( true ).ToObject( {} )        // = {}
Schema.Coerce( 1024 ).ToObject( {} )        // = {}
Schema.Coerce( null ).ToObject( { a: 1 } )  // = { a: 1 }
Schema.Coerce( null ).ToObject( [ 1, 2 ] )  // = [ 1, 2 ]

Types.GetFormat( Value )

Determine the type and format of a value.

Returns: string - An extended type description.

Parameters

Description

Iterates through Types.Formats in reverse order and calls each Format.IsFormat() function. When one of the formats returns true, then it's type and format are returned separated by :.

Examples

Liquicode.Types.GetFormat( '42' )         // = 'number:integer'
Liquicode.Types.GetFormat( 'Hello' )      // = 'string:string'
Liquicode.Types.GetFormat( new Date() )   // = 'object:datetime'
Liquicode.Types.GetFormat( [ 1, 2, 3 ] )  // = 'object:number-array'

Types.IsFormat( Value, Format )

Determine if a value is of a particular format.

Returns: boolean - True if the value matches the format.

Parameters

Description

Looks up the specified format in Types.Formats and calls the Format.IsFormat() function.

The Format parameter must specify both type and format to be tested for.

Examples

Liquicode.Types.IsFormat( 'Hello', 'string:string' )            // = true
Liquicode.Types.IsFormat( 'Hello', 'string:json' )              // = false
Liquicode.Types.IsFormat( [ 1, 2, 3 ], 'object:array' )         // = true
Liquicode.Types.IsFormat( [ 1, 2, 3 ], 'object:number-array' )  // = true
Liquicode.Types.IsFormat( [ 1, 2, 3 ], 'object:string-array' )  // = false

Object.Clone( From )

undefined

Returns: string

Parameters

Description

Returns a clone of the given object. This is equivalent to doing A = JSON.parse( JSON.stringify( B ) ).

Object.Merge( Original, Updates )

undefined

Returns: object

Parameters

Description

Merges the content of two objects and returns the composite result.

Similar to Object.Clone, this function will remove any non-data fields (i.e. functions and symbols) from the objects.

This function is similar to javascript's Object.assign function except that Object.Merge will do a recursive field-wise comparison, while Object.assign only compares top-level fields.

In cases where a field is an array, the field value will be overwritten. There is no element-wise comparison performed.

Examples

Simple Object Merging

let A = { one: 1, two: 0 };
let B = { two: 2 };
let C = LiquicodeJS.Object.Merge( A, B );
// C = { one: 1, two: 2 };

Merging with Nested Objects

let A = { misc: { foo: 'bar' }, numbers: { one: 1, two: 0 } };
let B = { numbers: { two: 2 } };
let C = LiquicodeJS.Object.Merge( A, B );
// C = {
// 	misc: { foo: 'bar' },
// 	numbers: { one: 1, two: 2 }
// };

Merging with Nested Arrays

let A = { misc: { foo: 'bar' }, numbers: '' };
let B = {
    numbers: [
        { value: 1 },
        { value: 2 }
    ]
};
let C = LiquicodeJS.Object.Merge( A, B );

// C = {
// 	misc: { foo: 'bar' },
// 	numbers: [
// 		{ value: 1 },
// 		{ value: 2 }
// 	]
// };

Object.FromJson( JsonString )

undefined

Returns: object

Parameters

Description

Parse a Json string and return an object value. This is identical Javascript's "JSON.parse()" function.

There are some significant differences from Javascript's version. The parser is a bit more relaxed and allows:

• Identifiers are not required to have quotes.
• A comma can appear after the last element of an array or object.
• String literals can use either single or double quotes.
• Parsing automatically stops when the closing brace or bracket is found in the json string.

Object.ToJsonOptions( PresetName )

undefined

Returns: object

Parameters

Description

Object.ToJson( Value, JsonOptions )

undefined

Returns: object

Parameters

Description

Object.FromIni( IniString )

undefined

Returns: object

Parameters

Description

Parse an Ini string and return an object value.

Object.ToIni( Value )

undefined

Returns: object

Parameters

Description

Parse an Ini string and return an object value.

Object.ValueArrayOf( Value )

undefined

Returns: array

Parameters

Description

Returns an array of values. If the Value parameter is missing or null, then an empty array [] is returned. If Value is an object, its values are returned in the array. If Value is already an array, it is returned unmodified. Otherwise, an array is returned containing Value as its only member.

Text.Compare( StringA, StringB, CaseSensitive )

undefined

Returns: string

Parameters

Description

Compares two strings. Returns a -1 if StringA is less than StringB. Returns a 1 if StringA is greater than than StringB. Returns a 0 if StringA and StringB are the same.

Text.Matches( Text, Pattern )

undefined

Returns: string

Parameters

Description

Matches the text against a wildcard-lik pattern. Returns true If the match succeeds, otherwise false.

Text.ReplaceCharacters( Text, SearchCharacters, ReplacementText, MaxTimes )

undefined

Returns: string

Parameters

Description

Replaces characters within a string. Returns the modified string.

Text.ReplaceText( Text, SearchText, ReplacementText, MaxTimes )

undefined

Returns: string

Parameters

Text.FindBetween( Text, StartText, EndText )

Search a string and return the text found between StartText and EndText.

Returns: string - The text found between StartText and EndText.

Parameters

Description

This function searches a string for StartText and EndText and returns all text found between the two.

If StartText is missing, then the search will return all text up to the found EndText.

If EndText is missing, then the search will return all text found after StartText.

If both StartText and EndText are missing, then the entire Text string will be returned.

If StartText or EndText are not found within Text, then a null is returned.

Text.ReplaceBetween( Text, StartText, EndText, ReplacementText, MaxTimes )

Search a string for StartText and EndText and replace the text found between the two.

Returns: integer - The new string with replacements performed.

Parameters

Description

This function searches a string for StartText and EndText and replaces all text found between the two.

If StartText is missing, then all text found up to EndText will be replaced.

If EndText is missing, then all text found after StartText will be replaced.

If both StartText and EndText are missing, then the entire Text string will be replaced.

If StartText or EndText are not found within Text, then this function returns 0 to indicate that no replacements were performed.

The MaxTimes parameter specifies the maximum number of replacements to perform. If MaxTimes is -1, then all possible replacements will be made throughout Text.

Text.FirstWord( Phrase, Delimiters )

undefined

Returns: string

Parameters

Description

Returns the first word of a text phrase.

Text.AfterFirstWord( Phrase, Delimiters )

undefined

Returns: string

Parameters

Description

Returns the remainder of a text phrase occurring after the first word.

Text.LastWord( Phrase, Delimiters )

undefined

Returns: string

Parameters

Description

Returns the last word of a text phrase.

Text.BeforeLastWord( Phrase, Delimiters )

undefined

Returns: string

Parameters

Description

Returns the remainder of a text phrase occurring befiore the last word.

Shapes.Matrix( Values, Options )

Matrix stores a two-dimensional jagged array and exposes manipulation functions.

Returns: object

Parameters

Description

A Matrix object is essentially a two-dimensional array (an array of arrays). This function will create and return a new Matrix object.

Values Parameter

You can specify the initial contents of the Matrix with the Values parameter. If Values is an array of arrays, then Matrix will contain those values. If Values is a one-dimensional array, then Matrix will have a single row reflecting those values. If Values is an integer, then Matrix will be created with that number of blank rows.

Note that the only way to create a new Matrix with no rows in it is: Shapes.Matrix( 0, Options )

Options Parameter

The Options parameter is an options object:

Options = {
    default_value: null,    // A default value to use when no other value exists.
    clone_values: true,     // If true, any values read from or written to the Matrix are cloned first.
}

The clone_values option is very important. It is initialliy set to true, providing the safest and most sensible operation. A performance improvement can be had by setting this to false; However, unintended consequences may occur if you are not careful. Alsa, this is a valid intended consequence if you want to use Matrix to quickly manipulate an existing array.

For example:

let test_array = [
    [ 1, 2, 3, 4 ],
    [ 5, 6, 7, 8 ],
];
// test_array.length == 2
// Encapsulate the array in a matrix.
let matrix = Liquicode.Shapes.Matrix( test_array, { clone_values: false } );
// Append a row to the matrix.
matrix.AppendRows( [ 'A', 'B', 'C' ] );
// Since test_array was not cloned first, the new row also appears in test_array.
// test_array.length == 3 !!!

How It Works

The Matrix object contains a RowData member which is an array of arrays that contains the values for the matrix. This is maintained as a jagged array, meaning that each row of the matrix may be of different lengths.

[	// Matrix maintains values in a jagged array:
    [ 1, 2, 3, 4 ],
    [ 1, 2, 3 ],
    [ 1, 2, 3, 4, 5 ],
]

When calling the AppendColumns, InsertColumns, SetColumn, or SetValue functions, it may be necessary for the matrix to fill out the columns of shorter rows so that the target column exists. For example, appending a blank column (AppendColumns()) to the matrix above would yield:

[	// Matrix fills columns with
    // default values as needed:
    [ 1, 2, 3, 4,    null, null ],
    [ 1, 2, 3, null, null, null ],
    [ 1, 2, 3, 4,    5,    null ],
]

You can change the value used to fill blank columns by changing Option.default_value.

Cell Addressing

When working with Matrix, you will usually need to identify a particular Row or Column to work with. Matrix supports three types of addressing modes:

• 1. A zero-based index used as a row/column index. This index must be greater than or equal to zero and less than the extent (i.e. the RowCount or ColumnCount).
• 2. A negative index that serves as an offset from the extent (e.g. -1 = RowCount - 1). This type of index must be between -extent and -1, inclusive.
• 3. A spreadsheet style address (e.g. 'A1', 'B2', etc.). This type of address has letters component which indicates a column. This is followed by a digits component that is a one-based row number.

Matrix Functions

The Matrix object also has a number of functions which allow you to manipulate the Matrix object.

• Addressing Functions: These are utility functions that assist when working with the spreadsheet style of addressing. These functions are used internally by Matrix. They do not consider the validity of any particular address or index within the current Matrix.

  • IsValidAddress( Address ): Returns true if Address is a valid address, otherwise false. A valid address must contain a column component in letters ('AB') and a row component in digits ('12'). This function determines only if the Address parameter is a properly formatted address, regardless if the address lies outside the bounds of this particular Matrix.

  • NumberToLetters( Number ): Returns the letters component of an address for any positive number (e.g. 1='A', 2='B', 28='AB', etc.).

  • LettersToNumber( Address ): Converts the letters component of an address to a positive number. Address is a string that starts with, or is entirely composed of, letters.

• Row Functions:

  • RowIndexOf( Address ): Will return a valid row index for this Matrix from the given Address. Address can represent any of the three addressing styles.

  • RowCount(): Returns the number of rows within the Matrix.

  • AppendRows( Values ): Appends one or more rows to the end of the Matrix. If Values is not supplied, then a blank row is appended. If Values is a one-dimensional array, then a single row is appended. If Values is a two-dimensional array, then multiple rows are appended.

  • InsertRows( Row, Values ): Inserts one or more rows within the Matrix, starting at the given Row address. If Values is not supplied, then a blank row is appended. If Values is a one-dimensional array, then a single row is appended. If Values is a two-dimensional array, then multiple rows are appended. Note that it is not possible to append a row to a Matrix by using this function.

  • DeleteRows( Row, Count ): Deletes one or more rows within the Matrix, starting at the given Row address. If Count is not supplied, then a single row is deleted.

  • GetRow( Row ): Returns a single row of values from the Matrix, at the given Row address.

  • SetRow( Row, Values ): Replaces a single row of values (a one-dimensional array) within the Matrix, at the given Row address. If Values is not supplied, then a blank row is set at that location.

• Column Functions:

  • ColumnIndexOf( Address ): Will return a valid column index for this Matrix from the given Address. Address can represent any of the three addressing styles.

  • ColumnCount(): Returns the number of columns within the Matrix.

  • AppendColumns( Values ): Appends one or more columns to the end of the Matrix. If Values is not supplied, then a blank column is appended. If Values is a one-dimensional array, then a single column is appended. If Values is a two-dimensional array, then multiple columns are appended.

  • InsertColumns( Column, Values ): Inserts one or more columns within the Matrix, starting at the given Column address. If Values is not supplied, then a blank column is appended. If Values is a one-dimensional array, then a single column is appended. If Values is a two-dimensional array, then multiple columns are appended. Note that it is not possible to append a column to a Matrix by using this function.

  • DeleteColumns( Column, Count ): Deletes one or more columns within the Matrix, starting at the given Column address. If Count is not supplied, then a single column is deleted.

  • GetColumn( Column ): Returns a single column of values from the Matrix, at the given Column address.

  • SetColumn( Column, Values ): Replaces a single column of values (a one-dimensional array) within the Matrix, at the given Column address. If Values is not supplied, then a blank column is set at that location.

• Value Functions:

  • GetValue( Row, Column ): Returns a single value located at Row and Column within the Matrix. Row can be a string address, in which case the Column parameter is omitted.

  • SetValue( Row, Column, Value ): Sets a single value located at Row and Column within the Matrix. Row can be a string address, in which case the Column parameter is omitted.

  • GetMatrix( Row, Column, RowCount, ColumnCount ): Constructs a new Matrix of values from within the called Matrix. Values are taken starting at the location described by Row and Column and extending for RowCount rows and ColumnCount columns.

    • You can call this using four parameters: GetMatrix( Row, Column, RowCount, ColumnCount )
    • You can call this using three parameters: GetMatrix( Address, RowCount, ColumnCount )
    • You can call this using two parameters: GetMatrix( Address, Size )

  • SetMatrix( Row, Column, Matrix ): Sets a matrix of values starting at Row and Column.

• Table Functions:

  • Clone(): Return a clone of this matrix. The clone will contain a copy of this matrix's data and options.

  • Transpose(): Return a copy of this matrix with its rows and column transposed.

  • Join( AtColumn, JoinType, JoinMatrix, MatrixColumn ): Return a new matrix by joining this matrix with another one. The join is produced by matching column values between the two matrices. The different supported join types are: 'inner', 'left', 'right', and 'full'.

Parse.TokenizeOptions( PresetName )

undefined

Returns: object

Parameters

Description

Returns a set of options for calling Tokenize(). Throws an error if an invalid value for PresetName is given.

Parse.Tokenize( PresetName )

undefined

Returns: object

Parameters

Description

Returns the parsed tokens.

Parse.DateParse( Value, TimeZoneOffset )

undefined

Returns: object

Parameters

Description

Dates and times are funny little creatures.

System.AsyncVisitFiles( StartFolder, FilePattern, Recurse, Visitor )

undefined

Returns: *

Parameters

Description

Scans a folder and calls the Visitor callback function for each folder/file encountered.

The FilePattern parameter is optional and can be a wildcard type string. For example, to visit all text files, you can pass '*.txt'. If FilePattern is not empty, then the callback will not be called for folders.

The Visitor callback function takes two parameters Visitor( Path, Filename ). If the Visitor callback returns a value, then the visitation process is halted and that value is returned by the VisitFiles function. The Visitor callback is called for each file encountered and for each folder encountered. When called for a folder, the Filename parameter will be null. The Visitor callback function can be either synchronous or asymchronous.

System.VisitFiles( StartFolder, FilePattern, Recurse, Visitor )

undefined

Returns: *

Parameters

Description

Scans a folder and calls the Visitor callback function for each folder/file encountered.

The FilePattern parameter is optional and can be a wildcard type string. For example, to visit all text files, you can pass '*.txt'. If FilePattern is not empty, then the callback will not be called for folders.

The Visitor callback function takes two parameters Visitor( Path, Filename ). If the Visitor callback returns a value, then the visitation process is halted and that value is returned by the VisitFiles function. The Visitor callback is called for each file encountered and for each folder encountered. When called for a folder, the Filename parameter will be null. The Visitor callback function must be synchronous.

System.CountFiles( StartFolder, FilePattern, Recurse )

undefined

Returns: number

Parameters

Description

Scans a folder and calls the Visitor callback function for each folder/file encountered. Returns the number of folders/files visited.

System.CountFolders( StartFolder, Recurse )

undefined

Returns: number

Parameters

Description

Scans a folder and calls the Visitor callback function for each folder/file encountered. Returns the number of folders/files visited.

System.CopyFolder( FromFolder, ToFolder, FilePattern, Overwrite, Recurse )

undefined

Returns: number

Parameters

Description

Copies files from one folder to another. Returns the number of files copied.

System.DeleteFolder( Folder, Recurse )

undefined

Returns: number

Parameters

Description

Deletes a folder and all of its sub-folders and files. Returns the number of folders and files deleted.

System.EmptyFolder( Folder )

undefined

Returns: number

Parameters

Description

Empties a folder by removing all of its sub-folders and files.

Returns the number of folders and files removed.

System.WithFileText( Filename, FileTextCallback )

undefined

Returns: boolean - False if no changes were made or True if changes were saved.

Parameters

Description

Loads content from a file and passes it to a callback function for processing.

The callback function takes two parameters: Filename and Text. Filename is the Filename passed to WithFileText and Text is the content of that file. The callback function is expected to return either undefined or null if no changes are made to the text. If changes are made, the callback function can return the new text which will be saved back to Filename.

If the file content is changed during callback processing, then WithFileText will return True.

System.AsyncSleep( Milliseconds )

undefined

Parameters

System.ExecuteProcess( Command, Environment, StartFolder )

undefined

Parameters

System.AsyncExecuteProcess( Command, Environment, StartFolder )

undefined

Parameters

System.StartProcess( Command, Environment, StartFolder )

undefined

Returns: string

Parameters

Description

Starts a new process and returns the ProcessID.

System.StopProcess( ProcessID )

undefined

Returns: string

Parameters

Description

Stops a running process by its ProcessID.

System.ContainerStatus( ContainerID )

undefined

Returns: string

Parameters

Description

Gets the status of a running Docker Container.

System.RunContainer( ImageName, Options )

undefined

Returns: string

Parameters

Description

Runs a Docker Container.

Options Parameter:

{
    name: '',           // Name of the container. Defaults to random name.
    hostname: '',       // Hostname for the container.
    network: '',        // Name of docker network for the container to use.
    ports: [],          // Array of port object { localhost: 80, container: 80 }
    volumes: [],        // Array of volume object { localhost: '/path', container: '/path' }
    environment: {},    // Environment variables and values.
}

Example:

let container_id = Liquicode.RunContainer( 'mongo:latest',
    {
        name: 'mongo-server',
        ports: [ { localhost: 27017, container: 27017 } ],
    } );

System.StartContainer( ContainerID )

undefined

Returns: string

Parameters

Description

Stops a running Docker Container.

System.StopContainer( ContainerID )

undefined

Returns: string

Parameters

Description

Stops a running Docker Container.

System.KillContainer( ContainerID )

undefined

Returns: string

Parameters

Description

Kills a running Docker Container.

Network.AsyncDownloadFile( )

undefined

Returns: string

Description

Download a file from an url.

Network.AsyncGetRequest( Url )

undefined

Returns: string

Parameters

Description

Make an http get request for a an url.