Commands

vCommands is, as the name suggests, centered around commands.

These commands can be invoked under an evaluation context, with a toggle status and a set of arguments, delivered as raw expressions.

Base command

Every command derives from an abstract Command class.

Every command has an Invocation event which is raised before the actual invocation.
This event provides most information needed and the possibility to cancel the invocation with a custom message. (status code is implicitly -2)

Each command has a name (by which it is looked up), a category (which defaults to Miscellaneous) and an abstract (short description for help text; defaults to empty). These are accessible to properties which are named accordingly: Name, Category and Abstract.

Types of commands

Currently, there are 3 types of commands, each with a unique and specific purpose.

Methods

These commands wrap around a .NET delegate which has the following signature:

public delegate EvaluationResult CommandMethod(bool? toggle, EvaluationContext context, Expression[] args);

Method commands must be initialized with a non-null instance of this delegate, and it cannot be changed after.
The invocation of the command is simply forwarded to this delegate, which is responsible for its functionality: Checking context, evaluating arguments, returning results.
Worthy of remembering is the toggle status - a trit: + = true, - = false, absent/none = null.

Any thrown exceptions are caught and returned with status code -1.
A lack of permission to execute the command should return status code -2.

It would be best if every unique possible error would have a unique status code. (on a per-command basis, at least)
A status code of 0 universally means success.
(The philosophy behind this is that, there is only one way a command could go well, but many more ways it could go wrong.)

A command's abstract should at least explain what it does without a toggler, shortly and concisely, as such:

help - Displays every available command and its description.

Aliases

These work similarly to Bash's aliases; they are a base expression.

The default command for creating an alias command is named alias.
It is used as such:

alias test [+echo "This is a test:"]

This creates an alias named 'test' with the given body.
Invoking an alias appends any given arguments to the given expression, simply.
Unlike user commands, aliases need to be turned into strings and re-parsed with additional arguments.

Thus, executing the following:

test asd fgh

Will print the following:

This is a test: asd fgh

Another example:

alias decimate [mul 0.9]  
decimate 300  

Will yield:

270

User commands

These are commands defined by a user, much more powerful than aliases.
The main difference is, they have access to arguments.

They require creating a sub-context of evaluation for storing their arguments, which implies a trivial but still existing overhead over aliases.
However, unlike aliases, the raw expressions are stored and always re-evaluated under different contexts.

The default command for creating a user command is define:

define cabs [eq [argc] 2 ! echo "Need two numbers as arguments" : sqrt [add [mul [arg 1] [arg 1]] [mul [arg 2] [arg 2]]]]  

This requires a bit more explanation: argc returns the number of arguments passed to the user command; eq checks all its arguments for equality. arg is a command that takes one argument, a 1-based index and it returns that specific argument passed to the user command.
So what this user command does is calculating the absolute value of a complex number (x + iy), by executing cabs x y. If it does not get exactly two arguments, it outputs "Need two numbers as arguments".
mul multiplies its arguments' numeric values, add adds its arguments' numeric values and sqrt outputs the square root of its argument's numeric value.
Thus, it is equivalent to the formula , where x and y are the two required numeric arguments.

Here are a few usage examples and their output:

cabs Need two numbers as arguments
cabs blah Need two numbers as arguments
cabs 1 2 3 4 5 6 Need two numbers as arguments
cabs 3 4 5
cabs 10 0 10
cabs 10 15 18.0277563773199