@node Environment
@section Environment

@menu
* Environment - Dictionary::
* Environment - C Reference::
@end menu

@node Environment - Dictionary
@subsection Dictionary
@lspindex disassemble
@lspindex ed
@lspindex trace

@defun disassemble function-designator*
Display the assembly code of a function 
@paragraph Synopsis
@table @var
@item function-designator
A symbol which is bound to a function in the global environment, or a lambda form
@end table
@paragraph Description
As specified in ANSI @bibcite{ANSI} this function outputs the internal representation of a compiled function, or of a lambda form, as it would look after being compiled.

ECL only has a particular difference: it has two different compilers, one based on bytecodes and one based on the C language. The output will thus depend on the arguments and on which compiler is active at the moment in which this function is run.

@itemize
@item If the argument is a bytecompiled function or a lambda form, it will be processed by the active compiler and the appropriate output (bytecodes or C) will be shown.
@item If the argument is a C-compiled form, disassembling the function by showing its C source code is not possible, since that would require saving not only the lambda form of the function, but also the precise configuration of the compiler when the function was compiled. Hence no output will be shown.
@end itemize
@end defun

@defun ed x?
Invoke an editor on the file or object specified by @var{x}.
@paragraph Synopsis
(ed @var{x?})
@table @var
@item x
@code{nil}, a file path, or an object to edit.
@end table

@paragraph Description
Starts the editor (on a file or an object if named).  Functions from the list @var{ext:*ed-functions*} are called in order with @var{x} as an argument until one of them returns non-@code{nil}; these functions are responsible for signalling a @code{file-error} to indicate failure to perform an operation on the file system. If no function returns a non-@code{nil} value or @var{ext:*ed-functions*} is @code{nil} then a @code{simple-error} will be signalled.

The Common Lisp specification states that the @var{x} argument is either @code{nil}, a function name, or an instance of @var{string} or @var{pathname} and that a @var{type-error} may be signalled if is not one of these types. ECL does not check the type of @var{x} and thus permits any object to be passed to the hook functions. This allows for the possibility of editing other objects that have a representation in source code such as class definitions. Therefore, the hook functions should not make any assumptions about the type of @var{x} and should instead return @code{nil} if there is not an approriate edit method for a specific value of @var{x}.

By default @var{ext:*ed-functions*} contains a single function that attempts to run the program named in the environment variable @code{EDITOR}. If this environment variable is not set then the fallback program is @code{vi}.
@end defun

@defmac trace function-name*
Follow the execution of functions
@paragraph Synopsis
(trace @var{function-name*})
@table @var
@item function-name
@{@var{symbol} | (@var{symbol} [@var{option} @var{form}]*)@}
@item symbol
A symbol which is bound to a function in the global environment. Not evaluated.
@item option
One of @code{:break}, @code{:break-after}, @code{:cond-before}, @code{:cond-after}, @code{:cond}, @code{:print}, @code{:print-after}, @code{:step}
@item form
A lisp form evaluated in an special environment (or a list of forms for
@code{:print} and @code{:print-after}).
@item returns
List of symbols with traced functions.
@end table

@paragraph Description
Causes one or more functions to be traced. Each @var{function-name} can be a symbol which is bound to a function, or a list containing that symbol plus additional options. If the function bound to that symbol is called, information about the arguments and output of this function will be printed. Trace options will modify the amount of information and when it is printed.

Not that if the function is called from another function compiled in the same file, tracing might not be enabled. If this is the case, to enable tracing, recompile the caller with a @code{notinline} declaration for the called function.

@code{trace} returns a name list of those functions that were traced by the call to @code{trace}. If no @var{function-name} is given, @code{trace} simply returns a name list of all the currently traced functions.

Trace options cause the normal printout to be suppressed, or cause extra information to be printed. Each option is a pair of an option keyword and a value form. If an already traced function is traced again, any new options replace the old options and a warning might be printed. The lisp @var{form} accompanying the option is evaluated in an environment where @var{sys::args} contains the list of arguments to the function.

The following options are defined:
@table @asis
@item @code{:cond}, @code{:cond-before}, @code{:cond-after}
If @code{:cond-before} is specified, then @code{trace} does nothing unless @var{form} evaluates to true at the time of the call. @code{:cond-after} is similar, but suppresses the initial printout, and is tested when the function returns. @code{:cond} tries both before and after.
@item @code{:step}
If @var{form} evaluates to true, the stepper is entered.
@item @code{:break}, @code{:break-after}
If specified, and @var{form} evaluates to true, then the debugger is invoked at the start of the function or at the end of the function according to the respective option.
@item @code{:print}, @code{:print-after}
In addition to the usual printout, the result of evaluating each entry
of the list of forms contained in @var{form} is printed at the start of
the function or at the end of the function, depending on the option.
@end table
@end defmac

See also the following example:

@exindex @code{trace} usage
@example
> (defun abc (x)
    (if (>= x 10)
        x
        (abc (+ x (abc (1+ x))))))
> (trace abc)

> (abc 9)
1> (ABC 9)
| 2> (ABC 10)
| <2 (ABC 10)
| 2> (ABC 19)
| <2 (ABC 19)
<1 (ABC 19)
19
> (untrace abc)

(ABC)
;; Break if the first argument of the function is greater than 10
> (trace (abc :break (>= (first si::args) 10)))

((ABC :BREAK (>= (FIRST SI::ARGS) 10)))
> (abc 9)
1> (ABC 9)
| 2> (ABC 10)

Condition of type: SIMPLE-CONDITION
tracing ABC
Available restarts:

1. (CONTINUE) Return from BREAK.
2. (RESTART-TOPLEVEL) Go back to Top-Level REPL.

Broken at ABC. In: #<process TOP-LEVEL 0x1842f80>.
>> 
@end example

@node Environment - C Reference
@subsection C Reference

@subsubsection ANSI Dictionary
Common Lisp and C equivalence

@multitable @columnfractions .3 .7
@headitem Lisp symbol @tab C function
@item @clhs{f_dec_un.htm,decode-universal-time} @tab cl_object cl_decode_universal_time(cl_narg narg, cl_object universal_time, ...)
@item @clhs{f_encode.htm,encode-universal-time} @tab cl_object cl_encode_universal_time(cl_narg narg, cl_object second, cl_object minute, cl_object hour, cl_object date, cl_object month, cl_object year, ...)
@item @clhs{f_get_un.htm,get-universal-time} @tab cl_object cl_get_universal_time(void)
@item @clhs{f_get_un.htm,get-decoded-time} @tab cl_object cl_get_decoded_time(void)
@item @clhs{f_sleep.htm,sleep} @tab cl_object cl_sleep(cl_object seconds)
@item @clhs{f_apropo.htm,apropos} @tab cl_object cl_apropos(cl_narg narg, cl_object string, ...)
@item @clhs{f_apropo.htm,apropos-list} @tab cl_object cl_apropos_list(cl_narg narg, cl_object string, ...)
@item @clhs{f_descri.htm,describe} @tab cl_object cl_describe(cl_narg narg, cl_object object, ...)
@item @clhs{f_desc_1.htm,describe-object} @tab [Only in Common Lisp]
@item @clhs{f_get_in.htm,get-internal-real-time} @tab cl_object cl_get_internal_real_time(void)
@item @clhs{f_get__1.htm,get-internal-run-time} @tab cl_object cl_get_internal_run_time(void)
@item @clhs{f_disass.htm,disassemble} @tab [Only in Common Lisp]
@item @clhs{f_docume.htm,documentation} @tab [Only in Common Lisp]
@item @clhs{f_room.htm,room} @tab [Only in Common Lisp]
@item @clhs{f_ed.htm,ed} @tab [Only in Common Lisp]
@item @clhs{f_inspec.htm,inspect} @tab cl_object cl_inspect(cl_object object)
@item @clhs{f_dribbl.htm,dribble} @tab cl_object cl_dribble(cl_narg narg, ...)
@item @clhs{f_lisp_i.htm,lisp-implementation-type} @tab cl_object cl_lisp_implementation_type(void)
@item @clhs{f_lisp_i.htm,lisp-implementation-version} @tab cl_object cl_lisp_implementation_version(void)
@item @clhs{f_short_.htm,short-site-name} @tab cl_object cl_short_site_name()
@item @clhs{f_short_.htm,long-site-name} @tab cl_object cl_long_site_name()
@item @clhs{f_mach_i.htm,machine-instance} @tab cl_object cl_machine_instance()
@item @clhs{f_mach_t.htm,machine-type} @tab cl_object cl_machine_type()
@item @clhs{f_mach_v.htm,machine-version} @tab cl_object cl_machine_version()
@item @clhs{f_sw_tpc.htm,software-type} @tab cl_object cl_software_type()
@item @clhs{f_sw_tpc.htm,software-version} @tab cl_object cl_software_version()
@item @clhs{f_user_h.htm,user-homedir-pathname} @tab cl_object cl_user_homedir_pathname(cl_narg narg, ...)
@end multitable
