Methods
String expansion handler. Called automatically for every double-quoted string that
has $* components.
Execute an external command. Waits for the command to finish unless "&" is specified.
Enables "nofail" command prefix.
Each operator.
Same as calling x.each(cb)
Returns c, wihout any processing. Convenient way to pass ready-to-run Command as an argument
Repeat all elements in arr n times
Call cb n times without any parameters and accumulate the results.
Add Hashes. Builds new hash with key-value pairs from both a and b. If same key is present in both a and b, the value from b is used.
Prepend each line in a with s
Append s to each line in a
Filter out all values in a that are also in b
Return string without the prefix. Throws MatchFail if pfx is MustPfx but s does not start with it.
Return string without the suffix. Throws MatchFail if pfx is MustSfx but s does not end with it.
Returns the string with one occurrence of regexp cut out of it. Throws InvalidArgument if s does not contain r.
Get attributes of a RegExp. Throws AttrNotFound if attr is not one of the allowed values. You should not use this directly. Use "~" and "~~" operators.
Get BasicType (Int, Arr, Hash, ...) attribute. Throws AttrNotFound.
Get NormalType (a type that is typically defined by user) attribute. Throws AttrNotFound.
Get NormalType (a type that is typically defined by user) instance attribute. Throws AttrNotFound.
Return array made of given attribute of each element of given array
Constructs open-open predicate range
Constructs closed-open numerical range
Constructs closed-closed predicate range
Constructs closed-closed numerical range
Set Normal type (a type that is typically defined by user) instance attribute. Throws AttrNotFound.
Map operator.
Same as calling x.map(mapper)
Concatenate two path parts using STDLIB_PATH_SEP (currently "/") but should be platform-specific later.
Concatenate two path parts using STDLIB_PATH_SEP (currently "/") but should be platform-specific later.
Concatenate two path parts using STDLIB_PATH_SEP (currently "/") but should be platform-specific later.
Concatenate two Path-s using /(a:Str, b:Str)
Regular expression constructor. Called by NGS when /myregex/ syntax is used.
Less-than-or-equal comparison
Less-than-or-equal comparison
Case sensitive LessThan or Equal comparison for strings
Types equality comparison. Implemented as sameness comparison.
Closure equality comparison. Implemented as sameness comparison.
Equality comparison. Using this operator/function is not recommended.
See http://how-to.wikia.com/wiki/Howto_compare_floating_point_numbers_in_the_C_programming_language .
Equaity test for normal type instances: must be of same type and have same attributes and their values
Arrays equality test.
True if arrays are of the same length and all elements are equal (==)
Compare two Hashes. Hashes must have same keys with same values in same order to return true.
Compare boxes. Empty boxes and boxes with same content are considered to be equal.
Greater-than-or-equal comparison
Greater-than-or-equal comparison
Filter operator.
Same as calling x.filter(predicate)
Unfinished feature. Don't use!
Get hash value by key. Throws KeyNotFound.
Set element in the underlying array.
Get array element by index from the end
Get array elements at specified indexes. Indexes specified by NumRange.
Extract array elements between the element that matches r.start and the element that matches r.end .
Starting and ending elements are optionally included, depending on r.include_start and r.include_end .
Get array elements at specified indexes.
Get given character (currently byte) of the string
Get given character (currently byte) of the string.
TODO: Document InvalidArgument exception.
Get a substring. Indexes in s are specified by NumRange.
Convenience method to access matches in MatchY
Get substring of a string that corresponds to first match of given regular expression
%EX "x10ab20c30y"[/[0-9]+/] # "10"
Get element from the underlying array.
Call operator.
Same as calling f(x)
Get command standard output. Similar to bash.
Get command standard output and parse() it.
Check whether all elements in arr satisfy the given predicate.
Check whether there is any element in arr that satisfies the given predicate.
TODO: Make it work on anything with Eachable2 too.
Sets ARGV matching option.
Make Arr from Hash. Each key/value pair becomes two-items array:
Make Arr from Arr. A no-op.
Convert range to an array
Convert EmptyBox to array
Throws AssertFail with givens message if condition is false
Throws AssertFail if condition is false
Get basename of the file. Uses BASENAME(1).
Call Bool() on the underlying array.
Whether there is a difference
Whether there is a difference
Checks whether the path is accessible using access(2) and F_OK.
Wait for process to finish and see whether exit code is 0
Check whether there are more array elements to iterate over.
true: next() will return next element. false: next() will throw NoNext
Main entry point. Executed on NGS boot.
Convert anything to Box (always FullBox)
Convert null to Box (always EmptyBox)
Convert array to a Box. Throws InvalidArgument if length of the array is not 0 or 1.
Convert array value indexed by the given index
Convert hash value indexed by the given key to a Box
Unfinished feature. Don't use!
Unfinished feature. Don't use!
Unfinished feature. Don't use!
Throws RegExpCompileFail on errors.
Search string for regular expression. Uses PCRE_EXEC(3). Do not use this function directly!
Call PTHREAD_CREATE(3). Not recommended for direct calls, use Thread type instead.
Call PTHREAD_JOIN(3). Not recommended for direct calls, use Thread type instead.
Implements calling of Return type instances
like the finish(i) call in the example below
Runs all handlers passing all args.
Calculate cell display width - any Str()-able instance
Calculate cell display width for an array
Calculate cell display width for an empty array
Get child process end file descriptor of Pipe. It's the writing end for Pipe(STDLIB_CHILD_TO_PARENT_PIPE_DIR).
Get child process end file descriptor of Pipe. It's the reading end for Pipe(STDLIB_PARENT_TO_CHILD_PIPE_DIR).
Get character (byte) by it's ordinal value.
Close a file and sets the "fd" field to null. Uses CLOSE(2).
Throws InvalidArgument if file is not open.
Throws FileIOFail if an underlying error occurs.
Close reading end of the Pipe
Close writing end of the Pipe
Convert an array to NGS code that would produce the array when executed. Not fully functional yet.
Convert a Hash to NGS code that would produce the given Hash when executed. Not fully functional yet.
Convert an Int to NGS code that would produce the integer when executed. Not fully functional yet.
Convert a Str to NGS code that would produce the string when executed. Not fully functional yet.
BUG: Does not do escaping.
Convert null to NGS code that would produce null when executed.
Defines collector { ... collect(...) ... } behaviour for arrays
Defines collector { ... collect(...) ... } behaviour for hashes
Defines collector { ... collect(...) ... } behaviour for integers (summarizes collected items).
Compile NGS source to bytecode.
Get configuration for the given key. Lookup order / first wins: (1) Environment variable NGS_$k (2) previously set config(k, v)
Set configuration. To be used with config(k:Str).
Count number of items that satisfy the predicate.
TODO: Make it work on anything with each() method.
Count number of key-value pairs in Hash that satisfy the predicate.
Same as debug('default', s)
Debug to standard error.
"DEBUG" environment variable must be non-empty string to activate. Otherwise nothing is outputted.
TODO: Not output thread ID if there is only one thread.
TODO: Timestamps?
Delete hash key. No exception is thrown if key is not found, the deletion is just skipped then.
Set an attribute in an instance if it's not already set
Set an attribute on instances if it's not already set
Set an key in a Hash if it's not already set
Write message in s to standard error and exit
Compare arrays. Warning: Hash is used so internal Hash keys comparison is used, not ==
List directory contents. Warning: "." and ".." are included.
Throws DirFail when directory can not be listed.
List directory contents and call cb with Path() of each found item. Warning: "." and ".." are included.
Fetch and drop next n values from iterator i.
EXPERIMENTAL! Do not use!
Low-level data structure dump. Used for debugging NGS itself.
DUP2(2) reading file descriptor
DUP2(2) writing file descriptor
Call cb for each element in the underlying array.
Iterates over the elements of r, passing each in turn to cb.
Iterates over the elements of arr, passing each in turn to cb along with args: cb(ITEM)
Process each N elements of an Array at a time.
Throws InvalidArgument if number of items in arr is not divisible by n.
cb is called as cb(eltI, ..., eltJ) where I is multiple of n and J is I+n-1
Call cb with the value of the FullBox
Iterate from zero up to but not including n
Iterates over all string characters (currently bytes).
TODO: example.
Calls cb with each element from i
Iterates over the elements of arr, passing each in turn to cb along with index and args: cb(INDEX, ITEM)
Print given string and a newline to stdout.
Print given string and a newline to a file referenced by descriptor.
Echo non-string. Converts x to string first, using Str()
Displays a table. Implemented only for tty output (or output_format=text configuration)
Output (echo) CSV table with cells that contain arrays converted to columns.
TODO: data escaping.
Encodes each character in a string as two uppercase hexadecimal digits
Encodes HTML. Escapes &, < and > .
Encodes HTML attribute. Escapes &, <, >, " and ' .
Encode JSON (serialize a data structure to JSON)
Encodes URI component, escaping with %XX hexadecimal codes.
Check whether a string ends with another string
Write error message to standard error.
Do nothing. Catch-all for exception_specific_message().
Format GlobalNotFound exception message.
read() and parse() the given file
Read standard input and parse() it, passing "source" equals "stdin" hint.
Filter something to an Arr (array) of values using predicate.
Filter nulls out.
DEPRECATED, USE something.without(null) INSTEAD.
Filter hash. Build new hash with kev-value pairs selected by predicate.
Get new DelimStr with some elements filtered out
Filter hash by keys, keeping matched
TODO: make sure cleanup() is not run twice in case of exception in cleanup() itself
Finds given binary and returns it's full path.
Throws ExecutableNotFound if the binary was not found.
Search strategy: "/" in the name of the binary means that given executable_name is a path so it's returned as-is (wrapped in Path).
If PATH environment variable exists, the given directories are searched.
If PATH is not set built-in value for PATH is used to search: /usr/local/bin:/usr/bin:/bin:/sbin:/usr/sbin
Decide whether process finished normally: exit code must be 0.
Decide whether /bin/false process finished normally: exit code must be 1.
Decide whether specific process finished normally: exit code must be 0 or 1.
Find first element in e that satisfies the predicate.
Find first element in e that satisfies Bool(e) == true.
Exactly same as first(e, identity).
Get hash value by key or dflt if it does not exist
Get hash value by key or null if it does not exist
Return array made of given attribute of each element of given Eachable1 where present
Return array made of given attribute of each element of given Eachable1 where present or default value where the attribute is not present
Return array (? depends on map() ?) made of given attribute of each element of given Eachable1
Get EmptyBox value. Always throws InvalidArgument.
Work in progress, do not use!
global_not_found_handler¶
Called when reading undefined global.
Implements autoloading.
Searches in $NGS_DIR/autoload/NAME.ngs
WARNING: May have security implications when looking up a name from untrusted source.
Get all global variables as Hash
TODO.
Group items from a by key returned by cb
Exactly same as "element in container". It's just more convenient in specific cases.
Get all attributes and their values as key-value pairs in the resulting Hash.
Get the underlying Hash with all the keys/values of the HashLike.
Note: the returned value is not a copy.
Create a Hash from Arr of Arr[2]
TODO. Not sure it's used anywhere. Maybe remove?
Create a Hash from keys in arr using cb for values calculation
Create a Hash from keys in "keys" and corresponding values in "values"
Create Hash from Arr of something that has key and value attribute
Calculate hash value. Same function that Hash uses internally. Currently Fowler-Noll-Vo (FNV) hash function.
Unfinished feature. Don't use!
Check whether NormalType (a type that is typically defined by user) instance has an attribute.
Check key presence in a Hash
Checks whether element x is in array arr
Determin if needle substring occurs at least once in haystack
Find index of first value that satisfies the predicate.
TODO: Make it work on anything with each() method.
Find all indexes of values that satisfy the predicate
TODO: Make it work on anything with each() method
Make t inherit from parent. Do not use directly. Use "type MyType(parent)".
Trivial initialization helper for init(o, ...)
Sets object fields from the supplied parameters
IndexNotFound exception constructor
CException constructor. In addition to storing message attribute, adds errno and errno_name attributes.
Do not use directly!
Helper constructor that throws InvalidArgument when
FullBox is created with zero or more than one argument.
FullBox constructor. Saves val into .val
Path constructor. Duplicates other Path.
Pipe constructor. Create UNIX pipe using PIPE(2). Throws PipeCreateFail if pipe can not be created.
Pipe constructor. Create UNIX pipe using PIPE(2). Throws PipeCreateFail if pipe can not be created.
Successful match constructor
Constant iterator constructor.
EXPERIMENTAL! Do not use!
Makes Stats, with each element in the array counted as if push()ed
Initialize rows to an empty array
Create named table containing provided rows
Convert Real (floating) number to Int. Floating part is truncated.
Convert base-10 string to Int.
Throws InvalidArgument if the number in s is not well-formatted.
Get closure code instruction pointer.
Check whether obj is of type t. Uses same function that is used for matching arguments with method parameters when calling a method.
"is not" operator. Exactly same as "not(a is b)".
Do not use directly! Check whether global variable is defined by index.
Check whether given fd represents a TTY. Uses ISATTY(3).
Throws TtyCheckFail.
Supports "for i in existing_iterator"
Calls ArrIter constructor.
EXPERIMENTAL! Do not use!
Join non-strings. Converts a elements to string first, then uses built-in join().
Get Hash keys as an array
Send signal to a process. Uses KILL(2). Throws KillFail on error.
Send signal to a Process. Uses KILL(2).
Throws InvalidArgument if Process does not have "pid".
Throws KillFail on error.
Get number of key-value pairs in a Hash
Get length of the underlying array.
Truncate an array if necessary so it would have maximum l elements.
Truncate a Hash if necessary so it would have maximum l key-value pairs.
Truncate a string if necessary so it would have maximum n characters (currently bytes).
Split s to strings using end-of-line separators.
UNIX and Windows line endings supported (Windows - not tested yet).
Warning: Max OS <= 9 line separation of CR (\r) is not supported
Split s to strings using end-of-line separators and call cb for each one of the lines.
TODO: More efficient implementation, which would not have temporary array of all lines.
Iterate over lines of the file
Wait for the process and return lines of its stdout.
Iterate lines of Process' stdout, calling cb with successive lines.
Warning: current implementation waits for the process to finish and accumulates all its stdout.
Log to standard output. Later log output will be treated specially by the shell. It will have suitable representation in the UI. Use log() when it's semantically a log.
Issue lstat() system call. Throws StatFail if the call fails.
Issue lstat() system call. Throws StatFail if the call fails.
Case-insensitive LessThan or Equal comparison for strings
Map something to an Arr (array) of values using mapper.
Map each N elements of an Array at a time.
mapper is called as cb(eltI, ..., eltJ) where I is multiple of n and J is I+n-1
Throws InvalidArgument if number of items in arr is not divisible by n.
mapper is called as mapper(eltI, ..., eltJ) where I is multiple of n and J is I+n-1
EXPERIMENTAL!
Map when there is more than one element. If there is exactly one element, it's left as is
Map an Arr to an Arr (array) of values using mapper
mapper is called as mapper(INDEX, ITEM)
Map Hash keys. Build new Hash with same values as in h but keys mapped by mapper.
Map Hash keys and values. Build new Hash with keys and values mapped by mapper.
Map Hash values. Build new Hash with same keys as in h but values mapped by mapper.
Used by match EXPR { ... } construct.
Convert hash values to integers where possible
Return the constant iterator value
Get value of the next element of the array iterated over.
Check that there is no element in e that satisfies the given predicate. Exactly same as not(any(e, predicate)) .
Boolean negation for non-boolean values. Converts to boolean first.
"not in" operator. Exactly same as "not(a in b)"
Used for command line arguments such as ['--vpc-id', my_vpc_id()].nuke_null()
If my_vpc_id() is null the whole array is not needed
Transform mapper to handle only items matching predicate. Non-matching items will be returned as is.
Open a file and set the "fd" field to the file descriptor. Uses OPEN(2).
Throws InvalidArgument if file is already open.
Throws FileIOFail if an underlying error occurs.
Get optional resource property, looking up in properties first and then in anchor
Run cb with optional resource property if it exists, uses opt_prop(ResDef, Str, Hash)
Get character (byte) ordinal value. Throws InvalidArgument if idx is not pointing into s.
Get character (currently byte) code. Throws InvalidArgument if s is not of length 1.
Get parent process end file descriptor of Pipe. It's the reading end for Pipe(STDLIB_CHILD_TO_PARENT_PIPE_DIR).
Get parent process end file descriptor of Pipe. It's the writing end for Pipe(STDLIB_PARENT_TO_CHILD_PIPE_DIR).
Attempt to parse JSON. Uses decode_json().
EXPERIMENTAL. KVS (key-value separator) hint for parse()
EXPERIMENTAL. FS (field separator) hint for parse()
Handle fields_names hint - run parse() and make Arr[Hash] from Arr[Arr] using provided fields_names
Parse the output of "aws" command. Extracts the array (see "s" below"). For "describe-instances", flattens the instance list.
Parse the output of "find" command which does not use "-printf". Handles "-print0".
Returns partially-applied function
Same as partial() but the bound arguments are last ones
Return the constant iterator value
Preview value of the next element of the array iterated over.
Does not affect internal pointer which means it does not affect of value returned by next().
Convenience method for creating MustPfx
Pop item from an array. Removes last item in array and returns it. Throws EmptyArrayFail.
Find substring in a string.
Convert anything to a predicate.
Convert a function to predicate.
Convert a type to a predicate.
Convert regular expression to a predicate.
Print exception to stderr. Uses inspect().
Push an element to the underlying array.
Add unnamed handler.
The hook is automatically named "pushed-N" where N is sequential integer.
Increment the named counter
rand¶
Get random number between 0 and RAND_MAX-1. Uses RANDOM(3).
Pick n elements from something. Uniqueness of picked elements is not guaranteed.
Pick random number from 0 up to but not including n
Pick one random element from array
Pick random character from a string
Pick one random element from a range
rand_uniq¶
Pick n random unique elements from something
Read all data from a file referenced by file descriptor without parsing it.
Read all data from a file referenced by file descriptor 0 (stdin) without parsing it. Same as read(0)
Read from Pipe without parsing. TODO: document if it throws.
Convert a string to real (floating) number, inefficiently
Combine items to a single value using the supplied binary function
First f is applied to start and the first element of something
then on each step f is applied to previous result and next element
of something.
Filter something to an Arr (array) of values using predicate
Filter hash by keys, removing matched
DISCOURAGED. Replace one object with another. dst and src must be of the same type.
Replace all occurrences of src with dst
Replace all occurrences of r
Get resource property, looking up in properties first and then in anchor
Do not use directly! Get global variable index by name.
Resolves Instruction Pointer to source location
Retry. Executes given "body" "times" times. Throws RetryFail if all calls fail and fail_cb is not provided.
Get closure-specific Return type. Throwing it, will return from the closure
Make new array which is a reversed given array
Don't use, subject to change, including name
Sets the given attribute to the given value
Do not use directly! Set global variable by index.
Convenience method for creating MustSfx
Get the given key from a Hash and remove it from the Hash.
Underlying h[k] may throw KeyNotFound.
Get a key from a Hash and remove it from the Hash.
If they key is not in the Hash, return dflt
Sort an array based on attribute value
EXPERIMENTAL, do not use outside of stdlib!
Instanciates Path sub-type, depending on what p is
Split string by substring
%EX "x10ab20c30y".split(/[0-9]+/).join(" :: ") # "x :: ab :: c :: y"
srand¶
Seed random generator. Uses SRANDOM(3).
Check whether a string starts with another string
Issue stat() system call. Throws StatFail if the call fails.
Issue stat() system call. Throws StatFail if the call fails.
Send status to standard error.
Later status output will be treated specially by the shell. It will have suitable representation in the UI.
Use status() when it's semantically a status - a task that's being done.
Convert "Tags" array in each element of AWS resources (typically returned by AWS CLI) into Hash.
Makes "Tags" much more usable.
Convert "Tags" array in the given AWS resource (typically returned by AWS CLI) into Hash.
String representation of native method.
String representation of a closure
String representation of a type
String representation of normal type instance i
Normal type is a user defined type. In addition some types defined by NGS are also normal types.
Convert range to human readable representation
Convert anything to Str of a given width
Pad a string to given width with spaces
Convert a number to a string and pad it
String representation of a Path (or it's sub-type)
String representation of File
Wait for the process to finish and return its standard output.
Textual representation of ArrIter.
Build array of Str where each resulting string is of the form "KEY=VALUE"
Calculate sum of the elements
Fetch and convert to array next n values from iterator i.
EXPERIMENTAL! Do not use!
Find the only element that satisfies the predicate.
Throws TheOneFail exception if there are no elements that satisfy the predicate or if there is more than one element that satisfies the predicate.
Find the only element that satisfies the predicate and execute given code with the value
Extract the only element.
Throws TheOneFail exception if there are no elements or if there is more than one element.
Private method of Iter.ngs, will be hidden in future.
Get time as the number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). Wraps TIME(2).
Call cb n times without arguments.
Zero for FullBox and one for EmptyBox
Convert Process to exit code. Waites for the process to finish and uses its exit code.
Convert Match to exit code.
Create a new type. Do not use directly. Use "type MyType".
Returns type of the given instance
Return unique values.
Warning: uses Hash so comparison is not using == but a built-in hash keys comparison.
Prepend one element to the given array
Update a Hash with key-value pairs from another Hash. For non destructive version use "dst + src".
Get Hash values as an array
Wait for the process to finish. Waits for reading and writing threads to finish first.
Write error message to standard error.
Filter out all occurrences of specific value
Filter out specific key-value pair
Get string with all occurrences of r removed
Get new DelimStr without the given element
Write data to a file referenced by file descriptor.
WARNING: Incomplete implementation.
TODO: handle errors, throw exceptions.
TODO: handle possible EINTR.
Write to Pipe. TODO: document if it throws.
Make new array which aggregates elements from each of the args arrays
n-th element of the new array is an array that contains n-th element of each of the given arrays
If some of the arrays in args are shorter than others, they will be logically padded with null
Match a type. Same as "something is t".
EXPERIMENTAL. For use with AWS Anchors.
Check whether s starts with pfx.
Check whether s ends with pfx.
Find PCRE regular expression in s. Empty string without options returns MatchN. Throws Error if more than 20 captures are used or if there is an error during matching.
Tries to match command line arguments with closure parameters.
Find all non-overlapping matches of regular expression in a string.