system value & command documentation
This commit is contained in:
parent
ef9d92be5c
commit
acb6909fc7
6
docs/README.md
Normal file
6
docs/README.md
Normal file
@ -0,0 +1,6 @@
|
||||
# CBQN-specific documentation
|
||||
|
||||
Only CBQN-specific things are here; for general documentation, see [the BQN documentation](https://mlochbaum.github.io/BQN/doc/index.html).
|
||||
|
||||
* [system functions](system.md)
|
||||
* [system commands](commands.md)
|
||||
41
docs/commands.md
Normal file
41
docs/commands.md
Normal file
@ -0,0 +1,41 @@
|
||||
# CBQN system commands
|
||||
|
||||
These are commands usable from a CBQN REPL that, for one reason or another, aren't suited to be system functions.
|
||||
|
||||
## `)ex path/to/file`
|
||||
|
||||
Execute the contents of the file as if it were REPL input (but allowing multiline definitions). Not a system function because modifying the list of global variables during execution is not allowed.
|
||||
|
||||
## `)t expr` / `)time expr` / `)t:n expr` / `)time:n expr`
|
||||
|
||||
Time the argument expression. `n` specifies the number of times to repeat. Exists to allow not escaping quotes and less overhead for timing very fast & small expressions.
|
||||
|
||||
## `)mem`
|
||||
|
||||
Get statistics on memory usage.
|
||||
|
||||
`)mem t` to get usage per object type.
|
||||
`)mem s` to get a breakdown of the number of objects with a specific size.
|
||||
`)mem f` to get breakdown of free bucket counts per size.
|
||||
|
||||
## `)erase name`
|
||||
|
||||
Erase the specified variable name.
|
||||
|
||||
Not a system function because it only clears the variables value (previous code `↩`ing it will still be able to), and to allow it to be executed even when the VM is completely out of memory such that it can't even parse an expression.
|
||||
|
||||
## `)vars`
|
||||
|
||||
List the globally defined variables.
|
||||
|
||||
## `)gc`
|
||||
|
||||
Force garbage collection.
|
||||
|
||||
`)gc disable` disables automatic garabage collection, and `)gc enable` enables it again.
|
||||
|
||||
Not a system function because currently CBQN doesn't support garbage collection in the middle of program execution.
|
||||
|
||||
## `)internalPrint expr`
|
||||
|
||||
Use the internal object printing system to show the expression result.
|
||||
102
docs/system.md
Normal file
102
docs/system.md
Normal file
@ -0,0 +1,102 @@
|
||||
# Supported standard system values
|
||||
|
||||
See [the BQN specification](https://mlochbaum.github.io/BQN/spec/system.html) for full descriptions of the following values.
|
||||
|
||||
| function | notes |
|
||||
|---------------|-------|
|
||||
| `•BQN` | |
|
||||
| `•ReBQN` | Supported options: `repl`, `primitives` |
|
||||
| `•primitives` | |
|
||||
| `•Import` | |
|
||||
| `•state` | |
|
||||
| `•args` | |
|
||||
| `•path` | |
|
||||
| `•name` | |
|
||||
| `•wdpath` | |
|
||||
| `•Exit` | |
|
||||
| `•file` | Fields: `path`, `At`, `List`, `Bytes`, `Chars`, `Lines`, `Type`, `Name` |
|
||||
| `•FChars` | |
|
||||
| `•FBytes` | |
|
||||
| `•FLines` | |
|
||||
| `•Out` | |
|
||||
| `•Show` | |
|
||||
| `•Repr` | |
|
||||
| `•Fmt` | |
|
||||
| `•term` | Fields: `Flush`, `RawMode`, `CharB`, `CharN` |
|
||||
| `•SH` | Left argument can be `{stdin⇐"input"}` |
|
||||
| `•Type` | |
|
||||
| `•Glyph` | |
|
||||
| `•Decompose` | |
|
||||
| `•UnixTime` | second-level precision |
|
||||
| `•MonoTime` | up to nanosecond level precision, depending on system support |
|
||||
| `•Delay` | |
|
||||
| `•_timed` | |
|
||||
| `•math` | Fields: `Sin`, `Cos`, `Tan`, `Asin`, `Acos`, `Atan`; `⁼` supported |
|
||||
| `•MakeRand` | uses wyhash, **not** cryptographically secure; Result fields: `Range`, `Deal`, `Subset` |
|
||||
| `•rand` | seeds with system time (can be hard-coded by setting the C macro `RANDSEED`), same algorithm as `•MakeRand` |
|
||||
| `•bit` | Fields: `_cast`; casting an sNaN bit pattern to a float is undefined behavior |
|
||||
|
||||
# CBQN-specific system functions
|
||||
|
||||
## `•term`
|
||||
|
||||
Besides the previously mentioned supported things, `•term.OutRaw` and `•term.ErrRaw` output the given bytes directly to the specific stream, without any trailing newline. May be removed once a proper interface for stream I/O has been made.
|
||||
|
||||
## `•_while_`
|
||||
|
||||
While `𝕨𝔾𝕩`, execute `𝕩↩𝕨𝔽𝕩`. Equivalent to `{𝕨𝔾𝕩? 𝕨 𝕊 𝕨𝔽𝕩; 𝕩}`.
|
||||
|
||||
## `•GetLine`
|
||||
|
||||
Ignores its argument and returns one line of stdin.
|
||||
|
||||
Might be removed, moved, or renamed in the future.
|
||||
|
||||
## `•Hash`
|
||||
|
||||
Get the hash of `𝕩`.
|
||||
|
||||
Monadically, use the global secret value which will differ between CBQN sessions.
|
||||
|
||||
Dyadically, use the integer left argument as the secret. Will be the same between multiple CBQN sessions, but may change between versions.
|
||||
|
||||
## `•PrimInd`
|
||||
|
||||
Return the primitive index of the argument.
|
||||
|
||||
Might be removed in the future.
|
||||
|
||||
## `•Cmp`
|
||||
|
||||
Compare arguments. Equal to `((⊑⍋-⍒)⋈)`.
|
||||
|
||||
## `•FromUTF8`
|
||||
|
||||
Convert the argument UTF-8 byte array (or character array consisting of codepoints 0-255) to a string.
|
||||
|
||||
May be removed in the future.
|
||||
|
||||
## `•CurrentError`
|
||||
|
||||
Get the current error message while within the catch side of `⎊`. Dynamically-scoped.
|
||||
|
||||
Might return a more informative object in the future (e.g. whether the error came from an `!`, the compiler or a builtin, maybe stacktrace reading, etc; such a format is TBD).
|
||||
|
||||
## `•internal`
|
||||
|
||||
Namespace of various internal functions. May change at any time.
|
||||
|
||||
| name | description |
|
||||
|----------------------------|-------------|
|
||||
| `•internal.Type` | Name of the internal type for an object |
|
||||
| `•internal.ElType` | Element size type identifier; see `enum ElType` |
|
||||
| `•internal.Refc` | Reference count of the argument, if it's heap-allocated |
|
||||
| `•internal.IsPure` | Whether the vm considers the argument pure (i.e. it can execute it safely for computing fills) |
|
||||
| `•internal.Info` | General internal info about the object; a left argument of `1` gives more details |
|
||||
| `•internal.HeapDump` | Create a heap dump file |
|
||||
| `•internal.Squeeze` | Try to convert the argument to its most compact representation |
|
||||
| `•internal.DeepSqueeze` | Try to convert the argument and all its subarrays to its most compact representation; won't squeeze namespace fields |
|
||||
| `•internal.ListVariations` | List the possible type variations of the argument array |
|
||||
| `•internal.Variation` | Convert `𝕩` to the variation specified in `𝕨` |
|
||||
| `•internal.ClearRefs` | Clear references `•internal.Variation` made for `*Inc` variations |
|
||||
| `•internal.Unshare` | Get a unique, reference count 1 version of the argument; recursively unshares array items, doesn't touch namespaces |
|
||||
Loading…
Reference in New Issue
Block a user