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