The global namespace

The main entry point to generated documentation

Sub-namespaces

AWS: Amazon Web Services. This namespace contains declarative primitives resource types that implement common methods: find(), create(), delete(), converge()
1 sub-namespaces, 31 types, 25 multimethods

AWS2: Amazon Web Services. This namespace is under development. Use at your own risk. This namespace contains resource types that implement common methods: find(), create(), delete(), converge()
39 types, 24 multimethods

Doc: EXPERIMENTAL. Do not use! Defines types and methods to work with document nodes. Can be used to relatively conveniently generate HTML.
7 types, 13 multimethods

GC: Control NGS garbage collection
3 top level methods

Types

121 types, which are descendants of types listed below, are not shown for brevity

Any: Any type is parent type of all types. All objects in NGS are of type Any. F(x) ... is same as F(x:Any) ...

Backtrace: Represents stack trace

BasicType: Type for builtin types. F f(t:BasicType) ...; f(Arr)

BasicTypeInstance: A type for objects of builtin types. Children types are not displayed as this type is specially optimized.

Bool: Boolean type. The only objects are true and false

C_DIR: C language DIR type for low level directory operations. Please do not use directly unless you are extending stdlib.

c_ffi_cif: Unfinished feature. Don't use!

c_ffi_type: Unfinished feature. Don't use!

c_pthread_attr_t: Undocumented

c_pthread_mutex_t: Undocumented

c_pthread_mutexattr_t: Undocumented

c_pthread_t: Undocumented

c_tm: Undocumented

CLib: C library, result of dlopen(), not used yet

Command: Undocumented

CommandsPipe: Undocumented

CommandsPipeline: Undocumented

CSym: C symbol, result of dlsym(), not used yet

Diff: Represents difference
Direct subtypes: 2

Eachable: Parent type of all types that have each() method
Direct subtypes: 2

Exception: Represents exceptional situaution. All thrown things shouhld inherit Exception.
Direct subtypes: 15

Exit: Information about exiting, used by bootstrap and as argument to exit_hook.

Fun: Function type: native method, user defined method, or a multimethod

Iter: Iterator. Parent type for all specific iterator types.
Direct subtypes: 7

LLHashEntry: Undocumented

Lock: Synchronization lock.
Direct subtypes: 1

Match: Successful or unsuccessful match result
Direct subtypes: 2

NativeMethod: Native method type. Methods implemented in C have this type.

NgsStrComp: Undocumented
Direct subtypes: 3

NoData: Absence of data
Direct subtypes: 2

NormalType: Type for user-defined types. type T1; F f(t:NormalType) ...; f(T1)

NormalTypeConstructor: Default constructor for Normal types. Normal types are user-defined and some of the built-in types.

NormalTypeInstance: A type for objects of user-defined types. Children types are not displayed as this type is specially optimized.

Num: A number
Direct subtypes: 2

Path: Represents file system path such as a file, a block device, etc
Direct subtypes: 7

Pipe: Wrapper around file descriptors returned by PIPE(2)
Direct subtypes: 2

Presence: Represents desired target configuration list item presence
Direct subtypes: 2

Process: Running or finished process

Range: A range
Direct subtypes: 2

Redir: Input/output redirection

RegExp: Undocumented

Res: Abstract resource
Direct subtypes: 2

Result: Result of a computation
Direct subtypes: 2

Return: Return instance type, when thrown, will exit the call frame where they were created returning given value.

Seq: Unused type

Stat: Result of stat() or lstat()

SubSeq: Undocumented
Direct subtypes: 3

TestsResults: Undocumented

Thread: Execution thread. Currently a POSIX thread.

Time: Undocumented

Type: Type for types. F f(t:Type) ...; f(Arr) ...

UserDefinedMethod: UserDefinedMethod type. User-defined functions/methods are Closures

Methods and Multimethods

!=: Inequality operator

!==: Non-sameness operator

"$*": String expansion handler. Called automatically for every double-quoted string that has $* components.

$(): MultiMethod with 3 methods

%: MultiMethod with 2 methods

%(): Returns cp, wihout any processing. Convenient way to pass ready-to-run Command as an argument

*: MultiMethod with 6 methods

+: MultiMethod with 9 methods

+?: Return a+b unless one of the arguments is falsy. In that case return that argument (a if both are falsy). Useful for building strings with optional parts.

-: MultiMethod with 7 methods

.: MultiMethod with 11 methods

..: MultiMethod with 2 methods

...: MultiMethod with 2 methods

.=: MultiMethod with 7 methods

/: MultiMethod with 8 methods

//: Regular expression constructor.

::: MultiMethod with 2 methods

::=: MultiMethod with 2 methods

<: MultiMethod with 3 methods

<=: MultiMethod with 5 methods

==: MultiMethod with 18 methods

===: Sameness comparison.

>: MultiMethod with 4 methods

>=: MultiMethod with 2 methods

?: Filter operator. Same as calling x.filter(predicate)

[]: MultiMethod with 16 methods

[]=: MultiMethod with 8 methods

\: MultiMethod with 2 methods

``: Get command standard output. Similar to bash. Does not strip trailing new line character(s) `line:true my_command` will return the first line, stripping trailing new line character(s)

````: Get command standard output and decode() it.

abs: Absolute value of a number

access: Check whether current process has the specified access to the file. Wrapper around ACCESS(2). Throws CException.

acquire: MultiMethod with 2 methods

all: Check whether all elements in arr satisfy the given predicate.

any: MultiMethod with 2 methods

Arg: MultiMethod with 4 methods

args: Get function arguments

Argv: MultiMethod with 2 methods

ArgvMatcher: Sets ARGV matching option.

assert: MultiMethod with 3 methods

assert_array: Assert actual is an Arr. Throws TestFail.

assert_baseinternal: A helper used by other assert_* methods. Please do not use directly.

assert_eq: Assert equality. Throws TestFail.

assert_exit_code: Assert process exits with the specified exit code. Throws TestFail.

assert_has: Assert having specific element or substring (checks with "has"). Throws TestFail.

assert_hash: Assert actual is a Hash. Throws TestFail.

assert_hash_keys: Assert actual is a Hash and it has the expected keys. Throws TestFail.

assert_hash_keys_values: Assert actual is a Hash and it has the expected keys with expected values. Throws TestFail.

assert_in: Assert element is in an array (or other Eachable1). Throws TestFail.

assert_match: Assert actual matches expected. Throws TestFail.

assert_min_len: Assert actual is of at least specified length. Throws TestFail.

assert_output_has: MultiMethod with 2 methods

assert_path_exists: Assert given path exists.

assert_resolvable: Assert given host is resolvable. Uses "dig" command line utility. Retries "times" times, sleeping "sleep" seconds in between. Throws TestFail.

assert_string: Assert actual is a string. Throws TestFail.

attempt: EXPERIMENTAL! Do not use!

attrs: MultiMethod with 2 methods

band: Bitwise and

basename: MultiMethod with 2 methods

body_missing_in_retry: Internal method. Used by retry().

bootstrapinternal: Internal method. Please do not use. Main entry point. Executed on NGS boot.

bootstrap_exception_catch_wrapperinternal: Internal method. Please do not use. Runs bootstrap() and handles exceptions.

bootstrap_find_ngs_dirinternal: Internal method. Please do not use. Find which of bootstrap_ngs_dir_candidates directories contains stdlib.ngs . That directory would be the "NGS_DIR".

bor: Bitwise or

bxor: Bitwise xor

c_access: Call ACCESS(2)

c_close: Close a file. Uses CLOSE(2).

c_closedir: Call CLOSEDIR(3)

c_dlopen: Unfinished feature. Don't use!

c_dup2: Duplicate a file descriptor. Uses DUP2(2).

c_errno: Use errno macro.

c_execve: Call EXECVE(2)

c_exit: Call EXIT(3). Don't use directly unless you must. Use FatalError exception.

c_ffi_call: Unfinished feature. Don't use!

c_ffi_prep_cif: Unfinished feature. Don't use!

c_fork: Call FORK(2)

c_fstat: Call FSTAT(2)

c_getpid: Call GETPID(2)

c_getppid: Call GETPPID(2)

c_gettimeofday: Wraps GETTIMEOFDAY(2).

c_gmtime: Call GMTIME_R(3)

c_isatty: Check if file descriptor refers to a TTY device. Uses ISATTY(3).

c_kill: Call KILL(2). Global variable SIGNALS contains mapping between signals' names and values.

c_localtime: Call LOCALTIME(3)

c_lseek: Call LSEEK(2).

c_lstat: Call LSTAT(2)

c_mktime: Call MKTIME(3)

c_open: Open a file. Uses OPEN(2).

c_opendir: Call OPENDIR(3)

c_pcre_compile: Throws RegExpCompileFail on errors.

c_pcre_exec: Search string for regular expression. Uses PCRE_EXEC(3). Do not use this function directly!

c_pipe: Call PIPE(2)

c_poll: Undocumented

c_pthread_attr_init: Call PTHREAD_ATTR_INIT(3)

c_pthread_create: Call PTHREAD_CREATE(3). Not recommended for direct calls, use Thread type instead.

c_pthread_join: Call PTHREAD_JOIN(3). Not recommended for direct calls, use Thread type instead.

c_pthread_mutex_init: MultiMethod with 2 methods

c_pthread_mutex_lock: Call PTHREAD_MUTEX_LOCK(3)

c_pthread_mutex_unlock: Call PTHREAD_MUTEX_UNLOCK(3)

c_pthread_mutexattr_init: Call PTHREAD_MUTEXATTR_INIT(3)

c_pthread_mutexattr_settype: Call PTHREAD_MUTEXATTR_SETTYPE(3)

c_pthread_self: Call PTHREAD_SELF(3)

c_read: Read from a file. Uses READ(2).

c_readdir: Call READDIR(3)

c_stat: Call STAT(2)

c_strcasecmp: Call STRCASECMP(3)

c_strcmp: Call STRCMP(3)

c_strerror: Call STRERROR(2)

c_strftime: Call STRFTIME(3)

c_strptime: Call STRPTIME(3)

c_time: Get time as the number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). Wraps TIME(2).

c_waitpid: Call WAITPID(2)

C_WEXITSTATUS: Use WEXITSTATUS macro.

c_write: Write to a file. Uses WRITE(2).

C_WTERMSIG: Use WTERMSIG macro.

cached: Cache cb results. Runs cb only once. TODO: Support arguments.

calculate_num_cols_to_show: Internal method. Please do not use.

call: MultiMethod with 2 methods

ceil: Ceil a number

cell_display_width: MultiMethod with 3 methods

child_fd: MultiMethod with 2 methods

chr: Get character (byte) by it's ordinal value.

close: MultiMethod with 3 methods

close_reading_end: Close reading end of the Pipe

close_writing_end: Close writing end of the Pipe

code: MultiMethod with 8 methods

collector: MultiMethod with 4 methods

column: MultiMethod with 2 methods

columns: Get values in all table columns.

compile: Compile NGS source to bytecode.

config: MultiMethod with 2 methods

converge: Ensure that resources matching resource definition have given properties. This operation will do necessary changes, including creating the resource(s) if they do not exist.

copy: MultiMethod with 3 methods

count: MultiMethod with 3 methods

create: MultiMethod with 13 methods

created: Called by create() on new resources. Appends the new resources to the list and runs update(). Don't call directly.

debug: MultiMethod with 2 methods

decode: MultiMethod with 8 methods

decode_hex: Undocumented

decode_json: Decode (parse) JSON.

decode_uri_component: Decodes URI component, unsecaping %XX hexadecimals

del: Delete hash key. Throws KeyNotFound if k is not in h. WARNING: this method will probably be renamed to "delete" in future versions.

delete: MultiMethod with 17 methods

dflt: MultiMethod with 6 methods

die: Write message in s to standard error and exit, printing backtrace

digest: Convert an array to a possibly shorter version, for displaying to human.

dir: MultiMethod with 3 methods

drop: MultiMethod with 2 methods

dump: Low-level data structure dump. Used for debugging NGS itself.

dup2: Duplicate a file descriptor. Uses DUP2(2). Handles EINTR.

dup2_reading_end: DUP2(2) reading file descriptor

dup2_writing_end: DUP2(2) writing file descriptor

each: MultiMethod with 17 methods

each_chunkexperimental: Call cb with array of maximum length of n, repeatedely for all items of e. TODO: better doc

each_group_test: Undocumented

each_idx_key_val: Iterate a Hash.

each_idx_val: MultiMethod with 2 methods

eachk: Iterate a Hash.

eachv: Iterate a Hash.

echo: MultiMethod with 5 methods

encode: Encode data as JSON if hints say that "filename" ends with ".json"

encode_hex: Encodes each character in a string as two uppercase hexadecimal digits

encode_html: Encodes HTML. Escapes &, < and > .

encode_html_attr: Encodes HTML attribute. Escapes &, <, >, " and ' .

encode_json: Encode JSON (serialize a data structure to JSON)

encode_uri_component: Encodes URI component, escaping with %XX hexadecimal codes.

ends_with: Check whether a string ends with another string

ensure_array: Optionally, wrap x in an array. Return x if it's already Arr.

error: Write error message to standard error.

exception_specific_message: MultiMethod with 2 methods

exit: MultiMethod with 2 methods

ExitCode: MultiMethod with 10 methods

expect: MultiMethod with 2 methods

fetch: MultiMethod with 4 methods

filter: MultiMethod with 12 methods

filterk: Filter hash by keys, keeping matched

filterv: Filter hash by values

finally: Run cleanup after successful execution of body or exception in body

find: MultiMethod with 25 methods

find_if_needed: Populates .resources by running .find(), if it was not done yet.

find_in_path: 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

finished_ok: MultiMethod with 5 methods

first: MultiMethod with 3 methods

flatten: Flatten one level.

floor: Floor a number

get: MultiMethod with 15 methods

glob: Work in progress, do not use!

global_not_found_handler: Called when reading undefined global. Implements autoloading. Searches in $NGS_DIR/autoload/GLOBAL_NAME.ngs WARNING: May have security implications when looking up a name from untrusted source.

globals: Get all global variables as Hash

gmtime: Low-level function. Do not use directly. Use Time type.

group: Group items from e by key returned by cb

has: Exactly same as "element in container". It's just more convenient in specific cases.

hash: Calculate hash value. Same function that Hash uses internally. Currently Fowler-Noll-Vo (FNV) hash function.

id: MultiMethod with 3 methods

identity: The identity function. Simply returns the given parameter.

ids: Get IDs of the resources matching resource definition.

in: MultiMethod with 9 methods

index: Find index of first value that satisfies the predicate. TODO: Make it work on anything with each() method. In future, will throw exception if element is not found and default is not provided. Now returns null for backwards compatibilty in this case.

indexes: MultiMethod with 2 methods

inherit: Make t inherit from parent. Do not use directly. Use "type MyType(parent)".

init: MultiMethod with 86 methods

inspect: MultiMethod with 13 methods

intersperse: %EX [1,2,3].intersperse(0) # [1,0,2,0,3]

ip: Get closure code instruction pointer.

is: 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: "is not" operator. Exactly same as "not(a is b)".

is_blocked_group: Undocumented

is_global_variable_defined: Do not use directly! Check whether global variable is defined by index.

isatty: Check whether given fd represents a TTY. Uses ISATTY(3). Throws TtyCheckFail.

join: MultiMethod with 5 methods

keys: MultiMethod with 2 methods

kill: MultiMethod with 3 methods

latest: MultiMethod with 2 methods

len: MultiMethod with 9 methods

limit: MultiMethod with 3 methods

lines: MultiMethod with 9 methods

ll_hash_entry_key: Low level. Do not use directly.

ll_hash_entry_next: Low level. Do not use directly.

ll_hash_entry_val: Low level. Do not use directly.

ll_hash_head: Low level. Do not use directly.

ll_hash_tail: Low level. Do not use directly.

ll_thread_local: Get thread-local storage

load: Load compiled bytecode.

localtime: Low-level function. Do not use directly. Use Time type.

log: MultiMethod with 3 methods

lstat: MultiMethod with 2 methods

lte: Case-insensitive LessThan or Equal comparison for strings

map: MultiMethod with 8 methods

map_base_idxdeprecated: Deprecated. Map when there is more than one element. If there is exactly one element, it's left as is

map_idx_key_val: MultiMethod with 2 methods

map_idx_val: MultiMethod with 2 methods

mapk: Map Hash keys. Build new Hash with same values as in h but keys mapped by mapper.

mapkv: Map Hash keys and values. Build new Hash with keys and values mapped by mapper.

mapoexperimental: EXPERIMENTAL! Do not use! Map e to same type. Mnemonics: "map original" / "MAP to Original type".

mapv: Map Hash values. Build new Hash with same keys as in h but values mapped by mapper.

match: Used by match EXPR { ... } construct to check whether the expression matches the case. %AUTO match EXPR { ... }

max: MultiMethod with 3 methods

merge_sorted: Merge sorted arrays.

method_not_found_handler: MultiMethod with 0 methods

min: MultiMethod with 3 methods

myip: Undocumented

ndeprecated: Convert hash values to integers where possible

next: MultiMethod with 7 methods

none: MultiMethod with 2 methods

nop: Do nothing

normalize_presence_list: Internal method. Please do not use. Converts Presence or Arr[something] to Arr[Presence]. Used by Res and friends.

not: MultiMethod with 2 methods

not in: "not in" operator. Exactly same as "not(a in b)"

nuke_nulldeprecated: DEPRECATED in favor of Argv facility. 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

only: Transform mapper to handle only items matching predicate. Non-matching items will be returned as is.

open: 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.

opt_prop: MultiMethod with 2 methods

ord: MultiMethod with 2 methods

params: MultiMethod with 2 methods

parent_fd: MultiMethod with 2 methods

partial: Returns partially-applied function

partial_tail: Same as partial() but the bound arguments are last ones

partition: Partition elements in something according to the predicate into two arrays. First array contains all elements for which predicate(elt) is true and the second array contains all elements for which predicate(elt) is false.

peek: MultiMethod with 5 methods

pid: Get process ID

pmap: Parallel map. Runs mapper in threads. Each thread processes one element from the array but this might change in future (preserving the total number of calls to mapper and the order of results).

pop: Pop item from an array. Removes last item in array and returns it. Throws EmptyArrayFail.

pos: MultiMethod with 2 methods

ppid: Get parent process ID

Pred: MultiMethod with 6 methods

print_exception: MultiMethod with 2 methods

ptimes: Run cb in n parallel threads. Each thread runs one cb but this might change in future (preserving the total n calls to cb).

push: MultiMethod with 8 methods

push_all: Push all elements of e into dst.

rand: MultiMethod with 7 methods

rand_uniq: Pick n random unique elements from something

read: MultiMethod with 7 methods

reduce: MultiMethod with 2 methods

register_column: Internal method. Please do not use.

reject: MultiMethod with 2 methods

rejectk: Filter hash by keys, removing matched. See filterk().

rejectv: Filter hash by values

release: Release the lock

replace: MultiMethod with 4 methods

report: Undocumented

req_prop: Get resource property, looking up in properties first and then in anchor

require: Runs the given file

resolve_global_variable: Do not use directly! Get global variable index by name.

resolve_instruction_pointer: Resolves Instruction Pointer to source location

retry: Retry. Executes given "body" "times" times. Throws RetryFail if all calls fail and fail_cb is not provided.

reverse: Make new array which is a reversed given array

round: Round a number

run: MultiMethod with 4 methods

SafeStrexperimental: Don't use, subject to change, including name

set: Sets the given field to the given value

set_global_variable: Do not use directly! Set global variable by index.

shift: MultiMethod with 4 methods

sort: MultiMethod with 3 methods

sortk: Sort Hash by keys

specific: EXPERIMENTAL, do not use outside of stdlib! Instanciates Path sub-type, depending on what p is

split: MultiMethod with 3 methods

srand: Seed random generator. Uses SRANDOM(3).

starts_with: Check whether a string starts with another string

stat: MultiMethod with 2 methods

status: MultiMethod with 4 methods

stdlib_aws_straighten_tags: MultiMethod with 3 methods

store: encode() and write() the data to the file

StrForTable: MultiMethod with 4 methods

strftime: Low-level function. Do not use directly. Use Time type.

StrParams: Do not use!

Strs: Build array of Str where each resulting string is of the form "KEY=VALUE"

subset: MultiMethod with 2 methods

sum: Calculate sum of the elements

table: DEPRECATED.

take: MultiMethod with 2 methods

tap: Call cb with val

test: MultiMethod with 2 methods

the_one: MultiMethod with 3 methods

throw_if_no_next: Private method of Iter.ngs, will be hidden in future.

time: MultiMethod with 2 methods

times: Call cb n times without arguments.

to_exit_codedeprecated: Deprecated. Use ExitCode.

trunc: Truncate a number

typeof: Returns type of the given object

uniq: Return unique values. Warning: uses Hash so comparison is not using == but a built-in hash keys comparison.

unshift: Prepend one element to the given array

update: MultiMethod with 16 methods

users_ids: MultiMethod with 2 methods

values: MultiMethod with 2 methods

wait: MultiMethod with 2 methods

warn: Write warning message to standard error. Prints backtrace if NGS_TRACE_WARNINGS environment variable is not an empty string.

width: Internal method. Please do not use.

without: MultiMethod with 5 methods

write: MultiMethod with 8 methods

zip: 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

~: MultiMethod with 8 methods

~~: MultiMethod with 2 methods

bootstrap_debug(s:Any) Source: bootstrap.ngs:69: Undocumented