tutorial.tex 139 KB
 Dave Cooper committed Oct 11, 2012 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 \documentclass [11pt]{book} \author {Dave Cooper} \textwidth 6.5in \topmargin 0in \textheight 8.5in \oddsidemargin 0in \evensidemargin 0in \pdfimageresolution 135 \title {GenDL Unified Documentation} \usepackage [dvips]{graphicx} \usepackage [usenames, dvipsnames]{color} \usepackage {makeidx}  Dave Cooper committed Oct 23, 2012 25 26 \usepackage {textcomp}  Dave Cooper committed Oct 11, 2012 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 \usepackage [colorlinks=true, urlcolor=cyan]{hyperref} \newsavebox {\boxedverb} \makeindex \begin{document} \frontmatter \maketitle \footnotetext{Copyright \copyright{} 2012, Genworks International. Duplication, by any means, in whole or in part, requires written consent from Genworks International.} \tableofcontents \mainmatter \chapter{Introduction} \label{chap:introduction}  Dave Cooper committed Oct 16, 2012 64 65 66 67 \section{Welcome} \label{sec:welcome}  Dave Cooper committed Jun 16, 2013 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 Congratulations on your decision to work with Genworks GDL\footnote{From time to time, you will also see references to Gendl.'' This refers to The Gendl Project'' which is the name of an open-source software project from which Genworks GDL draws for its core technology. The Gendl Project'' code is free to use for any purpose, but it is released under the Gnu Affero General Public License, which stipulates that applications code compiled with The Gendl Project compiler must be distributed as open-source under a compatible license (if distributed at all). Commercial Genworks GDL, properly licensed for development and/or runtime distribution, does not have this copyleft'' open-sourcing requirement.}. By first investing some of your valuable time into learning this system, you will be investing in your future productivity, and in the process you are becoming part of a quiet revolution. Although you may have come to Genworks GDL because of an interest in 3D modeling or mechanical engineering, you will find that a whole new world, and a unique approach to computing, will now be at your fingertips.  Dave Cooper committed Oct 16, 2012 83   Dave Cooper committed Oct 11, 2012 84 85 86 87 88 \section{Knowledge Base Concepts According to Genworks} \label{sec:knowledgebaseconceptsaccordingtogenworks} You may have an idea about Knowledge Base Systems,  Dave Cooper committed Jun 16, 2013 89 90 91 92 93 or Knowledge \emph{Based} Systems, from college textbooks or corporate marketing literature, and concluded that the concepts were too broad to be of practical use. Or you may have heard criticisms of the pretentious-sounding name, Knowledge-based Engineering,'' as in: you mean as opposed to \index{Ignorance-based Engineering}Ignorance-based Engineering?''  Dave Cooper committed Oct 11, 2012 94 95  To provide a clearer picture, we hope you will agree that our concept  Dave Cooper committed Jun 16, 2013 96 97 98 99 of a KB system is straightforward, relatively uncomplicated, and practical. In this manual our goal is to make you comfortable and motivated to explore the ideas we have implemented in our flagship system, Genworks GDL.  Dave Cooper committed Oct 11, 2012 100   Dave Cooper committed Jun 16, 2013 101 Our informal definition of a \emph{\index{Knowledge Base System}Knowledge Base System} is an object-oriented programming environment which implements the features of \emph{\index{Caching}Caching} and \emph{\index{Dependency tracking}Dependency tracking}. Caching means that once the KB has computed something, it might not need to repeat  Dave Cooper committed Oct 11, 2012 102 103 104 that computation if the same question is asked again. Dependency tracking is the flip side of that coin --- it ensures that if a cached result is \emph{stale}, the result will be recomputed the next time it is \emph{demanded}, so as to give a fresh result.  Dave Cooper committed Jun 16, 2013 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 \section{Classic Definition of Knowledge Based Engineering (KBE)} \label{sec:classicdefinitionofknowledgebasedengineering(kbe)} \footnote{Sections \ref{sec:classicdefinitionofknowledgebasedengineering(kbe)} through \ref{sec:objectorienteddesign} are derived from [cite LaRocca20120306]}Knowlege based engineering (KBE) is a technology based on the use of dedicated software tools called KBE systems, which are able to capture and systematically re-use product and process engineering knowledge, with the final goal of reducing time and costs of product development by means of the following: \ul{ \li{Automation of repetitive and non-creative design tasks} \li{Support of multidisciplinary design optimization in all the phases of the design process}} \section{Classic Caching Feature} \label{sec:classiccachingfeature} Caching refers to the ability of the KBE system to memorize at runtime the results of computed values (e.g. computed slots and instantiated objects), so that they can be reused when required, without the need to re-compute them again and again, unless necessary. The dependency tracking mechanism serves to keep track of the current validity of the cached values. As soon as these values are no longer valid (stale), they are set to unbound and recomputed if and only at the very moment they are again demanded. \p{This dependency tracking mechanism is at the base of associative modeling, which is of extreme interest for engineering design applications. For example, the shape of a wing rib can be defined accordingly to the shape of the wing aerodynamic surface. In case the latter is modified, the dependency tracking mechanism will notify the system that teh given rib instance is no longer valid and will be eliminated from the product tree, together with all the information (objects and attributes) depending on it. The new rib object, including its attributes and the rest of the affected information, will not be re-instantiated/updated/re-evaluated automatically, but only when and if needed (see demand driven instantiation in the next section)} \section{Demand-Driven Evaluation} \label{sec:demand-drivenevaluation} KBE systems use the \emph{demand-driven}approach. That is, they evaluate just those chains of expressions required to satisfy a direct request of the user (i.e. the evaluation of certain attributes ofor the instantiation of an object), or the indirect requests of another object, which is trying to satisfy a user demand. For example, the system will create an instance of the rib object only when the weight of the abovementioned wing rib is required. The reference wing surface will be generated only when the generation of the rib object is required, and so on, until all the information required to respond to the user request will be made available. It should be recognized that a typical object tree can be structured in hundreds of branches and include thousands of attributes. Hence, the ability to evaluate specific attributes and product model branches at demand, without the need to evaluate the whole model from its root, prevents waste of computational resources and in many cases brings seemingly intractible problems into the realm of the tractible. \section{The Object-Oriented Paradigm meets the Functional paradigm} \label{sec:theobject-orientedparadigmmeetsthefunctionalparadigm} In order to model very complex products and manage efficiently large bodies of knowledge, KBE systems tap the potential of the object oriented nature of their underlying language (e.g. Common Lisp). Object'' in this context refers to an instantiated data structure of a particular assigned data type. As is well-known in computing community, unrestricted state modification of objects leads to unmaintainable systems which are difficult to debug. KBE systems manage this drawback by strictly controlling and constraining any ability to modify or change state'' of objects. In essence, a KBE system generates a tree of inspectable objects which is analogous to the function call tree of pure functional-language systems. \section{Object-oriented Systems} \label{sec:object-orientedsystems} An object-oriented system is composed of objects (i.e. concrete instantiations of named classes), and the behavior of the system results from the collaboration of those objects. Collaboration between objects involves them sending messages to each other. Sending a message differs from calling a function in that when a target object receives a message, it decides on its own what function to carry out to service that message. The same message may be implemented by many different functions, the one selected depending on the current state of the target object. \section{Object-oriented Analysis} \label{sec:object-orientedanalysis} Object-oriented analysis (OOA) is the process of analyzing a task (also known as a problem domain) to develop a conceptual model that can then be used to complete the task. A typical OOA model would describe computer software that could be used to satisfy a set of customer-defined requirements. During the analysis phase of problem-solving, the analyst might consider a written requirements statement, a formal vision document, or interviews with stakeholders or other interested parties. The task to be addressed might be divided into several subtasks (or domains), each representing a different business, technological, or other area of business. Each subtask would be analyzed separately. Implementation constraints (e.g. concurrency, distribution, persistence, or how the system is to be built) are not considered during the analysis phase; rather, they are addressed during object-oriented design (OOD). The conceptual model that results from OOA will typically consist of a set of use cases, one or more UML class diagrams, and a number of interaction diagrams. It may also include some kind of user interface.  Dave Cooper committed Oct 11, 2012 235   Dave Cooper committed Jun 16, 2013 236 237 238 239 240 241 242 243 244 245 246 \section{Object-oriented Design} \label{sec:object-orienteddesign} During object-oriented design (OOD), a developer applies implementation constraints to the conceptual model produced in object-oriented analysis. Such constraints could include not only constraints imposed by the chosen architecture but also any non-functional --- technological or environmental --- constraints, such as transaction throughput, response time, run-time platform, development environment, or those inherent in the programming language. Concepts in the analysis model are mapped onto implementation classes and interfaces resulting in a model of the solution domain, i.e., a detailed description of \emph{how} the system is to be built.  Dave Cooper committed Oct 11, 2012 247   Dave Cooper committed Jun 16, 2013 248 249 250 251 252 253 254 \section{Goals for this Manual} \label{sec:goalsforthismanual} This manual is designed as a companion to a live two-hour GDL/GWL tutorial, but you may also be relying on it independent of the video tutorial. In either case, the basic goals are:  Dave Cooper committed Oct 11, 2012 255 256 257  \begin{itemize}  Dave Cooper committed Jun 16, 2013 258 \item Get you motivated about using Genworks GDL  Dave Cooper committed Oct 11, 2012 259   Dave Cooper committed Jun 16, 2013 260 \item Enable you to ascertain whether Genworks GDL is an appropriate tool for a given job  Dave Cooper committed Oct 11, 2012 261   Dave Cooper committed Jun 16, 2013 262 \item Equip you with the ability to state the case for using GDL/GWL when appropriate  Dave Cooper committed Oct 11, 2012 263   Dave Cooper committed Jun 16, 2013 264 265 \item Prepare you to begin authoring and maintaining GDL applications, or porting apps from similar KB systems into GDL.  Dave Cooper committed Oct 11, 2012 266 267 268  \end{itemize}  Dave Cooper committed Jun 16, 2013 269 270 271 272 273 274 This manual will begins with an introduction to the \index{Common Lisp}Common Lisp programming language. If you are new to Common Lisp: congratulations! You have just been introduced to a powerful tool backed by a rock-solid standard specification, which will protect your development investment for decades to come. In addition to the overview in this manual, many resources are available to get you started in CL --- for starters, we recommend  Dave Cooper committed Oct 11, 2012 275 \underline{\index{Basic Lisp Techniques}Basic Lisp Techniques}\footnote{  Dave Cooper committed Jun 16, 2013 276 \underline{BLT} is available at \texttt{http://www.franz.com/resources/educational\_resources/cooper.book.pdf}}, which was prepared by the author.  Dave Cooper committed Oct 11, 2012 277   Dave Cooper committed Jun 16, 2013 278 \section{What is GDL?}  Dave Cooper committed Oct 11, 2012 279   Dave Cooper committed Jun 16, 2013 280 \label{sec:whatisgdl?}  Dave Cooper committed Oct 11, 2012 281   Dave Cooper committed Jun 16, 2013 282 GDL is an acronym for  Dave Cooper committed Oct 11, 2012 283 284 General-purpose Declarative Language.''  Dave Cooper committed Jun 16, 2013 285 GDL is a superset of ANSI Common Lisp, and consists largely of  Dave Cooper committed Oct 11, 2012 286 automatic code-expanding extensions to Common Lisp implemented in the  Dave Cooper committed Jun 16, 2013 287 form of macros. When you write, for example, 20 lines in GDL, you  Dave Cooper committed Oct 11, 2012 288 might be writing the equivalent of 200 lines of Common Lisp. Of  Dave Cooper committed Jun 16, 2013 289 290 291 course, since GDL is a superset of Common Lisp, you still have the full power of the CL language at your disposal whenever you are working in GDL.  Dave Cooper committed Oct 11, 2012 292 293 294  \index{compiled language!benefits of}\index{macros!code-expanding}Since GDL expands into CL, everything you write in GDL will be compiled down to the metal'' to machine code with all the  Dave Cooper committed Jun 16, 2013 295 296 297 298 299 optimizations and safety that the tested-and-true CL compiler provides [this is an important distinction as contrasted to some other so-called KB systems on the market, which are essentially nothing more than interpreted \emph{scripting languages} which often impose arbitrary limits on the size and complexity of the application.  Dave Cooper committed Oct 11, 2012 300   Dave Cooper committed Jun 16, 2013 301 GDL is also a \emph{\index{declarative}declarative} language in the fullest sense. When you put together a GDL application, you write and think mainly  Dave Cooper committed Oct 11, 2012 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 in terms of objects and their properties, and how they depend on one another in a direct sense. You do not have to track in your mind explicitly how one object or property will call'' another object or propery, in what order this will happen, etc. Those details are taken care of for you automatically by the language. Because GDL is object-oriented, you have all the features you would normally expect from an object-oriented language, such as \begin{itemize} \item Separation between the \emph{definition} of an object and an \emph{instance} of an object \item High levels of data abstraction \item The ability for one object to inherit'' from others  Dave Cooper committed Jun 16, 2013 318 319 \item The ability to use'' an object without concern for its under-the-hood'' complexities  Dave Cooper committed Oct 11, 2012 320 321 322  \end{itemize}  Dave Cooper committed Jun 16, 2013 323 324 325 326 327 328 \index{object-orientation!message-passing}\index{object-orientation!generic-function}GDL supports the message-passing'' paradigm of object orientation, with some extensions. Since full-blown ANSI CLOS (Common Lisp Object System) is always available as well, the Generic Function paradigm is supported as well. Do not be concerned at this point if you are not fully aware of the differences between these two paradigms\footnote{See Paul Graham's  Dave Cooper committed Oct 11, 2012 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 \underline{ANSI Common Lisp}, page 192, for an excellent discussion of the Two Models of Object-oriented Programming.}. \section{Why GDL (what is GDL good for?)} \label{sec:whygdl(whatisgdlgoodfor?)} \begin{itemize} \item Organizing and interrelating large amounts of information in ways not possible or not practical using conventional languages or conventional relational database technology alone; \item Evaluating many design or engineering alternatives and performing various kinds of optimizations within specified design spaces; \item Capturing the procedures and rules used to solve repetitive tasks in engineering and other fields; \item Applying rules to achieve intermediate and final outputs, which may include virtual models of wireframe, surface, and solid geometric objects. \end{itemize} \section{What GDL is not} \label{sec:whatgdlisnot} \begin{itemize} \item A CAD system (although it may operate on and/or generate geometric entities); \item A drawing program (although it may operate on and/or generate geometric entities);  Dave Cooper committed Jun 16, 2013 371 372 373 \item An Artificial Intelligence system (although it is an excellent environment for developing capabilities which could be considered as such);  Dave Cooper committed Oct 11, 2012 374 375 376 377 378 379 380 381 382 383 384  \item An Expert System Shell (although one could be easily embedded within it). \end{itemize} Without further ado, then, let's turn the page and get started with some hands-on GDL... \chapter{Installation} \label{chap:installation}  Dave Cooper committed Oct 16, 2012 385 Follow Section  Dave Cooper committed Jun 16, 2013 386 387 388 389 \ref{sec:installationofpre-packagedgdl} if your email address is registered with Genworks and you will install a pre-packaged Genworks GDL distribution including its own Common Lisp engine. The foundation of Genworks GDL is also available as open-source software through The Gendl Project\footnote{http://github.com/genworks/gendl}; if you want to use that version, then please refer to Section  Dave Cooper committed Oct 16, 2012 390 \ref{sec:installationofopen-sourcegendl}.  Dave Cooper committed Oct 11, 2012 391   Dave Cooper committed Jun 16, 2013 392 \section{Installation of pre-packaged GDL}  Dave Cooper committed Oct 11, 2012 393   Dave Cooper committed Jun 16, 2013 394 \label{sec:installationofpre-packagedgdl}  Dave Cooper committed Oct 11, 2012 395   Dave Cooper committed Jun 16, 2013 396 397 398 399 This section will take you through the installation of Genworks GDL from a prepackaged distribution with the Allegro CL or LispWorks commercial Common Lisp engine and the Slime IDE (based on Gnu Emacs).  Dave Cooper committed Oct 11, 2012 400 401 402 403 404 405 406 407 408  \subsection{Download the Software and retrieve a license key} \label{subsec:downloadthesoftwareandretrievealicensekey} \begin{enumerate}  Dave Cooper committed Jun 16, 2013 409 \item Visit the Downloads section of the \href{http://genworks.com}{Genworks Website}  Dave Cooper committed Oct 11, 2012 410 411 412  \item Enter your email address\footnote{if your address is not on file, send mail to licensing@genworks.com}.  Dave Cooper committed Jun 16, 2013 413 414 415 \item Download the latest Payload for Windows, Linux, or Mac\footnote{Gnu Emacs is included with the download. The source code for this is available at http://downloads.genworks.com/emacs-windows-24.3.zip. Gnu Ghostscript is also included; please contact Genworks if you need the source code for this.}  Dave Cooper committed Oct 11, 2012 416 417 418 419 420 421 422 423 424 425 426  \item Click to receive license key file by email. \end{enumerate} \subsection{Unpack the Distribution} \label{subsec:unpackthedistribution}  Dave Cooper committed Jun 16, 2013 427 428 429 430 Genworks GDL is currently distributed as an setup executable for Windows, a dmg'' application bundle for Mac, and a self-contained zip file for Linux. \ul{ \item Run the installation executable. Accept the defaults when prompted.\footnote{For Linux, you have to install emacs and ghostscript yourself. Please use your distribution's package manager to complete this installation.}  Dave Cooper committed Oct 11, 2012 431 432  \item Copy the license key file as gdl.lic (for Trial,  Dave Cooper committed Jun 16, 2013 433 434  Student, Professional editions), or devel.lic (for Enterprise edition) into the \texttt{program/} directory within the \textt{gdl/gdl/program/} directory.  Dave Cooper committed Oct 11, 2012 435   Dave Cooper committed Jun 16, 2013 436 437 \item Launch the application by finding the Genworks program group in the Start menu (Windows), or by double-clicking the application icon (Mac), or by running the \texttt{run-gdl} script (Linux). }  Dave Cooper committed Oct 16, 2012 438 439 440 441 442 443 444  \section{Installation of open-source Gendl} \label{sec:installationofopen-sourcegendl} This section is only relevant if you have not received a pre-packaged Gendl distribution with its own Common Lisp engine. If  Dave Cooper committed Jun 16, 2013 445 you have received a pre-packaged Gendl distribution, then you may skip  Dave Cooper committed Oct 16, 2012 446 this section. In case you want to use the open-source Gendl, you will  Dave Cooper committed Jun 16, 2013 447 use your own Common Lisp installation and obtain Gendl (Genworks-GDL)  Dave Cooper committed Oct 16, 2012 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 using a very powerful and convenient CL package/library manager called \emph{Quicklisp}. \subsection{Install and Configure your Common Lisp environment} \label{subsec:installandconfigureyourcommonlispenvironment} Gendl is currently tested to build on the following Common Lisp engines: \begin{itemize} \item Allegro CL (commercial product from Franz Inc, free Express Edition available) \item LispWorks (commercial product from LispWorks Ltd, free Personal Edition available)  Dave Cooper committed May 16, 2013 463 464 \item Clozure CL (free CL engine from Clozure Associates, free for all use)  Dave Cooper committed Oct 16, 2012 465 466 467 468 \item Steel Bank Common Lisp (SBCL) (free open-source project with permissive license) \end{itemize}  Dave Cooper committed Jun 16, 2013 469 470 471 472 473 474 Please refer to the documentation for each of these systems for full information on installing and configuring the environment. Typically this will include a text editor, either Gnu Emacs with Superior Lisp Interaction Mode for Emacs (Slime), or a built-in text editing and development environment which comes with the Common Lisp system.  Dave Cooper committed Oct 16, 2012 475   Dave Cooper committed Jun 16, 2013 476 A convenient way to set up Emacs with Slime is to use the \href{http://github.com/quicklisp/quicklisp-slime-helper}{Quicklisp-slime-helper}.  Dave Cooper committed Oct 16, 2012 477 478 479 480 481  \subsection{Load and Configure Quicklisp} \label{subsec:loadandconfigurequicklisp}  Dave Cooper committed Jun 16, 2013 482 483 Quicklisp is the defacto standard library manager for Common Lisp.  Dave Cooper committed Oct 16, 2012 484 485 486 487 488 489 490 491 492 493 494  \begin{itemize} \item Visit the \href{http://quicklisp.org}{Quicklisp website} \item Follow the instructions there to download the \texttt{quicklisp.lisp} bootstrap file and load it to set up your Quicklisp environment. \end{itemize}  Dave Cooper committed Jun 16, 2013 495 \subsection{Load and Start Gendl}  Dave Cooper committed Oct 16, 2012 496   Dave Cooper committed Jun 16, 2013 497 \label{subsec:loadandstartgendl}  Dave Cooper committed Oct 16, 2012 498   Dave Cooper committed Jun 16, 2013 499 500 501 502 invoke the following commands at the Common Lisp toplevel repl'' prompt: \ol{ \li{\texttt{(ql:quickload :gendl)}} \li{\texttt{(gendl:start-gendl!)}}}  Dave Cooper committed Oct 16, 2012 503   Dave Cooper committed Jun 16, 2013 504 \section{System Testing}  Dave Cooper committed Oct 16, 2012 505   Dave Cooper committed Jun 16, 2013 506 \label{sec:systemtesting}  Dave Cooper committed Oct 16, 2012 507 508 509   Dave Cooper committed Jun 16, 2013 510 \subsection{Basic Sanity Test}  Dave Cooper committed Oct 16, 2012 511   Dave Cooper committed Jun 16, 2013 512 \label{subsec:basicsanitytest}  Dave Cooper committed Oct 16, 2012 513 514 515 516 517 518  You may test your installation using the following checklist. These tests are optional. You may perform some or all of them in order to ensure that your Gendl is installed correctly and running smoothly. In your Web Browser (e.g. Google Chrome, Firefox, Safari, Opera, Internet Explorer), perform the following steps:  Dave Cooper committed Oct 11, 2012 519 520 521 522 523 524 525 526 527 528 529  \begin{enumerate} \item visit http://localhost:9000/tasty. \item accept default robot:assembly. \item Select Add Leaves'' from the Tree menu. \item Click on the top node in the tree.  Dave Cooper committed Oct 16, 2012 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 \item Observe the wireframe graphics for the robot as shown in \ref{fig:tasty-robot}. \begin{figure} \begin{center} \includegraphics[width=3in,height=3in]{../images/tasty-robot.png} \end{center} \caption{Robot displayed in Tasty} \label{fig:tasty-robot} \end{figure} \begin{figure} \begin{center} \includegraphics[width=3in,height=3in]{../images/tasty-robot-x3dom.png} \end{center} \caption{Robot x3dom} \label{fig:tasty-robot-x3dom} \end{figure}  Dave Cooper committed Oct 11, 2012 554 555 556 557 558 559 560 561 562 563 564  \item Click on the robot to zoom in. \item Select Clear View!'' from the View menu. \item Select X3DOM'' from the View menu. \item Click on the top node in the tree. \item Refresh'' or Reload'' your browser window (may not be necessary).  Dave Cooper committed Oct 16, 2012 565 566 \item If your browser supports WebGL, you will see the robot in shaded dynamic view as shown in Figure \ref{fig:tasty-robot-x3dom}.  Dave Cooper committed Oct 11, 2012 567   Dave Cooper committed Jun 16, 2013 568 569 \item Select PNG'' from the View menu. You will see the wireframe view of the robot as a PNG image.  Dave Cooper committed Oct 11, 2012 570   Dave Cooper committed Jun 16, 2013 571 572 573 \item Select X3D'' from the View menu. If your browser has an X3D plugin installed (e.g. BS Contact), you will see the robot in a shaded dynamic view.  Dave Cooper committed Oct 11, 2012 574 575 576 577 578  \end{enumerate}  Dave Cooper committed Oct 16, 2012 579 580 581 582 \subsection{Full Regression Test} \label{subsec:fullregressiontest}  Dave Cooper committed Jun 16, 2013 583 584 585 586 587 588 \index{regression tests}The following commands will invoke a full regression test, including a test of the Surface and Solids primitives provided by the SMLib geometry kernel. Note that the SMLib geometry kernel is only available with proprietary Genworks GDL licenses --- therefore if you have open-source Gendl or a lite Trial version of Genworks GDL, these regression tests will not all function.  Dave Cooper committed Oct 16, 2012 589   Dave Cooper committed Oct 23, 2012 590 In Emacs at the \texttt{gdl-user>} prompt in the \texttt{*slime-repl...*} buffer, type the following commands:  Dave Cooper committed Oct 16, 2012 591 592 593  \begin{enumerate}  Dave Cooper committed Jun 16, 2013 594 \item \texttt{(ql:quickload :regression)}  Dave Cooper committed Oct 16, 2012 595 596 597 598 599 600 601  \item \texttt{(gdl-lift-utils::define-regression-tests)} \item \texttt{(gdl-lift-utils::run-regression-tests-pass-fail)} \item \texttt{(pprint gdl-lift-utils::*regression-test-report*)}  Dave Cooper committed Oct 11, 2012 602 603 604 605 \end{enumerate}  Dave Cooper committed Oct 16, 2012 606 \section{Getting Help and Support}  Dave Cooper committed Oct 11, 2012 607   Dave Cooper committed Oct 16, 2012 608 \label{sec:gettinghelpandsupport}  Dave Cooper committed Oct 11, 2012 609   Dave Cooper committed Jun 16, 2013 610 611 If you encounter unexplained errors in the installation and startup process, please contact the following resources:  Dave Cooper committed Oct 11, 2012 612   Dave Cooper committed Oct 16, 2012 613 \begin{enumerate}  Dave Cooper committed Oct 11, 2012 614   Dave Cooper committed Oct 16, 2012 615 \item Make a posting to the \href{http://groups.google.com/group/genworks}{Genworks Google Group}  Dave Cooper committed Oct 11, 2012 616   Dave Cooper committed Jun 16, 2013 617 618 \item Join the \#gendl IRC (Internet Relay Chat) channel on irc.freenode.net and discuss issues there.  Dave Cooper committed Oct 11, 2012 619   Dave Cooper committed Jun 16, 2013 620 621 622 623 624 625 \item For exclusively Common Lisp issues, join the \#lisp IRC (Internet Relay Chat) channel on irc.freenode.net and discuss issues there. \item Also for Common Lisp issues, follow the comp.lang.lisp Usenet group.  Dave Cooper committed Oct 11, 2012 626   Dave Cooper committed Oct 16, 2012 627 \item If you are a supported Genworks customer, send email to \href{mailto:support@genworks.com}{support@genworks.com}  Dave Cooper committed Oct 11, 2012 628   Dave Cooper committed Jun 16, 2013 629 630 631 632 \item If you are not a supported Genworks customer but you want to report an apparent bug or have other suggestions or inquiries, you may also send email to \href{mailto:support@genworks.com}{support@genworks.com}, but as a non-customer please understand that Genworks cannot guarantee a response or a particular timeframe for a response. Also note that we are not able to offer guaranteed support for Trial and Student licenses  Dave Cooper committed Oct 11, 2012 633   Dave Cooper committed Oct 16, 2012 634 \end{enumerate}  Dave Cooper committed Oct 11, 2012 635 636 637   Dave Cooper committed Jun 16, 2013 638 \chapter{Basic Operation of the GDL Environment}  Dave Cooper committed Oct 11, 2012 639   Dave Cooper committed Jun 16, 2013 640 \label{chap:basicoperationofthegdlenvironment}  Dave Cooper committed Oct 11, 2012 641   Dave Cooper committed Jun 16, 2013 642 643 644 645 646 647 This chapter will lead you through all the basic steps of operating a typical GDL-based development environment. We will not go into any depth about the additional features of the environment or language syntax in this section --- this is just for getting familiar and practicing with the mechanics of operating the environment with a keyboard.  Dave Cooper committed Oct 23, 2012 648   Dave Cooper committed Jun 16, 2013 649 \section{What is Different about GDL?}  Dave Cooper committed Oct 23, 2012 650   Dave Cooper committed Jun 16, 2013 651 \label{sec:whatisdifferentaboutgdl?}  Dave Cooper committed Oct 23, 2012 652   Dave Cooper committed Jun 16, 2013 653 654 655 656 657 658 GDL is a dynamic language environment with incremental compiling and in-memory definitions. That means that as long as the system is running you can \emph{compile} new \emph{definitions} of functions, objects, etc, and they will immediately become available as part of the running system, and you can begin testing them immediately or update an existing set of objects to observe their new behavior.  Dave Cooper committed Oct 11, 2012 659   Dave Cooper committed Jun 16, 2013 660 661 662 In many other programming language systems, to introduce a new function or object, one has to start the system from the beginning and reload all the files in order to test new functionality.  Dave Cooper committed Oct 23, 2012 663   Dave Cooper committed Jun 16, 2013 664 665 666 667 668 669 670 671 In GDL, if you shut down the system after having compiled and loaded a set of files with new definitions, then when you restart the system you will have to recompile and/or reload those definitions in order to bring the system back into the same state. This is typically done automatically, using commands placed into the \texttt{gdlinit.cl} initialization file, as introduced in Section \ref{sec:customizingyourenvironment}. Alternatively, you can compile and load definitions into your session, then save the world'' in that state. That way it is possible to start a new GDL world'' which already has all your  Dave Cooper committed Oct 23, 2012 672 673 674 application's definitions loaded and ready for use, without having to procedurally reload any files. You can then begin to make and test new definitions (and re-definitions) starting from this new world.''  Dave Cooper committed Oct 11, 2012 675   Dave Cooper committed Oct 23, 2012 676 \section{Startup, Hello, World!'' and Shutdown}  Dave Cooper committed Oct 11, 2012 677   Dave Cooper committed Oct 23, 2012 678 \label{sec:startup,hello,world!andshutdown}  Dave Cooper committed Oct 11, 2012 679 680   Dave Cooper committed Oct 23, 2012 681   Dave Cooper committed Jun 16, 2013 682 683 The typical GDL environment consists of three programs: Gnu Emacs (the editor), a Common Lisp engine with GDL system loaded or built into it (e.g. the \texttt{gdl.exe} executable in your \texttt{program/} directory), and (optionally) a web browser  Dave Cooper committed Oct 23, 2012 684 such as Firefox, Google Chrome, Safari, Opera, or Internet  Dave Cooper committed Jun 16, 2013 685 Explorer. Emacs runs as the main \emph{process}, and this in turn starts the CL engine with GDL as a \emph{sub-process}. The CL engine typically runs an embedded \emph{webserver}, enabling you to access your application through a standard web browser.  Dave Cooper committed Oct 16, 2012 686 687 688 689  As introduced in Chapter  Dave Cooper committed Jun 16, 2013 690 691 692 693 694 \ref{chap:installation}, the typical way to start a pre-packaged GDL environment is with the \texttt{run-gdl.bat} (Windows), or \texttt{run-gdl} (MacOS, Linux) script files, or with the installed Start program item (Windows) or application bundle (MacOS). Invoke this script file from the Start menu (Windows), your computer's file manager, or from a desktop shortcut if you have created one as outlined in section  Dave Cooper committed Oct 23, 2012 695 \ref{subsec:makeadesktopshortcut}. Your installation executable may also have created a  Dave Cooper committed Jun 16, 2013 696 Windows Start'' menu item for Genworks GDL. Of course you can also  Dave Cooper committed Oct 23, 2012 697 698 699 700 701 702 703 704 705 invoke \texttt{run-gdl.bat} from the Windows cmd'' command-line, or from another command shell such as Cygwin.\footnote{Cygwin is also useful as a command-line tool on Windows for interacting with a version control system like Subversion (svn).} \subsection{Startup} \label{subsec:startup}  Dave Cooper committed Jun 16, 2013 706  Startup of a typical GDL development session consists of  Dave Cooper committed Oct 23, 2012 707 two fundamental steps: (1) starting the Emacs editing environment,  Dave Cooper committed Jun 16, 2013 708 709 710 and (2) starting the actual GDL process as a sub-process'' or inferior'' process within Emacs. The GDL process should automatically establish a network connection back to Emacs, allowing you to interact directly with the GDL process from within Emacs.  Dave Cooper committed Oct 23, 2012 711 712 713  \begin{enumerate}  Dave Cooper committed Jun 16, 2013 714 715 716 \item Invoke the \texttt{run-gdl.bat}, \texttt{run-gdl.bat} startup script, or the provided executable from the Start menu (windows) or application bundle (Mac).  Dave Cooper committed Oct 23, 2012 717 718 719 720  \item You should see a blue emacs window as in Figure \ref{fig:emacs-startup}. (alternative colors are also possible).  Dave Cooper committed Jun 16, 2013 721 \item (MS Windows): Look for the Genworks GDL Console  Dave Cooper committed Oct 23, 2012 722 window, or (Linux, Mac) use the Emacs Buffer'' menu to visit the  Dave Cooper committed Jun 16, 2013 723 *inferior-lisp*'' buffer. Note that the Genworks GDL Console  Dave Cooper committed Oct 23, 2012 724 725 726 727 728 window might start as a minimized icon; click or double-click it to un-minimize. \item Watch the Genworks GDL Console window for any errors. Depending on your specific installation, it may take from a  Dave Cooper committed Jun 16, 2013 729 few seconds to several minutes for the Genworks GDL Console (or  Dave Cooper committed Oct 23, 2012 730 731 732 733 *inferior-lisp* buffer) to settle down and give you a \texttt{gdl-user(): } prompt. This window is where you will see most of your program's textual output, any error messages, warnings, etc. \item In Emacs, type: \texttt{C-x \&} (or select Emacs menu item Buffers$\rightarrow$*slime-repl...*) to visit the *slime-repl ...*'' buffer. The full name  Dave Cooper committed Jun 16, 2013 734 735 736 of this buffer depends on the specific CL/GDL platform which you are running. This buffer contains an interactive prompt, labeled \texttt{gdl-user>}, where you will enter most of your commands to interact with your running GDL session for testing, debugging, etc. There is also a web-based graphical interactive environment called \emph{tasty} which will be discussed in Chapter  Dave Cooper committed Oct 23, 2012 737 738 \ref{chapter:tasty}  Dave Cooper committed Jun 16, 2013 739 \item To ensure that the GDL command prompt is up and running, type: \texttt{(+ 2 3)} and press [Enter].  Dave Cooper committed Oct 23, 2012 740 741 742 743 744 745 746  \item You should see the result \texttt{5} echoed back to you below the prompt. \end{enumerate}  Dave Cooper committed Jun 16, 2013 747 \subsection{Developing and Testing a Hello World'' application}  Dave Cooper committed Oct 23, 2012 748   Dave Cooper committed Jun 16, 2013 749 \label{subsec:developingandtestingahelloworldapplication}  Dave Cooper committed Oct 23, 2012 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773  \begin{enumerate} \item type C-x (Control-x) 2, or C-x 3, or use the Split Screen'' option of the File menu to split the Emacs frame into two windows'' (windows'' in Emacs are non-overlapping panels, or rectangular areas within the main Emacs window). \item type C-x o several times to move from one window to the other, or move the mouse cursor and click in each window. Notice how the blinking insertion point moves from one window to the other. \item In the top (or left) window, type C-x C-f (or select Emacs menu item File$\rightarrow$Open File'') to get the Find file'' prompt in the mini-buffer. \item Type C-a to move the point to the beginning of the mini-buffer line. \item Type C-k to delete from the point to the end of the mini-buffer. \item Type \texttt{\textasciitilde/hello.gdl} and press [Enter]  Dave Cooper committed Jun 16, 2013 774 \item You are now editing a (presumably new) file of GDL  Dave Cooper committed Oct 23, 2012 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814  code, located in your HOME directory, called \texttt{hello.gdl} \item Enter the text from Figure \ref{fig:simpleobjectdefinition} into the \texttt{hello.gdl} buffer. You do not have to match the line breaks and whitespace as shown in the example. You can auto-indent each new line by pressing [TAB] after pressing [Enter] for the newline. \emph{Protip:}You can also try using \texttt{C-j} instead of [Enter], which will automatically give a newline and auto-indent. \begin{figure} \begin{lrbox}{\boxedverb} \begin{minipage}{\linewidth} \begin{verbatim} (in-package :gdl-user) (define-object hello () :computed-slots ((greeting "Hello, World!"))) \end{verbatim} \end{minipage} \end{lrbox} \fbox{\usebox{\boxedverb}} \caption{Example of Simple Object Definition} \label{fig:simpleobjectdefinition} \end{figure} \item type \texttt{C-x C-s} (or choose Emacs menu item \emph{File$\rightarrow$Save}) to save the contents of the buffer (i.e. the window) to the file in your HOME directory. \item type \texttt{C-c C-k} (or choose Emacs menu item \emph{SLIME$\rightarrow$Compilation$\rightarrow$Compile/Load File}) to compile \& load the code from this file. \item type \texttt{C-c o} (or move and click the mouse) to switch to the bottom window.  Dave Cooper committed Jun 16, 2013 815 \item In the bottom window, type \texttt{C-x \&} (or choose Emacs menu item \emph{Buffers$\rightarrow$*slime-repl...*}) to get the \texttt{*slime-repl ...*} buffer, which should contain a \texttt{gdl-user>} prompt. This is where you normally type interactive GDL commands.  Dave Cooper committed Oct 23, 2012 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839  \item If necessary, type \texttt{M \textgreater} (that is, hold down Meta (Alt), Shift, and the \textgreater'' key) to move the insertion point to the end of this buffer. \item At the \texttt{gdl-user>} prompt, type \begin{verbatim}(make-self 'hello) \end{verbatim} and press [Enter]. \item At the \texttt{gdl-user>} prompt, type \begin{verbatim}(the greeting) \end{verbatim} and press [Enter]. \item You should see the words \texttt{Hello, World!} echoed back to you below the prompt. \end{enumerate} \subsection{Shutdown} \label{subsec:shutdown}  Dave Cooper committed Jun 16, 2013 840  To shut down a development session gracefully, you should first shut down the GDL process,  Dave Cooper committed Oct 23, 2012 841 842 843 844 then shut down your Emacs. \begin{itemize}  Dave Cooper committed Jun 16, 2013 845 \item Type \texttt{M-x quit-gdl} (that is, hold Alt and press X, then release both while you type \texttt{quit-gdl} in the mini-buffer), then press [Enter]  Dave Cooper committed Oct 23, 2012 846   Dave Cooper committed Jun 16, 2013 847 848 849 850 851 852 \item alternatively, you can type \texttt{C-x &} (that is, hold Control and press X, then release both while you type &. This will visit the *slime-repl* buffer. Now type: \textt{, q} to quit the GDL session. \item Finally, type \texttt{C-x C-c} to quit from Emacs. Emacs will prompt you to save any modified buffers before exiting.  Dave Cooper committed Oct 23, 2012 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894  \end{itemize} \section{Working with Projects} \label{sec:workingwithprojects} Gendl contains utilities which allow you to treat your application as a project,'' with the ability to compile, incrementally compile, and load a project'' from a directory tree of source files representing your project. In this section we give an overview of the expected directory structure and available control files, followed by a reference for each of the functions included in the bootstrap module. \subsection{Directory Structure} \label{subsec:directorystructure} You should structure your applications in a modular fashion, with the directories containing actual Lisp sources called "source." You may have subdirectories which themselves contain "source" directories. We recommend keeping your codebase directories relatively flat, however. In Figure \ref{fig:yoyodyne-base} is an example application directory, with four source files.  Dave Cooper committed Oct 26, 2012 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 \begin{figure} \begin{lrbox}{\boxedverb} \begin{minipage}{\linewidth} \begin{verbatim} apps/yoyodyne/booster-rocket/source/assembly.gdl apps/yoyodyne/booster-rocket/source/package.gdl apps/yoyodyne/booster-rocket/source/parameters.gdl apps/yoyodyne/booster-rocket/source/rules.gdl \end{verbatim} \end{minipage} \end{lrbox} \fbox{\usebox{\boxedverb}} \caption{Example project directory with four source files} \label{fig:yoyodyne-base} \end{figure} \subsection{Source Files within a source/ subdirectory} \label{subsec:sourcefileswithinasource/subdirectory} \subsubsection{Enforcing Ordering} \label{subsubsec:enforcingordering} Within a source subdirectory, you may have a file called \texttt{file-ordering.isc}\footnote{\texttt{isc} stands for Intelligent Source Configuration''} to enforce a certain ordering on the files. Here is the contents of an example for the above application:  Dave Cooper committed Jun 16, 2013 934 935 \begin{verbatim}("package" "parameters") \end{verbatim}  Dave Cooper committed Oct 26, 2012 936 937 938 939 940 941 942 943 944  This will force package.lisp to be compiled/loaded first, and parameters.lisp to be compiled/loaded next. The ordering on the rest of the files should not matter (although it will default to lexigraphical ordering). Now our sample application directory looks like Figure  Dave Cooper committed Jun 16, 2013 945 \ref{fig:yoyodyne-with-file-ordering-isc}.  Dave Cooper committed Oct 26, 2012 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968  \begin{figure} \begin{lrbox}{\boxedverb} \begin{minipage}{\linewidth} \begin{verbatim} apps/yoyodyne/booster-rocket/source/assembly.gdl apps/yoyodyne/booster-rocket/source/file-ordering.isc apps/yoyodyne/booster-rocket/source/package.gdl apps/yoyodyne/booster-rocket/source/parameters.gdl apps/yoyodyne/booster-rocket/source/rules.gdl \end{verbatim} \end{minipage} \end{lrbox} \fbox{\usebox{\boxedverb}} \caption{Example project directory with file ordering configuration file} \label{fig:yoyodyne-with-file-ordering-isc} \end{figure}  Dave Cooper committed Oct 23, 2012 969   Dave Cooper committed Nov 19, 2012 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 \subsection{Generating an ASDF System} \label{subsec:generatinganasdfsystem} ASDF stands for Another System Definition Facility, which is the predominant system in use for Common Lisp third-party libraries. With Gendl, you can use the \texttt{:create-asd-file?} keyword argument to make cl-lite generate an ASDF system file instead of actually compiling and loading the system. For example: \begin{verbatim}(cl-lite "apps/yoyodyne/" :create-asd-file? t) \end{verbatim} In order to include a depends-on clause in your ASDF system file, create a file called \texttt{depends-on.isc} in the toplevel directory of your system. In this file, place a list of the systems your system depends on. This can be systems from your own local projects, or from third-party libraries. For example, if your system depends on the \texttt{:cl-json} third-party library, you would have the following contents in your \texttt{depends-on.isc}: \begin{verbatim}(:cl-json) \end{verbatim} \subsection{Compiling and Loading a System} \label{subsec:compilingandloadingasystem} Once you have generated an ASDF file, you can compile and load the system using Quicklisp. To do this for our example, follow these steps: \begin{enumerate} \item \begin{verbatim}(cl-lite "apps/yoyodyne/" :create-asd-file? t) \end{verbatim} to generate the asdf file for the yoyodyne system. This only has to be done once after every time you add, remove, or rename a file or folder from the system. \item \begin{verbatim}(pushnew "apps/yoyodyne/" ql:*local-project-directories*) \end{verbatim} This can be done in your \texttt{gdlinit.cl} for projects you want available during every development session. Note that you should include the full path prefix for the directory containing the ASDF system file. \item \begin{verbatim}(ql:quickload :gdl-yoyodyne)  Dave Cooper committed Jun 16, 2013 1019 1020 1021 1022 1023 1024 1025 1026 1027 \end{verbatim} this will compile and load the actual system. Quicklisp uses ASDF at the low level to compile and load the systems, and Quicklisp will retrieve any depended-upon third-party libraries from the Internet on-demand. Source files will be compiled only if the corresponding binary (fasl) file does not exist or is older than the source file. By default, ASDF keeps its binary files in a \emph{cache} directory, separated according to CL platform and operating system. The location of this cache is system-dependent, but you can see where it is by observing the compile and load process.  Dave Cooper committed Nov 19, 2012 1028 1029 1030 1031 1032  \end{enumerate}  Dave Cooper committed Oct 23, 2012 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 \section{Customizing your Environment} \label{sec:customizingyourenvironment} You may customize your environment in several different ways, for example by loading definitions and settings into your Gendl world'' automatically when the system starts, and by specifying fonts, colors, and default buffers (to name a few) for your emacs editing environment. \section{Saving the World}  Dave Cooper committed Oct 16, 2012 1044   Dave Cooper committed Oct 23, 2012 1045 \label{sec:savingtheworld}  Dave Cooper committed Oct 16, 2012 1046   Dave Cooper committed Nov 19, 2012 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108  Saving the world refers to a technique of saving a complete binary image of your Gendl world'' which contains all the currently compiled and loaded definitions and settings. This allows you to start up a saved world almost instantly, without having to reload all the definitions. You can then incrementally compile and load just the particular definitions which you are working on for your development session. To save a world, follow these steps: \begin{enumerate} \item Load the base Gendl code and (optionally) code for Gendl modules (e.g. gdl-yadd, gdl-tasty) you want to be in your saved image. For example: \begin{verbatim} (ql:quickload :gdl-yadd) (ql:quickload :gdl-tasty) \end{verbatim} \item \begin{verbatim}(ff:unload-foreign-library (merge-pathnames "smlib.dll" "sys:smlib;")) \end{verbatim} \item \begin{verbatim}(net.aserve:shutdown) \end{verbatim} \item \begin{verbatim}(setq excl:*restart-init-function* '(gdl:start-gdl :edition :trial)) \end{verbatim} \item (to save an image named yoyodyne.dxl) Invoke the command \begin{verbatim}(dumplisp :name "yoyodyne.dxl") \end{verbatim}Note that the standard extension for Allegro CL images is \texttt{.dxl}. Prepend the file name with path information, to write the image to a specific location. \end{enumerate} \section{Starting up a Saved World} \label{sec:startingupasavedworld} In order to start up Gendl using a custom saved image, or world,'' follow these steps \begin{enumerate} \item Exit Gendl \item Copy the supplied \texttt{gdl.dxl} to \texttt{gdl-orig.dxl}.  Dave Cooper committed Dec 13, 2012 1109 \item Move the custom saved dxl image to \texttt{gdl.dxl} in the Gendl application \texttt{"program/"} directory.  Dave Cooper committed Nov 19, 2012 1110   Dave Cooper committed Nov 19, 2012 1111 1112 \item Start Gendl as usual. Note: you may have to edit the system gdlinit.cl or your home gdlinit.cl to stop it from loading redundant code which is already in the saved image.  Dave Cooper committed Nov 19, 2012 1113 1114 1115 1116  \end{enumerate}  Dave Cooper committed Oct 11, 2012 1117   Dave Cooper committed Nov 20, 2012 1118 1119 1120 1121 1122 1123 \chapter{Understanding Common Lisp} \label{chap:understandingcommonlisp}  Dave Cooper committed Jun 16, 2013 1124 1125 1126 GDL is a superset of Common Lisp, and is embedded in Common Lisp. This means that when working with GDL, you have the full power of CL available to you. The lowest-level expressions in a GDL  Dave Cooper committed Nov 20, 2012 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 definition are CL symbolic expressions,'' or s-expressions.'' This chapter will familiarize you with CL s-expressions. \section{S-expression Fundamentals} \label{sec:s-expressionfundamentals} S-expressions can be used in your definitions to establish  Dave Cooper committed Jun 16, 2013 1139 1140 1141 the value of a particular \emph{slot} (i.e. named data value) in an object, which will be computed on-demand. You can also evaluate S-expressions at the toplevel \texttt{gdl-user\textgreater} prompt, and see the result immediately. In fact, this toplevel prompt is called a \emph{read-eval-print} loop, because its purpose is to \emph{read} each s-expression entered, \emph{evaluate} the expression to yield a result (or \emph{return-value}), and finally to \emph{print} that result.  Dave Cooper committed Nov 20, 2012 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161  CL s-expressions use a \emph{prefix} notation, which means that they consist of either an \emph{atom} (e.g. number, text string, symbol) or a list (one or more items enclosed by parentheses, where the first item is taken as a symbol which names an operator). Here is an example: \begin{verbatim}(+ 2 2) \end{verbatim}This expression consists of the function named by the symbol \texttt{+}, followed by the numeric arguments \texttt{2} and another \texttt{2}. As you may have guessed, when this expression is evaluated it will return the value 4.\emph{Try it: }try typing this expression at your command prompt, and see the return-value being printed on the console. What is actually happening here? When CL is asked to evaluate an expression, it processes the expression according to the following rules: \begin{itemize} \item If the expression is an \emph{atom} (e.g. a non-list datatype such as a number, text  Dave Cooper committed Jun 16, 2013 1162 1163 string, or literal symbol), it simply returns itself as its evaluated value. Examples:  Dave Cooper committed Nov 20, 2012 1164 1165 1166  \begin{itemize}  Dave Cooper committed Dec 13, 2012 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 \item \begin{verbatim}gdl-user> 99 99 \end{verbatim} \item \begin{verbatim}gdl-user> 99.9 99.9 \end{verbatim} \item \begin{verbatim}gdl-user> 3/5 3/5 \end{verbatim} \item \begin{verbatim}gdl-user> "Bob" "Bob" \end{verbatim} \item \begin{verbatim}gdl-user> "Our golden rule is simplicity" "Our golden rule is simplicity" \end{verbatim} \item \begin{verbatim}gdl-user> 'my-symbol my-symbol \end{verbatim}  Dave Cooper committed Nov 20, 2012 1203 1204 1205 1206 1207 1208 1209 1210 1211 \end{itemize} Note that numbers are represented directly (with decimal points and slashes for fractions allowed), strings are surrounded by double-quotes, and literal symbols are introduced with a preceding single-quote. Symbols are allowed to have dashes (-'') and most other special characters. By convention, the dash is used as a word separator in CL symbols.  Dave Cooper committed Jun 16, 2013 1212 1213 \item If the expression is a \emph{list} (i.e. is surrounded by parentheses), CL processes the \emph{first} element in this list as an \emph{operator name}, and the \emph{rest} of the elements in the list represent the \emph{arguments} to the operator. An operator can take zero or more  Dave Cooper committed Nov 20, 2012 1214 1215 arguments, and can return zero or more return-values. Some operators evaluate their arguments immediately and work directly on those  Dave Cooper committed Jun 16, 2013 1216 values (these are called \emph{functions}). Other operators expand into other code. These are called \emph{special operators} or \emph{macros}. Macros are what give Lisp (and CL in particular) its  Dave Cooper committed Nov 20, 2012 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 special power. Here are some examples of functional s-expressions: \begin{itemize} \item \begin{verbatim}gdl-user> (expt 2 5) 32 \end{verbatim} \item \begin{verbatim}gdl-user> (+ 2 5) 7 \end{verbatim} \item \begin{verbatim}gdl-user> (+ 2) 2 \end{verbatim} \item \begin{verbatim}gdl-user> (+ (+ 2 2) (+ 3 3 )) 10 \end{verbatim} \end{itemize} \end{itemize} \section{Fundamental CL Data Types} \label{sec:fundamentalcldatatypes} As we have seen, Common Lisp natively supports many data types common to other languages, such as numbers and text strings. CL also contains several compound data types such as lists, arrays, and hash tables. CL contains \emph{symbols} as well, which typically are used as names for other data elements.  Dave Cooper committed Jun 16, 2013 1268 Regarding data types, CL follows a system called dynamic  Dave Cooper committed Nov 20, 2012 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 typing. Basically this means that values have type, but variables do not necessarily have type, and typically variables are not pre-declared'' to be of a particular type. \subsection{Numbers} \label{subsec:numbers} As we have seen, numbers in CL are a native data type which simply evaluate to themselves when entered at the toplevel or included in an expression. Numbers in CL form a hierarchy of types, which includes Integers, Ratios, Floating Point, and Complex numbers. For many purposes, you only need to think of a value as a number'' without getting any more specific than that. Most arithmetic operations, such as \texttt{+}, \texttt{-}, \texttt{*}, \texttt{/} etc, will automaticaly do any necessary type coercion on their arguments and will return a number of the appropriate type. CL supports a full range of floating-point decimal numbers, as well as true Ratios, which means that \texttt{1/3} is a true one-third, not \texttt{0.333333333} rounded off at some arbitrary precision. \subsection{Strings} \label{subsec:strings} Strings are actually a specialized kind of array, namely a one-dimensional array (vector) made up of text characters. These characters can be letters, numbers, or punctuation, and in some cases can include characters from international character sets (e.g. Unicode or UTF-8) such as Chinese Hanzi or Japanese Kanji. The string delimiter in CL is the double-quote character. As we have seen, strings in CL are a native data type which simply evaluate to themselves when included in an expression.  Dave Cooper committed Dec 13, 2012 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 A common way to produce a string in CL is with the \texttt{format} function. Although the \texttt{format} function can be used to send output to any kind of destination, or \emph{stream}, it will simply yield a string if you specify \texttt{nil} for the stream. Example: {\small \begin{verbatim} gdl-user> (format nil "The time is: ~a" (get-universal-time)) "The time is: 3564156603" gdl-user> (format nil "The time is: ~a" (iso-8601-date (get-universal-time))) "The time is: 2012-12-10" gdl-user> (format nil "The time is: ~a" (iso-8601-date (get-universal-time) :include-time? t)) "The time is: 2012-12-10T14:30:17" \end{verbatim}} As you can see from the above example, \texttt{format} takes a \emph{stream designator} or \texttt{nil} as its first argument, then a \emph{format-string}, then enough arguments to match the \emph{format directives} in the format-string. Format directives begin with the  Dave Cooper committed Jun 16, 2013 1333 tilde character (\~). The format-directive \texttt{~a} indicates that the printed representation of the corresonding argument should simpy be  Dave Cooper committed Dec 13, 2012 1334 1335 1336 1337 1338 1339 substituted into the format-string at the point where it occurs. We will cover more details on \texttt{format} in Section \ref{sec:input-output} on Input/Output, but for now, a familiarity with the simple use of \texttt{(format nil ...} will be helpful for Chapter  Dave Cooper committed Jun 16, 2013 1340 \ref{chapter:understandinggdlcoregdlsyntax}.  Dave Cooper committed Dec 13, 2012 1341 1342 1343   Dave Cooper committed Nov 20, 2012 1344 1345 1346 1347 1348 1349 \subsection{Symbols} \label{subsec:symbols}  Dave Cooper committed Jun 16, 2013 1350 Symbols are such an important data structure in CL that people  Dave Cooper committed Nov 20, 2012 1351 1352 sometimes refer to CL as a Symbolic Computing Language.'' Symbols are a type of CL object which provides your program with a built-in  Dave Cooper committed Jun 16, 2013 1353 capacity to store and retrieve values and functions, as well as being  Dave Cooper committed Nov 20, 2012 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 useful in their own right. A symbol is most often known by its name (actually a string), but in fact there is much more to a symbol than its name. In addition to the name, symbols also contain a \emph{function} slot, a \emph{value} slot, and an open-ended \emph{property-list} slot in which you can store an arbitrary number of named properties. For a named function such as \texttt{+} the function-slot contains the actual function object for performing numeric addition. The value-slot of a symbol can contain any value, allowing the symbol to act as a global variable, or \emph{parameter}. And the property-list, also known as the \emph{plist} slot, can contain an arbitrary amount of information. This separation of the symbol data structure into function, value, and  Dave Cooper committed Jun 16, 2013 1367 plist slots is one fundamental distinction between Common Lisp and most  Dave Cooper committed Nov 20, 2012 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 other Lisp dialects. Most other dialects allow only one (1) thing'' to be stored in the symbol data structure, other than its name (e.g. either a function or a value, but not both at the same time). Because Common Lisp does not impose this restriction, it is not necessary to contrive names, for example for your variables, to avoid conflicting with existing reserved words'' in the system. For example, \texttt{list} is the name of a built-in function in CL. But you may freely use \texttt{list} as a variable name as well. There is no need to contrive arbitrary abbreviations such as \texttt{lst}. How symbols are evaluated depends on where they occur in an  Dave Cooper committed Jun 16, 2013 1381 1382 expression. As we have seen, if a \emph{symbol} appears first in a list expression, as with the \texttt{+} in \texttt{(+ 2 2)}, the symbol is evaluated for its function slot. If the first element of an expression indeed has a \emph{function} in its function slot, then any  Dave Cooper committed Nov 20, 2012 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 subsequent symbol in the expression is taken as a variable, and it is evaluated for its global or local value, depending on its scope (more on variables and scope later). As noted in Section 3.1.3, if you want a literal symbol itself, one way to achieve this is to quote'' the symbol name: \begin{verbatim}'a \end{verbatim} Another way is for the symbol to appear within a quoted list expression, for example: \begin{verbatim}'(a b c) \end{verbatim} or \begin{verbatim}'(a (b c) d) \end{verbatim} Note that the quote (\texttt{'}) applies across everything in the list expression, including any sub- expressions.  Dave Cooper committed Dec 13, 2012 1411 \subsection{List Basics}  Dave Cooper committed Nov 20, 2012 1412   Dave Cooper committed Dec 13, 2012 1413 \label{subsec:listbasics}  Dave Cooper committed Nov 20, 2012 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431  Lisp takes its name from its strong support for the list data structure. The list concept is important to CL for more than this reason alone --- most notably, lists are important because \emph{all CL programs are themselves lists.} Having the list as a native data structure, as well as the form of all programs, means that it is straightforward for CL programs to compute and generate other CL programs. Likewise, CL programs can read and manipulate other CL programs in a natural manner. This cannot be said of most other languages, and is one of the primary distinguishing characteristics of Lisp as a language.  Dave Cooper committed Jun 16, 2013 1432 1433 Textually, a list is defined as zero or more items surrounded by parentheses. The items can be objects of any valid CL data types,  Dave Cooper committed Nov 20, 2012 1434 1435 1436 1437 1438 1439 1440 such as numbers, strings, symbols, lists, or other kinds of objects. As we have seen, you must quote a literal list to evaluate it or CL will assume you are calling a function. Now look at the following list: \begin{verbatim}(defun hello () (write-string "Hello, World!")) \end{verbatim}This list also happens to be a valid CL program (function definition,  Dave Cooper committed Jun 16, 2013 1441 in this case). Don't concern yourself about analyzing the function definition  Dave Cooper committed Nov 20, 2012 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 right now, but do take a few moments to convince yourself that it meets the requirements for a list. What are the types of the elements in this list? In addition to using the quote (') to produce a literal list, another way to produce a list is to call the function \texttt{list}. The function \texttt{list} takes any number of arguments, and returns a list made up from the result of evaluating each argument. As with all functions, the arguments to the \texttt{list} function get evaluated, from left to right, before being processed by the function. For example: \begin{verbatim}(list ’a ’b (+ 2 2)) \end{verbatim}will return the list \begin{verbatim}(a b 4)  Dave Cooper committed Dec 13, 2012 1461 \end{verbatim}The two quoted symbols evaluate to symbols, and the function  Dave Cooper committed Nov 20, 2012 1462 1463 1464 1465 call \texttt{(+ 2 2)} evaluates to the number 4.  Dave Cooper committed Dec 13, 2012 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 \subsection{The List as a Data Structure} \label{subsec:thelistasadatastructure} In this section we will present a few of the fundamental native CL operators for manipulating lists as data structures. These include operators for doing things such as: \begin{enumerate} \item finding the length of a list \item accessing particular members of a list \item appending multiple lists together to make a new list \end{enumerate} \subsubsection{Finding the Length of a List} \label{subsubsec:findingthelengthofalist} The function \texttt{length} will return the length of any type of sequence, including a list: \begin{verbatim}gdl-user> (length '(a b c d e f g h i j) 10 gdl-user> (length nil) 0 \end{verbatim}Note that \texttt{nil} qualifies as a list (albeit the empty list), so taking its length yields the integer \texttt{0}. \subsubsection{Accessing the Elements of a List} \label{subsubsec:accessingtheelementsofalist} Common Lisp defines the accessor functions \texttt{first} through \texttt{tenth} as a means of accessing the first ten elements in a list: \begin{verbatim} gdl-user> (first '(a b c)) a gdl-user> (second '(a b c)) b gdl-user> (third '(a b c)) c \end{verbatim}For accessing elements in an arbitrary position in the list, you can use the function nth, which takes an integer and a list as its two arguments: \begin{verbatim} gdl-user> (nth 0 '(a b c)) a gdl-user> (nth 1 '(a b c)) b gdl-user> (nth 2 '(a b c)) c \end{verbatim}Note that nth starts its indexing at zero (0), so \texttt{(nth 0 ...)} is equivalent to \texttt{(first ...)}and \texttt{(nth 1 ...)} is equivalent to \texttt{(second ...)}, etc. \subsubsection{Using a List to Store and Retrieve Named Values} \label{subsubsec:usingalisttostoreandretrievenamedvalues} Lists can also be used to store and retrieve named values. When a list is used in this way, it is called a \emph{plist}. Plists contain pairs of elements, where each pair consists of a \emph{key} and some \emph{value}. The key is typically an actual keyword symbol --- that is, a symbol preceded by a colon (:). The value can be any value, such as  Dave Cooper committed Jun 16, 2013 1540 a number, a string, or even a GDL object representing something  Dave Cooper committed Dec 13, 2012 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 complex such as an aircraft. A plist can be constructed in the same manner as any list, e.g. with the \texttt{list} operator: \begin{verbatim}(list :a 10 :b 20 :c 30) \end{verbatim}In order to access any element in this list, you can use the \texttt{getf} operator. The \texttt{getf} operator is specially intended for use with plists: \begin{verbatim}gdl-user> (getf (list :a 10 :b 20 :c 30) :b 20 gdl-user> (getf (list :a 10 :b 20 :c 30) :c 30 \end{verbatim} Common Lisp contains several other data structures for mapping keywords or numbers to values, such as \emph{arrays} and \emph{hash tables}. But for relatively short lists, and especially for rapid prototyping and testing work, plists can be useful. Plists can also be written and read (i.e. saved and restored) to and from plain text files in your filesystem, in a very natural way. \subsubsection{Appending Lists} \label{subsubsec:appendinglists} The function \texttt{append} takes any number of lists, and returns a new list which results from appending them together. Like many CL functions, append does not \emph{side-effect}, that is, it simply returns a new list as a return-value, but does not modify its arguments in any way: \begin{verbatim}  Dave Cooper committed Jun 16, 2013 1566  gdl-user> (defparameter my-slides '(introduction welcome lists functions))  Dave Cooper committed Dec 13, 2012 1567 1568  (introduction welcome lists functions)  Dave Cooper committed Jun 16, 2013 1569  gdl-user> (append my-slides '(numbers))  Dave Cooper committed Dec 13, 2012 1570 1571 1572 1573 1574 1575  (introduction welcome lists functions numbers) gdl-user> my-slides (introduction welcome lists functions) \end{verbatim}Note that the simple call to \texttt{append} does not affect the variable \texttt{my-slides}. Later we will see how one may alter the value of a variable such as \texttt{my-slides}.  Dave Cooper committed Jun 16, 2013 1576 \chapter{Understanding GDL --- Core GDL Syntax}  Dave Cooper committed Nov 21, 2012 1577   Dave Cooper committed Jun 16, 2013 1578 \label{chap:understandinggdl---coregdlsyntax}  Dave Cooper committed Nov 21, 2012 1579 1580 1581   Dave Cooper committed Jun 16, 2013 1582 1583 1584 1585 Now that you have a basic grasp of Common Lisp syntax (or, more accurately, \emph{absence} of syntax), we will move directly into the GDL framework. By using GDL you can formulate most of your engineering and computing problems in a natural way, without becoming entangled in the complexity of the Common Lisp Object System (CLOS).  Dave Cooper committed Nov 21, 2012 1586 1587 1588   Dave Cooper committed Jun 16, 2013 1589 1590 1591 1592 1593 1594 The GDL product is a commercially available KBE system with Proprietary licensing. The Gendl Project is an open-source Common Lisp library which contains the core language kernel of GDL, and is licensed under the terms of the Affero Gnu Public License. The core GDL language is a proposed standard for a vendor-neutral KBE language.  Dave Cooper committed Nov 21, 2012 1595 1596 1597   Dave Cooper committed Jun 16, 2013 1598 1599 1600 1601 1602 As discussed in the previous chapter, GDL is based on and is a superset of ANSI Common Lisp. Because ANSI CL is unencumbered and an open standard, with several commercial and free implementations, it is a good wager that applications written in it will continue to be usable 50, 100, or even hundreds of years from now.  Dave Cooper committed Nov 21, 2012 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612  \section{Defining a Working Package} \label{sec:definingaworkingpackage} In Common Lisp, \emph{packages} are a mechanism to separate symbols into  Dave Cooper committed Jun 16, 2013 1613 1614 1615 namespaces. Using packages it is possible to avoid naming conflicts in large projects. Consider this analogy: in the United States, telephone numbers consist of a three-digit area code and a seven-digit  Dave Cooper committed Nov 21, 2012 1616 1617 1618 1619 1620 number. The same seven-digit number can occur in two or more separate area codes, without causing a conflict.  Dave Cooper committed Jun 16, 2013 1621 The macro \texttt{gdl:define-package}is used to set up a new working package in GDL.  Dave Cooper committed Nov 21, 2012 1622 1623 1624 1625 1626 1627  Example: \begin{verbatim}(gdl:define-package :yoyodyne)  Dave Cooper committed Jun 16, 2013 1628 \end{verbatim} will establish a new package called \texttt{:yoyodyne} which has all the GDL operators available.  Dave Cooper committed Nov 21, 2012 1629 1630 1631 1632 1633 1634 1635 1636 1637  The \texttt{:gdl-user} package is an empty, pre-defined package for your use if you do not wish to make a new package just for scratch work. For real projects it is recommended that you make and work in your own  Dave Cooper committed Jun 16, 2013 1638 GDL package, defined as above with \texttt{gdl:define-package}.  Dave Cooper committed Nov 21, 2012 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722