[#evaluating]
== Quickly evaluating expressions

It is often useful to evaluate Elisp expressions in context of the
project you develop — and probably using functions from the project.
There are two commands for this in Eldev: `eval` and `exec`.  The only
difference between them is that `exec` doesn’t print results to
stdout, i.e. it assumes that the forms you evaluate produce some
detectable side-effects.  Because of this similarity, we’ll consider
only `eval` here.

The basic usage should be obvious:

    $ eldev eval "(+ 1 2)"

Of course, evaluating `(+ 1 2)` form is not terribly useful.  Usually
you’ll want to use at least one function or variable from the project.
However, for that you need your project not only to be in `load-path`
(which Eldev guarantees), but also ``require``d.  Luckily, you don’t
have to repeat `(require 'my-package)` all the time on the command
line, as Eldev does this too, so normally you can just run it like
this:

    $ eldev eval "(my-package-function)"

What Eldev actually does is requiring all features listed in variable
`eldev-eval-required-features`.  If value of that variable is symbol
`:default`, value of `eldev-default-required-features` is taken
instead.  And finally, when value of the latter is symbol
`:project-name`, only one feature with the same name as that of the
project is required.  In 95% of the cases this is exactly what you
need.  However, if the main feature of the project has a different
name, you can always change the value of one of the mentioned
variables in file `Eldev`.

It can also make sense to change the variable’s value in `Eldev-local`
if you want certain features to always be available for quick testing.

{since-0-11} If you have larger scripts to evaluate (but still not as
standard as to abstract as a custom builder or a command), you can
evaluate expressions stored in a file using `--file` (`-f`) option:

    $ eldev eval -f useful-expressions.el

Note that this is _not_ performed using Elisp file loading.  Instead,
the file is parsed as a sequence of Elisp expression and those are
then evaluated/executed in exactly the same way as if specified on the
command line.  In particular, for command `eval` results are still
printed after every expression, even if they all come from the same
file.  As in several other places, when variable `eldev-dwim` (“do
what I mean”) is non-nil, option `-f` can be omitted as long as
filename ends in `.el`.  In other words, you can just invoke:

    $ eldev eval useful-expressions.el

for the expected effect.

To simplify command-line usage a bit, commands accept multiple
expressions in one parameter, to reduce the number of quotes to type.
E.g.:

    $ eldev eval "(+ 1 2) (+ 3 4)"
    3
    7

{since-1-1} There are “magic” variables called `@`, `@1`, `@2` and so
on, aimed at simplifying accessing to previous form results from
subsequent forms.  Variable `@` always holds the result of previous
form evaluation; it is thus not available in the very first form.
Variables `@N`, where `N` is a number, hold result of `N`’s form (`N`
starts with 1, not 0).  They can be used both in `eval` and `exec`,
even if the latter doesn’t print the results.

All forms for evaluation/execution are indexed with the same number
sequence, regardless if they come from command line (including
multiple forms per parameter) or from a file.

To illustrate:

    $ eldev eval "(generate-new-buffer \"abc\") (buffer-name @)"
    #<buffer abc>
    "abc"

Or:

    $ eldev eval "(+ 1 2) (+ 3 4) (* @1 @2)"
    3
    7
    21

{since-0-11} Commands `eval` and `exec` also have a few options aimed
at code profiling.  See <<profiling-eval,relevant section below>>.
