A lot of re-structuring of the text, better conventions for handling classes of text...
[clinton/lisp-on-lines.git] / lisp-on-lines.lyx
1 #LyX 1.3 created this file. For more info see http://www.lyx.org/
2 \lyxformat 221
3 \textclass article
4 \language english
5 \inputencoding auto
6 \fontscheme default
7 \graphics default
8 \paperfontsize default
9 \papersize Default
10 \paperpackage a4
11 \use_geometry 0
12 \use_amsmath 0
13 \use_natbib 0
14 \use_numerical_citations 0
15 \paperorientation portrait
16 \secnumdepth 3
17 \tocdepth 3
18 \paragraph_separation indent
19 \defskip medskip
20 \quotes_language english
21 \quotes_times 2
22 \papercolumns 1
23 \papersides 1
24 \paperpagestyle default
25
26 \layout Title
27
28 LISP-ON-LINES
29 \layout Author
30
31
32 \noun on
33 Drew Crapmsie
34 \noun default
35 ,
36 \noun on
37 José Pablo Ezequiel
38 \begin_inset Quotes eld
39 \end_inset
40
41 Pupeno
42 \begin_inset Quotes erd
43 \end_inset
44
45 Fernández Silva
46 \layout Abstract
47
48
49 \noun on
50 Lisp-On-Lines
51 \noun default
52 is a very useful module that works on top of the
53 \noun on
54 UnCommon Web
55 \noun default
56 framework to do rapid developing of complex data-driven web appilcations
57 (on
58 \noun on
59 Common Lisp
60 \noun default
61 , of course).
62 \layout Section
63
64 Introduction
65 \layout Subsection
66
67 Conventions
68 \layout Standard
69
70 The conventions used in this manual are:
71 \layout Itemize
72
73 Lisp code is shown as a monospace font.
74 It is assumed that the user is working in an interactive environment and
75 what the user should type appears as bold, for example:
76 \begin_deeper
77 \layout LyX-Code
78
79 >
80 \series bold
81 (+ 5 10)
82 \layout LyX-Code
83
84 15
85 \end_deeper
86 \layout Itemize
87
88 Names of people or products are show as small caps, like
89 \noun on
90 Drew Crapmsie
91 \noun default
92 or
93 \noun on
94 Lisp-On-Lines
95 \noun default
96 .
97 \layout Itemize
98
99 Sections marked with
100 \series bold
101 \color red
102 ToDo
103 \series default
104 \color default
105 require further revision.
106 \layout Standard
107
108
109 \series bold
110 \color red
111 ToDo: Add more conventions as they are needed, possible classes of text:
112 names of concepts, name of programming entities, like variables, functions,
113 etc (which are embedded in text, should they be shown monospaced ?).
114 \layout Section
115
116 Components
117 \layout Description
118
119 Meta\SpecialChar ~
120 Model\SpecialChar ~
121 Protocol A Protocol for introspection on relational objects.
122 \layout Description
123
124 Mewa\SpecialChar ~
125 Presentations A Mewa-like
126 \begin_inset Foot
127 collapsed true
128
129 \layout Standard
130
131 http://www.adrian-lienhard.ch/files/mewa.pdf
132 \end_inset
133
134 layer for UncommonWeb
135 \begin_inset Foot
136 collapsed true
137
138 \layout Standard
139
140 http://common-lisp.net/project/ucw/
141 \end_inset
142
143 Presentations.
144 \layout Section
145
146 Example
147 \layout Standard
148
149 First we start with the data model.
150 The Meta Model Protocol (MMP) is used to provide information on the data
151 objects and how they relate to one another.
152 Its is currently implemented as a layer over CLSQL
153 \begin_inset Foot
154 collapsed true
155
156 \layout Standard
157
158 http://clsql.b9.com/
159 \end_inset
160
161 , although support is planned for other backends (
162 \noun on
163 CLOS
164 \noun default
165 ,
166 \noun on
167 Elephant
168 \noun default
169 [4], whatever).
170 \layout Standard
171
172 The MMP shares its definition syntax with
173 \emph on
174 \noun on
175 CLSQL
176 \emph default
177 \noun default
178 's Object Oriented Data Definition Language (OODDL)
179 \begin_inset Foot
180 collapsed true
181
182 \layout Standard
183
184 http://clsql.b9.com/manual/ref-ooddl.html
185 \begin_inset Note
186 collapsed true
187
188 \layout Standard
189
190 Shouldn't this footnote be a bibliographical entry ? or something like that
191 ?
192 \end_inset
193
194
195 \end_inset
196
197 .
198 The macro to define view-classes is named DEF-VIEW-CLASS/META, and takes
199 the same arguments as DEF-VIEW-CLASS from CLSQL.
200 For the purposes of this simple example, we will only need two functions
201 from the MMP beyond what CLSQL provides : LIST-SLOTS and LIST-SLOT-TYPES[5].
202 \layout Standard
203
204 We'll define a simple class to hold a user.
205 \layout LyX-Code
206
207 >
208 \series bold
209 (def-view-class/meta user ()
210 \layout LyX-Code
211
212
213 \series bold
214 ((userid :initarg :userid :accessor userid :type integer :db-kind :key)
215 \layout LyX-Code
216
217
218 \series bold
219 (username :initarg :username :accessor username :type string :db-kind
220 :base)
221 \layout LyX-Code
222
223
224 \series bold
225 (password :initarg :password :accessor password :type string :db-kind
226 :base)))
227 \layout Standard
228
229 and now we create a user:
230 \layout LyX-Code
231
232 >
233 \series bold
234 (defparameter user (make-instance 'user :userid 1
235 \layout LyX-Code
236
237
238 \series bold
239 :username "drewc"
240 \layout LyX-Code
241
242
243 \series bold
244 :password "p@ssw0rd"))
245 \layout Standard
246
247 We can see the slots of users running:
248 \layout LyX-Code
249
250 >
251 \series bold
252 (lisp-on-lines::list-slots user)
253 \layout LyX-Code
254
255 (USERID USERNAME PASSWORD)
256 \layout Standard
257
258 or the types with:
259 \layout LyX-Code
260
261 >
262 \series bold
263 (lisp-on-lines::list-slot-types user)
264 \layout LyX-Code
265
266 ((USERID INTEGER) (USERNAME STRING) (PASSWORD STRING))
267 \layout Standard
268
269 We can run:
270 \layout LyX-Code
271
272 >
273 \series bold
274 (lisp-on-lines::default-attributes user)
275 \layout LyX-Code
276
277 ((USERID INTEGER :LABEL "USERID" :SLOT-NAME USERID)
278 \layout LyX-Code
279
280 (USERNAME STRING :LABEL "USERNAME" :SLOT-NAME USERNAME)
281 \layout LyX-Code
282
283 (PASSWORD STRING :LABEL "PASSWORD" :SLOT-NAME PASSWORD))
284 \layout Standard
285
286 What does this do ?
287 \layout LyX-Code
288
289 >
290 \series bold
291 (set-default-attributes user)
292 \layout LyX-Code
293
294 ((USERID INTEGER :LABEL "USERID" :SLOT-NAME USERID)
295 \layout LyX-Code
296
297 (USERNAME STRING :LABEL "USERNAME" :SLOT-NAME USERNAME)
298 \layout LyX-Code
299
300 (PASSWORD STRING :LABEL "PASSWORD" :SLOT-NAME PASSWORD))
301 \layout Standard
302
303 Class attributes?
304 \layout LyX-Code
305
306 >
307 \series bold
308 (lisp-on-lines::find-class-attributes user)
309 \layout LyX-Code
310
311 (USER (PASSWORD STRING :LABEL "PASSWORD" :SLOT-NAME PASSWORD)
312 \layout LyX-Code
313
314 (USERNAME STRING :LABEL "USERNAME" :SLOT-NAME USERNAME)
315 \layout LyX-Code
316
317 (USERID INTEGER :LABEL "USERID" :SLOT-NAME USERID)
318 \layout LyX-Code
319
320 NIL)
321 \layout Standard
322
323 note that the mewa functions (find-attribute, set-attribute etc) can take
324 either an instance, or a class-name as a symbol:
325 \layout LyX-Code
326
327 >
328 \series bold
329 (lisp-on-lines::find-class-attributes 'user)
330 \layout LyX-Code
331
332 (USER (PASSWORD STRING :LABEL "PASSWORD" :SLOT-NAME PASSWORD)
333 \layout LyX-Code
334
335 (USERNAME STRING :LABEL "USERNAME" :SLOT-NAME USERNAME)
336 \layout LyX-Code
337
338 (USERID INTEGER :LABEL "USERID" :SLOT-NAME USERID)
339 \layout LyX-Code
340
341 NIL)
342 \layout LyX-Code
343
344 >
345 \series bold
346 (lisp-on-lines::find-class-attributes (make-instance 'user))
347 \layout LyX-Code
348
349 (USER (PASSWORD STRING :LABEL "PASSWORD" :SLOT-NAME PASSWORD)
350 \layout LyX-Code
351
352 (USERNAME STRING :LABEL "USERNAME" :SLOT-NAME USERNAME)
353 \layout LyX-Code
354
355 (USERID INTEGER :LABEL "USERID" :SLOT-NAME USERID)
356 \layout LyX-Code
357
358 NIL)
359 \layout Standard
360
361 Using that information, we have enough to create an interface to the object.
362 UncommonWeb includes a powerful presentation system, but it is not quite
363 dynamic enough for our needs.
364 Mewa defines an approach to presentations that suits our purposes, but
365 the paper is written from a smalltalk point of view.
366 A mixture of the two , Mewa Presentations(MP), is described here.
367 \layout Standard
368
369 MP introduces to UCW the concept of attributes.
370 an attribute is essentially a named version of the defpresentation slot-like
371 arguments.
372 for example in :
373 \layout Standard
374
375 (defpresentation person-editor (object-presentation)
376 \layout Standard
377
378 ((string :label "First Name" :slot-name 'first-name :max-length 30)))
379 \layout Standard
380
381 the (string :label "First Name" ...) form is an attribute definiton.
382 Attributes are accessed through FIND-ATTIRIBUTES, and are composed at run
383 time (where the current system is done at compile time) to display the
384 object.
385 This allows a very flexible system of displaying objects which is reminiscent
386 of CSS.
387 I discovered this, rather than invent or design it, so there are some rough
388 edges, but its a good start.
389 \layout Standard
390
391 Its much easier to show this then to tell.
392 Lets present our user class.
393 Currently in UCW, you'd define a presentation as such :
394 \layout Standard
395
396 (defpresentation user-presentation (object-presentation)
397 \layout Standard
398
399 ((INTEGER :LABEL "USERID" :SLOT-NAME USERID)
400 \layout Standard
401
402 (STRING :LABEL "USERNAME" :SLOT-NAME USERNAME)
403 \layout Standard
404
405 (STRING :LABEL "PASSWORD" :SLOT-NAME PASSWORD)))
406 \layout Standard
407
408 which could be presented using PRESENT-OBJECT :
409 \layout Standard
410
411 (present-object user :using 'user-presentation)
412 \layout Standard
413
414 The equiv approach using mewa presentations is actually longer and more
415 verbose(!) but it serves to demonstrate how the MP system works.
416 \layout Standard
417
418 Mewa Presentations adds a set of attributes to a class, keyed off the class
419 name.
420 Attributes are inherited, so if you define an attribute on T, you can use
421 it with any class.
422 \layout Standard
423
424 MP stores named attributes keyed on a class name.
425 to achieve the same functionality as the above using mp would look like
426 this :
427 \layout Standard
428
429 LISP-ON-LINES> (setf (find-attribute 'user :viewer) '(mewa-object-presentation
430 :attributes (userid username password) :global-properties (:editablep nil)))
431 \layout Standard
432
433 (:VIEWER MEWA-OBJECT-PRESENTATION
434 \layout Standard
435
436 :ATTRIBUTES
437 \layout Standard
438
439 (USERID USERNAME PASSWORD)
440 \layout Standard
441
442 :GLOBAL-PROPERTIES
443 \layout Standard
444
445 (:EDITABLEP NIL))
446 \layout Standard
447
448 LISP-ON-LINES> (setf (find-attribute 'user 'userid) '(INTEGER :LABEL "USERID"
449 :SLOT-NAME USERID))
450 \layout Standard
451
452 (USERID INTEGER :LABEL "USERID" :SLOT-NAME USERID)
453 \layout Standard
454
455 LISP-ON-LINES> (setf (find-attribute 'user 'username) '(STRING :LABEL "USERNAME"
456 :SLOT-NAME USERNAME))
457 \layout Standard
458
459 (USERNAME STRING :LABEL "USERNAME" :SLOT-NAME USERNAME)
460 \layout Standard
461
462 LISP-ON-LINES> (setf (find-attribute 'user 'password) '(STRING :LABEL "USERNAME"
463 :SLOT-NAME PASSWORD))
464 \layout Standard
465
466 (PASSWORD STRING :LABEL "USERNAME" :SLOT-NAME PASSWORD)
467 \layout Standard
468
469 LISP-ON-LINES> (find-class-attributes 'user)
470 \layout Standard
471
472 (USER (PASSWORD STRING :LABEL "PASSWORD" :SLOT-NAME PASSWORD)
473 \layout Standard
474
475 (USERNAME STRING :LABEL "USERNAME" :SLOT-NAME USERNAME)
476 \layout Standard
477
478 (USERID INTEGER :LABEL "USERID" :SLOT-NAME USERID)
479 \layout Standard
480
481 (:VIEWER MEWA-OBJECT-PRESENTATION
482 \layout Standard
483
484 :ATTRIBUTES
485 \layout Standard
486
487 (USERID USERNAME PASSWORD)
488 \layout Standard
489
490 :GLOBAL-PROPERTIES
491 \layout Standard
492
493 (:EDITABLEP NIL))
494 \layout Standard
495
496 COMMON-LISP:NIL)
497 \layout Standard
498
499 this is all turned into a UCW presentation at runtime using MAKE-PRESENTATION
500 :
501 \layout Standard
502
503 (defmethod render-on ((res response) (e presentations-index))
504 \layout Standard
505
506 "
507 \layout Standard
508
509 As you'll see, nothing is exported from the LISP-ON-LINES package.
510
511 \layout Standard
512
513 if you wish to use LOL in your own package (or in UCW-USER or whatever),
514 \layout Standard
515
516 you simply need to use the MEWA and META-MODEL packages"
517 \layout Standard
518
519 (<ucw:render-component :component (lisp-on-lines::make-presentation lisp-on-line
520 s::user :type :viewer)))
521 \layout Standard
522
523 SET-ATTRIBUTE can be used in place of (setf (find-attribute)) when you want
524 to "inherit" the properties of an existing attribute definition :
525 \layout Standard
526
527 LISP-ON-LINES> (set-attribute 'user 'password '(string :label "password:
528 (must be at leat 8 chars)"))
529 \layout Standard
530
531 (PASSWORD STRING
532 \layout Standard
533
534 :LABEL
535 \layout Standard
536
537 "password: (must be at leat 8 chars)"
538 \layout Standard
539
540 :SLOT-NAME
541 \layout Standard
542
543 PASSWORD)
544 \layout Standard
545
546 Now we want to create a presentation with which to edit the username.
547 we will use the existing attributes on a subclass of mewa-object-presetation
548 :
549 \layout Standard
550
551 LISP-ON-LINES> (defcomponent user-editor (mewa-object-presentation)
552 \layout Standard
553
554 ()
555 \layout Standard
556
557 (:default-initargs
558 \layout Standard
559
560 :attributes '((username :label "Enter your New Username") password)
561 \layout Standard
562
563 :global-properties '(:editablep t)))
564 \layout Standard
565
566 USER-EDITOR
567 \layout Standard
568
569 LISP-ON-LINES> (setf (find-attribute 'user :editor) '(user-editor))
570 \layout Standard
571
572 (:EDITOR USER-EDITOR)
573 \layout Standard
574
575 LISP-ON-LINES>
576 \layout Standard
577
578 which we then can display below our earlier example :
579 \layout Standard
580
581 (defmethod render-on ((res response) (e presentations-index))
582 \layout Standard
583
584 "
585 \layout Standard
586
587 As you'll see, nothing is exported from the LISP-ON-LINES package.
588
589 \layout Standard
590
591 if you wish to use LOL in your own package (or in UCW-USER or whatever),
592 \layout Standard
593
594 you simply need to use the MEWA and META-MODEL packages"
595 \layout Standard
596
597 (<ucw:render-component :component (lisp-on-lines::make-presentation lisp-on-line
598 s::user :type :viewer))
599 \layout Standard
600
601 (<ucw:render-component :component (lisp-on-lines::make-presentation lisp-on-line
602 s::user :type :editor)))
603 \layout Standard
604
605 that should give you some idea on how it works ..
606 ask me when you get confused :)
607 \the_end