The full manual for KeplerKV including syntax and command specifics.
Last updated: 2024-09-06
- General syntax
- Commands: System
- Commands: Data
- Commands: Data Manipulation
All tokens are assumed space-delimited and whitespace is ignored.
Optional comma delimiters can be used for clarity, be sure to separate distinct tokens by spaces when required. For example, the following examples show equivalent commands:
\set apple 1 banana 2
\set apple 1, banana 2
\set apple,1 banana,2
\get apple banana
\get apple, banana
Multiple commands can be completed at once by separating them with semicolons:
\set a 1 ; \get a
OK # confirmation of \set
a | int: 1 # output of \get
Commands are case-insentive and may have alternate syntax. This documentation denotes commands and their arguments as:
{set of equivalent invocations} required-argument [optional-arguments]
Many commands allow for batching such that multiple of the same command can be invoked:
\get a b
a | ...
b | ...
Identifiers are case-sensitive and must begin with an alphabetical character or an underscore, with any alphanumeric or underscore characters permitted afterwards.
_name |
|
Age |
age (different from Age !) |
_patient0 |
0patient |
Cannot start with a number |
hash# |
Only alphanumeric characters and underscores are allowed |
{\q, \quit}
Quit the KeplerKV program.
\clear
Clear the terminal screen, returning to the >
prompt.
\save [filename]
Save the current state of the store into a save file of .kep
extension.
\set a 1
\save manual
SAVED
Filenames follow the same rules as strings (surrounded by quotes) and identifiers. If you have spaces or special characters within a filename, it is safer to put quotes around the name.
Verify what special characters are permitted in your file system.
\load [filename]
Load in a store state from a valid save file produced from SAVE
, denoted by the .kep
extension.
\load manual
LOADED
\stats
Displays basic statistics about the current instance of KeplerKV, including the total number of keys by type, and the memory usage.
{\set, \s} key value [k2 v2 k3 v3 ...]
Set a key-value pair to the store.
-
Integers
\set num 1
-
Floats
\set num 1.2
-
Strings
\set str "hello world!"
Strings must be denoted with starting and closing quotation single or double quotation marks.
To have a quotation mark inside of a string, the inner must be of the opposite kind of the outer.
\set str 'look its a "string", nice'
-
Lists
\set list [1, 2, 3]
Multidimensional lists are supported.
\set matrix [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
{\get, \g} key [k2 k3 ...]
Get the value of a key in the store.
\set num 1
\get num
num | int: 1
If the key is not present in the store, NOT FOUND
is returned.
{\del, \delete \d} key [k2 k3 ...]
Delete a key from the store if it is present.
\set num 1
\del num
OK
If the key is not present in the store, NOT FOUND
is returned and no effect is done to the store.
{\update, \u} key value [k2 v2 k3 v3 ...]
Update the value of a key that is present in the store.
Keys must be set in the store to some initial value before they can be updated. The new value can be of a different data type than the old, keys are not held to a specific type during their lifetime!
\set id 123
\update id "an actual name!"
{\list, \ls, \l}
List out all items that are currently in the store.
\set a 1, b "abc", c [1, 2, 3]
\list
c | list: [int: 1, int: 2, int: 3]
b | str: "abc"
a | int: 1
{\resolve, \res, \r} key [k2 k3 ...]
Resolve the values of keys that reference another key (or form a key-chain!). RESOLVE
works identically to GET
when keys are not recursive.
Recursive keys are lazily evaluated, which means the value of the key being referenced need not be defined until resolution is required.
\set a b # a -> b
\get a
a | id: b # a references b
\resolve a
NOT FOUND # Since b is not defined, no value is found when attempting to resolve
\set b 1
\resolve a
a | int: 1 # a can be resolved to b, which resolves to an integer
\resolve b
b | int: 1 # b is not recursive and resolves to its primitive value (same output as GET)
In short: GET
only evaluates one level of the key-value pair, while RESOLVE
evaluates until a primitive is found.
Similar to C++ references, affecting b
also affects a
since a
is an alias for b
.
\update b 2
\resolve b
b | int: 2
\resolve a
a | int: 2
If manipulation commands such as [INCR](#incr)
are used upon an alias, the action will affect the alias and the referenced keys.
\set a 1
\set b a # b -> a
\incr b
\get a
a | int: 2
\resolve b
b | int: 2
{\rename, \rn} oldKeyName newKeyName [o2 k2 ...]
Renames a value's key.
\set a 1
a | int: 1
\rename a b
b | int: 1
Note: if the new key name already exists in the store, you will be asked to confirm if that key should be overwritten with the data from the old key name.
\search regex1 [r2 r3 ...]
Searches for keys using typical C++ regex rules. For the least buggy experience, format the regex argument as a string with quotes around it.
\set a 1
\set b 2
\search "."
. (2)
b
a
\incr key [k2 k3 ...]
Increment a numeric (integer or float) key. Throws an error if invoked on other types.
\set a 1
a | int: 1
\incr a
a | int: 2
\decr key [k2 k3 ...]
Decrement a numeric (integer or float) key. Throws an error if invoked on other types.
\set a 1
a | int: 1
\decr a
a | int: 0
\append key value [v2 v3 ...]
Append elements to a list. Throws an error if invoked on other types
\set a [1]
a | list: [int: 1]
\append a 2
a | list: [int: 1, int: 2]
\prepend key value [v2 v3 ...]
Prepend elements to a list. Throws an error if invoked on other types
\set a [1]
a | list: [int: 1]
\prepend a 2
a | list: [int: 2, int: 1]