Skip to content

Manual

Jump to bottom
Sneha De edited this page Mar 24, 2025 · 1 revision

The full manual for KeplerKV including syntax and command specifics.

Last updated: 2024-12-29

Contents

General syntax

Tokenization

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

Command syntax

Commands are case-insensitive 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

Identifiers are case-sensitive and must begin with an alphabetical character or an underscore, with any alphanumeric or underscore characters permitted afterwards.

Examples of allowed identifiers
_name
Age age (different from Age!)
_patient0

Examples of disallowed identifiers
0patient Cannot start with a number
hash# Only alphanumeric characters and underscores are allowed

Running mode

KeplerKV can be ran interactively simply by not passing in any .kep files. When at least one is passed in, the program runs these script files.

./KeplerKV              # Interactive mode
./KeplerKV script.kep   # Non-interactive mode

All commands in a .kep file must be ended with a semicolon.

Options

Global options are ran at the program-level. That is, these are command-line arguments passed in when running the executable:

  • -h: View the help menu
  • -s, --silent: Run the program silently, with some exceptions

Command options are applicable to each command specifically. These should be double-dashed always.

  • --y, --yes: Say YES to any prompts that may spawn during execution
  • --y, --yes: Say NO to any prompts that may spawn during execution

Example: name conflict

\set a 1
\set b 2
\rename b a             # Will get prompted to confirm this overwrite
> Warning: key 'a' already exists. Do you want to overwrite it? (y/n)

---
\rename b a --yes       # Will answer prompt
    OK

\rename b a --no   
    No changes made to the store.

Commands: System

QUIT

{\q, \quit}

Quit the KeplerKV program.

CLEAR

\clear

Clear the terminal screen, returning to the > prompt.

SAVE

\save [filename]

Save the current state of the store into a save file of .kep extension.

\set a 1
\save manual
    SAVED

Valid filenames

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

\load [filename]

Load in a store state from a valid save file produced from SAVE, denoted by the .kep extension.

\load manual
    LOADED

STATS

\stats

Displays basic statistics about the current instance of KeplerKV, including the total number of keys by type, and the memory usage.

Commands: Data

SET

{\set, \s} key value [k2 v2 k3 v3 ...]

Set a key-value pair to the store.

Supported types

  1. Integers
\set num 1
  1. Floats
\set num 1.2
  1. 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'
  1. Lists
\set list [1, 2, 3]

Multidimensional lists are supported.

\set matrix [[1, 2, 3], [4, 5, 6], [7, 8, 9]]

GET

{\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

{\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

{\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

{\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

{\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.

Lazy evaluation

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

Data manipulation

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

{\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

\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

Commands: Data Manipulation

INCR

\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

\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

\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

\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]

Commands: Transactions

BEGIN

\begin

Begins a transaction.

All commands will still be validated. If a command is incorrect, errors will be reported and the command will not be logged.

Certain commands occur in real-time regardless of whether you are in a transaction or not. These include:

  • QUIT
  • LIST
  • SAVE
  • LOAD
  • SEARCH
  • STATS

COMMIT

\commit

Commits a transaction.

Each logged command will be performed at this time.

ROLLBACK

\rollback

Rollbacks a transaction.

All commands that were logged are discarded.

Clone this wiki locally