1$XFree86: xc/programs/xedit/lisp/README,v 1.12 2002/11/23 08:26:47 paulo Exp $
2
3LAST UPDATED: $Date$
4
5
6 SUMMARY
7
8 This is a small lisp interpreter for xedit. It implements a subset of
9Common Lisp and the xedit package implements several of the basic Emacs
10lisp functions.
11
12(shared modules not broken, but needs a redesign for better performance,
13 but won't be made available in the default build probably for a long time,
14 it would be really better to generate the interface dinamically, and/or just
15 link agains't the required libraries and use a ffi interface)
16+------------------------------------------------------------------------
17| It has a very simple method for loading shared modules, slightly based on
18| the XFree86 loader code, that is currently disabled by default. To enable it,
19| edit lisp.cf and change BuildSharedLispModules to YES.
20|
21| Assuming you have built it with BuildSharedLispModules enabled, you can build
22| a small test application can be built in this directory running "make lsp".
23| Two lisp programs are available in the test directory. To test the programs
24| run "./lsp test/hello.lsp" or "./lsp test/widgets.lsp".
25+------------------------------------------------------------------------
26
27 Currently, it should be used as an helper and/or a small calculator embedded
28in xedit. For the future it should be possible to write entire interfaces
29in the xedit text buffers.
30
31
32 USAGE SUMMARY
33
34 To evaluate lisp expressions, put the text cursor just after the
35lisp expression and press:
36C-x,C-e - will evaluate it, and print the result to the message window
37C-j - will evaluate it, and print the result to the edit window, any
38 errors are printed to the message window.
39C-g - will send an SIGINT to the lisp process, and that process will
40 stop whatever it was processing and jump to the toplevel,
41 to wait for more input.
42
43Note that C-j will only work in the *scratch* buffer.
44
45
46 NOTES
47
48 The improvements to xedit including the several possibilites to extend
49the editor using Lisp are expected to allow making of xedit a versatile
50text editor for programming, but there is code being (slowly) developed
51that should also make it useable as a small word processor, for things
52like WYSIWYG html, etc.
53 The xedit development is being done very slowly, maybe it will get
54somewhere someday, but it is a pet/hobby project, there is no intention
55of making of it an end user editor (the idea is to make it an useful
56development tool).
57 In some aspects the development is trying to mimic several Emacs
58features, but there is no intention of competition (if xedit ever get
59something better than Emacs, I hope that it serves as a motivation to
60make of Emacs an even better editor), actually it is expected to explore
61different areas and use alternate solutions for the implementation.
62 Most work in a computer is done in a text editor and the more the editor
63can help the user the better.
64
65
66(debugger is broken and very slow, no prevision for fixing it, but is
67 expected to work correctly for interpreted only code)
68+------------------------------------------------------------------------
69| DEBUGGER
70|
71| There is a, currently, very simple debugger implement in the interpreter.
72| The debugger is now optional, and off by default. To make it available,
73| you need to recompile with -DDEBUGGER.
74| To use the debugger, run the lsp sample program as "./lsp -d", and optionally
75| pass a second parameter, for the file to be interpreted. Once the debugger
76| prompt is visible, type "help" for a summary of options. To leave the debugger
77| type "continue".
78| Note that the debugger is still very simple, it won't work from xedit, and
79| won't drop to the debugger on "fatal errors". It allows adding breakpoints to
80| functions and watchpoints to variables. Support for changing data and going to
81| the debugger on fatal errors should be added at some time.
82+------------------------------------------------------------------------
83
84
85 COMPILER
86
87 Now there is a very simple bytecode compiler. It is far from finished, but
88for simple code can show significant better performance.
89 There is not yet an interface to compile entire files and no interface to
90store the generated bytecode in disk. There is an interface to bytecode
91compile toplevel forms as a LAMBDA NIL, but it is not yet exported.
92 If your code needs to call GO/RETURN/RETURN-FROM as the result of an EVAL,
93it must jump to code in the interpreter, after compiling all calls to
94GO/RETURN/RETURN-FROM are just stack adjusting and jumps in the bytecode.
95CATCH/THROW and UNWIND-PROTECT are running as interpreted code for now, so it
96is safe to use these, but code in such blocks is not compiled/optimized
97(not even macro expansion is done, as it understands that while not compiled,
98everything is candidate to redefinition at any time).
99 To compile the code, just write a function, and compile it, example:
100
101 (defun fact (n)
102 (if (< n 2)
103 1
104 (* n (fact (1- n)))
105 )
106 )
107 FACT
108
109 (compile 'fact)
110 FACT
111 NIL
112 NIL
113
114 (disassemble 'fact)
115 Function FACT:
116 1 required argument: N
117 0 optional arguments
118 0 keyword parameters
119 No rest argument
120
121 Bytecode header:
122 1 element used in the stack
123 2 elements used in the builtin stack
124 0 elements used in the protected stack
125 Constant 0 = 1
126 Constant 1 = (2)
127 Symbol 0 = N
128 Builtin 0 = *
129 Builtin 1 = 1-
130 Builtin 2 = <
131
132 Initial stack:
133 0 = N
134
135 Bytecode stream:
136 0 LOAD&PUSH (0)
137 2 LOADCON&PUSH [1] ; (2)
138 4 CALL 2 [2] ; <
139 7 JUMPNIL 8
140 10 LOADCON [0] ; 1
141 12 NOOP
142 13 JUMP 19
143 16 LOAD&PUSH (0)
144 18 LOAD&PUSH (0)
145 20 CALL 1 [1] ; 1-
146 23 LET* [0] ; N
147 25 LETREC 1
148 27 UNLET 1
149 29 BCONS1
150 30 CALL 1 [0] ; *
151 33 RETURN
152 FACT
153
154
155 There are several optimizations that should be done at some time, I don't
156think adding NOOP opcodes will help everywhere to make aligned memory reads
157of shorts and ints.
158 It should have explicitly visible registers, not the abstraction of "the
159current value", so the code generator can choose register allocation for
160loop control variables, commonly used variables, etc, for example. Jumps
161should have 3 types: byte relative, 2 bytes relative and 4 bytes relative.
162For now there is only 2 byte relative jumps, byte relative jumps
163can show a significant performance increase, but they are disable until
164it is decided how inlined functions will work, if it just updates the bytecode
165header and cut&past the bytecode, jumps must be updated, and some jumps
166may not fit anymore in a byte.
167
168
169 OPTIMIZATION
170
171 There are plenty of possibilities to make the interpreter run faster. Some
172optimizations that can make it run quite faster in certain cases are:
173 o Better object memory layout and gc. The current memory allocation code
174 is very bad, it try to keep 3 times more free objects than the currently
175 used number, this can consume a lot of memory. The reason is to reduce
176 the gc time cost so that it will in average miss only one in every 4
177 collect tries.
178 o Implement real vectors, currently they are just a list, so it cannot
179 just deference a given index, and gc time is very long also.
180 o Most lists are never changed once created, it could somehow add an index
181 field in the cons cell, so that NTH/NTHCDR/LENGTH like code could just
182 deference the correct object, instead of traversing the CDR of every
183 cons. This would probably require implementing lists as vectors, while
184 making it easy to deference would make life harder when deleting/inserting
185 sublists in a list. It should also better be done in a way that does
186 not require a lot of objects allocated linearly.
187
188
189 HELPING
190
191 Send comments and code to me (paulo@XFree86.Org) or to the XFree86
192mailing/patch lists.
193
194--
195Paulo
196