☰

# API naming design

The API is designed to be easy to use and consistent. Ease of use is measured by the number of calls to achieve a concrete high-level action.

# Naming scheme

The library uses a simple naming scheme that makes use of common abbreviations to keep the names short but meaningful. Since version 0.8.2 many symbols have been renamed to fit this scheme. The ultimate goal is that the programmer can guess a name.

English word | To use | Notes
--- | --- | ---
initialize | initT | `init` is used to create a value type `T`
new | newP | `new` is used to create a reference type `P`
find | find | should return the position where something was found; for a bool result use `contains`
contains | contains | often short for `find() >= 0`
append | add | use `add` instead of `append`
compare | cmp | should return an int with the `< 0` `== 0` or `> 0` semantics; for a bool result use `sameXYZ`
put | put, `[]=` | consider overloading `[]=` for put
get | get, `[]` | consider overloading `[]` for get; consider to not use `get` as a prefix: `len` instead of `getLen`
length | len | also used for number of elements
size | size, len | size should refer to a byte size
capacity | cap |
memory | mem | implies a low-level operation
items | items | default iterator over a collection
pairs | pairs | iterator over (key, value) pairs
delete | delete, del | del is supposed to be faster than delete, because it does not keep the order; delete keeps the order
remove | delete, del | inconsistent right now
remove-and-return | pop | `Table`/`TableRef` alias to `take`
include | incl |
exclude | excl |
command | cmd |
execute | exec |
environment | env |
variable | var |
value | value, val | val is preferred, inconsistent right now
executable | exe |
directory | dir |
path | path | path is the string "/usr/bin" (for example), dir is the content of "/usr/bin"; inconsistent right now
extension | ext |
separator | sep |
column | col, column | col is preferred, inconsistent right now
application | app |
configuration | cfg |
message | msg |
argument | arg |
object | obj |
parameter | param |
operator | opr |
procedure | proc |
function | func |
coordinate | coord |
rectangle | rect |
point | point |
symbol | sym |
literal | lit |
string | str |
identifier | ident |
indentation | indent |