| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" |
| 2 | "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> |
| 3 | <html xmlns="http://www.w3.org/1999/xhtml" |
| 4 | lang="en" xml:lang="en"> |
| 5 | <head> |
| 6 | <title>Lisp on Lines : The Missing Manual.</title> |
| 7 | <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"/> |
| 8 | <meta name="generator" content="Org-mode"/> |
| 9 | <meta name="generated" content="2009/07/27 01:46:25 PM"/> |
| 10 | <meta name="author" content="Drew Crampsie"/> |
| 11 | <style type="text/css"> |
| 12 | html { |
| 13 | font-family: Times, serif; |
| 14 | font-size: 12pt; |
| 15 | } |
| 16 | .title { text-align: center; } |
| 17 | .todo { color: red; } |
| 18 | .done { color: green; } |
| 19 | .timestamp { color: grey } |
| 20 | .timestamp-kwd { color: CadetBlue } |
| 21 | .tag { background-color:lightblue; font-weight:normal } |
| 22 | .target { } |
| 23 | pre { |
| 24 | border: 1pt solid #AEBDCC; |
| 25 | background-color: #F3F5F7; |
| 26 | padding: 5pt; |
| 27 | font-family: courier, monospace; |
| 28 | font-size: 90%; |
| 29 | } |
| 30 | table { border-collapse: collapse; } |
| 31 | td, th { |
| 32 | vertical-align: top; |
| 33 | <!--border: 1pt solid #ADB9CC;--> |
| 34 | } |
| 35 | dt { font-weight: bold; } |
| 36 | </style> |
| 37 | </head><body> |
| 38 | <h1 class="title">Lisp on Lines : The Missing Manual.</h1> |
| 39 | <i>Abstract</i>: Lisp on Lines is a Common Lisp based framework for rapid |
| 40 | development of data-driven applications. It is particularly useful |
| 41 | for producing Web based applications, but is also useful elsewhere. |
| 42 | |
| 43 | |
| 44 | |
| 45 | <div id="table-of-contents"> |
| 46 | <h2>Table of Contents</h2> |
| 47 | <div id="text-table-of-contents"> |
| 48 | <ul> |
| 49 | <li><a href="#sec-1">1 Introduction</a></li> |
| 50 | <li><a href="#sec-2">2 Installation</a></li> |
| 51 | <li><a href="#sec-3">3 Describing the domain with the MAO protocol.</a> |
| 52 | <ul> |
| 53 | <li><a href="#sec-3.1">3.1 Descriptions</a></li> |
| 54 | <li><a href="#sec-3.2">3.2 Attributes and Properties</a></li> |
| 55 | <li><a href="#sec-3.3">3.3 Contexts</a></li> |
| 56 | </ul> |
| 57 | </li> |
| 58 | <li><a href="#sec-4">4 Defining and Using Descriptions</a> |
| 59 | <ul> |
| 60 | <li><a href="#sec-4.1">4.1 Defining a simple description </a></li> |
| 61 | <li><a href="#sec-4.2">4.2 Using descriptions as and with contexts.</a></li> |
| 62 | <li><a href="#sec-4.3">4.3 T : The root of all descriptions.</a></li> |
| 63 | <li><a href="#sec-4.4">4.4 DESCRIPTION-OF : Permanently Associate a description with a class.</a></li> |
| 64 | </ul> |
| 65 | </li> |
| 66 | <li><a href="#sec-5">5 The DISPLAY Protocol</a></li> |
| 67 | <li><a href="#sec-6">6 Automatic Descriptions for CLOS classes.</a> |
| 68 | <ul> |
| 69 | <li><a href="#sec-6.1">6.1 Described CLOS objects an the EDITABLE description</a></li> |
| 70 | <li><a href="#sec-6.2">6.2 Extending the generated description</a></li> |
| 71 | </ul> |
| 72 | </li> |
| 73 | <li><a href="#sec-7">7 Using Lisp-on-Lines for the Web.</a></li> |
| 74 | </ul> |
| 75 | </div> |
| 76 | </div> |
| 77 | |
| 78 | <div id="outline-container-1" class="outline-2"> |
| 79 | <h2 id="sec-1">1 Introduction</h2> |
| 80 | <div id="text-1"> |
| 81 | |
| 82 | |
| 83 | <p> |
| 84 | Lisp on Lines (LoL) is a framework for rapid development of data-driven |
| 85 | applications, with a particular focus on web-based applications. It |
| 86 | builds on the UncommonWeb engine and Contextl, and uses CLOS and the |
| 87 | MOP extensively. Most of LoL can be used both at the REPL and through |
| 88 | the browser, offering many options for development and testing. |
| 89 | </p> |
| 90 | <p> |
| 91 | While the target audience for LoL is developers experienced with both |
| 92 | web technologies and common lisp, a good programmer with a little |
| 93 | experience in either should be able to pick things up fairly quickly. |
| 94 | </p> |
| 95 | </div> |
| 96 | |
| 97 | </div> |
| 98 | |
| 99 | <div id="outline-container-2" class="outline-2"> |
| 100 | <h2 id="sec-2">2 Installation</h2> |
| 101 | <div id="text-2"> |
| 102 | |
| 103 | |
| 104 | <p> |
| 105 | LoL has a load of dependencies, which themselves depend on others, |
| 106 | etc. The best way to deal with this is to use <a href="http://common-lisp.net/project/clbuild/">clbuild</a>, a library |
| 107 | management tool. |
| 108 | </p> |
| 109 | <p> |
| 110 | If you'd prefer to manage your libraries manually, the dependencies, |
| 111 | according to clbuild, are : |
| 112 | </p> |
| 113 | <p> |
| 114 | alexandria arnesi bordeaux-threads cl-base64 cl-fad cl-mime cl-ppcre |
| 115 | cl-qprint closer-mop contextl iterate lift local-time lw-compat |
| 116 | net-telent-date parenscript parse-number portable-threads puri rfc2109 |
| 117 | slime split-sequence trivial-garbage ucw usocket yaclml |
| 118 | </p> |
| 119 | <p> |
| 120 | All libraries should be installed from version control where available. |
| 121 | </p> |
| 122 | </div> |
| 123 | |
| 124 | </div> |
| 125 | |
| 126 | <div id="outline-container-3" class="outline-2"> |
| 127 | <h2 id="sec-3">3 Describing the domain with the MAO protocol.</h2> |
| 128 | <div id="text-3"> |
| 129 | |
| 130 | |
| 131 | <p> |
| 132 | LoL uses a protocol it calls Meta-Attributed Objects, or MAO, as the |
| 133 | basis of its display mechanism. In MAO, we create context-aware |
| 134 | DESCRIPTIONs of objects, and those descriptions are used to generate |
| 135 | the display of the object itself. By having these external |
| 136 | descriptions change based on the context in which they are used, a few |
| 137 | generic components can come together to create complex interfaces. |
| 138 | </p> |
| 139 | |
| 140 | </div> |
| 141 | |
| 142 | <div id="outline-container-3.1" class="outline-3"> |
| 143 | <h3 id="sec-3.1">3.1 Descriptions</h3> |
| 144 | <div id="text-3.1"> |
| 145 | |
| 146 | <p>Descriptions are a similar conceptually to classes. Every Lisp object |
| 147 | has one, and the root description that all descriptions inherit from |
| 148 | is known as T. FIND-DESCRIPTION is used to, well, find descriptions. |
| 149 | </p> |
| 150 | |
| 151 | |
| 152 | <pre class="src"> (find-description t) |
| 153 | => #<DESCRIPTION T {B7B9861}> |
| 154 | </pre> |
| 155 | |
| 156 | |
| 157 | </div> |
| 158 | |
| 159 | </div> |
| 160 | |
| 161 | <div id="outline-container-3.2" class="outline-3"> |
| 162 | <h3 id="sec-3.2">3.2 Attributes and Properties</h3> |
| 163 | <div id="text-3.2"> |
| 164 | |
| 165 | <p>A description is a collection of ATTRIBUTEs, among other things. Each |
| 166 | attribute describes a part of an object, and any number of attributes |
| 167 | may or may not be active. The ATTRIBUTES function is used to find a |
| 168 | the list attributes that are both active and applicable in the current |
| 169 | context. |
| 170 | </p> |
| 171 | |
| 172 | |
| 173 | <pre class="src">(attributes (find-description t)) |
| 174 | =>(#<ATTRIBUTE IDENTITY {BBC9691}> |
| 175 | #<ATTRIBUTE TYPE {BBC96A1}> |
| 176 | #<ATTRIBUTE CLASS {BBC96B1}>) |
| 177 | </pre> |
| 178 | |
| 179 | |
| 180 | <p> |
| 181 | The functions DESCRIPTION-ATTRIBUTES, DESCRIPTION-ACTIVE-ATTRIBUTES |
| 182 | and DESCRIPTION-CURRENT-ATTRIBUTES return all the descriptions |
| 183 | attributes, Attributes that are currently active regardless of |
| 184 | context, and attributes that exist in the current context but may or |
| 185 | may not be active, respectively. |
| 186 | </p> |
| 187 | <p> |
| 188 | Attributes have properties, for example ATTRIBUTE-LABEL and |
| 189 | ATTRIBUTE-VALUE. By simply iterating through the attributes of a |
| 190 | described object, we can create a generic display for any lisp |
| 191 | object. This is very similar, and was inspired by the technique |
| 192 | outlined by Adrian Lienhard in <a href="http://www.adrian-lienhard.ch/files/mewa.pdf">MEWA: A Meta-level Architecture for Generic Web-Application Construction_</a>. |
| 193 | </p> |
| 194 | |
| 195 | <p> |
| 196 | For attribute properties to be useful, the description must be |
| 197 | associated with the object it is meant to describe. |
| 198 | </p> |
| 199 | <p> |
| 200 | The function FUNCALL-WITH-DESCRIBED-OBJECT takes care of setting up |
| 201 | the proper context. There is some syntax for it in the form of |
| 202 | WITH-DESCRIBED-OBJECT : |
| 203 | </p> |
| 204 | |
| 205 | |
| 206 | <pre class="src"> |
| 207 | (<span style="color: #a020f0;">let</span> ((description (find-description t)) |
| 208 | (object <span style="color: #bc8f8f;">"Hello World"</span>)) |
| 209 | (<span style="color: #a020f0;">with-described-object</span> (object description) |
| 210 | (<span style="color: #a020f0;">dolist</span> (a (attributes description)) |
| 211 | (format t <span style="color: #bc8f8f;">"~@[~A: ~]~A~%"</span> |
| 212 | (attribute-label a) |
| 213 | (attribute-value a))))) |
| 214 | => |
| 215 | Hello World |
| 216 | Type: (SIMPLE-ARRAY CHARACTER (11)) |
| 217 | Class: #<BUILT-IN-CLASS SB-KERNEL::SIMPLE-CHARACTER-STRING> |
| 218 | |
| 219 | NIL |
| 220 | </pre> |
| 221 | |
| 222 | |
| 223 | <p> |
| 224 | FUNCALL-WITH-DESCRIBED-OBJECT binds two specials, <b>DESCRIPTION</b> and |
| 225 | <b>OBJECT</b>, to its arguments. Knowing this, we can shorten our code |
| 226 | somewhat. Later on we'll be far away from the lexical bindings of |
| 227 | description and object, so these special variables are essential. |
| 228 | </p> |
| 229 | <p> |
| 230 | Another reason for the <b>description</b> variable is that |
| 231 | WITH-DESCRIBED-OBJECT will use DESCRIPTION-OF to determine the |
| 232 | description if the DESCRIPTION argument is NIL |
| 233 | </p> |
| 234 | |
| 235 | |
| 236 | <pre class="src">(<span style="color: #a020f0;">with-described-object</span> (<span style="color: #bc8f8f;">"Hello World"</span> nil) |
| 237 | (<span style="color: #a020f0;">dolist</span> (a (attributes *description*)) |
| 238 | (format t <span style="color: #bc8f8f;">"~@[~A: ~]~A~%"</span> |
| 239 | (attribute-label a) |
| 240 | (attribute-value a)))) |
| 241 | |
| 242 | Lets wrap that up in a function that we can re-use. LoL includes an |
| 243 | entire DISPLAY mechanism that is slightly more involved, but this |
| 244 | serves as an excellent example with not bogging us down in details. |
| 245 | |
| 246 | <span style="color: #b22222;">#+BEGIN_SRC lisp</span> |
| 247 | (<span style="color: #a020f0;">defun</span> <span style="color: #0000ff;">present</span> (object <span style="color: #228b22;">&optional</span> description) |
| 248 | (<span style="color: #a020f0;">with-described-object</span> (object description) |
| 249 | (<span style="color: #a020f0;">dolist</span> (a (attributes *description*)) |
| 250 | (format t <span style="color: #bc8f8f;">"~@[~A: ~]~A~%"</span> |
| 251 | (attribute-label a) |
| 252 | (attribute-value a))))) |
| 253 | </pre> |
| 254 | |
| 255 | |
| 256 | </div> |
| 257 | |
| 258 | </div> |
| 259 | |
| 260 | <div id="outline-container-3.3" class="outline-3"> |
| 261 | <h3 id="sec-3.3">3.3 Contexts</h3> |
| 262 | <div id="text-3.3"> |
| 263 | |
| 264 | |
| 265 | <p> |
| 266 | MAO adds to MEWA the concept of dynamic context. By changing the |
| 267 | context in which an object is described, we combine and specialize the |
| 268 | generic displays, ultimately creating different views of our |
| 269 | objects. LoL uses ContextL extensively. Descriptions are contextl |
| 270 | layers, and attributes themselves are layered classes. Most of the |
| 271 | exported functions are layered methods, and the idea of dynamic |
| 272 | context-sensitivity is used throughout LoL. If you're not familiar |
| 273 | with contextl, don't worry, LoL mostly stands on its own. Still, |
| 274 | reading through the material on contextl won't hurt. |
| 275 | </p> |
| 276 | <p> |
| 277 | Descriptions may have different attributes dependant on what |
| 278 | description contexts (or layers) are currently active. Attributes |
| 279 | themselves might have different properties. |
| 280 | </p> |
| 281 | <p> |
| 282 | When an object is being described (using WITH-DESCRIBED-OBJECT), it is |
| 283 | also activated as a layer context. One can also activate/deactivate |
| 284 | contexts manually, using WITH-ACTIVE-DESCRIPTIONS and |
| 285 | WITH-INACTIVE-DESCRIPTIONS. |
| 286 | </p> |
| 287 | <p> |
| 288 | Hopefully a little code will make this more clear : |
| 289 | </p> |
| 290 | |
| 291 | |
| 292 | <pre class="src">(present <span style="color: #bc8f8f;">"Hello World"</span>) |
| 293 | => |
| 294 | Hello World |
| 295 | Type: (SIMPLE-ARRAY CHARACTER (11)) |
| 296 | Class: #<BUILT-IN-CLASS SB-KERNEL::SIMPLE-CHARACTER-STRING> |
| 297 | Simple character string |
| 298 | |
| 299 | <span style="color: #b22222;">;; </span><span style="color: #b22222;">Now we'll activate a built-in description, INLINE. |
| 300 | </span> |
| 301 | (<span style="color: #a020f0;">with-active-descriptions</span> (<span style="color: #a020f0;">inline</span>) |
| 302 | (present <span style="color: #bc8f8f;">"Hello World"</span>)) |
| 303 | => |
| 304 | Hello World |
| 305 | </pre> |
| 306 | |
| 307 | |
| 308 | <p> |
| 309 | You can see that the behavior of PRESENT changed when the INLINE |
| 310 | context was activated. This is the key innovation that makes LoL so |
| 311 | useful. In the next chapter we'll create our own descriptions and |
| 312 | demonstrate this further. |
| 313 | </p> |
| 314 | </div> |
| 315 | </div> |
| 316 | |
| 317 | </div> |
| 318 | |
| 319 | <div id="outline-container-4" class="outline-2"> |
| 320 | <h2 id="sec-4">4 Defining and Using Descriptions</h2> |
| 321 | <div id="text-4"> |
| 322 | |
| 323 | |
| 324 | |
| 325 | </div> |
| 326 | |
| 327 | <div id="outline-container-4.1" class="outline-3"> |
| 328 | <h3 id="sec-4.1">4.1 Defining a simple description </h3> |
| 329 | <div id="text-4.1"> |
| 330 | |
| 331 | <p>The basics of the MAO should now (hopefully) be clear, so lets start |
| 332 | using it. First, we'll create our very own description. |
| 333 | </p> |
| 334 | |
| 335 | |
| 336 | <pre class="src">(<span style="color: #a020f0;">define-description</span> hello-world () |
| 337 | ((title <span style="color: #da70d6;">:value</span> <span style="color: #bc8f8f;">"Lisp on Lines Demo"</span>) |
| 338 | (identity <span style="color: #da70d6;">:label</span> <span style="color: #bc8f8f;">"Message"</span>) |
| 339 | (length <span style="color: #da70d6;">:label</span> <span style="color: #bc8f8f;">"Length"</span> <span style="color: #da70d6;">:function</span> #'length) |
| 340 | (active-attributes <span style="color: #da70d6;">:value</span> '(title identity length)))) |
| 341 | </pre> |
| 342 | |
| 343 | |
| 344 | <p> |
| 345 | Descriptions are defined very much like CLOS classes, and are in fact |
| 346 | implemented that way, inheritance rules apply. The object returned |
| 347 | from FIND-DESCRIPTION is best described as a prototype-based |
| 348 | singleton. In other words, there is only one instance, and it inherits |
| 349 | attributes and properties from further up its hierarchy unless |
| 350 | specifically overridden. |
| 351 | </p> |
| 352 | <p> |
| 353 | Attributes can have any number of properties, (see the class |
| 354 | STANDARD-ATTRIBUTE), but the three most important are accessed via the |
| 355 | methods ATTRIBUTE-LABEL, ATTRIBUTE-VALUE and ATTRIBUTE-FUNCTION,and |
| 356 | named (in DEFINE-DESCRIPTION forms and elsewhere) |
| 357 | by the :label, :value, and :function keywords. |
| 358 | </p> |
| 359 | <p> |
| 360 | ATTRIBUTE-LABEL is simply a textual label that describes the |
| 361 | attribute. ATTRIBUTE-VALUE is defined to return the result of calling |
| 362 | ATTRIBUTE-FUNCTION with the object as its argument. If |
| 363 | ATTRIBUTE-FUNCTION is NIL, the value of the :value property is returned |
| 364 | directly. |
| 365 | </p> |
| 366 | <p> |
| 367 | In the example above, the IDENTITY and ACTIVE-ATTRIBUTES attributes |
| 368 | are inherited from T, and we are simply overriding the default |
| 369 | properties for our description. LENGTH and TITLE are specific to this |
| 370 | description. A look at src/standard-descriptions/t.lisp may be |
| 371 | instructive at this point. |
| 372 | </p> |
| 373 | <p> |
| 374 | Now, we can present our object using our new description. |
| 375 | </p> |
| 376 | |
| 377 | |
| 378 | <pre class="src">(present <span style="color: #bc8f8f;">"Hello World"</span> (find-description 'hello-world)) |
| 379 | => |
| 380 | Lisp on Lines Demo |
| 381 | Message: Hello World |
| 382 | Length: 11 |
| 383 | |
| 384 | NIL |
| 385 | </pre> |
| 386 | |
| 387 | |
| 388 | </div> |
| 389 | |
| 390 | </div> |
| 391 | |
| 392 | <div id="outline-container-4.2" class="outline-3"> |
| 393 | <h3 id="sec-4.2">4.2 Using descriptions as and with contexts.</h3> |
| 394 | <div id="text-4.2"> |
| 395 | |
| 396 | |
| 397 | <p> |
| 398 | A we mentioned earlier, when an object is being described, the |
| 399 | 'description context' is also made active. On top of that, one can |
| 400 | define partial descriptions that are only active when other |
| 401 | description contexts have been activated. |
| 402 | </p> |
| 403 | <p> |
| 404 | We'll make a ONE-LINE description similar to the INLINE description |
| 405 | demonstrated earlier. |
| 406 | </p> |
| 407 | |
| 408 | |
| 409 | <pre class="src">(<span style="color: #a020f0;">define-description</span> one-line ()) |
| 410 | |
| 411 | (<span style="color: #a020f0;">define-description</span> hello-world () |
| 412 | ((identity <span style="color: #da70d6;">:label</span> nil) |
| 413 | (active-attributes <span style="color: #da70d6;">:value</span> '(identity))) |
| 414 | (<span style="color: #da70d6;">:in-description</span> one-line)) |
| 415 | |
| 416 | </pre> |
| 417 | |
| 418 | |
| 419 | <p> |
| 420 | Here we've defined a new description, ONE-LINE, and a |
| 421 | context-sensitive extension to our HELLO-WORLD description. This |
| 422 | partial desription will be active only when in the context of a |
| 423 | one-line description. One can have attributes that only exist in |
| 424 | certain description contexts, and attributes can have different |
| 425 | properties. |
| 426 | </p> |
| 427 | |
| 428 | |
| 429 | <pre class="src">(<span style="color: #a020f0;">let</span> ((message <span style="color: #bc8f8f;">"Hello World!"</span>) |
| 430 | (description (find-description 'hello-world))) |
| 431 | (print <span style="color: #da70d6;">:normal</span>)(terpri) |
| 432 | (present message description) |
| 433 | (print <span style="color: #da70d6;">:one-line</span>)(terpri) |
| 434 | (<span style="color: #a020f0;">with-active-descriptions</span> (one-line) |
| 435 | (present message description))) |
| 436 | => |
| 437 | <span style="color: #da70d6;">:NORMAL</span> |
| 438 | Lisp on Lines Demo |
| 439 | Message: Hello World! |
| 440 | Length: 12 |
| 441 | |
| 442 | <span style="color: #da70d6;">:ONE-LINE</span> |
| 443 | Hello World! |
| 444 | |
| 445 | NIL |
| 446 | </pre> |
| 447 | |
| 448 | |
| 449 | <p> |
| 450 | By activating the description ONE-LINE, we've changed the context in |
| 451 | which our object is displayed. We can create any number of |
| 452 | descriptions and contexts and activate/deactivate them in any order. |
| 453 | </p> |
| 454 | <p> |
| 455 | Descriptions are implemented as ContextL 'layers', so if all |
| 456 | this seems weird, reading the ContextL papers might help. |
| 457 | </p> |
| 458 | </div> |
| 459 | |
| 460 | </div> |
| 461 | |
| 462 | <div id="outline-container-4.3" class="outline-3"> |
| 463 | <h3 id="sec-4.3">4.3 T : The root of all descriptions.</h3> |
| 464 | <div id="text-4.3"> |
| 465 | |
| 466 | |
| 467 | <p> |
| 468 | Because all descriptions inherit from T, we can define contexts for T |
| 469 | and they will apply to every description. The INLINE description can |
| 470 | be found in standard-descriptions/inline.lisp, where we define |
| 471 | a desription for T in the context of the INLINE description : |
| 472 | </p> |
| 473 | |
| 474 | |
| 475 | <pre class="src"><span style="color: #b22222;">;; </span><span style="color: #b22222;">Defined by LoL in inline.lisp : |
| 476 | </span>(<span style="color: #a020f0;">define-description</span> t () |
| 477 | ((identity <span style="color: #da70d6;">:label</span> nil) |
| 478 | (active-attributes <span style="color: #da70d6;">:value</span> '(identity)) |
| 479 | (attribute-delimiter <span style="color: #da70d6;">:value</span> <span style="color: #bc8f8f;">", "</span>) |
| 480 | (label-formatter <span style="color: #da70d6;">:value</span> (curry #'format nil <span style="color: #bc8f8f;">"~A: "</span>)) |
| 481 | (value-formatter <span style="color: #da70d6;">:value</span> (curry #'format nil <span style="color: #bc8f8f;">"~A"</span>))) |
| 482 | (<span style="color: #da70d6;">:in-description</span> inline))} |
| 483 | |
| 484 | </pre> |
| 485 | |
| 486 | |
| 487 | <p> |
| 488 | The does for the LoL DISPLAY mechanism what ONE-LINE did for PRESENT, |
| 489 | only with more magic. By exetending T in this way, it's easy to create |
| 490 | contexts the redefine the behavior of LoL while still reusing the basics. |
| 491 | </p> |
| 492 | </div> |
| 493 | |
| 494 | </div> |
| 495 | |
| 496 | <div id="outline-container-4.4" class="outline-3"> |
| 497 | <h3 id="sec-4.4">4.4 DESCRIPTION-OF : Permanently Associate a description with a class.</h3> |
| 498 | <div id="text-4.4"> |
| 499 | |
| 500 | |
| 501 | <p> |
| 502 | The LAYERED-FUNCTION DESCRIPTION-OF will return the description |
| 503 | associated with an object. |
| 504 | </p> |
| 505 | |
| 506 | |
| 507 | <pre class="src"> |
| 508 | (description-of nil) |
| 509 | => |
| 510 | #<DESCRIPTION NULL {AA04F49}> |
| 511 | |
| 512 | (description-of t) |
| 513 | => |
| 514 | #<DESCRIPTION SYMBOL {AA04541}> |
| 515 | |
| 516 | (description-of '(1 2 3)) |
| 517 | => |
| 518 | #<DESCRIPTION CONS {AA04C29}> |
| 519 | |
| 520 | <span style="color: #b22222;">;;</span><span style="color: #b22222;">etc |
| 521 | </span> |
| 522 | </pre> |
| 523 | |
| 524 | |
| 525 | </div> |
| 526 | </div> |
| 527 | |
| 528 | </div> |
| 529 | |
| 530 | <div id="outline-container-5" class="outline-2"> |
| 531 | <h2 id="sec-5">5 The DISPLAY Protocol</h2> |
| 532 | <div id="text-5"> |
| 533 | |
| 534 | |
| 535 | <p> |
| 536 | Our function, PRESENT, is very basic, though pretty powerful when |
| 537 | combined with descriptions and contexts. LoL includes a superset of |
| 538 | such functionality built-in. |
| 539 | </p> |
| 540 | <p> |
| 541 | The main entry point into this protocol is the DISPLAY |
| 542 | function. The signature for this functions is : |
| 543 | </p> |
| 544 | |
| 545 | |
| 546 | <pre class="src">(display DISPLAY OBJECT <span style="color: #228b22;">&REST</span> ARGS <span style="color: #228b22;">&KEY</span> DEACTIVATE ACTIVATE <span style="color: #228b22;">&ALLOW-OTHER-KEYS</span>) |
| 547 | </pre> |
| 548 | |
| 549 | |
| 550 | <p> |
| 551 | The first argument, DISPLAY, is the place where we will display |
| 552 | to/on/in/with. It could be a stream, a UCW component, a CLIM gadget, |
| 553 | or anything else you might want to use. |
| 554 | </p> |
| 555 | <p> |
| 556 | One can specialize on this argument (though it's better to specialize |
| 557 | DISPLAY-USING-DESCRIPTION… more on that later) to use generic |
| 558 | descriptions to display objects in different environments. |
| 559 | </p> |
| 560 | <p> |
| 561 | The second argument is simply the object to be displayed. Here's a |
| 562 | simple example : |
| 563 | </p> |
| 564 | |
| 565 | |
| 566 | <pre class="src">(display t t) |
| 567 | => |
| 568 | T |
| 569 | Type:BOOLEAN |
| 570 | Class:#<BUILT-IN-CLASS SYMBOL> |
| 571 | Symbol |
| 572 | Name:T |
| 573 | Value:T |
| 574 | Package:#<PACKAGE <span style="color: #bc8f8f;">"COMMON-LISP"</span>> |
| 575 | Function:<UNBOUND> |
| 576 | <span style="color: #b22222;">; </span><span style="color: #b22222;">No value |
| 577 | </span></pre> |
| 578 | |
| 579 | |
| 580 | <p> |
| 581 | The two arguments specified in the lambda-list, ACTIVATE and |
| 582 | DEACTIVATE, are used to activate and deactivate description contexts in |
| 583 | the scope of the display function. |
| 584 | </p> |
| 585 | |
| 586 | |
| 587 | <pre class="src"> |
| 588 | (display nil t <span style="color: #da70d6;">:activate</span> '(<span style="color: #a020f0;">inline</span>)) |
| 589 | => |
| 590 | <span style="color: #bc8f8f;">"t"</span> |
| 591 | (<span style="color: #a020f0;">with-active-descriptions</span> (<span style="color: #a020f0;">inline</span>) |
| 592 | (display nil t <span style="color: #da70d6;">:deactivate</span> '(<span style="color: #a020f0;">inline</span>))) |
| 593 | => |
| 594 | <span style="color: #bc8f8f;">"T |
| 595 | Type:BOOLEAN |
| 596 | Class:#<BUILT-IN-CLASS SYMBOL> |
| 597 | Symbol |
| 598 | Name:T |
| 599 | Value:T |
| 600 | Package:#<PACKAGE \"COMMON-LISP\"> |
| 601 | Function:<UNBOUND>"</span> |
| 602 | |
| 603 | </pre> |
| 604 | |
| 605 | |
| 606 | <p> |
| 607 | Any other keyword arguments passed will be used to set the value of an |
| 608 | attribute with a :keyword property, in the dynamic context of the |
| 609 | DISPLAY function call. Once such attribute, and a very useful one is |
| 610 | ACTIVE-ATTRIBUTES with its :attributes keyword : |
| 611 | </p> |
| 612 | |
| 613 | |
| 614 | <pre class="src"> |
| 615 | (display t t <span style="color: #da70d6;">:attributes</span> '(class package)) |
| 616 | => |
| 617 | Class:#<BUILT-IN-CLASS SYMBOL> |
| 618 | Package:#<PACKAGE <span style="color: #bc8f8f;">"COMMON-LISP"</span>> |
| 619 | |
| 620 | </pre> |
| 621 | |
| 622 | |
| 623 | <p> |
| 624 | The properties of attributes that do not have a :keyword property can |
| 625 | also be set dynamically. Since :attributes is the :keyword property of |
| 626 | the ACTIVE-ATTRIBUTES attribute, the following form is equivalent to |
| 627 | the previous : |
| 628 | </p> |
| 629 | |
| 630 | |
| 631 | <pre class="src">(display t t <span style="color: #da70d6;">:attributes</span> '((active-attributes |
| 632 | <span style="color: #da70d6;">:value</span> (class package)))) |
| 633 | => |
| 634 | Class:#<BUILT-IN-CLASS SYMBOL> |
| 635 | Package:#<PACKAGE <span style="color: #bc8f8f;">"COMMON-LISP"</span>> |
| 636 | </pre> |
| 637 | |
| 638 | |
| 639 | <p> |
| 640 | Setting the attributes this way is almost like creating an anonymous |
| 641 | description context… you can express just about anything you would |
| 642 | in a DEFINE-DESCRIPTION. Here's a more involved example : |
| 643 | </p> |
| 644 | |
| 645 | |
| 646 | <pre class="src">(display t t <span style="color: #da70d6;">:attributes</span> `((identity <span style="color: #da70d6;">:label</span> <span style="color: #bc8f8f;">"The Object"</span>) |
| 647 | (class <span style="color: #da70d6;">:label</span> <span style="color: #bc8f8f;">"CLOS Class"</span>) |
| 648 | (package <span style="color: #da70d6;">:value</span> <span style="color: #bc8f8f;">"COMMON LISP"</span> <span style="color: #da70d6;">:function</span> nil) |
| 649 | (type <span style="color: #da70d6;">:value-formatter</span> |
| 650 | ,(<span style="color: #a020f0;">lambda</span> (a) |
| 651 | (format nil <span style="color: #bc8f8f;">"Got a value? ~A"</span> a))))) |
| 652 | => |
| 653 | |
| 654 | The Object:T |
| 655 | CLOS Class:#<BUILT-IN-CLASS SYMBOL> |
| 656 | Package:COMMON LISP |
| 657 | Type:Got a value? BOOLEAN |
| 658 | |
| 659 | </pre> |
| 660 | |
| 661 | |
| 662 | <p> |
| 663 | I hope that serves well to demonstrate the concepts behind LoL, as |
| 664 | there is no API documentation available at the moment… use the |
| 665 | source luke! |
| 666 | </p> |
| 667 | |
| 668 | </div> |
| 669 | |
| 670 | </div> |
| 671 | |
| 672 | <div id="outline-container-6" class="outline-2"> |
| 673 | <h2 id="sec-6">6 Automatic Descriptions for CLOS classes.</h2> |
| 674 | <div id="text-6"> |
| 675 | |
| 676 | |
| 677 | <p> |
| 678 | Lisp-on-Lines includes a compose-able metaclass, DESCRIBED-CLASS. It |
| 679 | can be combined with <u>any</u> other metaclass without affecting the |
| 680 | behavior of that class. DESCRIBED-CLASS has been used with the |
| 681 | metaclasses provided by CLSQL, ROFL, Rucksack and UCW simply by |
| 682 | defining a class that inherits from both metaclasses. |
| 683 | </p> |
| 684 | <p> |
| 685 | DESCRIBED-CLASS creates a base description for the class, named |
| 686 | DESCRIPTION-FOR-<class>, and another description with the same name |
| 687 | as the class that has the previous description as a superclass. The |
| 688 | then defines a method on DESCRIPTION-OF that returns the second |
| 689 | description. |
| 690 | </p> |
| 691 | <p> |
| 692 | LoL includes DESCRIBED-STANDARD-CLASS, which is subclass of |
| 693 | STANDARD-CLASS and DESCRIBED-CLASS. We'll use this to create a class |
| 694 | and its description. |
| 695 | </p> |
| 696 | |
| 697 | |
| 698 | <pre class="src"> |
| 699 | (<span style="color: #a020f0;">defclass</span> <span style="color: #228b22;">person</span> () |
| 700 | (first-name last-name company-name |
| 701 | date-of-birth phone fax email |
| 702 | address city province postal-code) |
| 703 | (<span style="color: #da70d6;">:metaclass</span> described-standard-class)) |
| 704 | => |
| 705 | #<DESCRIBED-STANDARD-CLASS PERSON> |
| 706 | |
| 707 | (display t (make-instance 'person)) |
| 708 | => |
| 709 | First name:#<UNBOUND> |
| 710 | Last name:#<UNBOUND> |
| 711 | Company name:#<UNBOUND> |
| 712 | Date of birth:#<UNBOUND> |
| 713 | Phone:#<UNBOUND> |
| 714 | Fax:#<UNBOUND> |
| 715 | Email:#<UNBOUND> |
| 716 | Address:#<UNBOUND> |
| 717 | City:#<UNBOUND> |
| 718 | Province:#<UNBOUND> |
| 719 | Postal code:#<UNBOUND> |
| 720 | |
| 721 | </pre> |
| 722 | |
| 723 | |
| 724 | |
| 725 | </div> |
| 726 | |
| 727 | <div id="outline-container-6.1" class="outline-3"> |
| 728 | <h3 id="sec-6.1">6.1 Described CLOS objects an the EDITABLE description</h3> |
| 729 | <div id="text-6.1"> |
| 730 | |
| 731 | |
| 732 | <p> |
| 733 | The slots of an object are SETF'able places, and LoL takes |
| 734 | advantage of that to provide EDITABLE descriptions |
| 735 | automatically. When the EDITABLE description is active, and editor |
| 736 | will be presented. The REPL based editor is pretty basic, but still |
| 737 | useful. The HTML based editor will be described later. |
| 738 | </p> |
| 739 | |
| 740 | |
| 741 | |
| 742 | <pre class="src">(<span style="color: #a020f0;">defun</span> <span style="color: #0000ff;">edit-object</span> (object <span style="color: #228b22;">&rest</span> args) |
| 743 | (<span style="color: #a020f0;">with-active-descriptions</span> (editable) |
| 744 | (apply #'display t object args))) |
| 745 | |
| 746 | (<span style="color: #a020f0;">let</span> ((object (make-instance 'person))) |
| 747 | (edit-object object) |
| 748 | (terpri) |
| 749 | (display t object)) |
| 750 | |
| 751 | <span style="color: #b22222;">;; </span><span style="color: #b22222;">What follows are prompts and the information i entered |
| 752 | </span> |
| 753 | First name:Drew |
| 754 | |
| 755 | Last name:Crampsie |
| 756 | |
| 757 | Company name:The Tech Co-op |
| 758 | |
| 759 | Date of birth:1978-07-31 |
| 760 | |
| 761 | Phone:555-5555 |
| 762 | |
| 763 | Fax:555-5555 |
| 764 | |
| 765 | Email:drewc@tech.coop |
| 766 | |
| 767 | Address:s/v Kanu, Lower Fraser River |
| 768 | |
| 769 | City:Richmond |
| 770 | |
| 771 | Province:BC |
| 772 | |
| 773 | Postal code:V1V3T6 |
| 774 | |
| 775 | <span style="color: #b22222;">;; </span><span style="color: #b22222;">And this is what was displayed. |
| 776 | </span> |
| 777 | First name:Drew |
| 778 | Last name:Crampsie |
| 779 | Company name:The Tech Co-op |
| 780 | Date of birth:1978-07-31 |
| 781 | Phone:555-5555 |
| 782 | Fax:555-5555 |
| 783 | Email:drewc@tech.coop |
| 784 | Address:s/v Kanu, Lower Fraser River |
| 785 | City:Richmond |
| 786 | Province:BC |
| 787 | Postal code:V1V3T6 |
| 788 | </pre> |
| 789 | |
| 790 | |
| 791 | </div> |
| 792 | |
| 793 | </div> |
| 794 | |
| 795 | <div id="outline-container-6.2" class="outline-3"> |
| 796 | <h3 id="sec-6.2">6.2 Extending the generated description</h3> |
| 797 | <div id="text-6.2"> |
| 798 | |
| 799 | |
| 800 | <p> |
| 801 | We mentioned earlier that DESCRIBED-CLASS creates two descriptions : |
| 802 | </p> |
| 803 | |
| 804 | |
| 805 | <pre class="src"> |
| 806 | (find-description 'description-for-person) |
| 807 | => |
| 808 | #<DESCRIPTION DESCRIPTION-FOR-PERSON {D296DE1}> |
| 809 | |
| 810 | (find-description 'person) |
| 811 | => |
| 812 | #<DESCRIPTION PERSON {ADFEDB1}> |
| 813 | |
| 814 | (description-of (make-instance 'person)) |
| 815 | => |
| 816 | #<DESCRIPTION PERSON {ADFEDB1}> |
| 817 | |
| 818 | </pre> |
| 819 | |
| 820 | |
| 821 | |
| 822 | <p> |
| 823 | The reason for this is so we can redefine the description PERSON while |
| 824 | keeping all the generated information from DESCRIPTION-FOR-PERSON. |
| 825 | </p> |
| 826 | <p> |
| 827 | In this case, we will add an attribute, PERSON-AGE, that calculates |
| 828 | a persons age based on the data in the date-of-birth slot. |
| 829 | </p> |
| 830 | |
| 831 | |
| 832 | |
| 833 | |
| 834 | |
| 835 | |
| 836 | |
| 837 | |
| 838 | |
| 839 | |
| 840 | |
| 841 | |
| 842 | </div> |
| 843 | </div> |
| 844 | |
| 845 | </div> |
| 846 | |
| 847 | <div id="outline-container-7" class="outline-2"> |
| 848 | <h2 id="sec-7">7 Using Lisp-on-Lines for the Web.</h2> |
| 849 | <div id="text-7"> |
| 850 | |
| 851 | |
| 852 | <p> |
| 853 | LoL was developed, and is primarily used, for implementing |
| 854 | data-driven web applications. As such, it comes with a host of |
| 855 | features for doing just that. |
| 856 | </p> |
| 857 | <p> |
| 858 | LoL, by default, implements its web portion on top of the wonderful |
| 859 | UnCommon Web meta-framework. The LISP-ON-LINES-UCW ASDF system |
| 860 | should be loaded, as it provides the features we're going to |
| 861 | discuss. |
| 862 | </p> |
| 863 | |
| 864 | |
| 865 | |
| 866 | |
| 867 | |
| 868 | |
| 869 | |
| 870 | |
| 871 | |
| 872 | |
| 873 | |
| 874 | |
| 875 | |
| 876 | |
| 877 | </div> |
| 878 | </div> |
| 879 | <div id="postamble"><p class="author"> Author: Drew Crampsie |
| 880 | <a href="mailto:Drew Crampsie <drewc@tech.coop>"><Drew Crampsie <drewc@tech.coop>></a> |
| 881 | </p> |
| 882 | <p class="date"> Date: 2009/07/27 01:46:25 PM</p> |
| 883 | <p>HTML generated by org-mode 6.05 in emacs 22<p> |
| 884 | </div></body> |
| 885 | </html> |