Standard YAQL Library

Comparison operators

Common module describes comparison operators for different types. Comparing with null value is considered separately.

operator !=

Returns true if left and right are not equal, false otherwise.

It is system function and can be used to override behavior of comparison between objects.

operator <

  • Returns false. This function is called when left is not null and right is null.
    signature:left < right
    callAs:operator
    arg left:left operand
    argType left:not null
    arg right:right operand
    argType right:null
    returnType:boolean
  • Returns false. This function is called when left and right are null.
    signature:left < right
    callAs:operator
    arg left:left operand
    argType left:null
    arg right:right operand
    argType right:null
    returnType:boolean
  • Returns true. This function is called when left is null and right is not.
    signature:left < right
    callAs:operator
    arg left:left operand
    argType left:null
    arg right:right operand
    argType right:not null
    returnType:boolean

operator <=

  • Returns false. This function is called when left is not null and right is null.
    signature:left <= right
    callAs:operator
    arg left:left operand
    argType left:not null
    arg right:right operand
    argType right:null
    returnType:boolean
  • Returns true. This function is called when left and right are null.
    signature:left <= right
    callAs:operator
    arg left:left operand
    argType left:null
    arg right:right operand
    argType right:null
    returnType:boolean
  • Returns true. This function is called when left is null and right is not.
    signature:left <= right
    callAs:operator
    arg left:left operand
    argType left:null
    arg right:right operand
    argType right:not null
    returnType:boolean

operator =

Returns true if left and right are equal, false otherwise.

It is system function and can be used to override behavior of comparison between objects.

operator >

  • Returns true. This function is called when left is not null and right is null.
    signature:left > right
    callAs:operator
    arg left:left operand
    argType left:not null
    arg right:right operand
    argType right:null
    returnType:boolean
  • Returns false. This function is called when left and right are null.
    signature:left > right
    callAs:operator
    arg left:left operand
    argType left:null
    arg right:right operand
    argType right:null
    returnType:boolean
  • Returns false. This function is called when left is null and right is not.
    signature:left > right
    callAs:operator
    arg left:left operand
    argType left:null
    arg right:right operand
    argType right:not null
    returnType:boolean

operator >=

  • Returns true. This function is called when left is not null and right is null.
    signature:left >= right
    callAs:operator
    arg left:left operand
    argType left:not null
    arg right:right operand
    argType right:null
    returnType:boolean
  • Returns true. This function is called when left and right are null.
    signature:left >= right
    callAs:operator
    arg left:left operand
    argType left:null
    arg right:right operand
    argType right:null
    returnType:boolean
  • Returns false. This function is called when left is null and right is not.
    signature:left >= right
    callAs:operator
    arg left:left operand
    argType left:null
    arg right:right operand
    argType right:not null
    returnType:boolean

Boolean logic functions

Whenever an expression is used in the context of boolean operations, the following values are interpreted as false: false, null, numeric zero of any type, empty strings, empty dict, empty list, empty set, zero timespan. All other values are interpreted as true.

bool

Returns true or false after value type conversion to boolean. Function returns false if value is 0, false, empty list, empty dictionary, empty string, empty set, and timespan(). All other values are considered to be true.

signature:bool(value)
callAs:function
arg value:value to be converted
argType value:any
returnType:boolean
yaql> bool(1)
true
yaql> bool([])
false

isBoolean

Returns true if value is boolean, otherwise false.

signature:isBoolean(value)
callAs:function
arg value:value to check
argType value:any
returnType:boolean
yaql> isBoolean(false)
true
yaql> isBoolean(0)
false

operator and

Returns left operand if it evaluates to false. Otherwise evaluates right operand and returns it.

signature:left and right
callAs:operator
arg left:left operand
argType left:any
arg right:right operand
argType right:any
returnType:any (left or right operand types)
yaql> 1 and 0
0
yaql> 1 and 2
2
yaql> [] and 1
[]

operator not

Returns true if arg evaluates to false. Otherwise returns false.

signature:not arg
callAs:operator
arg arg:value to be converted
argType arg:any
returnType:boolean
yaql> not true
false
yaql> not {}
true
yaql> not [1]
false

operator or

Returns left operand if it evaluates to true. Otherwise evaluates right operand and returns it.

signature:left or right
callAs:operator
arg left:left operand
argType left:any
arg right:right operand
argType right:any
returnType:any (left or right operand types)
yaql> 1 or 0
1
yaql> 1 or 2
1
yaql> [] or 1
1

Working with collections

Functions that produce or consume finite collections - lists, dicts and sets.

add

Returns a new set with added args.

signature:set.add([args])
callAs:method
receiverArg set:
 input set
argType set:set
arg [args]:values to be added to set
argType [args]:chain of any type
returnType:set
yaql> set(0, 1).add("", [1, 2, 3])
[0, 1, "", [1, 2, 3]]

contains

Returns true if value is contained in collection, false otherwise.

signature:collection.contains(value)
callAs:method
receiverArg collection:
 collection to find occurrence in
argType collection:
 iterable
arg value:value to be checked for occurrence
argType value:any
returnType:boolean
yaql> ["a", "b"].contains("a")
true

containsKey

Returns true if the dictionary contains the key, false otherwise.

signature:dict.containsKey(key)
callAs:method
receiverArg dict:
 dictionary to find occurrence in
argType dict:mapping
arg key:value to be checked for occurrence
argType key:any
returnType:boolean
yaql> {"a" => 1, "b" => 2}.containsKey("a")
true

containsValue

Returns true if the dictionary contains the value, false otherwise.

signature:dict.containsValue(value)
callAs:method
receiverArg dict:
 dictionary to find occurrence in
argType dict:mapping
arg value:value to be checked for occurrence
argType value:any
returnType:boolean
yaql> {"a" => 1, "b" => 2}.containsValue("a")
false
yaql> {"a" => 1, "b" => 2}.containsValue(2)
true

delete

  • Returns collection with removed [position, position+count) elements.

    signature:collection.delete(position, count => 1)
    callAs:method
    receiverArg collection:
     input collection
    argType collection:
     iterable
    arg position:index to start remove
    argType position:
     integer
    arg count:how many elements to remove, 1 by default
    argType position:
     integer
    returnType:iterable
    yaql> [0, 1, 3, 4, 2].delete(2, 2)
    [0, 1, 2]
    
  • Returns dict with keys removed.

    signature:dict.delete([args])
    callAs:method
    receiverArg dict:
     input dictionary
    argType dict:mapping
    arg [args]:keys to be removed from dictionary
    argType [args]:chain of keywords
    returnType:mapping
    yaql> {"a" => 1, "b" => 2, "c" => 3}.delete("a", "c")
    {"b": 2}
    

deleteAll

Returns dict with keys removed. Keys are provided as an iterable collection.

signature:dict.deleteAll(keys)
callAs:method
receiverArg dict:
 input dictionary
argType dict:mapping
arg keys:keys to be removed from dictionary
argType keys:iterable
returnType:mapping
yaql> {"a" => 1, "b" => 2, "c" => 3}.deleteAll(["a", "c"])
{"b": 2}

dict

  • Returns dictionary of provided keyword values.

    signature:dict([args])
    callAs:function
    arg [args]:arguments to create a dictionary
    argType [args]:mappings
    returnType:dictionary
    yaql> dict(a => 1, b => 2)
    { "a": 1, "b": 2}
    
  • Returns dictionary with keys and values built on items pairs.

    signature:dict(items)
    callAs:function
    arg items:list of pairs [key, value] for building dictionary
    argType items:list
    returnType:dictionary
    yaql> dict([["a", 2], ["b", 4]])
    {"a": 2, "b": 4}
    
  • Returns dict built on collection where keys are keySelector applied to collection elements and values are valueSelector applied to collection elements.

    signature:collection.toDict(keySelector, valueSelector => null)
    callAs:method
    receiverArg collection:
     collection to build dict from
    argType collection:
     iterable
    arg keySelector:
     lambda function to get keys from collection elements
    argType keySelector:
     lambda
    arg valueSelector:
     lambda function to get values from collection elements. null by default, which means values to be collection items
    argType valueSelector:
     lambda
    returnType:dictionary
    yaql> [1, 2].toDict($, $ + 1)
    {"1": 2, "2": 3}
    

difference

Return the difference of left and right sets as a new set.

signature:left.difference(right)
callAs:method
receiverArg left:
 left set
argType left:set
arg right:right set
argType right:set
returnType:set
yaql> set(0, 1, 2).difference(set(0, 1))
[2]

flatten

Returns an iterator to the recursive traversal of collection.

signature:collection.flatten()
callAs:method
receiverArg collection:
 collection to be traversed
argType collection:
 iterable
returnType:list
yaql> ["a", ["b", [2,3]]].flatten()
["a", "b", 2, 3]

get

Returns value of a dictionary by given key or default if there is no such key.

signature:dict.get(key, default => null)
callAs:method
receiverArg dict:
 input dictionary
argType dict:dictionary
arg key:key
argType key:keyword
arg default:default value to be returned if key is missing in dictionary. null by default
argType default:
 any
returnType:any (appropriate value type)
yaql> {"a" => 1, "b" => 2}.get("c")
null
yaql> {"a" => 1, "b" => 2}.get("c", 3)
3

insert

  • Returns collection with inserted value at the given position.

    signature:collection.insert(position, value)
    callAs:method
    receiverArg collection:
     input collection
    argType collection:
     iterable
    arg position:index for insertion. value is inserted in the end if position greater than collection size
    argType position:
     integer
    arg value:value to be inserted
    argType value:any
    returnType:iterable
    yaql> [0, 1, 3].insert(2, 2)
    [0, 1, 2, 3]
    
  • Returns collection with inserted value at the given position.

    signature:collection.insert(position, value)
    callAs:method
    receiverArg collection:
     input collection
    argType collection:
     sequence
    arg position:index for insertion. value is inserted in the end if position greater than collection size
    argType position:
     integer
    arg value:value to be inserted
    argType value:any
    returnType:sequence
    yaql> [0, 1, 3].insert(2, 2)
    [0, 1, 2, 3]
    

insertMany

Returns collection with inserted values at the given position.

signature:collection.insertMany(position, values)
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
arg position:index for insertion. value is inserted in the end if position greater than collection size
argType position:
 integer
arg values:items to be inserted
argType values:iterable
returnType:iterable
yaql> [0, 1, 3].insertMany(2, [2, 22])
[0, 1, 2, 22, 3]

intersect

Returns set with elements common to left and right sets.

signature:left.intersect(right)
callAs:method
receiverArg left:
 left set
argType left:set
arg right:right set
argType right:set
returnType:set
yaql> set(0, 1, 2).intersect(set(0, 1))
[0, 1]

isDict

Returns true if arg is dictionary, false otherwise.

signature:isDict(arg)
callAs:function
arg arg:value to be checked
argType arg:any
returnType:boolean
yaql> isDict([1, 2])
false
yaql> isDict({"a" => 1})
true

isList

Returns true if arg is a list, false otherwise.

signature:isList(arg)
callAs:function
arg arg:value to be checked
argType arg:any
returnType:boolean
yaql> isList([1, 2])
true
yaql> isList({"a" => 1})
false

isSet

Returns true if arg is set, false otherwise.

signature:isSet(arg)
callAs:function
arg arg:value to be checked
argType arg:any
returnType:boolean
yaql> isSet({"a" => 1})
false
yaql> isSet(set(1, 2))
true

items

Returns an iterator over pairs [key, value] of input dict.

signature:dict.items()
callAs:method
receiverArg dict:
 input dictionary
argType dict:dictionary
returnType:iterator
yaql> {"a" => 1, "b" => 2}.items()
[["a", 1], ["b", 2]]

keys

Returns an iterator over the dictionary keys.

signature:dict.keys()
callAs:method
receiverArg dict:
 input dictionary
argType dict:dictionary
returnType:iterator
yaql> {"a" => 1, "b" => 2}.keys()
["a", "b"]

len

  • Returns size of the dictionary.

    signature:dict.len()
    callAs:function or method
    receiverArg dict:
     input dictionary
    argType dict:mapping
    returnType:integer
    yaql> {"a" => 1, "b" => 2}.len()
    2
    
  • Returns length of the list.

    signature:sequence.len()
    callAs:function or method
    receiverArg sequence:
     input sequence
    argType dict:sequence
    returnType:integer
    yaql> [0, 1, 2].len()
    3
    
  • Returns size of the set.

    signature:set.len()
    callAs:function or method
    receiverArg set:
     input set
    argType set:set
    returnType:integer
    yaql> set(0, 1, 2).len()
    3
    

list

  • Returns list of provided args.

    signature:list([args])
    callAs:function
    arg [args]:arguments to create a list
    argType [args]:any types
    returnType:list
    yaql> list(1, "", 2)
    [1, "", 2]
    
  • Returns list of provided args and unpacks arg element if it's iterable.

    signature:list([args])
    callAs:function
    arg [args]:arguments to create a list
    argType [args]:chain of any types
    returnType:list
    yaql> list(1, "", range(2))
    [1, "", 0, 1]
    

operator *

  • Returns sequence repeated count times.

    signature:left * right
    callAs:operator
    arg left:multiplier
    argType left:integer
    arg right:input sequence
    argType right:sequence
    returnType:sequence
    yaql> 2 * [1, 2]
    [1, 2, 1, 2]
    
  • Returns sequence repeated count times.

    signature:left * right
    callAs:operator
    arg left:input sequence
    argType left:sequence
    arg right:multiplier
    argType right:integer
    returnType:sequence
    yaql> [1, 2] * 2
    [1, 2, 1, 2]
    

operator +

  • Returns combined left and right dictionaries.

    signature:left + right
    callAs:operator
    arg left:left dictionary
    argType left:mapping
    arg right:right dictionary
    argType right:mapping
    returnType:mapping
    yaql> {"a" => 1, b => 2} + {"b" => 3, "c" => 4}
    {"a": 1, "c": 4, "b": 3}
    
  • Returns two iterables concatenated.

    signature:left + right
    callAs:operator
    arg left:left list
    argType left:iterable
    arg right:right list
    argType right:iterable
    returnType:iterable
    yaql> [1, 2] + [3]
    [1, 2, 3]
    

operator .

Returns value of a dictionary by given key.

signature:left.right
callAs:operator
arg left:input dictionary
argType left:dictionary
arg right:key
argType right:keyword
returnType:any (appropriate value type)
yaql> {"a" => 1, "b" => 2}.a
1

operator <

Returns true if left set is subset of right set and left size is strictly less than right size, false otherwise.

signature:left < right
callAs:operator
arg left:left set
argType left:set
arg right:right set
argType right:set
returnType:boolean
yaql> set(0) < set(0, 1)
true

operator <=

Returns true if left set is subset of right set.

signature:left <= right
callAs:operator
arg left:left set
argType left:set
arg right:right set
argType right:set
returnType:boolean
yaql> set(0, 1) <= set(0, 1)
true

operator >

Returns true if right set is subset of left set and left size is strictly greater than right size, false otherwise.

signature:left > right
callAs:operator
arg left:left set
argType left:set
arg right:right set
argType right:set
returnType:boolean
yaql> set(0, 1) > set(0, 1)
false

operator >=

Returns true if right set is subset of left set.

signature:left >= right
callAs:operator
arg left:left set
argType left:set
arg right:right set
argType right:set
returnType:boolean
yaql> set(0, 1) >= set(0, 1)
true

operator in

Returns true if there is at least one occurrence of value in collection, false otherwise.

signature:left in right
callAs:operator
arg left:value to be checked for occurrence
argType left:any
arg right:collection to find occurrence in
argType right:iterable
returnType:boolean
yaql> "a" in ["a", "b"]
true

operator indexer

  • Returns value of a dictionary by given key.

    signature:left[right]
    callAs:function
    arg left:input dictionary
    argType left:dictionary
    arg right:key
    argType right:keyword
    returnType:any (appropriate value type)
    yaql> {"a" => 1, "b" => 2}["a"]
    1
    
  • Returns value of a dictionary by given key or default if there is no such key.

    signature:left[right, default]
    callAs:function
    arg left:input dictionary
    argType left:dictionary
    arg right:key
    argType right:keyword
    arg default:default value to be returned if key is missing in dictionary
    argType default:
     any
    returnType:any (appropriate value type)
    yaql> {"a" => 1, "b" => 2}["c", 3]
    3
    
  • Returns value of sequence by given index.

    signature:left[right]
    callAs:function
    arg left:input sequence
    argType left:sequence
    arg right:index
    argType right:integer
    returnType:any (appropriate value type)
    yaql> ["a", "b"][0]
    "a"
    

remove

Returns the set with excluded values provided in arguments.

signature:set.remove([args])
callAs:method
receiverArg set:
 input set
argType set:set
arg [args]:values to be removed from set
argType [args]:chain of any type
returnType:set
yaql> set(0, 1, "", [1, 2, 3]).remove("", 0, [1, 2, 3])
[1]

replace

Returns collection where [position, position+count) elements are replaced with value.

signature:collection.replace(position, value, count => 1)
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
arg position:index to start replace
argType position:
 integer
arg value:value to be replaced with
argType value:any
arg count:how many elements to replace, 1 by default
argType count:integer
returnType:iterable
yaql> [0, 1, 3, 4, 2].replace(2, 100, 2)
[0, 1, 100, 2]

replaceMany

Returns collection where [position, position+count) elements are replaced with values items.

signature:collection.replaceMany(position, values, count => 1)
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
arg position:index to start replace
argType position:
 integer
arg values:items to replace
argType values:iterable
arg count:how many elements to replace, 1 by default
argType count:integer
returnType:iterable
yaql> [0, 1, 3, 4, 2].replaceMany(2, [100, 200], 2)
[0, 1, 100, 200, 2]

set

  • Returns dict with provided key set to value.

    signature:dict.set(key, value)
    callAs:method
    receiverArg dict:
     input dictionary
    argType dict:dictionary
    arg key:key
    argType key:keyword
    arg value:value to be set to input key
    argType value:any
    returnType:dictionary
    yaql> {"a" => 1, "b" => 2}.set("c", 3)
    {"a": 1, "b": 2, "c": 3}
    yaql> {"a" => 1, "b" => 2}.set("b", 3)
    {"a": 1, "b": 3}
    
  • Returns dict with replacements keys set to replacements values.

    signature:dict.set(replacements)
    callAs:method
    receiverArg dict:
     input dictionary
    argType dict:dictionary
    arg replacements:
     mapping with keys and values to be set on input dict
    argType key:dictionary
    returnType:dictionary
    yaql> {"a" => 1, "b" => 2}.set({"b" => 3, "c" => 4})
    {"a": 1, "c": 4, "b": 3}
    
  • Returns dict with args keys set to args values.

    signature:dict.set([args])
    callAs:method
    receiverArg dict:
     input dictionary
    argType dict:dictionary
    arg [args]:key-values to be set on input dict
    argType [args]:chain of mappings
    returnType:dictionary
    yaql> {"a" => 1, "b" => 2}.set("b" => 3, "c" => 4)
    {"a": 1, "c": 4, "b": 3}
    
  • Returns set initialized with args.

    signature:set([args])
    callAs:function
    arg [args]:args to build a set
    argType [args]:chain of any type
    returnType:set
    yaql> set(0, "", [1, 2])
    [0, "", [1, 2]]
    

symmetricDifference

Returns symmetric difference of left and right sets as a new set.

signature:left.symmetricDifference(right)
callAs:method
receiverArg left:
 left set
argType left:set
arg right:right set
argType right:set
returnType:set
yaql> set(0, 1, 2).symmetricDifference(set(0, 1, 3))
[2, 3]

toList

Returns list built from iterable.

signature:collection.toList()
callAs:method
receiverArg collection:
 collection to be transferred to list
argType collection:
 iterable
returnType:list
yaql> range(3).toList()
[0, 1, 2]

toSet

Returns set built from iterable.

signature:collection.toSet()
callAs:method
receiverArg collection:
 collection to build a set
argType collection:
 iterable
returnType:set
yaql> [0, 1, 1, 2].toSet()
[0, 1, 2]

union

Returns union of two sets.

signature:left.union(right)
callAs:method
receiverArg left:
 input set
argType left:set
arg right:input set
argType right:set
returnType:set
yaql> set(0, 1).union(set(1, 2))
[0, 1, 2]

values

Returns an iterator over the dictionary values.

signature:dict.values()
callAs:method
receiverArg dict:
 input dictionary
argType dict:dictionary
returnType:iterator
yaql> {"a" => 1, "b" => 2}.values()
[1, 2]

Querying data

Queries module.

accumulate

Applies selector of two arguments cumulatively to the items of collection from begin to end, so as to accumulate the collection to a list of intermediate values.

signature:collection.accumulate(selector, seed => NoValue)
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
arg selector:function of two arguments to be applied on every next pair of collection
argType selector:
 lambda
arg seed:value to use as the first for accumulating. noValue by default
argType seed:collection elements type
returnType:list
yaql> [1, 2, 3].accumulate($1+$2)
[1, 3, 6]
yaql> [1, 2, 3].accumulate($1+$2, 100)
[100, 101, 103, 106]
yaql> [].accumulate($1+$2,1)
[1]

aggregate

Applies selector of two arguments cumulatively: to the first two elements of collection, then to the result of the previous selector applying and to the third element, and so on. Returns the result of last selector applying.

signature:collection.aggregate(selector, seed => NoValue)
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
arg selector:function of two arguments to be applied on every next pair of collection
argType selector:
 lambda
arg seed:if specified, it is used as start value for accumulating and becomes a default when the collection is empty. NoValue by default
argType seed:collection elements type
returnType:collection elements type
yaql> [a,a,b,a,a].aggregate($1 + $2)
"aabaa"
yaql> [].aggregate($1 + $2, 1)
1

all

Returns true if all the elements of a collection evaluate to true. If a predicate is specified, returns true if the predicate is true for all elements in the collection.

signature:collection.all(predicate => null)
callAs:function or method
receiverArg collection:
 input collection
argType collection:
 iterable
arg predicate:lambda function to apply to every collection value. null by default, which means evaluating collections elements to boolean with no predicate
argType predicate:
 lambda
returnType:boolean
yaql> [1, [], ''].all()
false
yaql> [1, [0], 'a'].all()
true

any

Returns true if a collection is not empty. If a predicate is specified, determines whether any element of the collection satisfies the predicate.

signature:collection.any(predicate => null)
callAs:function or method
receiverArg collection:
 input collection
argType collection:
 iterable
arg predicate:lambda function to apply to every collection value. null by default, which means checking collection length
argType predicate:
 lambda
returnType:boolean
yaql> [[], 0, ''].any()
true
yaql> [[], 0, ''].any(predicate => $)
false

append

Returns a collection with appended args.

signature:collection.append([args])
callAs:function or method
receiverArg collection:
 input collection
argType collection:
 iterable
arg [args]:arguments to be appended to input collection
argType [args]:chain of any types
returnType:iterable
yaql> [1, 2, 3].append(4, 5)
[1, 2, 3, 4, 5]

concat

Returns an iterator that consequently iterates over elements of the first collection, then proceeds to the next collection and so on.

signature:collection.concat([args])
callAs:function or method
receiverArg collection:
 input collection
argType collection:
 iterable
arg [args]:iterables to be concatenated with input collection
argType [args]:chain of iterable
returnType:iterable
yaql> [1].concat([2, 3], [4, 5])
[1, 2, 3, 4, 5]

count

Returns the size of the collection.

signature:collection.count()
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
returnType:integer
yaql> [1, 2].count()
2

cycle

Makes an iterator returning elements from the collection as if it cycled.

signature:collection.cycle()
callAs:method
receiverArg collection:
 value to be cycled
argType collection:
 iterable
returnType:iterator
yaql> [1, 2].cycle().take(5)
[1, 2, 1, 2, 1]

defaultIfEmpty

Returns default value if collection is empty.

signature:collection.defaultIfEmpty(default)
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
arg default:value to be returned if collection size is 0
argType default:
 iterable
returnType:iterable
yaql> [].defaultIfEmpty([1, 2])
[1, 2]

distinct

Returns only unique members of the collection. If keySelector is specified, it is used to determine uniqueness.

signature:collection.distinct(keySelector => null)
callAs:function or method
receiverArg collection:
 input collection
argType collection:
 iterable
arg keySelector:
 specifies a function of one argument that is used to extract a comparison key from each collection element. The default value is null, which means elements are compared directly
argType keySelector:
 lambda
returnType:iterable
yaql> [1, 2, 3, 1].distinct()
[1, 2, 3]
yaql> [{'a'=> 1}, {'b'=> 2}, {'a'=> 1}].distinct()
[{"a": 1}, {"b": 2}]
yaql> [['a', 1], ['b', 2], ['c', 1], ['a', 3]].distinct($[1])
[['a', 1], ['b', 2], ['a', 3]]

enumerate

Returns an iterator over pairs (index, value), obtained from iterating over a collection.

signature:collection.enumerate(start => 0)
callAs:function or method
receiverArg collection:
 input collection
argType collection:
 iterable
arg start:a value to start with numerating first element of each pair, 0 is a default value
argType start:integer
returnType:list
yaql> ['a', 'b', 'c'].enumerate()
[[0, 'a'], [1, 'b'], [2, 'c']]
yaql> ['a', 'b', 'c'].enumerate(2)
[[2, 'a'], [3, 'b'], [4, 'c']]

first

Returns the first element of the collection. If the collection is empty, returns the default value or raises StopIteration if default is not specified.

signature:collection.first(default => NoValue)
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
arg default:value to be returned if collection is empty. NoValue by default
argType default:
 any
returnType:type of collection's elements or default value type
yaql> [3, 1, 2].first()
3

generate

Returns iterator to values beginning from initial value with every next value produced with producer applied to every previous value, while predicate is true. Represents traversal over the list where each next element is obtained by the lambda result from the previous element.

signature:generate(initial, predicate, producer, selector => null, decycle => false)
callAs:function
arg initial:value to start from
argType initial:
 any type
arg predicate:function of one argument to be applied on every new value. Stops generating if return value is false
argType predicate:
 lambda
arg producer:function of one argument to produce the next value
argType producer:
 lambda
arg selector:function of one argument to store every element in the resulted list. none by default which means to store producer result
argType selector:
 lambda
arg decycle:return only distinct values if true, false by default
argType decycle:
 boolean
returnType:list
yaql> generate(0, $ < 10, $ + 2)
[0, 2, 4, 6, 8]
yaql> generate(1, $ < 10, $ + 2, $ * 1000)
[1000, 3000, 5000, 7000, 9000]

generateMany

Returns iterator to values beginning from initial queue of values with every next value produced with producer applied to top of queue, while predicate is true. Represents tree traversal, where producer is used to get child nodes.

signature:generateMany(initial, producer, selector => null, decycle => false, depthFirst => false)
callAs:function
arg initial:value to start from
argType initial:
 any type
arg producer:function to produce the next value for queue
argType producer:
 lambda
arg selector:function of one argument to store every element in the resulted list. none by default which means to store producer result
argType selector:
 lambda
arg decycle:return only distinct values if true, false by default
argType decycle:
 boolean
arg depthFirst:if true puts produced elements to the start of queue, false by default
argType depthFirst:
 boolean
returnType:list
yaql> generateMany("1", {"1" => ["2", "3"],
                         "2"=>["4"], "3"=>["5"]
                         }.get($, []))
["1", "2", "3", "4", "5"]

indexOf

Returns the index in the collection of the first item which value is item. -1 is a return value if there is no such item

signature:collection.indexOf(item)
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
arg item:value to find in collection
argType item:any
returnType:integer
yaql> [1, 2, 3, 2].indexOf(2)
1
yaql> [1, 2, 3, 2].indexOf(102)
-1

indexWhere

Returns the index in the collection of the first item which value satisfies the predicate. -1 is a return value if there is no such item

signature:collection.indexWhere(predicate)
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
arg predicate:function of one argument to apply on every value
argType predicate:
 lambda
returnType:integer
yaql> [1, 2, 3, 2].indexWhere($ > 2)
2
yaql> [1, 2, 3, 2].indexWhere($ > 3)
-1

isIterable

Returns true if value is iterable, false otherwise.

signature:isIterable(value)
callAs:function
arg value:value to be checked
argType value:any
returnType:boolean
yaql> isIterable([])
true
yaql> isIterable(set(1,2))
true
yaql> isIterable("foo")
false
yaql> isIterable({"a" => 1})
false

join

Returns list of selector applied to those combinations of collection1 and collection2 elements, for which predicate is true.

signature:collection1.join(collection2, predicate, selector)
callAs:method
receiverArg collection1:
 input collection
argType collection1:
 iterable
arg collection2:
 other input collection
argType collection2:
 iterable
arg predicate:function of two arguments to apply to every (collection1, collection2) pair, if returned value is true the pair is passed to selector
argType predicate:
 lambda
arg selector:function of two arguments to apply to every (collection1, collection2) pair, for which predicate returned true
argType selector:
 lambda
returnType:iterable
yaql> [1,2,3,4].join([2,5,6], $1 > $2, [$1, $2])
[[3, 2], [4, 2]]

last

Returns the last element of the collection. If the collection is empty, returns the default value or raises StopIteration if default is not specified.

signature:collection.last(default => NoValue)
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
arg default:value to be returned if collection is empty. NoValue is default value.
argType default:
 any
returnType:type of collection's elements or default value type
yaql> [0, 1, 2].last()
2

lastIndexOf

Returns the index in the collection of the last item which value is item. -1 is a return value if there is no such item

signature:collection.lastIndexOf(item)
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
arg item:value to find in collection
argType item:any
returnType:integer
yaql> [1, 2, 3, 2].lastIndexOf(2)
3

lastIndexWhere

Returns the index in the collection of the last item which value satisfies the predicate. -1 is a return value if there is no such item

signature:collection.lastIndexWhere(predicate)
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
arg predicate:function of one argument to apply on every value
argType predicate:
 lambda
returnType:integer
yaql> [1, 2, 3, 2].lastIndexWhere($ = 2)
3

len

Returns the size of the collection.

signature:collection.len()
callAs:function or method
receiverArg collection:
 input collection
argType collection:
 iterable
returnType:integer
yaql> [1, 2].len()
2

limit

Returns the first count elements of a collection.

signature:collection.limit(count)
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
arg count:how many first elements of a collection to return. If count is greater or equal to collection size, return value is input collection
argType count:integer
returnType:iterable
yaql> [1, 2, 3, 4, 5].limit(4)
[1, 2, 3, 4]

max

Returns max value in collection. Considers initial if specified.

signature:collection.max(initial => NoValue)
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
arg initial:value to start with. NoValue by default
argType initial:
 collection's elements type
returnType:collection's elements type
yaql> [3, 1, 2].max()
3

memorize

Returns an iterator over collection and memorizes already iterated values. This function can be used for iterating over collection several times as it remembers elements, and when given collection (iterator) is too large to be unwrapped at once.

signature:collection.memorize()
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
returnType:iterator to collection
yaql> let(range(4)) -> $.sum() + $.len()
6
yaql> let(range(4).memorize()) -> $.sum() + $.len()
10

mergeWith

Performs a deep merge of two dictionaries.

signature:dict.mergeWith(another, listMerger => null, itemMerger => null, maxLevels => null)
callAs:method
receiverArg dict:
 input dictionary
argType dict:mapping
arg another:dictionary to merge with
argType another:
 mapping
arg listMerger:function to be applied while merging two lists. null is a default which means listMerger to be distinct(lst1 + lst2)
argType listMerger:
 lambda
arg itemMerger:function to be applied while merging two items. null is a default, which means itemMerger to be a second item for every pair.
argType itemMerger:
 lambda
arg maxLevels:number which describes how deeply merge dicts. 0 by default, which means going throughout them
argType maxLevels:
 int
returnType:mapping
yaql> {'a'=> 1, 'b'=> 2, 'c'=> [1, 2]}.mergeWith({'d'=> 5, 'b'=> 3,
                                                  'c'=> [2, 3]})
{"a": 1, "c": [1, 2, 3], "b": 3, "d": 5}
yaql> {'a'=> 1, 'b'=> 2, 'c'=> [1, 2]}.mergeWith({'d'=> 5, 'b'=> 3,
                                                  'c'=> [2, 3]},
                                                  $1+$2)
{"a": 1, "c": [1, 2, 2, 3], "b": 3, "d": 5}
yaql> {'a'=> 1, 'b'=> 2, 'c'=> [1, 2]}.mergeWith({'d'=> 5, 'b'=> 3,
                                                  'c'=> [2, 3]},
                                                  $1+$2, $1)
{"a": 1, "c": [1, 2, 2, 3], "b": 2, "d": 5}
yaql> {'a'=> 1, 'b'=> 2, 'c'=> [1, 2]}.mergeWith({'d'=> 5, 'b'=> 3,
                                                  'c'=> [2, 3]},
                                                  maxLevels => 1)
{"a": 1, "c": [2, 3], "b": 3, "d": 5}

min

Returns min value in collection. Considers initial if specified.

signature:collection.min(initial => NoValue)
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
arg initial:value to start with. NoValue by default
argType initial:
 collection's elements type
returnType:collection's elements type
yaql> [3, 1, 2].min()
1

operator .

Retrieves the value of an attribute for each element in a collection and returns a list of results.

signature:collection.attribute
callAs:operator
arg collection:input collection
argType collection:
 iterable
arg attribute:attribute to get on every collection item
argType attribute:
 keyword
returnType:list
yaql> [{"a" => 1}, {"a" => 2, "b" => 3}].a
[1, 2]

orderBy

Returns an iterator over collection elements sorted in ascending order. Selector is applied to each element of the collection to extract sorting key.

signature:collection.orderBy(selector)
callAs:method
receiverArg collection:
 collection to be ordered
argType collection:
 iterable
arg selector:specifies a function of one argument that is used to extract a comparison key from each element
argType selector:
 lambda
returnType:iterator
yaql> [[1, 'c'], [2, 'b'], [3, 'c'], [0, 'd']].orderBy($[1])
[[2, 'b'], [1, 'c'], [3, 'c'], [0, 'd']]

orderByDescending

Returns an iterator over collection elements sorted in descending order. Selector is applied to each element of the collection to extract sorting key.

signature:collection.orderByDescending(selector)
callAs:method
receiverArg collection:
 collection to be ordered
argType collection:
 iterable
arg selector:specifies a function of one argument that is used to extract a comparison key from each element
argType selector:
 lambda
returnType:iterator
yaql> [4, 2, 3, 1].orderByDescending($)
[4, 3, 2, 1]

range

  • Returns an iterator over values from 0 up to stop, not including stop, i.e. [0, stop).

    signature:range(stop)
    callAs:function
    arg stop:right bound for generated list numbers
    argType stop:integer
    returnType:iterator
    yaql> range(3)
    [0, 1, 2]
    
  • Returns an iterator over values from start up to stop, not including stop, i.e [start, stop) with step 1 if not specified.

    signature:range(start, stop, step => 1)
    callAs:function
    arg start:left bound for generated list numbers
    argType start:integer
    arg stop:right bound for generated list numbers
    argType stop:integer
    arg step:the next element in list is equal to previous + step. 1 is value by default
    argType step:integer
    returnType:iterator
    yaql> range(1, 4)
    [1, 2, 3]
    yaql> range(4, 1, -1)
    [4, 3, 2]
    

repeat

Returns collection with value repeated.

signature:value.repeat(times => -1)
callAs:method
receiverArg value:
 value to be repeated
argType value:any
arg times:how many times repeat value. -1 by default, which means that returned value will be an iterator to the endless sequence of values
argType times:int
returnType:iterable
yaql> 1.repeat(2)
[1, 1]
yaql> 1.repeat().take(3)
[1, 1, 1]

reverse

Returns reversed collection, evaluated to list.

signature:collection.reverse()
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
returnType:list
yaql> [1, 2, 3, 4].reverse()
[4, 3, 2, 1]

select

Applies the selector to every item of the collection and returns a list of results.

signature:collection.select(selector)
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
arg selector:expression for processing elements
argType selector:
 lambda
returnType:iterable
yaql> [1, 2, 3, 4, 5].select($ * $)
[1, 4, 9, 16, 25]
yaql> [{'a'=> 2}, {'a'=> 4}].select($.a)
[2, 4]

selectMany

Applies a selector to each element of the collection and returns an iterator over results. If the selector returns an iterable object, iterates over its elements instead of itself.

signature:collection.selectMany(selector)
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
arg selector:function to be applied to every collection element
argType selector:
 lambda
returnType:iterator
yaql> [0, 1, 2].selectMany($ + 2)
[2, 3, 4]
yaql> [0, [1, 2], 3].selectMany($ * 2)
[0, 1, 2, 1, 2, 6]

sequence

Returns an iterator to the sequence beginning from start with step.

signature:sequence(start => 0, step => 1)
callAs:function
arg start:start value of the sequence. 0 is value by default
argType start:integer
arg step:the next element is equal to previous + step. 1 is value by default
argType step:integer
returnType:iterator
yaql> sequence().take(5)
[0, 1, 2, 3, 4]

single

Checks that collection has only one element and returns it. If the collection is empty or has more than one element, raises StopIteration.

signature:collection.single()
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
returnType:type of collection's elements
yaql> ["abc"].single()
"abc"
yaql> [1, 2].single()
Execution exception: Collection contains more than one item

skipWhile

Skips elements from the collection as long as the predicate is true. Then returns an iterator to collection of remaining elements

signature:collection.skipWhile(predicate)
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
arg predicate:function of one argument to apply to every collection value
argType predicate:
 lambda
returnType:iterator
yaql> [1, 2, 3, 4, 5].skipWhile($ < 3)
[3, 4, 5]

slice

Returns collection divided into list of collections with max size of new parts equal to length.

signature:collection.slice(length)
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
arg length:max length of new collections
argType length:integer
returnType:list
yaql> range(1,6).slice(2)
[[1, 2], [3, 4], [5]]

sliceWhere

Splits collection into lists. Within every list predicate evaluated on its items returns the same value while predicate evaluated on the items of the adjacent lists returns different values. Returns an iterator to lists.

signature:collection.sliceWhere(predicate)
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
arg predicate:function of one argument to be applied on every element. Elements for which predicate returns true are delimiters for new list and are present in new collection as separate collections
argType predicate:
 lambda
returnType:iterator
yaql> [1, 2, 3, 4, 5, 6, 7].sliceWhere($ mod 3 = 0)
[[1, 2], [3], [4, 5], [6], [7]]

splitAt

Splits collection into two lists by index.

signature:collection.splitAt(index)
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
arg index:the index of collection to be delimiter for splitting
argType index:integer
returnType:list
yaql> [1, 2, 3, 4].splitAt(1)
[[1], [2, 3, 4]]
yaql> [1, 2, 3, 4].splitAt(0)
[[], [1, 2, 3, 4]]

splitWhere

Returns collection divided into list of collections where delimiters are values for which predicate returns true. Delimiters are deleted from result.

signature:collection.splitWhere(predicate)
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
arg predicate:function of one argument to be applied on every element. Elements for which predicate returns true are delimiters for new list
argType predicate:
 lambda
returnType:list
yaql> [1, 2, 3, 4, 5, 6, 7].splitWhere($ mod 3 = 0)
[[1, 2], [4, 5], [7]]

sum

Returns the sum of values in a collection starting from initial if specified.

signature:collection.sum(initial => NoValue)
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
arg initial:value to start sum with. NoValue by default
argType initial:
 collection's elements type
returnType:collection's elements type
yaql> [3, 1, 2].sum()
6
yaql> ['a', 'b'].sum('c')
"cab"

takeWhile

Returns elements from the collection as long as the predicate is true.

signature:collection.takeWhile(predicate)
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
arg predicate:function of one argument to apply to every collection value
argType predicate:
 lambda
returnType:iterable
yaql> [1, 2, 3, 4, 5].takeWhile($ < 4)
[1, 2, 3]

thenBy

To be used with orderBy or orderByDescending. Uses selector to extract secondary sort key (ascending) from the elements of the collection and adds it to the iterator.

signature:collection.thenBy(selector)
callAs:method
receiverArg collection:
 collection to be ordered
argType collection:
 iterable
arg selector:specifies a function of one argument that is used to extract a comparison key from each element
argType selector:
 lambda
returnType:iterator
yaql> [[3, 'c'], [2, 'b'], [1, 'c']].orderBy($[1]).thenBy($[0])
[[2, 'b'], [1, 'c'], [3, 'c']]

thenByDescending

To be used with orderBy or orderByDescending. Uses selector to extract secondary sort key (descending) from the elements of the collection and adds it to the iterator.

signature:collection.thenByDescending(selector)
callAs:method
receiverArg collection:
 collection to be ordered
argType collection:
 iterable
arg selector:specifies a function of one argument that is used to extract a comparison key from each element
argType selector:
 lambda
returnType:iterable
yaql> [[3,'c'], [2,'b'], [1,'c']].orderBy($[1]).thenByDescending($[0])
[[2, 'b'], [3, 'c'], [1, 'c']]

where

Returns only those collection elements, for which the filtering query (predicate) is true.

signature:collection.where(predicate)
callAs:method
receiverArg collection:
 collection to be filtered
argType collection:
 iterable
arg predicate:filter for collection elements
argType predicate:
 lambda
returnType:iterable
yaql> [1, 2, 3, 4, 5].where($ > 3)
[4, 5]

zip

Returns an iterator over collections, where the n-th iterable contains the n-th element from each of collections. Stops iterating as soon as any of the collections is exhausted.

signature:collection.zip([args])
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
arg [args]:collections for zipping with input collection
argType [args]:chain of collections
returnType:iterator
yaql> [1, 2, 3].zip([4, 5], [6, 7])
[[1, 4, 6], [2, 5, 7]]

zipLongest

Returns an iterator over collections, where the n-th iterable contains the n-th element from each of collections. Iterates until all the collections are not exhausted and fills lacking values with default value, which is null by default.

signature:collection.zipLongest([args], default => null)
callAs:method
receiverArg collection:
 input collection
argType collection:
 iterable
arg [args]:collections for zipping with input collection
argType [args]:chain of collections
arg default:default value for lacking values, can be passed only as keyword argument. null by default
argType default:
 any type
returnType:iterator
yaql> [1, 2, 3].zipLongest([4, 5])
[[1, 4], [2, 5], [3, null]]
yaql> [1, 2, 3].zipLongest([4, 5], default => 100)
[[1, 4], [2, 5], [3, 100]]

Branching functions

The module describes branching functions such as switch, case, and others.

coalesce

Returns the first predicate which evaluates to non-null value. Returns null if no arguments are provided or if all of them are null.

signature:coalesce([args])
callAs:function
arg [args]:input arguments
argType [args]:chain of any types
returnType:any
yaql> coalesce(null)
null
yaql> coalesce(null, [1, 2, 3][0], "abc")
1
yaql> coalesce(null, false, 1)
false

examine

Evaluates predicates one by one and casts the evaluation results to boolean. Returns an iterator to collection of casted results. The actual evaluation is done lazily as the iterator advances, not during the function call.

signature:examine([args])
callAs:function
arg [args]:predicates to be evaluated
argType [args]:chain of predicates functions
returnType:iterator
yaql> examine("ab" > "abc", "ab" <= "abc", "ab" < "abc")
[false, true, true]

selectAllCases

Evaluates input predicates and returns an iterator to collection of zero-based indexes of predicates which were evaluated to true. The actual evaluation is done lazily as the iterator advances, not during the function call.

signature:selectAllCases([args])
callAs:function
arg [args]:predicates to check for true
argType [args]:chain of predicates
returnType:iterator
yaql> selectAllCases("ab" > "abc", "ab" <= "abc", "ab" < "abc")
[1, 2]

selectCase

Returns a zero-based index of the first predicate evaluated to true. If there is no such predicate, returns the count of arguments. All the predicates after the first one which was evaluated to true remain unevaluated.

signature:selectCase([args])
callAs:function
arg [args]:predicates to check for true
argType [args]:chain of predicates
returnType:integer
yaql> selectCase("ab" > "abc", "ab" >= "abc", "ab" < "abc")
2

switch

Returns the value of the first argument for which the key evaluates to true, null if there is no such arg.

signature:switch([args])
callAs:function
arg [args]:mappings with keys to check for true and appropriate values
argType [args]:chain of mapping
returnType:any (types of values of args)
yaql> switch("ab" > "abc" => 1, "ab" >= "abc" => 2, "ab" < "abc" => 3)
3

switchCase

Returns evaluated case-th argument. If case is less than 0 or greater than the amount of predicates, returns evaluated last argument. Returns null if no args are provided.

signature:case.switchCase([args])
callAs:method
recieverArg case:
 index of predicate to be evaluated
argType case:integer
arg [args]:input predicates
argType [args]:chain of any types
returnType:any
yaql> 1.switchCase('a', 1 + 1, [])
2
yaql> 2.switchCase('a', 1 + 1, [])
[]
yaql> 3.switchCase('a', 1 + 1, [])
[]
yaql> let(1) -> selectCase($ < 0, $ = 0).switchCase("less than 0",
                                                    "equal to 0",
                                                    "greater than 0")
"greater than 0"

String manipulations

The module describes which operations can be done with strings in YAQL.

characters

Returns a list of all distinct items of specified types.

signature:characters(digits => false, hexdigits => false, asciiLowercase => false, asciiUppercase => false, asciiLetters => false, letters => false, octdigits => false, punctuation => false, printable => false, lowercase => false, uppercase => false, whitespace => false)
callAs:function
arg digits:include digits in output list if true, false by default
argType digits:boolean
arg hexdigits:include hexademical digits in output list if true, false by default
argType hexdigits:
 boolean
arg asciiLowercase:
 include ASCII lowercase letters in output list if true, false by default
argType asciiLowercase:
 boolean
arg asciiUppercase:
 include ASCII uppercase letters in output list if true, false by default
argType asciiUppercase:
 boolean
arg asciiLetters:
 include both ASCII lowercase and uppercase letters in output list if true, false by default
argType asciiLetters:
 boolean
arg letters:include both lowercase and uppercase letters in output list if true, false by default
argType letters:
 boolean
arg octdigits:include digits from 0 to 7 in output list if true, false by default
argType octdigits:
 boolean
arg punctuation:
 include ASCII characters, which are considered punctuation, in output list if true, false by default
argType punctuation:
 boolean
arg printable:include digits, letters, punctuation, and whitespace in output list if true, false by default
argType printable:
 boolean
arg lowercase:include lowercase letters in output list if true, false by default
argType lowercase:
 boolean
arg uppercase:include uppercase letters in output list if true, false by default
argType uppercase:
 boolean
arg whitespace:include all characters that are considered whitespace in output list if true, false by default
argType whitespace:
 boolean
returnType:list
yaql> characters(digits => true)
["1", "0", "3", "2", "5", "4", "7", "6", "9", "8"]

concat

Returns concatenated args.

signature:concat([args])
callAs:function
arg [args]:values to be joined
argType [args]:string
returnType:string
yaql> concat("abc", "de", "f")
"abcdef"

endsWith

Returns true if a string ends with any of given args.

signature:string.endsWith([args])
callAs:method
receiverArg string:
 input string
argType string:string
arg [args]:chain of strings to check input string with
argType [args]:strings
returnType:boolean
yaql> "abcd".endsWith("cd", "xx")
true
yaql> "abcd".endsWith("yy", "xx", "zz")
false

format

Returns a string formatted with positional and keyword arguments.

signature:string.format([args], {kwargs})
callAs:function or method
receiverArg string:
 input string for formatting. Can be passed only as first positional argument if used as a function. Can contain literal text or replacement fields marked by braces {}. Every replacement field should contain either the numeric index of a positional argument or the name of a keyword argument
argType string:string
arg [args]:values for replacements for numeric markers
argType [args]:chain of strings
arg {kwargs}:values for keyword replacements
argType {kwargs}:
 chain of key-value arguments, where values are strings
returnValue:string
yaql> "abc{0}ab{1}abc".format(" ", ",")
"abc ab,abc"
yaql> "abc{foo}ab{bar}abc".format(foo => " ", bar => ",")
"abc ab,abc"
yaql> format("abc{0}ab{foo}abc", ' ', foo => ",")
"abc ab,abc"

hex

Returns a string with hexadecimal representation of num.

signature:hex(num)
callAs:function
arg num:input number to be converted to hexademical
argType num:number
returnType:string
yaql> hex(256)
"0x100"

indexOf

  • Returns an index of first occurrence sub in string beginning from start. -1 is a return value if there is no any occurrence.

    signature:string.indexOf(sub, start => 0)
    callAs:method
    receiverArg string:
     input string
    argType string:string
    arg sub:substring to find in string
    argType sub:string
    arg start:index to start search with, 0 by default
    argType start:integer
    returnType:integer
    yaql> "cabcdab".indexOf("ab")
    1
    yaql> "cabcdab".indexOf("ab", 2)
    5
    yaql> "cabcdab".indexOf("ab", 6)
    -1
    
  • Returns an index of first occurrence sub in string beginning from start ending with start+length. -1 is a return value if there is no any occurrence.

    signature:string.indexOf(sub, start, length)
    callAs:method
    receiverArg string:
     input string
    argType string:string
    arg sub:substring to find in string
    argType sub:string
    arg start:index to start search with, 0 by default
    argType start:integer
    arg length:length of string to find substring in
    argType length:integer
    returnType:integer
    yaql> "cabcdab".indexOf("bc", 2, 2)
    2
    

isEmpty

Returns true if the string with removed leading and trailing chars is empty.

signature:string.isEmpty(trimSpaces => true, chars => null)
callAs:function or method
receiverArg string:
 value to be checked for emptiness after trim
argType string:string
arg trimSpaces:true by default, which means string to be trimmed with chars. false means checking whether input string is empty
argType trimSpaces:
 boolean
arg chars:symbols for trimming. null by default, which means trim is done with whitespace characters
argType chars:string
returnType:boolean
yaql> "abaab".isEmpty(chars=>"ab")
true
yaql> "aba".isEmpty(chars=>"a")
false

isString

Returns true if arg is a string.

signature:isString(arg)
callAs:function
arg arg:input value
argType arg:any
returnType:boolean
yaql> isString("ab")
true
yaql> isString(1)
false

join

  • Returns a string with sequence elements joined by the separator.

    signature:sequence.join(separator)
    callAs:method
    receiverArg sequence:
     chain of values to be joined
    argType sequence:
     sequence of strings
    arg separator:value to be placed between joined pairs
    argType separator:
     string
    returnType:string
    yaql> ["abc", "de", "f"].join("")
    "abcdef"
    yaql> ["abc", "de", "f"].join("|")
    "abc|de|f"
    
  • Returns a string with sequence elements joined by the separator.

    signature:separator.join(sequence)
    callAs:method
    receiverArg separator:
     value to be placed between joined pairs
    argType separator:
     string
    arg sequence:chain of values to be joined
    argType sequence:
     sequence of strings
    returnType:string
    yaql> "|".join(["abc", "de", "f"])
    "abc|de|f"
    

lastIndexOf

  • Returns an index of last occurrence sub in string beginning from start. -1 is a return value if there is no any occurrence.

    signature:string.lastIndexOf(sub, start => 0)
    callAs:method
    receiverArg string:
     input string
    argType string:string
    arg sub:substring to find in string
    argType sub:string
    arg start:index to start search with, 0 by default
    argType start:integer
    returnType:integer
    yaql> "cabcdab".lastIndexOf("ab")
    5
    
  • Returns an index of last occurrence sub in string beginning from start ending with start+length. -1 is a return value if there is no any occurrence.

    signature:string.lastIndexOf(sub, start, length)
    callAs:method
    receiverArg string:
     input string
    argType string:string
    arg sub:substring to find in string
    argType sub:string
    arg start:index to start search with, 0 by default
    argType start:integer
    arg length:length of string to find substring in
    argType length:integer
    returnType:integer
    yaql> "cabcdbc".lastIndexOf("bc", 2, 5)
    5
    

len

Returns size of the string.

signature:string.len()
callAs:function or method
receiverArg string:
 input string
argType string:string
returnType:integer
yaql> "abc".len()
3

norm

Returns a string with the leading and trailing chars removed. If the resulting string is empty, returns null.

signature:string.norm(chars => null)
callAs:function or method
receiverArg string:
 value to be cut with specified chars
argType string:string
arg chars:symbols to be removed from the start and the end of input string. null by default, which means norm is done with whitespace characters
argType chars:string
returnType:string
yaql> "  abcd ".norm()
"abcd"
yaql> "aaaa".norm("a")
null

operator *

  • Returns string repeated count times.

    signature:left * right
    callAs:operator
    arg left:left operand, how many times repeat input string
    argType left:integer
    arg right:right operator
    argType right:string
    returnType:string
    yaql> 2 * "ab"
    "abab"
    
  • Returns string repeated count times.

    signature:left * right
    callAs:operator
    arg left:left operand
    argType left:string
    arg right:right operator, how many times repeat input string
    argType right:integer
    returnType:string
    yaql> "ab" * 2
    "abab"
    

operator <

Returns true if the left operand is strictly less than the right, ordering lexicographically, otherwise false.

signature:left < right
callAs:operator
arg left:left operand
argType left:string
arg right:right operand
argType right:string
returnType:boolean
yaql> "ab" < "abc"
true
yaql> "abb" < "abc"
true
yaql> "abc" < "abc"
false

operator <=

Returns true if the left operand is less or equal to the right, ordering lexicographically, otherwise false.

signature:left <= right
callAs:operator
arg left:left operand
argType left:string
arg right:right operand
argType right:string
returnType:boolean
yaql> "ab" <= "abc"
true
yaql> "abc" <= "abc"
true

operator >

Returns true if the left operand is strictly greater than the right, ordering lexicographically, otherwise false.

signature:left > right
callAs:operator
arg left:left operand
argType left:string
arg right:right operand
argType right:string
returnType:boolean
yaql> "abc" > "ab"
true
yaql> "abc" > "abb"
true
yaql> "abc" > "abc"
false

operator >=

Returns true if the left operand is greater or equal to the right, ordering lexicographically, otherwise false.

signature:left >= right
callAs:operator
arg left:left operand
argType left:string
arg right:right operand
argType right:string
returnType:boolean
yaql> "abc" >= "ab"
true
yaql> "abc" >= "abc"
true

operator in

Returns true if there is at least one occurrence of left string in right.

signature:left in right
callAs:operator
arg left:left operand, which occurrence is checked
argType left:string
arg right:right operand
argType right:string
returnType:boolean
yaql> "ab" in "abc"
true
yaql> "ab" in "acb"
false

replace

  • Returns a string with first count occurrences of old replaced with new.

    signature:string.replace(old, new, count => -1)
    callAs:method
    receiverArg string:
     input string
    argType string:string
    arg old:value to be replaced
    argType old:string
    arg new:replacement for old value
    argType new:string
    arg count:how many first replacements to do. -1 by default, which means to do all replacements
    argType count:integer
    returnType:string
    yaql> "abaab".replace("ab", "cd")
    "cdacd"
    
  • Returns a string with all occurrences of replacements' keys replaced with corresponding replacements' values. If count is specified, only the first count occurrences of every key are replaced.

    signature:string.replace(replacements, count => -1)
    callAs:method
    receiverArg string:
     input string
    argType string:string
    arg replacements:
     dict of replacements in format {old => new ...}
    argType replacements:
     mapping
    arg count:how many first occurrences of every key are replaced. -1 by default, which means to do all replacements
    argType count:integer
    returnType:string
    yaql> "abc ab abc".replace({abc => xx, ab => yy})
    "xx yy xx"
    yaql> "abc ab abc".replace({ab => yy, abc => xx})
    "yyc yy yyc"
    yaql> "abc ab abc".replace({ab => yy, abc => xx}, 1)
    "yyc ab xx"
    

rightSplit

Returns a list of tokens in the string, using separator as the delimiter. If maxSplits is given then at most maxSplits splits are done - the rightmost ones.

signature:string.rightSplit(separator => null, maxSplits => -1)
callAs:method
receiverArg string:
 value to be splitted
argType string:string
arg separator:delimiter for splitting. null by default, which means splitting with whitespace characters
argType separator:
 string
arg maxSplits:number of splits to be done - the rightmost ones. -1 by default, which means all possible splits are done
argType maxSplits:
 integer
returnType:list
yaql> "abc     de  f".rightSplit()
["abc", "de", "f"]
yaql> "abc     de  f".rightSplit(maxSplits => 1)
["abc     de", "f"]

split

Returns a list of tokens in the string, using separator as the delimiter.

signature:string.split(separator => null, maxSplits => -1)
callAs:method
receiverArg string:
 value to be splitted
argType string:string
arg separator:delimiter for splitting. null by default, which means splitting with whitespace characters
argType separator:
 string
arg maxSplits:maximum number of splittings. -1 by default, which means all possible splits are done
argType maxSplits:
 integer
returnType:list
yaql> "abc     de  f".split()
["abc", "de", "f"]
yaql> "abc     de  f".split(maxSplits => 1)
["abc", "de  f"]
yaql> "abcde".split("c")
["ab", "de"]

startsWith

Returns true if a string starts with any of given args.

signature:string.startsWith([args])
callAs:method
receiverArg string:
 input string
argType string:string
arg [args]:chain of strings to check input string with
argType [args]:strings
returnType:boolean
yaql> "abcd".startsWith("ab", "xx")
true
yaql> "abcd".startsWith("yy", "xx", "zz")
false

str

Returns a string representation of the value.

signature:str(value)
callAs:function
arg value:value to be evaluated to string
argType value:any
returnType:string
yaql> str(["abc", "de"])
"(u'abc', u'd')"
yaql> str(123)
"123"

substring

Returns a substring beginning from start index ending with start+end index.

signature:string.substring(start, length => -1)
callAs:method
receiverArg string:
 input string
argType string:string
arg start:index for substring to start with
argType start:integer
arg length:length of substring. -1 by default, which means end of substring to be equal to the end of input string
argType length:integer
returnType:string
yaql> "abcd".substring(1)
"bcd"
yaql> "abcd".substring(1, 2)
"bc"

toCharArray

Converts a string to array of one character strings.

signature:string.toCharArray()
callAs:method
receiverArg string:
 input string
argType string:string
returnType:list
yaql> "abc de".toCharArray()
["a", "b", "c", " ", "d", "e"]

toLower

Returns a string with all case-based characters lowercase.

signature:string.toLower()
callAs:method
receiverArg string:
 value to lowercase
argType string:string
returnType:string
yaql> "AB1c".toLower()
"ab1c"

toUpper

Returns a string with all case-based characters uppercase.

signature:string.toUpper()
callAs:method
receiverArg string:
 value to uppercase
argType string:string
returnType:string
yaql> "aB1c".toUpper()
"AB1C"

trim

Returns a string with the leading and trailing chars removed.

signature:string.trim(chars => null)
callAs:method
receiverArg string:
 value to be trimmed
argType string:string
arg chars:symbols to be removed from input string. null by default, which means trim is done with whitespace characters
argType chars:string
returnType:string
yaql> "  abcd ".trim()
"abcd"
yaql> "aababa".trim("a")
"bab"

trimLeft

Returns a string with the leading chars removed.

signature:string.trimLeft(chars => null)
callAs:method
receiverArg string:
 value to be trimmed
argType string:string
arg chars:symbols to be removed from start of input string. null by default, which means trim is done with whitespace characters
argType chars:string
returnType:string
yaql> "  abcd ".trimLeft()
"abcd "
yaql> "aababa".trimLeft("a")
"baba"

trimRight

Returns a string with the trailing chars removed.

signature:string.trimRight(chars => null)
callAs:method
receiverArg string:
 value to be trimmed
argType string:string
arg chars:symbols to be removed from end of input string. null by default, which means trim is done with whitespace characters
argType chars:string
returnType:string
yaql> "  abcd ".trimRight()
"  abcd"
yaql> "aababa".trimRight("a")
"aabab"

Math functions

The Math module describes implemented math operations on numbers.

abs

Returns the absolute value of a number.

signature:abs(op)
callAs:function
arg op:input value
argType op:number
returnType:number
yaql> abs(-2)
2

bitwiseAnd

Returns applied "bitwise and" to left and right integers. Each bit of the output is 1 if the corresponding bit of left AND right is 1, otherwise 0.

signature:bitwiseAnd(left, right)
callAs:function
arg left:left value
argType left:integer
arg right:right value
argType right:integer
returnType:integer
yaql> bitwiseAnd(6, 12)
4

bitwiseNot

Returns an integer where each bit is a reversed corresponding bit of arg.

signature:bitwiseNot(arg)
callAs:function
arg arg:input value
argType arg:integer
returnType:integer
yaql> bitwiseNot(6)
-7

bitwiseOr

Returns applied "bitwise or" to left and right numbers. Each bit of the output is 1 if the corresponding bit of left OR right is 1, otherwise 0.

signature:bitwiseOr(left, right)
callAs:function
arg left:left value
argType left:integer
arg right:right value
argType right:integer
returnType:integer
yaql> bitwiseOr(6, 12)
14

bitwiseXor

Returns applied "bitwise exclusive or" to left and right numbers. Each bit of the output is equal to the sum of corresponding left and right bits mod 2.

signature:bitwiseXor(left, right)
callAs:function
arg left:left value
argType left:integer
arg right:right value
argType right:integer
returnType:integer
yaql> bitwiseXor(6, 12)
10

float

Returns a floating number built from number, string or null value.

signature:float(value)
callAs:function
arg value:input value
argType value:number, string or null
returnType:float
yaql> float("2.2")
2.2
yaql> float(12)
12.0
yaql> float(null)
0.0

int

Returns an integer built from number, string or null value.

signature:int(value)
callAs:function
arg value:input value
argType value:number, string or null
returnType:integer
yaql> int("2")
2
yaql> int(12.999)
12
yaql> int(null)
0

isInteger

Returns true if value is an integer number, otherwise false.

signature:isInteger(value)
callAs:function
arg value:input value
argType value:any
returnType:boolean
yaql> isInteger(12.0)
false
yaql> isInteger(12)
true

isNumber

Returns true if value is an integer or floating number, otherwise false.

signature:isNumber(value)
callAs:function
arg value:input value
argType value:any
returnType:boolean
yaql> isNumber(12.0)
true
yaql> isNumber(12)
true

max

Returns max from a and b.

signature:max(a, b)
callAs:function
arg a:input value
argType a:number
arg b:input value
argType b:number
returnType:number
yaql> max(8, 2)
8

min

Returns min from a and b.

signature:min(a, b)
callAs:function
arg a:input value
argType a:number
arg b:input value
argType b:number
returnType:number
yaql> min(8, 2)
2

operator *

Returns left multiplied by right.

signature:left * right
callAs:operator
arg left:left operand
argType left:number
arg right:right operand
argType right:number
returnType:number
yaql> 3 * 2.5
7.5

operator +

Returns the sum of left and right operands.

signature:left + right
callAs:operator
arg left:left operand
argType left:number
arg right:right operand
argType right:number
returnType:number
yaql> 3 + 2
5

operator -

Returns the difference between left and right.

signature:left - right
callAs:operator
arg left:left operand
argType left:number
arg right:right operand
argType right:number
returnType:number
yaql> 3 - 2
1

operator /

Returns left divided by right.

signature:left / right
callAs:operator
arg left:left operand
argType left:number
arg right:right operand
argType right:number
returnType:number
yaql> 3 / 2
1
yaql> 3.0 / 2
1.5

operator <

Returns true if left is strictly less than right, false otherwise.

signature:left < right
callAs:operator
arg left:left operand
argType left:number
arg right:right operand
argType left:number
returnType:boolean
yaql> 3 < 2
false

operator <=

Returns true if left is less or equal to right, false otherwise.

signature:left <= right
callAs:operator
arg left:left operand
argType left:number
arg right:right operand
argType left:number
returnType:boolean
yaql> 3 <= 3
true

operator >

Returns true if left is strictly greater than right, false otherwise.

signature:left > right
callAs:operator
arg left:left operand
argType left:number
arg right:right operand
argType left:number
returnType:boolean
yaql> 3 > 2
true

operator >=

Returns true if left is greater or equal to right, false otherwise.

signature:left >= right
callAs:operator
arg left:left operand
argType left:number
arg right:right operand
argType left:number
returnType:boolean
yaql> 3 >= 3
true

operator mod

Returns left modulo right.

signature:left mod right
callAs:operator
arg left:left operand
argType left:number
arg right:right operand
argType right:number
returnType:number
yaql> 3 mod 2
1

operator unary +

Returns +op.

signature:+op
callAs:operator
arg op:operand
argType op:number
returnType:number
yaql> +2
2

operator unary -

Returns -op.

signature:-op
callAs:operator
arg op:operand
argType op:number
returnType:number
yaql> -2
-2

pow

Returns a to the power b modulo c.

signature:pow(a, b, c => null)
callAs:function
arg a:input value
argType a:number
arg b:power
argType b:number
arg c:modulo. null by default, which means no modulo is done after power.
argType c:integer
returnType:number
yaql> pow(3, 2)
9
yaql> pow(3, 2, 5)
4

random

  • Returns the next random floating number from [0.0, 1.0).

    signature:random()
    callAs:function
    returnType:float
    yaql> random()
    0.6039529924951869
    
  • Returns the next random integer from [a, b].

    signature:random(from, to)
    callAs:function
    arg from:left value for generating random number
    argType from:integer
    arg to:right value for generating random number
    argType to:integer
    returnType:integer
    yaql> random(1, 2)
    2
    yaql> random(1, 2)
    1
    

round

Returns a floating number rounded to ndigits after the decimal point.

signature:round(number, ndigits => 0)
callAs:function
arg number:input value
argType number:number
arg ndigits:with how many digits after decimal point to round. 0 by default
argType ndigits:
 integer
returnType:number
yaql> round(12.52)
13
yaql> round(12.52, 1)
12.5

shiftBitsLeft

Shifts the bits of value left by the number of bits bitsNumber.

signature:shiftBitsLeft(value, bitsNumber)
callAs:function
arg value:given value
argType value:integer
arg bitsNumber:number of bits
argType right:integer
returnType:integer
yaql> shiftBitsLeft(8, 2)
32

shiftBitsRight

Shifts the bits of value right by the number of bits bitsNumber.

signature:shiftBitsRight(value, bitsNumber)
callAs:function
arg value:given value
argType value:integer
arg bitsNumber:number of bits
argType right:integer
returnType:integer
yaql> shiftBitsRight(8, 2)
2

sign

Returns 1 if num > 0; 0 if num = 0; -1 if num < 0.

signature:sign(num)
callAs:function
arg num:input value
argType num:number
returnType:integer (-1, 0 or 1)
yaql> sign(2)
1

Regex functions

The module contains functions for regular expressions.

escapeRegex

Returns string with all the characters except ASCII letters, numbers, and '_' escaped.

signature:escapeRegex(string)
callAs:function
arg string:string to backslash all non-alphanumerics
argType string:string
returnType:string
yaql> escapeRegex('a.')
"a\."

isRegex

Returns true if value is a regex object.

signature:isRegex(value)
callAs:function
arg value:string to backslash all non-alphanumerics
argType value:any
returnType:boolean
yaql> isRegex(regex("a.c"))
true
yaql> isRegex(regex("a.c").matches("abc"))
false

matches

  • Returns true if string matches regexp.

    signature:regexp.matches(string)
    callAs:method
    receiverArg regexp:
     regex pattern
    argType regexp:regex object
    arg string:string to find match in
    argType string:string
    returnType:boolean
    yaql> regex("a.c").matches("abc")
    true
    
  • Returns true if string matches regexp, false otherwise.

    signature:string.matches(regexp)
    callAs:method
    receiverArg string:
     string to find match in
    argType string:string
    arg regexp:regex pattern
    argType regexp:regex object
    returnType:boolean
    yaql> "abc".matches("a.c")
    true
    

operator !~

  • Returns true if left doesn't match right, false otherwise.

    signature:left !~ right
    callAs:operator
    arg left:string to find match in
    argType left:string
    arg right:regex pattern
    argType right:regex
    returnType:boolean
    yaql> "acb" !~ regex("a.c")
    true
    yaql> "abc" !~ regex("a.c")
    false
    
  • Returns true if left doesn't match right, false otherwise.

    signature:left !~ right
    callAs:operator
    arg left:string to find match in
    argType left:string
    arg right:regex pattern
    argType right:regex object
    returnType:boolean
    yaql> "acb" !~ regex("a.c")
    true
    yaql> "abc" !~ regex("a.c")
    false
    

operator =~

  • Returns true if left matches right, false otherwise.

    signature:left =~ right
    callAs:operator
    arg left:string to find match in
    argType left:string
    arg right:regex pattern
    argType right:regex
    returnType:boolean
    yaql> "abc" =~ regex("a.c")
    true
    
  • Returns true if left matches right, false otherwise.

    signature:left =~ right
    callAs:operator
    arg left:string to find match in
    argType left:string
    arg right:regex pattern
    argType right:string
    returnType:boolean
    yaql> "abc" =~ "a.c"
    true
    

regex

Returns regular expression object with provided flags. Can be used for matching using matches method.

signature:regex(pattern,ignoreCase => false, multiLine => false, dotAll => false)
callAs:function
arg pattern:regular expression pattern to be compiled to regex object
argType pattern:
 string
arg ignoreCase:true makes performing case-insensitive matching.
argType ignoreCase:
 boolean
arg multiLine:true makes character '^' to match at the beginning of the string and at the beginning of each line, the character '$' to match at the end of the string and at the end of each line. false means '^' to match only at the beginning of the string, '$' only at the end of the string.
argType multiLine:
 boolean
arg dotAll:true makes the '.' special character to match any character (including a newline). false makes '.' to match anything except a newline.
argType dotAll:boolean
returnType:regex object
yaql> regex("a.c").matches("abc")
true
yaql> regex("A.c").matches("abc")
false
yaql> regex("A.c", ignoreCase => true).matches("abc")
true

replace

  • Returns the string obtained by replacing the leftmost non-overlapping matches of regexp in string by the replacement repl, where the latter is only string-type.

    signature:regexp.replace(string, repl, count => 0)
    callAs:method
    receiverArg regexp:
     regex pattern
    argType regexp:regex object
    arg string:string to make replace in
    argType string:string
    arg repl:string to replace matches of regexp
    argType repl:string
    arg count:how many first replaces to do. 0 by default, which means to do all replacements
    argType count:integer
    returnType:string
    yaql> regex("a.").replace("abcadc", "xx")
    "xxcxxc"
    yaql> regex("a.").replace("abcadc", "xx", count => 1)
    "xxcadc"
    
  • Returns the string obtained by replacing the leftmost non-overlapping matches of regexp in string by the replacement repl, where the latter is only string-type.

    signature:string.replace(regexp, repl, count => 0)
    callAs:method
    receiverArg string:
     string to make replace in
    argType string:string
    arg regexp:regex pattern
    argType regexp:regex object
    arg repl:string to replace matches of regexp
    argType repl:string
    arg count:how many first replaces to do. 0 by default, which means to do all replacements
    argType count:integer
    returnType:string
    yaql> "abcadc".replace(regex("a."), "xx")
    "xxcxxc"
    

replaceBy

  • Returns the string obtained by replacing the leftmost non-overlapping matches of regexp in string by repl, where the latter is an expression to get replacements by obtained matches.

    signature:regexp.replaceBy(string, repl, count => 0)
    callAs:method
    receiverArg regexp:
     regex pattern
    argType regexp:regex object
    arg string:string to make replace in
    argType string:string
    arg repl:lambda function which returns string to make replacements according to input matches
    argType repl:lambda
    arg count:how many first replaces to do. 0 by default, which means to do all replacements
    argType count:integer
    returnType:string
    yaql> regex("a.c").replaceBy("abcadc", switch($.value = "abc" => xx,
                                                  $.value = "adc" => yy))
    "xxyy"
    
  • Replaces matches of regexp in string with values provided by the supplied function.

    signature:string.replaceBy(regexp, repl, count => 0)
    callAs:method
    receiverArg string:
     string to make replace in
    argType string:string
    arg regexp:regex pattern
    argType regexp:regex object
    arg repl:lambda function which returns string to make replacements according to input matches
    argType repl:lambda
    arg count:how many first replaces to do. 0 by default, which means to do all replacements
    argType count:integer
    returnType:string
    yaql> "abcadc".replaceBy(regex("a.c"), switch($.value = "abc" => xx,
                                                  $.value = "adc" => yy))
    "xxyy"
    

searchAll

Search all substrings which matches regexp. Returns list of applied to dictionary {"start" => ..., "end" => ..., "value" => ...} selector, where appropriate values describe start of every substring, its end and itself. By default, if no selector is specified, returns only list of substrings.

signature:regexp.searchAll(string, selector => null)
callAs:method
receiverArg regexp:
 regex pattern
argType regexp:regex object
arg string:string to find match in
argType string:string
arg selector:lambda function to be applied to resulted dictionary of every substring with keys 'start', 'end', 'value'. null by default, which means to return only list of substrings.
argType selector:
 lambda
returnType:list
yaql> regex("a.c").searchAll("abcadc")
["abc", "adc"]
yaql> regex("a.c").searchAll("abcadc", $)
[
    {
        "start": 0,
        "end": 3,
        "value": "abc"
    },
    {
        "start": 3,
        "end": 6,
        "value": "adc"
    }
]
name:searchAll

split

  • Splits string by regexp matches and returns list of strings.

    signature:regexp.split(string, maxSplit => 0)
    callAs:method
    receiverArg regexp:
     regex pattern
    argType regexp:regex object
    arg string:string to be splitted
    argType string:string
    arg maxSplit:how many first splits to do. 0 by default, which means to split by all matches
    argType maxSplit:
     integer
    returnType:list
    yaql> regex("a.").split("abcadc")
    ["", "c", "c"]
    yaql> regex("a.").split("abcadc", maxSplit => 1)
    ["", "cadc"]
    
  • Splits string by regexp matches and returns list of strings.

    signature:string.split(regexp, maxSplit => 0)
    callAs:method
    receiverArg string:
     string to be splitted
    argType string:string
    arg regexp:regex pattern
    argType regexp:regex object
    arg maxSplit:how many first splits to do. 0 by default, which means to split by all matches
    argType maxSplit:
     integer
    returnType:list
    yaql> "abcadc".split(regex("a."))
    ["", "c", "c"]
    yaql> "abcadc".split(regex("a."), maxSplit => 1)
    ["", "cadc"]
    

DateTime functions

The module describes which operations can be done with datetime objects.

datetime

  • Returns datetime object built on year, month, day, hour, minute, second, microsecond, offset.

    signature:datetime(year, month, day, hour => 0, minute => 0, second => 0, microsecond => 0, offset => timespan(0))
    callAs:function
    arg year:number of years in datetime
    argType year:integer between 1 and 9999 inclusive
    arg month:number of months in datetime
    argType month:integer between 1 and 12 inclusive
    arg day:number of days in datetime
    argType day:integer between 1 and number of days in given month
    arg hour:number of hours in datetime, 0 by default
    argType hour:integer between 0 and 23 inclusive
    arg minute:number of minutes in datetime, 0 by default
    argType minute:integer between 0 and 59 inclusive
    arg second:number of seconds in datetime, 0 by default
    argType second:integer between 0 and 59 inclusive
    arg microsecond:
     number of microseconds in datetime, 0 by default
    argType microsecond:
     integer between 0 and 1000000-1
    arg offset:datetime offset in microsecond resolution, needed for tzinfo, timespan(0) by default
    argType offset:timespan type
    returnType:datetime object
    yaql> let(datetime(2015, 9, 29)) -> [$.year, $.month, $.day]
    [2015, 9, 29]
    
  • Returns datetime object built by string parsed with format.

    signature:datetime(string, format => null)
    callAs:function
    arg string:string representing datetime
    argType string:string
    arg format:format for parsing input string which should be supported with C99 standard of format codes. null by default, which means parsing with Python dateutil.parser usage
    argType format:string
    returnType:datetime object
    yaql> let(datetime("29.8?2015")) -> [$.year, $.month, $.day]
    [2015, 8, 29]
    yaql> let(datetime("29.8?2015", "%d.%m?%Y"))->[$.year, $.month, $.day]
    [2015, 8, 29]
    
  • Returns datetime object built by timestamp.

    signature:datetime(timestamp, offset => timespan(0))
    callAs:function
    arg timestamp:timespan object to represent datetime
    argType timestamp:
     number
    arg offset:datetime offset in microsecond resolution, needed for tzinfo, timespan(0) by default
    argType offset:timespan type
    returnType:datetime object
    yaql> let(datetime(1256953732)) -> [$.year, $.month, $.day]
    [2009, 10, 31]
    

format

Returns a string representing datetime, controlled by a format string.

signature:dt.format(format)
callAs:method
receiverArg dt:input datetime object
argType dt:datetime object
arg format:format string
argType format:string
returnType:string
yaql> now().format("%A, %d. %B %Y %I:%M%p")
"Tuesday, 19. July 2016 08:49AM"

isDatetime

Returns true if value is datetime object, false otherwise.

signature:isDatetime(value)
callAs:function
arg value:input value
argType value:any
returnType:boolean
yaql> isDatetime(now())
true
yaql> isDatetime(datetime(2010, 10, 10))
true

isTimespan

Returns true if value is timespan object, false otherwise.

signature:isTimespan(value)
callAs:function
arg value:input value
argType value:any
returnType:boolean
yaql> isTimespan(now())
false
yaql> isTimespan(timespan())
true

localtz

Returns local time zone in timespan object.

signature:localtz()
callAs:function
returnType:timespan object
yaql> localtz().hours
3.0

now

Returns the current local date and time.

signature:now(offset => timespan(0))
callAs:function
arg offset:datetime offset in microsecond resolution, needed for tzinfo, timespan(0) by default
argType offset:timespan type
returnType:datetime
yaql> let(now()) -> [$.year, $.month, $.day]
[2016, 7, 18]
yaql> now(offset=>localtz()).hour - now().hour
3

operator *

  • Returns timespan object built on number multiplied by timespan.

    signature:left * right
    callAs:operator
    arg left:number to multiply timespan
    argType left:number
    arg right:timespan object
    argType right:timespan object
    returnType:timespan
    yaql> let(2 * timespan(hours => 24)) -> $.hours
    48.0
    
  • Returns timespan object built on timespan multiplied by number.

    signature:left * right
    callAs:operator
    arg left:timespan object
    argType left:timespan object
    arg right:number to multiply timespan
    argType right:number
    returnType:timespan
    yaql> let(timespan(hours => 24) * 2) -> $.hours
    48.0
    

operator +

  • Returns datetime object with added timespan.

    signature:left + right
    callAs:operator
    arg left:input datetime object
    argType left:datetime object
    arg right:input timespan object
    argType right:timespan object
    returnType:datetime object
    yaql> let(now() + timespan(days => 100)) -> $.month
    10
    
  • Returns datetime object with added timespan.

    signature:left + right
    callAs:operator
    arg left:input timespan object
    argType left:timespan object
    arg right:input datetime object
    argType right:datetime object
    returnType:datetime object
    yaql> let(timespan(days => 100) + now()) -> $.month
    10
    
  • Returns sum of two timespan objects.

    signature:left + right
    callAs:operator
    arg left:input timespan object
    argType left:timespan object
    arg right:input timespan object
    argType right:timespan object
    returnType:timespan object
    yaql> let(timespan(days => 1) + timespan(hours => 12)) -> $.hours
    36.0
    

operator -

  • Returns datetime object dt1 with subtracted dt2.

    signature:left - right
    callAs:operator
    arg left:input datetime object
    argType left:datetime object
    arg right:datetime object to be subtracted
    argType right:datetime object
    returnType:timespan object
    yaql> let(now() - now()) -> $.microseconds
    -325
    
  • Returns datetime object with subtracted timespan.

    signature:left - right
    callAs:operator
    arg left:input datetime object
    argType left:datetime object
    arg right:input timespan object
    argType right:timespan object
    returnType:datetime object
    yaql> let(now() - timespan(days => 100)) -> $.month
    4
    
  • Returns timespan object with subtracted another timespan object.

    signature:left - right
    callAs:operator
    arg left:input timespan object
    argType left:timespan object
    arg right:input timespan object
    argType right:timespan object
    returnType:timespan object
    yaql> let(timespan(days => 1) - timespan(hours => 12)) -> $.hours
    12.0
    

operator /

  • Returns timespan object divided by number.

    signature:left / right
    callAs:operator
    arg left:left timespan object
    argType left:timespan object
    arg right:number to divide by
    argType right:number
    returnType:timespan object
    yaql> let(timespan(hours => 24) / 2) -> $.hours
    12.0
    
  • Returns result of division of timespan microseconds by another timespan microseconds.

    signature:left / right
    callAs:operator
    arg left:left timespan object
    argType left:timespan object
    arg right:right timespan object
    argType right:timespan object
    returnType:float
    yaql> timespan(hours => 24) / timespan(hours => 12)
    2.0
    

operator <

  • Returns true if left datetime is strictly less than right datetime, false otherwise.

    signature:left < right
    callAs:operator
    arg left:left datetime object
    argType left:datetime object
    arg right:right datetime object
    argType right:datetime object
    returnType:boolean
    yaql> datetime(2011, 11, 11) < datetime(2011, 11, 11)
    false
    
  • Returns true if left timespan is strictly less than right timespan, false otherwise.

    signature:left < right
    callAs:operator
    arg left:left timespan object
    argType left:timespan object
    arg right:right timespan object
    argType right:timespan object
    returnType:boolean
    yaql> timespan(hours => 23) < timespan(days => 1)
    true
    

operator <=

  • Returns true if left datetime is less or equal to right datetime, false otherwise.

    signature:left <= right
    callAs:operator
    arg left:left datetime object
    argType left:datetime object
    arg right:right datetime object
    argType right:datetime object
    returnType:boolean
    yaql> datetime(2011, 11, 11) <= datetime(2011, 11, 11)
    true
    
  • Returns true if left timespan is less or equal to right timespan, false otherwise.

    signature:left <= right
    callAs:operator
    arg left:left timespan object
    argType left:timespan object
    arg right:right timespan object
    argType right:timespan object
    returnType:boolean
    yaql> timespan(hours => 23) <= timespan(days => 1)
    true
    

operator >

  • Returns true if left datetime is strictly greater than right datetime, false otherwise.

    signature:left > right
    callAs:operator
    arg left:left datetime object
    argType left:datetime object
    arg right:right datetime object
    argType right:datetime object
    returnType:boolean
    yaql> datetime(2011, 11, 11) > datetime(2010, 10, 10)
    true
    
  • Returns true if left timespan is strictly greater than right timespan, false otherwise.

    signature:left > right
    callAs:operator
    arg left:left timespan object
    argType left:timespan object
    arg right:right timespan object
    argType right:timespan object
    returnType:boolean
    yaql> timespan(hours => 2) > timespan(hours => 1)
    true
    

operator >=

  • Returns true if left datetime is greater or equal to right datetime, false otherwise.

    signature:left >= right
    callAs:operator
    arg left:left datetime object
    argType left:datetime object
    arg right:right datetime object
    argType right:datetime object
    returnType:boolean
    yaql> datetime(2011, 11, 11) >= datetime(2011, 11, 11)
    true
    
  • Returns true if left timespan is greater or equal to right timespan, false otherwise.

    signature:left >= right
    callAs:operator
    arg left:left timespan object
    argType left:timespan object
    arg right:right timespan object
    argType right:timespan object
    returnType:boolean
    yaql> timespan(hours => 24) >= timespan(days => 1)
    true
    

operator unary +

Returns timespan.

signature:+arg
callAs:operator
arg arg:input timespan object
argType arg:timespan object
returnType:timespan object
yaql> let(+timespan(hours => -24)) -> $.hours
-24.0

operator unary -

Returns negative timespan.

signature:-arg
callAs:operator
arg arg:input timespan object
argType arg:timespan object
returnType:timespan object
yaql> let(-timespan(hours => 24)) -> $.hours
-24.0

replace

Returns datetime object with applied replacements.

signature:dt.replace(year => null, month => null, day => null, hour => null, minute => null, second => null, microsecond => null, offset => null)
callAs:method
receiverArg dt:input datetime object
argType dt:datetime object
arg year:number of years to replace, null by default which means no replacement
argType year:integer between 1 and 9999 inclusive
arg month:number of months to replace, null by default which means no replacement
argType month:integer between 1 and 12 inclusive
arg day:number of days to replace, null by default which means no replacement
argType day:integer between 1 and number of days in given month
arg hour:number of hours to replace, null by default which means no replacement
argType hour:integer between 0 and 23 inclusive
arg minute:number of minutes to replace, null by default which means no replacement
argType minute:integer between 0 and 59 inclusive
arg second:number of seconds to replace, null by default which means no replacement
argType second:integer between 0 and 59 inclusive
arg microsecond:
 number of microseconds to replace, null by default which means no replacement
argType microsecond:
 integer between 0 and 1000000-1
arg offset:datetime offset in microsecond resolution to replace, null by default which means no replacement
argType offset:timespan type
returnType:datetime object
yaql> datetime(2015, 9, 29).replace(year => 2014).year
2014

timespan

Returns timespan object with specified args.

signature:timespan(days => 0, hours => 0, minutes => 0, seconds => 0, milliseconds => 0, microseconds => 0)
callAs:function
arg days:number of days in timespan, 0 by default
argType days:integer
arg hours:number of hours in timespan, 0 by default
argType hours:integer
arg minutes:number of minutes in timespan, 0 by default
argType minutes:
 integer
arg seconds:number of seconds in timespan, 0 by default
argType seconds:
 integer
arg milliseconds:
 number of microseconds in timespan, 0 by default
argType milliseconds:
 integer
arg microsecond:
 number of microseconds in timespan, 0 by default
argType microsecond:
 integer
returnType:timespan object
yaql> timespan(days => 1, hours => 2, minutes => 3).hours
26.05

utctz

Returns UTC time zone in timespan object.

signature:utctz()
callAs:function
returnType:timespan object
yaql> utctz().hours
0.0

Intrinsic functions

The module describes main system functions for working with objects.

assert

Evaluates condition against object. If it evaluates to true returns the object, otherwise throws an exception with provided message.

signature:obj.assert(condition, message => "Assertion failed")
callAs:method
arg obj:object to evaluate condition on
argType obj:any
arg condition:lambda function to be evaluated on obj. If result of function evaluates to false then trows exception message
argType condition:
 lambda
arg message:message to trow if condition returns false
argType message:
 string
returnType:obj type or message
yaql> 12.assert($ < 2)
Execution exception: Assertion failed
yaql> 12.assert($ < 20)
12
yaql> [].assert($, "Failed assertion")
Execution exception: Failed assertion

call

  • Evaluates function with specified args and kwargs and returns the result. This function is used to transform expressions like '$foo(args, kwargs)' to '#call($foo, args, kwargs)'. Note that to use this functionality 'delegate' mode has to be enabled.

    signature:call(callable, args, kwargs)
    callAs:function
    arg callable:callable function
    argType callable:
     python type
    arg args:sequence of items to be used for calling
    argType args:sequence
    arg kwargs:dictionary with kwargs to be used for calling
    argType kwargs:mapping
    returnType:any (callable return type)
  • Evaluates function name with specified args and kwargs and returns the result.

    signature:call(name, args, kwargs)
    callAs:function
    arg name:name of callable
    argType name:string
    arg args:sequence of items to be used for calling
    argType args:sequence
    arg kwargs:dictionary with kwargs to be used for calling
    argType kwargs:mapping
    returnType:any (callable return type)
    yaql> call(let, [1, 2], {a => 3, b => 4}) -> $1 + $a + $2 + $b
    10
    

def

Returns new context object with function name defined.

signature:def(name, func)
callAs:function
arg name:name of function
argType name:string
arg func:function to be stored under provided name
argType func:lambda
returnType:context object
yaql> def(sq, $*$) -> [1, 2, 3].select(sq($))
[1, 4, 9]

getContextData

Returns the context value by its name. This function is system and can be overridden to change the way of getting context data.

signature:getContextData(name)
callAs:function
arg name:value's key name
argType name:string
returnType:any (value type)

lambda

Constructs a new anonymous function Note that to use this function 'delegate' mode has to be enabled.

signature:lambda(func)
callAs:function
arg func:function to be returned
argType func:lambda
returnType:obj type or message
yaql> let(func => lambda(2 * $)) -> [1, 2, 3].select($func($))
[2, 4, 6]
yaql> [1, 2, 3, 4].where(lambda($ > 3)($ + 1))
[3, 4]

let

Returns context object where args are stored with 1-based indexes and kwargs values are stored with appropriate keys.

signature:let([args], {kwargs})
callAs:function
arg [args]:values to be stored under appropriate numbers $1, $2, ...
argType [args]:chain of any values
arg {kwargs}:values to be stored under appropriate keys
argType {kwargs}:
 chain of mappings
returnType:context object
yaql> let(1, 2, a => 3, b => 4) -> $1 + $a + $2 + $b
10

operator ->

Evaluates lambda on provided context and returns the result.

signature:left -> right
callAs:operator
arg left:context to be used for function
argType left:context object
arg right:function
argType right:lambda
returnType:any (function return value type)
yaql> let(a => 1) -> $a
1

operator .

  • Returns value of 'name' property.

    signature:left.right
    callAs:operator
    arg left:object
    argType left:any
    arg right:object property name
    argType right:keyword
    returnType:any
    yaql> now().year
    2016
    
  • Returns expr evaluated on receiver.

    signature:receiver.expr
    callAs:operator
    arg receiver:object to evaluate expression
    argType receiver:
     any
    arg expr:expression
    argType expr:expression that can be evaluated as a method
    returnType:expression result type
    yaql> [0, 1].select($+1)
    [1, 2]
    

operator ?.

Evaluates expr on receiver if receiver isn't null and returns the result. If receiver is null returns null.

signature:receiver?.expr
callAs:operator
arg receiver:object to evaluate expression
argType receiver:
 any
arg expr:expression
argType expr:expression that can be evaluated as a method
returnType:expression result or null
yaql> [0, 1]?.select($+1)
[1, 2]
yaql> null?.select($+1)
null

unpack

Returns context object with sequence values unpacked to args. If args size is equal to sequence size then args get appropriate sequence values. If args size is 0 then args are 1-based indexes. Otherwise ValueError is raised.

signature:sequence.unpack([args])
callAs:method
receiverArg sequence:
 iterable of items to be passed as context values
argType sequence:
 iterable
arg [args]:keys to be associated with sequence items. If args size is equal to sequence size then args get appropriate sequence items. If args size is 0 then args are indexed start from 1. Otherwise exception will be thrown
argType [args]:chain of strings
returnType:context object
yaql> [1, 2].unpack(a, b) -> $a + $b
3
yaql> [2, 3].unpack() -> $1 + $2
5

with

Returns new context object where args are stored with 1-based indexes.

signature:with([args])
callAs:function
arg [args]:values to be stored under appropriate numbers $1, $2, ...
argType [args]:chain of any values
returnType:context object
yaql> with("ab", "cd") -> $1 + $2
"abcd"

YAQL`ization of Python classes

Any Python class or object can be yaqlized. It is possible to call methods, access attributes/properties and index of yaqlized objects.

The first way to yaqlize object is using function call:

class A(object):
    foo = 256
    def bar(self):
        print('yaqlization works with methods too')

sample_object = A()
yaqlization.yaqlize(sample_object)

The second way is using decorator:

@yaqlization.yaqlize
class A(object):
    foo = 256
    def bar(self):
        print('yaqlization works with methods too')

Any mentioned operation on yaqlized objects can be disabled with additional parameters for yaqlization. Also it is possible to specify whitelist/blacklist of methods/attributes/keys that are exposed to the yaql.

This module provides implemented operators on Yaqlized objects.

operator .

  • Returns attribute of the object.
    signature:obj.attr
    callAs:operator
    arg obj:yaqlized object
    argType obj:yaqlized object, initialized with yaqlize_attributes equal to True
    arg attr:attribute name
    argType attr:keyword
    returnType:any
  • Evaluates expression on receiver and returns its result.
    signature:receiver.expr
    callAs:operator
    arg receiver:yaqlized receiver
    argType receiver:
     yaqlized object, initialized with yaqlize_methods equal to True
    arg expr:expression to be evaluated
    argType expr:expression
    returnType:any (expression return type)

operator indexer

Returns value of attribute/property key of the object.

signature:obj[key]
callAs:function
arg obj:yaqlized object
argType obj:yaqlized object, initialized with yaqlize_indexer equal to True
arg key:index name
argType key:keyword
returnType:any

Legacy YAQL compatibility functions

The module describes functions which are available with backward compatibility mode with YAQL v0.2. Examples are provided with CLI started with legacy mode.

as

Returns context object with mapping functions applied on receiver and passed under corresponding keys.

signature:receiver.as([args])
callAs:method
receiverArg receiver:
 value to be used for mappings lambdas evaluating
argType receiver:
 any type
arg [args]:tuples with lambdas and appropriate keys to be passed to context
argType [args]:chain of tuples
returnType:context object
yaql> [1, 2].as(len($) => a, sum($) => b) -> $a + $b
5

dict

Returns dict built from tuples.

signature:dict([args])
callAs:function or method
arg [args]:chain of tuples to be interpreted as (key, value) for dict
argType [args]:chain of tuples
returnType:dictionary
yaql> dict(a => 1, b => 2)
{"a": 1, "b": 2}
yaql> dict(tuple(a, 1), tuple(b, 2))
{"a": 1, "b": 2}

operator .

Returns dict's key value.

signature:left.right
callAs:operator
arg left:input dictionary
argType left:mapping
arg right:key
argType right:keyword
returnType:any (appropriate value type)
yaql> {a => 2, b => 2}.a
2

operator =>

Returns tuple.

signature:left => right
callAs:operator
arg left:left value for tuple
argType left:any
arg right:right value for tuple
argType right:any
returnType:tuple
yaql> a => b
["a", "b"]
yaql> null => 1 => []
[null, 1, []]

range

Returns sequence from [start, stop).

signature:start.range(stop => null)
callAs:function or method
receiverArg start:
 value to start from
argType start:integer
arg stop:value to end with. null by default, which means returning iterator to sequence
argType stop:integer
returnType:sequence
yaql> 0.range(3)
[0, 1, 2]
yaql> 0.range().take(4)
[0, 1, 2, 3]

switch

Returns the value of the first key-value pair for which condition returned true. If there is no such returns null.

signature:value.switch([args])
callAs:function or method
receiverArg value:
 value to be used evaluating conditions
argType value:any type
arg [args]:conditions to be checked for the first true
argType [args]:chain of mappings
returnType:any (appropriate value type)
yaql> 15.switch($ < 3 => "a", $ < 7 => "b", $ => "c")
"c"

toList

Returns collection converted to list.

signature:collection.toList()
callAs:method
receiverArg collection:
 collection to be converted
argType collection:
 iterable
returnType:list
yaql> range(0, 3).toList()
[0, 1, 2]

tuple

Returns tuple of args.

signature:tuple([args])
callAs:function
arg [args]:chain of values for tuple
argType [args]:chain of any types
returnType:tuple
yaql> tuple(0, [], "a")
[0, [], "a"]