Elvis can evaluate expressions involving numbers, strings, and boolean values, using a C-like syntax. These are used in several EX commands, one VI command, and a couple of other situations.
There are two syntaxes. The normal syntax is extremely similar to C, and is used in circumstances where you probably would never use a literal value, such as for the :if command. The simpler syntax makes literal values easier to enter, while still making the full power of the expression evaluator available if you need it.
The normal syntax is intended to resemble the syntax of the C programming language very closely. You can't define your own functions or use flow-control constructs though; you can only use expressions. In traditional C documentation, these would be called "rvalues." Basically that means you can use literal values, option names, operators, parentheses, and some built-in functions.
\b, \E
(uppercase, representing the Esc character), \f,
\n, \r, and \t.
Also, you can use \\ for a literal backslash character, or
\" for a literal double-quote character within a string.
The following examples produce exactly identical results.
:calc "8" 8 :calc 8 8 :calc 010 8 :calc 0x8 8 :calc '\b' 8
You can also use option names in elvis the same way you would use variable names in C.
:calc list false :calc scroll 12 :calc display normal
Additionally, a dollar sign followed by the name of an environment variable is replaced by the value of that environment variable. If there is no such environment variable, then elvis will act as though it exists and has a null value.
In some circumstances, you can use a dollar sign followed by a digit to access special arguments. This is used in error messages and also in the values of a few options, as described in section 13.6. These special arguments can only be supplied by elvis' internal code, and it only supplies them in a few special circumstances so you can't use them in :calculate, for example.
Also, the / operator can be used to combine a directory name and a file name, to form an absolute pathname. Here are some examples showing how this works in DOS:
:set dir home directory=C:\temp home=C:\ :calc dir/"tempfile" C:\temp\tempfile :calc home/"elvis.rc" C:\elvis.rc
:calc \[("port" << 6)\]
[port ]
:calc \[("starboard" >> 6)\]
[rboard]
: and third argument are optional; if omitted,
then elvis mentally sticks :"" on the end of the expression.
quote()
and unquote() functions.
(no operator), except that
(no operator) has an extremely high precedence, and
; has an extremely low precedence.
:calc 1+2 3*4 93 :calc 1+2;3*4 312
The :eval command uses the simpler syntax, and the :echo command displays its arguments. These commands can be used together to experiment with the simpler syntax, the same way we used :calculate to experiment with the normal syntax.
:eval echo TERM=$TERM TERM=xterm :eval echo home=(home) home=/home/steve :eval echo 2+2=(2+2) 2+2=4
.------------------.--------------------------------------------.
| FUNCTION(ARG) | RETURN VALUE |
|------------------|--------------------------------------------|
| strlen(string) | number of characters in the string |
| toupper(string) | uppercase version of string |
| tolower(string) | lowercase version of string |
| isnumber(string) | "true" iff string is a decimal number |
| htmlsafe(string) | convert characters from ASCII to HTML |
| hex(number) | string of hex digits representing number |
| octal(number) | string of octal digits representing number |
| char(number) | convert number to 1 ASCII char, as a string|
| quote(list,str) | insert backslashes before chars in list |
| unquote(list,str)| remove backslashes before chars in list |
| exists(file) | "true" iff file exists |
| dirperm(file) | string indicating file attributes |
| dirfile(file) | filename.ext part of a path |
| dirname(file) | directory part of a pathname |
| dirdir(file) | directory, like dirname(file) |
| dirext(file) | extension (including the . ) |
| basename(file) | filename without extension |
| fileeol(file) | newline style of the file |
| absolute(file) | return a full path-name for a given file |
| getcwd() | return the current working directory name |
| elvispath(file) | locate a file in elvis' configuration path |
| shell(program) | run program, and return its output |
| knownsyntax(file)| language of a file if in elvis.syn, else ""|
| buffer(bufname) | "true" iff buffer exists |
| alias(name) | "true" iff an alias exists with that name |
| current(item) | value indicating an aspect of elvis' state |
| line(bufname,num)| return the contents of a given line |
| feature(name) | "true" iff a given feature is supported |
^------------------^--------------------------------------------^
(Note: "iff" is short for "if and only if")
Some of these deserve further comment.
The isnumber() function uses the same test that the operators use when deciding whether to use the string version or the number version of their behavior. You can use isnumber() to predict how operators will behave.
The hex() and octal() functions return strings which look like C-style hex or octal constants, respectively. The isnumber() function will return false when passed one of these strings; they are no longer considered to be numbers. In fact, the only reason you can use hex and octal literals is because they are converted into decimal strings by the parser, before evaluation even begins. The following example demonstrates that hex literals are converted to decimal, and that the value returned by hex() is something else.
:calc strlen(0xff) 3 :calc strlen(hex(255)) 4
The char() function returns a one-character string;
that character's decimal value will be the argument number.
For example, "char(65)" returns "A".
Note that the returned value does not look quite like
a character constant.
The quote() and unquote() functions add and remove backslashes before special characters. The backslash character itself is always considered to be "special," so backslashes are converted to double-backslashes and vice versa. In the argument, any characters which precede the first comma are used as a list of other special characters, and the remainder of the argument is the string to be quoted/unquoted. For example...
:set t="/* regexp */" :set r="*^$/.[" :eval /(quote(r, t))/... will search for the next instance of of the literal string "/* regexp */". The '/' and '*' characters won't be treated as metacharacters in the regular expression, because the quote() function inserts backslashes before them. Also, notice that the comma operator concatenates two strings and inserts a comma between them. That's handy!
The dirperm() function returns one of the following strings to indicate the file's type and permissions:
The fileeol() function opens the file in binary mode,
reads the first hundred bytes, and inspects those bytes to make a guess about
the file's newline format.
It is commonly used for setting the readeol
option.
fileeol() returns one of the following strings:
The elvispath() function searches through the directories listed in the elvispath option's value, looking for the argument file name. If it is found, then the full pathname of the file is returned; otherwise it returns a null string.
The absolute() function attempts to construct a full pathname for a given file name. If the given file name is actually a URL, or if it is already a full pathname, then this function returns it unchanged. Otherwise it combines the getcwd() value with the given name.
The knownsyntax() function determines whether the given file can be displayed in the syntax display mode. It does this by looking for the file name extension in the elvis.syn configuration file. If the file's extension is listed there, then this function returns the name of the language. Otherwise, it just returns an empty string.
The current() function examines elvis' internal variables, and returns a string indicating the value of one of them. The argument determines which variable is examined, as follows:
showtag option is false, or the
cursor is located above the first tag defined in this file, then current("tag")
will return an empty string.
The line() function returns the contents of a single line from an edit buffer. If two arguments are given, then the first argument is taken to be the name of the edit buffer, and the second argument is used as the line number. If only one argument is given, then it is assumed to be a line number within the current buffer. If no arguments are given, then it assumes it should use the current line of the current buffer. If the line is too long to fit in the result variable, then it is truncated.
The feature() function is intended to allow you to write
EX scripts which work with different configurations of elvis.
For example, you can compile elvis without support for the hex display mode;
if you do that, then feature("hex") will return false.
Currently feature() returns true for all
supported display modes, network protocols, and maybe "showtag" and "lpr";
it returns false for anything else.
As new features are added to future versions of elvis,
I expect to add them to feature()'s list.
The :if command evaluates its argument using the normal syntax. If the resulting value is any Boolean true value then a flag is set; otherwise the flag is reset. After that, you can use :then and :else commands to conditionally execute some commands, depending on the state of that flag.
The :eval command evaluates its arguments using the simpler syntax. The resulting string value is then interpreted as an EX command line. This gives you a way to use the expression evaluator with commands which otherwise wouldn't evaluate expressions.
The :let command allows you to change the
values of options.
Its syntax is ":let option=expression",
where expression is any expression using the normal syntax.
You can use this to change the value of any unlocked option,
similarly to :set.
:set i=14 :calc i 14 :let i=i+1 :set i? i=15 :eval set i=(i*2) :calc i 30 :let elvispath="." :let list="false" :let sidescroll=0x10
Note that the = operator only works this way when used with the v command for marking characters. If you visibly mark lines, or use the traditional =movement syntax, then elvis will send the selected lines though the external filter program named in the equalprg option.
The # command doesn't use expressions, but it does perform some simple math.
The full power of the expression evaluator is available; you can use it to do more than just expand environment variable names. For example, you could store the name of a file in one of the user options, and then later use that option name in parentheses wherever a filename was expected.
:set f=myfile.txt :w (f) wrote myfile.txt, ...
If you use this trick, remember that it only works when elvis is expecting a file name. It won't work when invoking external programs, because elvis doesn't know which program arguments are supposed to be file names. Elvis always passes program arguments literally.
Recall that when a backslash character is followed by an alphanumeric character, both the backslash and the alphanumeric character become part of the resulting value. This was done mostly for the benefit of file names. If the backslash was always dropped then MS-DOS users would have a heck of a time entering pathnames of files! By making the backslash a little smarter, we avoid that problem.
:eval echo c:\tmp \(notice the backslashes\) c:\tmp (notice the backslashes)
To simplify the task of writing portable ex scripts, the behavior of the / operator has been extended. When one or both of its arguments are strings, it concatenates them as a directory name and a file name, yielding a full pathname.