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