lac : c0e377aa8dcdbecd287f98d7f89349f2afeb909c
1: \input texinfo
2: @setfilename lac
3: @comment $Id@w{$}
4: @comment %**start of header
5: @include version.texi
6: @settitle The LAC LISP Library Manual
7: @syncodeindex pg cp
8: @comment %**end of header
9:
10: @copying
11: This manual is for the LAC LISP Library (version @value{VERSION}).
12:
13: Copyright @copyright{} 2017 Gianluca Guida
14: @quotation
15: Permission is granted to copy, distribute and/or modify this document
16: under the terms of the GNU Free Documentation License, Version 1.3 or
17: any later version published by the Free Software Foundation; with no
18: Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
19: Texts. A copy of the license is included in the section entitled
20: ``GNU Free Documentation License''.
21: @end quotation
22: @end copying
23:
24: @dircategory Texinfo documentation system
25: @direntry
26: * lac: (lac)The LAC LISP Library.
27: @end direntry
28:
29: @titlepage
30: @title The LAC LISP Library Manual
31: @subtitle for version @value{VERSION}.
32: @author Gianluca Guida
33: @page
34: @vskip 0pt plus 1filll
35: @insertcopying
36: @end titlepage
37:
38: @contents
39:
40: @ifnottex
41: @node Top
42: @top The LAC LISP Library Manual
43:
44:
45: This manual is for the LAC LISP Library (version @value{VERSION}.
46: @end ifnottex
47:
48: @menu
49: * Introduction::
50: * Using LAC::
51: * The LAC Language::
52: * The LAC Library::
53: * Extending the language::
54: * Adding LAC to your program::
55: * GNU Free Documentation License::
56: * Index::
57: @end menu
58:
59: @node Introduction
60: @chapter Introduction
61: @cindex Introduction
62:
63: This manual is an introduction and a reference for the LAC LISP
64: Library (LAC hereinafter).
65:
66: LAC is a simple LISP implementation. Its interpreter is meant be
67: embedded in your application (@pxref{Adding LAC to your program}).
68:
69: LAC is also extensible: you can add new atom types and execute your
70: own functions written in lower level, compiled languages
71: (@pxref{Extending the language}).
72:
73: For more information about the language itself, @pxref{The LAC Language}.
74:
75: @node Using LAC
76: @chapter Using LAC
77: @cindex LAC, Using
78:
79: LAC is a library that implements a LISP interpreter with a system
80: library that contains many useful functions to handle lists, symbols
81: and integers.
82:
83: The interpreter itself can be extended to add features, and this is
84: the real power of LAC.
85:
86: The rest of the chapter will introduce two common ways of using LAC:
87: @i{@acronym{REPL} extension} and @i{embedding}.
88: The difference between the two is that in the former the
89: interpreter has control of the application, while in the latter the
90: LISP interpreter can be called at will by the application to execute
91: commands.
92:
93: Please note that this chapter is just introductory. For a more in-depth discussion of the topic, @pxref{Adding LAC to your program}.
94:
95: @menu
96: * REPL Extension::
97: * Embedding LAC::
98: @end menu
99:
100: @node REPL Extension
101: @section REPL Extension
102:
103: Suppose you have a low-level library that implements some features in
104: a specific domain, and you need a language capable of using those
105: features to create small scripts, write prototypes, explore the
106: library capabilities.
107:
108: What you can do is to first use LAC to create a @acronym{REPL}
109: @footnote{@acronym{REPL} stands for @i{Read}, @i{Eval}, @i{Print
110: Loop}. It is used to describe the core functionality of an
111: interpreter: reading an input, evaluating the value of the input and
112: printing the calculated output value.} and then extend the LAC
113: language with elements from your library.
114:
115: @subsection Writing a REPL for LAC
116:
117: Writing a @acronym{REPL} in LAC is extremely simple. The C program in
118: @ref{repl basic code} produces an interactive command line
119: @acronym{REPL} capable of executing LAC statements, e.g.:
120:
121:
122: @example
123: LAC>(+ 2 2)
124: 4
125: @end example
126:
127:
128: This will be essentially an interpreter for a basic LISP-like
129: language, and you will be able to do integer, list and
130: symbol processing with ease. You will also be able to create macros to
131: extend the language to your needs. @xref{The LAC Language}.
132:
133: @float Figure, repl basic code
134: @caption{A simple REPL for the LAC library}
135: @smallexample
136: @verbatim
137: #include <stdio.h>
138: #include <readline/readline.h>
139: #include <lac.h>
140:
141: int main (int argc, char *argv[])
142: {
143: lenv_t *null_env;
144:
145: /* Initialize LAC (create NULL environment) */
146: null_env = lac_init();
147: if (null_env == NULL)
148: {
149: fprintf(stderr, "Could not initialize lac");
150: return -1;
151: }
152:
153: /* REPL loop. */
154: while (1)
155: {
156: char *buf;
157: lreg_t res;
158:
159: /* Read an input line */
160: buf = readline ("LAC>");
161: if (buf == NULL)
162: break;
163:
164: /* Evaluate S-Expressions. */
165: res = sexpr_eval_string (buf, null_env);
166:
167: /* Print the result */
168: sexpr_fprint(stdout, res);
169: printf("\n");
170: }
171:
172: /* Exit REPL */
173: return 0;
174: }
175: @end verbatim
176: @end smallexample
177: @end float
178:
179:
180: @subsection Extending the interpreter
181:
182: The usefulness of LAC emerges when you add support for your own
183: libraries to this language, and you can do this in two ways: adding
184: @i{Native Procedures} and @i{Atom Types}.
185:
186: @subsubsection Native Procedures
187:
188: Procedures in LISP-like languages are similar to what functions are
189: in C. There are some major differences with C functions, for example
190: in LAC procedures are @i{first-class functions}@footnote{This
191: essentially means that a procedure (and its scope) can be treated as a
192: value, passed as a parameter and returned by another procedure} and
193: that they can be defined and modified at runtime.
194:
195: A @i{Native Procedure} is a procedure written in a low level language,
196: opaque to the interpreter (cannot be inspected or changed). LAC
197: defines a standard C interface for the @i{low-level procedures}, and
198: functions to hook this function to symbols in the LISP machine.
199:
200: Let's clarify the previous sentence with an example: the following C function is a @i{Native Procedure}.
201:
202: @sp 1
203: @example
204: @verbatim
205: LAC_API static lreg_t
206: proc_hello (lreg_t args, lenv_t * argenv, lenv_t * env)
207: {
208: fprintf(stdout, "Hello, World!");
209: return NIL;
210: }
211: @end verbatim
212: @end example
213: @sp 1
214:
215: It is a simple procedure that, ignoring all arguments passed, will
216: always print to standard output the string ``Hello, World!'', and
217: return the empty value NIL.
218:
219: LAC_API is mostly needed to tell the compiler to follow certain rules
220: (mostly alignment) that will ensure that it can be processed
221: internally by the interpreter.
222:
223: Adding this line to the code in @ref{repl basic code} is not enough though to access it. We need to associate this function to a symbol, and this is called @i{registering}.
224:
225: @sp 1
226: @example
227: @verbatim
228: /* PRE: lac_init() has already been
229: called, and has returned null_env. */
230: lac_extproc_register (null_env, "hello", proc_hello);
231: @end verbatim
232: @end example
233: @sp 1
234:
235: This will hook the procedure defined above to the symbol @i{HELLO}. If
236: we add to our code and run the @acronym{REPL} again, we will have a new
237: command available in our interpreter. Note that symbols are case
238: insensitive.
239:
240: @sp 1
241: @example
242: LAC>HELLO
243: <#LLPROC>
244: LAC>(HELLO)
245: Hello, World!()
246: LAC>(hello)
247: Hello, World!()
248: LAC>
249: @end example
250: @sp 1
251:
252: The function, as you can see above, first prints out to the screen the
253: word ``Hello, World!'', and then returns, NIL, the void value of LISP,
254: which is also the empty list, and this gets printed by the @i{Print}
255: phase of the @acronym{REPL} as @code{()}.
256:
257: To complete the example, we can change @code{proc_hello} to return a
258: string instead of printing it to screen directly:
259: @sp 1
260: @example
261: @verbatim
262: LAC_API static lreg_t
263: proc_hello(lreg_t args, lenv_t * argenv, lenv_t * env)
264: {
265: return lac_string_box("Hello, World!");
266: }
267: @end verbatim
268: @end example
269: @sp 1
270: If we register the above function, the @acronym{REPL} will return a string @i{atom}:
271: @sp 1
272: @example
273: LAC>(hello)
274: "Hello, World!"
275: LAC>
276: @end example
277:
278: @subsubsection Adding Atom Types
279:
280:
281: @node Embedding LAC
282: @section Embedding LAC
283:
284: @node The LAC Language
285: @chapter The LAC Language
286: @cindex The LAC Language
287: @cindex LAC, the language
288:
289: @menu
290: * The LAC System Library::
291: @end menu
292:
293: @node The LAC System Library
294: @section The LAC System Library
295: @cindex LAC System Library
296:
297: @node The LAC Library
298: @chapter The LAC Library
299: @cindex The LAC Library
300: @cindex LAC, the library
301:
302: @node Extending the language
303: @chapter Extending the language
304: @cindex Extending the language
305: @cindex LAC, extending the language
306:
307: @node Adding LAC to your program
308: @chapter Adding LAC to your program
309: @cindex Adding LAC to your program
310: @cindex LAC, adding to your program
311:
312: @node GNU Free Documentation License
313: @chapter GNU Free Documentation License
314:
315:
316: @node Index
317: @unnumbered Index
318: @printindex cp
319: @bye
Generated by git2html.