JSDoc: Utilities

Methods

bubble_babble(input) → {string} Bubble/Babble encoder that provides a human readable encoding of an input stream.

Parameters:

Name	Type	Description
`input`	string	Input string

Returns:

Encoded string

Type: string

cipher(input, key, algorithm) → {object} Returns the ciphered version of input as well as an initialization vector.

Parameters:

Name	Type	Argument	Default	Description
`input`	string			Input string to be ciphered encoded in UTF-8
`key`	string			The key material of the secret key. It must be a valid key for the specified algorithm.
`algorithm`	string	<optional>	AES/CBC/PKCS5Padding	Algorithm to be used. Only algorithm derived from AES are supported.

See:

utilities#decipher
utilities#generate_key

Returns:

An Object containing the initialization vector (`iv` field) and the ciphered version of input (`ciphered` field)

Type: object

csv_to_json(input, options) → {string} Convert the CSV input to JSON format

Converts an CSV string into a JSON string. If no header row is present in the input, the result will be an array of arrays. If a header row is present and the option 'header' is set to true, the result will be an array of objects having the column names from the header row as attributes.

Parameters:

Name Type Argument Description

input object CSV to convert to JSON format

options

object

options to be used for defining the JSON parsing behavior

Properties

Name	Type	Argument	Default	Description
`header`	boolean	<optional>	false	set to true if a header row is present in the input
`trim`	boolean	<optional>	false	if set to true, leading and trailing white spaces will be removed from each entry in the input
`charset`	string	<optional>	UTF-8	the character set used in the input. More information about character sets
`delimiter`	string	<optional>	"	the delimiter used for entries potentially containing special characters like line break or the separator
`separator`	string	<optional>	,	the column separator used in the input - e.g. ; or \t for SCSV or TSV
`empty`	string	<optional>	"" (empty string)	value to be used to represent an empty or not existing value
`parse_numbers`	array	<optional>		a JSON array of column names or indices (zero based) containing numerical values that should be stored as numbers. Examples: ["ratio", 3] will parse the column with header "ratio" and the fourth column.
`parse_longs`	array	<optional>		a JSON array of column names or indices (zero based) containing numerical values that should be stored as longs. Examples: ["age", 1] will parse the column with header "age" and the second column.
`parse_booleans`	array	<optional>		a JSON array of column names or indices (zero based) containing values that should be stored as booleans. Examples: ["ready", 2] will parse the column with header "ready" and the third column.

Returns:

the resulting JSON data as string

Type: string

Examples

<#assign no_header = '1,true,hello\n2,false,world'>
  ${csv_to_json(no_header)}
  //returns [["1", "true", "hello"], ["2", "false", "world"] - without parsing information, all data is handled as string

<#assign no_header_parse = '1,true,hello\n2,false,world'>
  <#assign options = {"parse_longs":[0], "parse_booleans":[1]}>
  ${csv_to_json(no_header_parse, options)}
  //returns [[1, true, "hello"], [2, false, "world"]]

<#assign header_parse = 'longValue;booleanValue;stringValue\n1;true;hello\n2;false;world'>
  <#assign options = {"header":true, "separator":";", "parse_longs":["longValue"], "parse_booleans":["booleanValue"]}>
  ${csv_to_json(header_parse, options)}
  //returns [{"longValue":1, "booleanValue":true, "stringValue":"hello"},
  {"longValue":2, "booleanValue":false, "stringValue":"world"}]

date_format(date, initial_format, target_format) → {string} Modify the format of a date.

Modify the format of a date. This method can be used in a web interface.

Parameters:

Name	Type	Description
`date`	string	Date to be formatted
`initial_format`	string	Initial format
`target_format`	string	Target format

Returns:

formatted date

Type: string

date_offset(date, offset, format) → {string} Return the a date +/- a number of days.

This method can be used in a web interface.

Parameters:

Name	Type	Argument	Default	Description
`date`	string			Initial date as a string
`offset`	integer	<optional>	0	Ofset in days
`format`	string	<optional>	yyyy-MM-dd	Format of the initial date

Returns:

formatted and offset date

Type: string

decipher(input, iv, key, algorithm) → {object} Returns the deciphered version of the ciphered string provided in input.

Parameters:

Name	Type	Argument	Default	Description
`input`	string			Ciphered string
`iv`	string			the initialization vector
`key`	string			The key material of the secret key. It must be a valid key for the specified algorithm.
`algorithm`	string	<optional>	AES/CBC/PKCS5Padding	Algorithm to be used. Only algorithm derived from AES are supported.

See:

utilities#cipher
utilities#generate_key

Returns:

Deciphered string

Type: object

decode(algorithm, input) → {object} Decode a string.

Returns the decoded version of the encoded string provided in `input`. This method can be used in a web interface

Parameters:

Name	Type	Description
`algorithm`	string	Algorithm to be used. Only algorithm "Base64" is supported.
`input`	string	Encoded string

See:

utilities#encode

Returns:

Decoded string

Type: object

encrypt(algorithm, input, output_type) Returns the encrypted version of a string.

Returns the encrypted version of the string provided in input. This method can be used in a web interface.

Parameters:

Name	Type	Argument	Default	Description
`algorithm`	string	<optional>	BASE64/MD5/SHA1/SHA256	Algorithm to be used.
`input`	string			Input string to be encrypted
`output_type`	string	<optional>	CHAR/HEXA

Example

${encrypt('BASE64','mytext','HEXA')}
		${encrypt('SHA1,BASE64', nonce+created+WS_password, 'CHAR')}

generate_key(paswword, algorithm) → {string} Generate a secret key.

Generate a secret key based on a password and possibly an algorithm.

Parameters:

Name	Type	Argument	Default	Description
`paswword`	string			Password used as a salt to generate the key
`algorithm`	string	<optional>	AES	Algorithm to be used to generate the key

See:

utilities#cipher
utilities#decipher

Returns:

a secret key

Type: string

get_date(seconds, format) → {string} Format a timestamp in seconds into a date.

Format a timestamp in seconds into a date. This method can be used in a web interface.

Parameters:

Name	Type	Argument	Default	Description
`seconds`	integer			Timestamp in seconds
`format`	string	<optional>	yyyy-MM-dd	Target format

Returns:

formatted date

Type: string

get_random() → {float} Returns a random number generated by a uniform distribution.

Returns a random number generated by a uniform distribution. This method can be used in a web interface.

Returns:

Random number with 6 decimals

Type: float

get_random_gaussian(average, stdv) → {float} Returns a random number generated by a gaussian distribution.

Returns a random number generated by a gaussian distribution parameterized by its mean and standard deviation This method can be used in a web interface

Parameters:

Name	Type	Description
`average`	string	Average of the Gaussian distribution
`stdv`	string	Standard deviation of the Gaussian distribution

Returns:

Random number with a gaussian distribution with 6 decimals

Type: float

get_time(date, format) → {integer} Transform a date into a timestamp.

Transform a date into a timestamp. This method can be used in a web interface.

Parameters:

Name	Type	Argument	Default	Description
`date`	string			Date to be transformed
`format`	string	<optional>	yyyy-MM-dd	Format of the start date

Returns:

Number of seconds elapsed between January 1st 1970 and `date`

Type: integer

json_to_csv(input, options) → {string} Convert the JSON input array to CSV format

Converts an array of either JSON objects or arrays to a CSV string. The contained JSON objects must only consist of simple types - no nested objects are allowed. Arrays also must only consist of simple types. The line end is CRLF.

Parameters:

Name Type Argument Description

input object JSON array to convert to CSV format

options

object

options to be used for defining the CSV format

Properties

Name	Type	Argument	Default	Description
`header`	boolean	<optional>	false	if set to true, the JSON attribute names will added as header row at the beginning (only effective when input is an array of JSON objects)
`trim`	boolean	<optional>	false	if set to true, leading and trailing white spaces will be removed from strings
`separator`	string	<optional>	,	the column separator - e.g. ; or \t to get a SCSV or TSV
`empty`	string	<optional>	"" (empty string)	value to be used to represent an empty value (null or a not existing attribute)
`decimal_separator`	string	<optional>	,	the decimal separator to be used for numbers with a fraction
`parse_dates`	object	<optional>		a JSON object having the attribute names to be handled as date as attributes and the date/time patterns to be applied as value (only effective when input is an array of JSON objects). Example: {"birthday":"MM/dd/yyyy"}

Returns:

the resulting CSV data as string

Type: string

Examples

<#assign arrays = [[1, true, "hello"], [null, false, "world"]]>
  ${json_to_csv(simple)}
  //returns 1,true,"hello"CRLF,false,"world"

<#assign objects = [{"birthday":1138752000, "favourite_color":"green", "score":65.7}, 
  {"birthday":"1187136000", "favourite_color":"blue", "score":70}]>
  <#assign options = {"header":true, "separator":";", "decimal_separator":".", "parse_dates"={"birthday":dd.MM.yyyy}}>
  ${json_to_csv(objects, options)}
  //returns birthday;favourite_color;scoreCRLF01.02.2006;"green";65.7CRLF15.08.2007;"blue";70

load(input, format, charset, options) → {object} Convert/parse input to JSON according to its original format

Parameters:

Name Type Argument Default Description

input string content to be loaded

format string <optional> content format, can be one of : `TEXT`, `JSON`, `XML`, `EDI`, `CSV_HEAD`, `CSV_NOHEAD`, `ESKV`, `URL`

charset string <optional> UTF-8 character set of the content to be parsed. More information about character sets

options

object

options to be used for `CSV_HEAD` or `CSV_NOHEAD` format only

Properties

Name	Type	Argument	Default	Description
`separator`	string	<optional>	;	separator between two values (for example `;` or `,`)
`delimiter`	string	<optional>	"	delimiter used to allow values containing the separator character (for example `"` or `'`), to include a delimiter in a value, use two delimiters (`""` for example)
`empty`	string	<optional>	""	value to be used to represent an empty value (two separators in a row)
`parse_numbers`	array	<optional>		array of names or indices (zero based) of columns containing numerical values that should be stored as numbers. Examples : `["age",3]` is asking the loader to parse column with header `"age"` and the fourth column.

Returns:

a variable containing the loaded content

Type: object

now(format) → {string} Get the current date and time.

Get the current date and time. This method can be used in a web interface.

Parameters:

Name	Type	Argument	Default	Description
`format`	string	<optional>	yyyy-MM-dd	Formatting description

Returns:

Current date

Type: string

P_json_accumulate(object, field, value, forceString) → {object} Add a field to an existing object

Add a field to an existing object. If the given field already exists, it will be transformed into an array (if not already an array), and the new value will be added to this array

Parameters:

Name	Argument	Default	Description
`object`			object to add a field to
`field`			name of the field to be added
`value`			value to be associated to the new field, may be a string, a number, an object
`forceString`	<optional>	false	hint to force the value to be considered as a string, even if it's a number or another type of object

See:

utilities#P_json_putAll
utilities#P_json_put
utilities#P_json_accumulateAll

Returns:

the object with the new field

Type: object

Examples

<#assign myObject=P_json_accumulate( myObject, "firstname", myValue, true )>

<#assign myObject=P_json_accumulate( myObject, "age", 32 )> // add age = 32

<#assign myObject=P_json_accumulate( myObject, "status", 404, true )>  // add status="404"

<#assign myObject=P_json_accumulate( myObject, "b", 3 )>  // before: {'a':1,'b':2}, after: {'a':1,'b':[2,3]}

P_json_accumulateAll(object, object2) → {object} Add all fields of an object into another object.

Parameters:

Name	Type	Description
`object`		the object to add the new fields to
`object2`		the object to copy fields from

Returns:

an object containing all fields of object and object2. If both objects have some fields in common, object2 fields will be added to object fields previously transformed into an array if needed

Type: object

P_json_parse(value) → {object} Parse an expression representing a JSONObject, into an object.

Parameters:

Name	Type	Description
`value`		the serialized object to be parsed

Returns:

an object, result of the parsing

Type: object

Example

<#assign myObject=P_json_parse( "{'b':1","a":2}" )>

P_json_put(object, field, value, forceString) → {object} Add a field to an existing object

Parameters:

Name	Type	Argument	Default	Description
`object`	object			object to add a field to
`field`	string			name of the field to be added
`value`	object			value to be associated to the new field, may be a string, a number, an object
`forceString`	boolean	<optional>	false	hint to force the value to be considered as a string, even if it's a number or another type of object

See:

utilities#P_json_put_ext
utilities#P_json_putAll
utilities#P_json_accumulate
utilities#P_json_accumulateAll

Returns:

the object with the new field

Type: object

Examples

<#assign myObject=P_json_put( myObject, "firstname", myValue, true )>

<#assign myObject=P_json_put( myObject, "age", 32 )> // add age = 32

<#assign myObject=P_json_put( myObject, "status", 404, true )>  // add status="404"

P_json_put_ext(object, field, value, forceString) → {object} Add a field to an existing object. This also works for nested objects. Objects within the path, that don't exist, will be created.

Parameters:

Name	Type	Argument	Default	Description
`object`	object			object to add a field to
`field`	string			name of the field to be added or the path separated by '.'
`value`	object			value to be associated to the new field, may be a string, a number, an object
`forceString`	boolean	<optional>	false	hint to force the value to be considered as a string, even if it's a number or another type of object

See:

utilities#P_json_put
utilities#P_json_putAll
utilities#P_json_accumulate
utilities#P_json_accumulateAll

Returns:

the object with the new field

Type: object

Examples

<#assign myObject=P_json_put_ext( myObject, "firstname", myValue, true )>

<#assign myObject=P_json_put_ext( myObject, "age", 32 )> // add age = 32

<#assign myObject=P_json_put_ext( myObject, "status", 404, true )>  // add status="404"

<#assign myObject=P_json_put( myObject, "status.code", 404 )>  // add code=404 to attribute myObject.status; status will be created if not existing

P_json_putAll(object, object2) → {object} Add all fields of an object into another object.

Parameters:

Name	Type	Description
`object`		the object to add the new fields to
`object2`		the object to copy fields from

Returns:

an object containing all fields of object and object2. If both objects have some fields in common, object2 fields will be kept

Type: object

P_json_remove(object, field) → {object} Remove a field from an object.

Parameters:

Name	Type	Description
`object`		object to remove a field from
`field`		field to be removed

Returns:

the object with the given field removed if found, the same object otherwise

Type: object

Example

<#assign myObject=P_json_remove( myObject, "b" )>  // before: {'a':1,'b':2}, after: {'a':1}

P_json_remove_ext(object, field) → {object} Remove a field from an object. This also works for nested objects. If attributes in the path don't exist, nothing will be done.

Parameters:

Name	Type	Description
`object`		object to remove a field from
`field`		field to be removed or path to the field to remove separated by '.'

Returns:

the object with the given field removed if found, the same object otherwise

Type: object

Examples

<#assign myObject=P_json_remove_ext( myObject, "b" )>  // before: {'a':1,'b':2}, after: {'a':1}

<#assign myObject=P_json_remove_ext( myObject, "b.x" )>  // before: {'a':1,'b':{'x':1,'y':2}}, after: {'a':1,'b':{'y':2}}

P_json_stringify(object) → {string} Serialize an object into a JSON string.

Parameters:

Name	Type	Description
`object`		object to be serialized

Returns:

a string, representing the serialized object

Type: string

P_markdown_to_html(content, options) → {string} Converts a Markdown document into its HTML representation. Markdown processor

Parameters:

Name	Type	Argument	Description
`content`	string		Document to process
`options`	object	<optional>	An object to pass some options. `css` and `title` are the two possible options. `css` can be used to specify a css file url or inlined css. `title` is used to give the resulting Html document title.

Returns:

Html representation of the Markdown document

Type: string

Examples

${markdown_to_html(content, {"title":"My Title", "css":"http://server.com/style.css"})}

${markdown_to_html(content, {"title":"My Title", "css":"*{font:15px}"})}

P_quoted(input, quote) → {string} Convenient method to quote a string.

Convenient method to quote a string (this include the backslash of all quote inside the string but also the carriage return...)

Parameters:

Name	Type	Argument	Default	Description
`input`	string			the string value to quote
`quote`	string	<optional>	'] - OPTIONAL the character use to quote (default is simple quote ['

Returns:

a quoted string

Type: string

P_to_array(json_object, key) Returns a JSONArray containing the content associated to a certain key in a JSONObject.

Returns a JSONArray containing the content associated to a certain key in a JSONObject. This method is particularly useful to retrieve the result of Web service call in a clean structure

Parameters:

Name	Type	Description
`json_object`	JSONObject	JSONObject to parse
`key`	string	key

Example

<#assign var1 = {"feed":{"entry":[{"title":"John"},{"title":"Mathew"}]}}>
	${P_to_array(var1.feed,"entry")}
	//returns [{"title":"John"},{"title":"Mathew"}]
	<#assign var2 = {"feed":{"entry":{"title":"John"}}}>
	${P_to_array(var2.feed,"entry")}
	//returns [{"title":"John"}]
	<#assign var31 = {"feed":{}}>
	${P_to_array(var3.feed,"entry")}
	//returns []

password_digest(password) → {string} Returns the encrypted version of a password that can be used in a Digest authentication

Parameters:

Name	Type	Description
`password`	string

Returns:

Type: string

R_encode(encoding, input, result) → {object} Encode a string.

Returns the encoded version of the string provided in `input`.

Parameters:

Name	Type	Argument	Default	Description
`encoding`	string			Encoding to be used. BASE64, BASE64URL or URL
`input`	string			Encoded string
`result`	string	<optional>	CHAR	Type of result expected: characters (CHAR) or hexadecimal (HEXA).

See:

utilities#decode

Returns:

Encoded string

Type: object

R_hmac_hash(data, key, algorithm, encoding) → {string} HMAC is a keyed-hash message authentication code.

A common use case is the generation of a signature for AWS platform requests

Parameters:

Name	Type	Argument	Default	Description
`data`	string			Data to be signed
`key`	string			-
`algorithm`	string	<optional>	SHA256	SHA256 (default), SHA1 or MD5
`encoding`	string	<optional>	BASE64	BASE64 (default), BASE64URL or HEXA

Returns:

Data signed

Type: string

R_rsa_hash(data, key, algorithm, encoding) → {string} Generating RSA digital signature

Generating RSA digital signature specifying the algorithm & encoding

Parameters:

Name	Type	Argument	Default	Description
`data`	string			Data to be signed
`key`	string			The private key readers supports PEM files with PKCS#8 or PKCS#1 encodings. It doesn't support encrypted PEM files
`algorithm`	string	<optional>	SHA256	SHA256 (default), SHA1 or MD5
`encoding`	string	<optional>	BASE64	BASE64 (default), BASE64URL or HEXA

Returns:

Data signed

Type: string

safe_get(key, defaultValue, encoding) → {string} Returns the value of the key in the current context or defaultValue when key is undefined.

Parameters:

Name	Type	Argument	Default	Description
`key`	string			-
`defaultValue`	string			Default value if no value exists for `key`
`encoding`	string	<optional>	NONE	Encoding to be applied to the retrieved value

Returns:

Type: string

timestamp(unit) → {integer} Get a timestamp.

Get a timestamp. This method can be used in a web interface.

Parameters:

Name	Type	Argument	Default	Description
`unit`	string	<optional>	MILLISEC	Unit of the timestamp (SECOND or MILLISEC)

Returns:

Timestamp

Type: integer

to_xml(root, input) → {string} Transform a JSON object into a XML. Fields starting with @ will be output as XML attributes.

Transform a JSON object into a XML. Fields starting with `@` will be output as XML attributes. This method can be used in a web interface

Parameters:

Name	Type	Description
`root`	string	Name of the root element in the resulting XML. If the input object has only one child, pass an empty string as root to use this child as an xml root
`input`	object	Input object

Returns:

XML transform of `ìnput`

Type: string

transpose(input) → {string} Transposition method of an array (in the application widget sense).

Transposition method of an array (in the application widget sense). This method can be used in a web interface

Parameters:

Name	Type	Description
`input`	object	JSON object associating a variable (the column) to a JSON array representing the values in the column or JSONArray of JSONObjects representing the values of the lines

Returns:

Transposition of `ìnput` (columns become rows and vice versa)

Type: string

Example

<#assign rows=[{"a":"a1","b":"b1"},{"a":"a2","b":"b2"}]>
	<#assign to_columns = transpose(rows)>
	//to_columns : {"a":["a1","a2"],"b":["b1","b2"]}  
	<#assign columns={"a":["a1","a2"],"b":["b1","b2"]}>
	<#assign to_rows = transpose(columns)>
	//to_rows : [{"a":"a1","b":"b1"},{"a":"a2","b":"b2"}]

uuid() → {string} Generate a UUID.

Generate a universally unique identifier or UUID

Returns:

a UUID

Type: string

Docs

Utilities

Methods

bubble_babble(input) → {string}

Parameters:

Returns:

cipher(input, key, algorithm) → {object}

Parameters:

Returns:

csv_to_json(input, options) → {string}

Parameters:

Properties

Returns:

Examples

date_format(date, initial_format, target_format) → {string}

Parameters:

Returns:

date_offset(date, offset, format) → {string}

Parameters:

Returns:

decipher(input, iv, key, algorithm) → {object}

Parameters:

Returns:

decode(algorithm, input) → {object}

Parameters:

Returns:

encrypt(algorithm, input, output_type)

Parameters:

Example

generate_key(paswword, algorithm) → {string}

Parameters:

Returns:

get_date(seconds, format) → {string}

Parameters:

Returns:

get_random() → {float}

Returns:

get_random_gaussian(average, stdv) → {float}

Parameters:

Returns:

get_time(date, format) → {integer}

Parameters:

Returns:

json_to_csv(input, options) → {string}

Parameters:

Properties

Returns:

Examples

load(input, format, charset, options) → {object}

Parameters:

Properties

Returns:

now(format) → {string}

Parameters:

Returns:

P_json_accumulate(object, field, value, forceString) → {object}

Parameters:

Returns:

Examples

P_json_accumulateAll(object, object2) → {object}

Parameters:

Returns:

P_json_parse(value) → {object}

Parameters:

Returns:

Example

P_json_put(object, field, value, forceString) → {object}

Parameters:

Returns:

Examples

P_json_put_ext(object, field, value, forceString) → {object}

Parameters:

Returns:

Examples

P_json_putAll(object, object2) → {object}

Parameters:

Returns:

P_json_remove(object, field) → {object}

Parameters:

Returns: