marcuskammer/cl-sites
1
0
Fork 0
Code Activity
cl-sites/ecl.common-lisp.dev/static/manual/Environment.html
Marcus Kammer a4f013bd3f
Add ecl manual
2024-12-24 19:15:49 +01:00

373 lines
21 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.0.3, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Environment (ECL Manual)</title>
<meta name="description" content="Environment (ECL Manual)">
<meta name="keywords" content="Environment (ECL Manual)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link href="index.html" rel="start" title="Top">
<link href="Indexes.html" rel="index" title="Indexes">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Standards.html" rel="up" title="Standards">
<link href="System-construction.html" rel="prev" title="System construction">
<style type="text/css">
<!--
/* colors */
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
div.example {margin-left: 3.2em}
span.r {font-family: initial; font-weight: normal; font-style: normal}
span:hover a.copiable-link {visibility: visible}
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
ul.mark-bullet {list-style-type: disc}
@media (prefers-color-scheme: dark) {
/* dark theme */
html { color: seashell;
background: #1A1A1A; }
body { background: #1A1A1A; }
th { border-bottom: 2px solid lightgray; }
h1, h2, h3, h4, h5 { background-image: linear-gradient(to left, #202020, #3A3A3A); }
code, var, code a { color: darkorange;
background: #2A2A2A; }
a { color: seashell; }
pre { background: #2A2A2A;
color: seashell;
/* mark longer code block with stripe on the left */
border-left: 5px solid darkorange;
padding-left: 10px; }
pre.screen { background: #2A2A2A;
border: 1px solid lightgray; }
pre.programlisting { background: #2A2A2A;
border-left: 1px solid lightgray;
border-top: 1px solid lightgray; }
/* we need a light background in order for the images to be readable */
img { background: white }
}
@media (prefers-color-scheme: light) {
/* light theme */
html { background: white }
body { background: white }
th { border-bottom: 2px solid gray; }
h1, h2, h3, h4, h5 { background: lightgray; }
code, var, code a { color: darkred;
background: whitesmoke; }
a { color: #000; }
pre { background: whitesmoke;
color: black;
/* mark longer code block with stripe on the left */
border-left: 5px solid darkred;
padding-left: 10px; }
pre.screen { background: #EEE;
border: 1px solid black; }
pre.programlisting { background: #EEEEEE;
border-left: 1px solid black;
border-top: 1px solid black; }
}
body {
margin: 1em 125px 0 10%;
line-height: 1.5em;
padding: 0 2em 1em 2em;
font: 13px Verdana,Arial, sans-serif
}
ul, dd, dl, dt { margin-top: 0; margin-bottom: 0; }
p, code, td, dl, dt {
line-height: 1.5em;
}
table {
font: inherit;
border-collapse: collapse;
}
th, td {
vertical-align: top;
}
h1, h2, h3 { padding-left: 15px; }
h4, h5 { padding-left: 5px; }
code, pre {
font-size: 1em;
font-family: monospace;
}
var {
font-size: 1em;
}
/* links inside code appear the same as the code itself */
code a {
font-weight: normal;
text-decoration: none;
}
/* but get an underline when hovering */
code a:hover {
text-decoration: underline;
}
/* ordinary links appear in bold */
a { font-weight: bold; }
pre.verbatim {
margin: 0 0 0 0;
}
pre {
overflow: auto;
}
pre.screen {
font-weight: bold;
padding: 0.5em;
}
pre.programlisting {
padding: 0.5em;
}
div p { padding: 0 2em }
li p { padding: 0; margin: 0 }
hr { display: none; }
div.funcsynopsis p {
text-indent: -2em;
}
div.variablelist {
padding: 0 2em;
}
.type, .funcsynopsis, .symbol {
font-family: monospace;
}
.type, .symbol, .replaceable {
white-space: nowrap;
}
-->
</style>
</head>
<body lang="en">
<div class="section-level-extent" id="Environment">
<div class="nav-panel">
<p>
Previous: <a href="System-construction.html" accesskey="p" rel="prev">System construction</a>, Up: <a href="Standards.html" accesskey="u" rel="up">Standards</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Environment-1">2.23 Environment</h3>
<ul class="mini-toc">
<li><a href="Environment.html#Environment-_002d-Dictionary" accesskey="1">Dictionary</a></li>
<li><a href="Environment.html#Environment-_002d-C-Reference" accesskey="2">C Reference</a></li>
</ul>
<hr>
<div class="subsection-level-extent" id="Environment-_002d-Dictionary">
<div class="nav-panel">
<p>
Next: <a href="Environment.html#Environment-_002d-C-Reference" accesskey="n" rel="next">C Reference</a>, Up: <a href="Environment.html#Environment" accesskey="u" rel="up">Environment</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
</div>
<h4 class="subsection" id="Dictionary-3">2.23.1 Dictionary</h4>
<a class="index-entry-id" id="index-disassemble-1"></a>
<a class="index-entry-id" id="index-ed-1"></a>
<a class="index-entry-id" id="index-trace-1"></a>
<dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-disassemble"><span class="category-def">Function: </span><span><strong class="def-name">disassemble</strong> <var class="def-var-arguments">function-designator*</var><a class="copiable-link" href='Environment.html#index-disassemble'> &para;</a></span></dt>
<dd><p>Display the assembly code of a function
</p>
<p><b class="b">Synopsis</b>
</p>
<dl class="table">
<dt><var class="var">function-designator</var></dt>
<dd><p>A symbol which is bound to a function in the global environment, or a lambda form
</p></dd>
</dl>
<p><b class="b">Description</b>
</p>
<p>As specified in ANSI [see <a class="pxref" href="Bibliography.html">ANSI</a>] this function outputs the internal representation of a compiled function, or of a lambda form, as it would look after being compiled.
</p>
<p>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.
</p>
<ul class="itemize mark-bullet">
<li>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.
</li><li>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.
</li></ul>
</dd></dl>
<dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-ed"><span class="category-def">Function: </span><span><strong class="def-name">ed</strong> <var class="def-var-arguments">x?</var><a class="copiable-link" href='Environment.html#index-ed'> &para;</a></span></dt>
<dd><p>Invoke an editor on the file or object specified by <var class="var">x</var>.
</p>
<p><b class="b">Synopsis</b>
</p>
<p>(ed <var class="var">x?</var>)
</p><dl class="table">
<dt><var class="var">x</var></dt>
<dd><p><code class="code">nil</code>, a file path, or an object to edit.
</p></dd>
</dl>
<p><b class="b">Description</b>
</p>
<p>Starts the editor (on a file or an object if named). Functions from the list <var class="var">ext:*ed-functions*</var> are called in order with <var class="var">x</var> as an argument until one of them returns non-<code class="code">nil</code>; these functions are responsible for signalling a <code class="code">file-error</code> to indicate failure to perform an operation on the file system. If no function returns a non-<code class="code">nil</code> value or <var class="var">ext:*ed-functions*</var> is <code class="code">nil</code> then a <code class="code">simple-error</code> will be signalled.
</p>
<p>The Common Lisp specification states that the <var class="var">x</var> argument is either <code class="code">nil</code>, a function name, or an instance of <var class="var">string</var> or <var class="var">pathname</var> and that a <var class="var">type-error</var> may be signalled if is not one of these types. ECL does not check the type of <var class="var">x</var> 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 class="var">x</var> and should instead return <code class="code">nil</code> if there is not an approriate edit method for a specific value of <var class="var">x</var>.
</p>
<p>By default <var class="var">ext:*ed-functions*</var> contains a single function that attempts to run the program named in the environment variable <code class="code">EDITOR</code>. If this environment variable is not set then the fallback program is <code class="code">vi</code>.
</p></dd></dl>
<dl class="first-deffn first-defmac-alias-first-deffn">
<dt class="deffn defmac-alias-deffn" id="index-trace"><span class="category-def">Macro: </span><span><strong class="def-name">trace</strong> <var class="def-var-arguments">function-name*</var><a class="copiable-link" href='Environment.html#index-trace'> &para;</a></span></dt>
<dd><p>Follow the execution of functions
</p>
<p><b class="b">Synopsis</b>
</p>
<p>(trace <var class="var">function-name*</var>)
</p><dl class="table">
<dt><var class="var">function-name</var></dt>
<dd><p>{<var class="var">symbol</var> | (<var class="var">symbol</var> [<var class="var">option</var> <var class="var">form</var>]*)}
</p></dd>
<dt><var class="var">symbol</var></dt>
<dd><p>A symbol which is bound to a function in the global environment. Not evaluated.
</p></dd>
<dt><var class="var">option</var></dt>
<dd><p>One of <code class="code">:break</code>, <code class="code">:break-after</code>, <code class="code">:cond-before</code>, <code class="code">:cond-after</code>, <code class="code">:cond</code>, <code class="code">:print</code>, <code class="code">:print-after</code>, <code class="code">:step</code>
</p></dd>
<dt><var class="var">form</var></dt>
<dd><p>A lisp form evaluated in an special environment (or a list of forms for
<code class="code">:print</code> and <code class="code">:print-after</code>).
</p></dd>
<dt><var class="var">returns</var></dt>
<dd><p>List of symbols with traced functions.
</p></dd>
</dl>
<p><b class="b">Description</b>
</p>
<p>Causes one or more functions to be traced. Each <var class="var">function-name</var> 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.
</p>
<p>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 class="code">notinline</code> declaration for the called function.
</p>
<p><code class="code">trace</code> returns a name list of those functions that were traced by the call to <code class="code">trace</code>. If no <var class="var">function-name</var> is given, <code class="code">trace</code> simply returns a name list of all the currently traced functions.
</p>
<p>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 class="var">form</var> accompanying the option is evaluated in an environment where <var class="var">sys::args</var> contains the list of arguments to the function.
</p>
<p>The following options are defined:
</p><dl class="table">
<dt><code class="code">:cond</code>, <code class="code">:cond-before</code>, <code class="code">:cond-after</code></dt>
<dd><p>If <code class="code">:cond-before</code> is specified, then <code class="code">trace</code> does nothing unless <var class="var">form</var> evaluates to true at the time of the call. <code class="code">:cond-after</code> is similar, but suppresses the initial printout, and is tested when the function returns. <code class="code">:cond</code> tries both before and after.
</p></dd>
<dt><code class="code">:step</code></dt>
<dd><p>If <var class="var">form</var> evaluates to true, the stepper is entered.
</p></dd>
<dt><code class="code">:break</code>, <code class="code">:break-after</code></dt>
<dd><p>If specified, and <var class="var">form</var> 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.
</p></dd>
<dt><code class="code">:print</code>, <code class="code">:print-after</code></dt>
<dd><p>In addition to the usual printout, the result of evaluating each entry
of the list of forms contained in <var class="var">form</var> is printed at the start of
the function or at the end of the function, depending on the option.
</p></dd>
</dl>
</dd></dl>
<p>See also the following example:
</p>
<a class="index-entry-id" id="index-trace-usage"></a>
<div class="example">
<pre class="example-preformatted">&gt; (defun abc (x)
(if (&gt;= x 10)
x
(abc (+ x (abc (1+ x))))))
&gt; (trace abc)
&gt; (abc 9)
1&gt; (ABC 9)
| 2&gt; (ABC 10)
| &lt;2 (ABC 10)
| 2&gt; (ABC 19)
| &lt;2 (ABC 19)
&lt;1 (ABC 19)
19
&gt; (untrace abc)
(ABC)
;; Break if the first argument of the function is greater than 10
&gt; (trace (abc :break (&gt;= (first si::args) 10)))
((ABC :BREAK (&gt;= (FIRST SI::ARGS) 10)))
&gt; (abc 9)
1&gt; (ABC 9)
| 2&gt; (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: #&lt;process TOP-LEVEL 0x1842f80&gt;.
&gt;&gt;
</pre></div>
<hr>
</div>
<div class="subsection-level-extent" id="Environment-_002d-C-Reference">
<div class="nav-panel">
<p>
Previous: <a href="Environment.html#Environment-_002d-Dictionary" accesskey="p" rel="prev">Dictionary</a>, Up: <a href="Environment.html#Environment" accesskey="u" rel="up">Environment</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
</div>
<h4 class="subsection" id="C-Reference-22">2.23.2 C Reference</h4>
<ul class="mini-toc">
<li><a href="Environment.html#ANSI-Dictionary-14" accesskey="1">ANSI Dictionary</a></li>
</ul>
<div class="subsubsection-level-extent" id="ANSI-Dictionary-14">
<h4 class="subsubsection">2.23.2.1 ANSI Dictionary</h4>
<p>Common Lisp and C equivalence
</p>
<table class="multitable">
<thead><tr><th width="30%">Lisp symbol</th><th width="70%">C function</th></tr></thead>
<tbody><tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_dec_un.htm">decode-universal-time</a></td><td width="70%">cl_object cl_decode_universal_time(cl_narg narg, cl_object universal_time, ...)</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_encode.htm">encode-universal-time</a></td><td width="70%">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, ...)</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_get_un.htm">get-universal-time</a></td><td width="70%">cl_object cl_get_universal_time(void)</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_get_un.htm">get-decoded-time</a></td><td width="70%">cl_object cl_get_decoded_time(void)</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_sleep.htm">sleep</a></td><td width="70%">cl_object cl_sleep(cl_object seconds)</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_apropo.htm">apropos</a></td><td width="70%">cl_object cl_apropos(cl_narg narg, cl_object string, ...)</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_apropo.htm">apropos-list</a></td><td width="70%">cl_object cl_apropos_list(cl_narg narg, cl_object string, ...)</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_descri.htm">describe</a></td><td width="70%">cl_object cl_describe(cl_narg narg, cl_object object, ...)</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_desc_1.htm">describe-object</a></td><td width="70%">[Only in Common Lisp]</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_get_in.htm">get-internal-real-time</a></td><td width="70%">cl_object cl_get_internal_real_time(void)</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_get__1.htm">get-internal-run-time</a></td><td width="70%">cl_object cl_get_internal_run_time(void)</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_disass.htm">disassemble</a></td><td width="70%">[Only in Common Lisp]</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_docume.htm">documentation</a></td><td width="70%">[Only in Common Lisp]</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_room.htm">room</a></td><td width="70%">[Only in Common Lisp]</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_ed.htm">ed</a></td><td width="70%">[Only in Common Lisp]</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_inspec.htm">inspect</a></td><td width="70%">cl_object cl_inspect(cl_object object)</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_dribbl.htm">dribble</a></td><td width="70%">cl_object cl_dribble(cl_narg narg, ...)</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_lisp_i.htm">lisp-implementation-type</a></td><td width="70%">cl_object cl_lisp_implementation_type(void)</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_lisp_i.htm">lisp-implementation-version</a></td><td width="70%">cl_object cl_lisp_implementation_version(void)</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_short_.htm">short-site-name</a></td><td width="70%">cl_object cl_short_site_name()</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_short_.htm">long-site-name</a></td><td width="70%">cl_object cl_long_site_name()</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_mach_i.htm">machine-instance</a></td><td width="70%">cl_object cl_machine_instance()</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_mach_t.htm">machine-type</a></td><td width="70%">cl_object cl_machine_type()</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_mach_v.htm">machine-version</a></td><td width="70%">cl_object cl_machine_version()</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_sw_tpc.htm">software-type</a></td><td width="70%">cl_object cl_software_type()</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_sw_tpc.htm">software-version</a></td><td width="70%">cl_object cl_software_version()</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_user_h.htm">user-homedir-pathname</a></td><td width="70%">cl_object cl_user_homedir_pathname(cl_narg narg, ...)</td></tr>
</tbody>
</table>
</div>
</div>
</div>
<hr>
<div class="nav-panel">
<p>
Previous: <a href="System-construction.html" accesskey="p" rel="prev">System construction</a>, Up: <a href="Standards.html" accesskey="u" rel="up">Standards</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
View git blame Copy permalink