Syntax

The command strings in vCommands employ a simple syntax for fulfilling the most basic needs. Other needs are usually satisfied by a few default commands.
The introduction page contains details about the origin and inspiration of the syntax.

Command invocations

The most basic syntactic feature is command invocations.

These are denoted by a command name, optionally preceded by a toggler, and an optional sequence of constant or compound arguments.

The toggler can be either + (positive), - (negative), or even absent (neutral). This was introduced to make a few commands much more expressive.

The command name can be a fully-qualified constant string (as shown in the next section), but it is recommended to keep them short, descriptive and limited to alphanumeric characters with few symbols.

The command name and the arguments must be separated by at least one white-space (space, tabulator or newline).

Here are a few examples of command invocations:

hi
-hello
eval yada
+echo blah
-echo a b c d e f g h i j k l m n o p q r s t u v w x y z

Constant arguments and strings

These are the building blocks of command invocations.

A constant string is required for a command name, and such a string can also be passed as argument to a command.

Any string that does not contain a white-space or any syntax-contributing characters (+ - [ ] ? ! : ;) is a fully-qualified constant string on its own.

Should a constant string require a character mentioned above (including white-spaces), it can be escaped.
A \ (backslash) will make the character directly after it be interpreted literally in the string. Backslashes themselves need escaping too.

A string can also be surrounded with " (double-quotes), and every character inside (except ") will be interpreted literally.
For a literal ", it needs to be escaped.
The double quotes may also be preceded or succeeded by characters (non-separated by white-space), and those characters will be affixed to the enclosed strings.

A few examples of constant strings: (what is inside an inlined code block is the interpretation)

simple simple
c\ompl\ex complex
with\ space with space
yes;semicolon yes;semicolon
"with many characters" with many characters
"with+characters-and;syntax?symbols!" with+characters-and;syntax?symbols!
"I contain "double-quotes"" I contain "double-quotes"
abc"d e f"ghi abcd e fghi
a"b c"d"e f"g"h i"j ab cde fgh ij

Conditionals

These are expressive control structures.

They contain a condition, a primary action and an optional secondary action.
The conditional can be inclusive or exclusive, and they are signaled with a different operator.

The ? (question mark) character creates an inclusive conditional and introduces a primary action.
The ! (exclamation mark) character creates an exclusive conditional and introduces a primary action.
The : (colon) character introduces a secondary action to an already-existing conditional.

If the condition evaluates to the required truth value (true for inclusive ? and false for exclusive !), the primary action is evaluated. Otherwise, if a secondary action is found, it is evaluated.

All conditionals are left-associative, meaning that a ? b ? c means (a ? b) ? c.
Likewise, a ! b ! c means (a ! b) ! c.
Secondary actions also belong to the conditional to their left, meaning that a ? b : c ! d means (a ? b : c) ! d.
(Note: Parentheses in examples are only for suggestion! a, b, c and d are placeholders for command invocations)

Here are some examples of conditional structures (inside inlined blocks) and how they are executed in pseudo-code:

a ? b if a then b
a ! b if not a then b or unless a then b
a ? b : c if a then b else c
a ! b : c unless a then b else c or if a then c else b
a ? b ? c ? d if a then b; if b then c; if c then d. If a is false, nothing else is executed.
a ? b : c ! d if a then b else c; d is evaluated if the last evaluated expression (either b or c in this example) is false.

It would be naive to think that a ? b ! c and a ? b : c are the same.
Having in mind left-associativity, a ? b ! c will execute b if a is true, otherwise it will execute c. However, if b is executed and returns false, c will be executed!

Series

These represent a basic sequence of commands.

The commands are separated by a ; (semicolon) and they are all executed in order, from left to right.

This takes precedence over every other expression, except compound arguments!

The following examples show how various commands are separated (with the aid of hypothetical parentheses):

a ? b; c (a ? b); c
a; b ? c a; (b ? c)
a ? b; c ! d : e (a ? b); (c ! d : e)
a b c; d e f (a b c); (d e f)

Compound Arguments

These allow forwarding an expression's output to a command, as argument.

A compound argument starts with a [ (opening square bracket) and ends in a ] (closing square bracket).
Any expression can be located within, including other compound arguments, and series.

Examples

Here you may see an example of a syntactically-correct statement:

eq [cvar a] [cvar b] ? echo "the two cvars are equal" : +cvar b [cvar a]; echo "... done" Checks if cvars a and b have equal values. If they do, it prints the two cvars are equal, otherwise it changes the value of cvar b to that of cvar a. After this, it simply prints ... done.

How it works

For details on control flow, please check the Parser page.