This document contains commonly used words, concepts and jargon for the Carp programming language. It should be particularly helpful when naming things and writing documentation. Ideally it will remove ambiguity, make us spell things the same way, and generally make the Carp ecosystem feel more unified.
Pull requests for this document are very welcome, and please tell us in the Gitter Channel if something is missing!
What should this mean exactly? Ideally it should only be used for functions ending in a ! that return (). Perhaps it should be called "externally mutating function"..? Or maybe "exo-functions" :)
An owning function is a function that takes ownership over the value it is passed. This means that is has responsibility of freeing that memory (or pass it to another owning function, or return it).
A borrowing function is a function that does not take ownership over the value it is passed. This means that is is not allowed to free the memory of that value but must leave it intact.
What is a good name for a function that is both owning and internally mutating, like endo-map? These functions are common in Carp and allow for a functional programming style without the need to copy or allocate memory.
Unsafe functions (most often) start with the prefix unsafe- and can crash the program if certain preconditions are not met. A good example is Array.unsafe-first which gets the first value in an array. Calling this if the array is empty will crash the program.
The unsafe- prefix is an optional naming convention; there are a few functions that are not safe which does not use this naming scheme. A notable example is Array.nth which crashes if given an invalid index. Any other unsafe functions should be thoroughly documented as such, and using the unsafe- prefix is very much encouraged in library code!
REPL stands for "Read Eval Print Loop" and is a common feature of a Lisp system. It allows expressions to be entered and executed at a command prompt. In Carp it is spelled with uppercase letters.