tutorial.tex 139 KB
Newer Older
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's avatar
Dave Cooper committed
25 26
\usepackage {textcomp}

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}



64 65 66 67
\section{Welcome}

\label{sec:welcome}

Dave Cooper's avatar
Dave Cooper committed
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.
83

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's avatar
Dave Cooper committed
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?'' 
94 95

To provide a clearer picture, we hope you will agree that our concept
Dave Cooper's avatar
Dave Cooper committed
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.
100

Dave Cooper's avatar
Dave Cooper committed
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 
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's avatar
Dave Cooper committed
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.


235

Dave Cooper's avatar
Dave Cooper committed
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.
247

Dave Cooper's avatar
Dave Cooper committed
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:
255 256 257

\begin{itemize}

Dave Cooper's avatar
Dave Cooper committed
258
\item Get you motivated about using Genworks GDL
259

Dave Cooper's avatar
Dave Cooper committed
260
\item Enable you to ascertain whether Genworks GDL is an appropriate tool for a given job
261

Dave Cooper's avatar
Dave Cooper committed
262
\item Equip you with the ability to state the case for using GDL/GWL when appropriate
263

Dave Cooper's avatar
Dave Cooper committed
264 265
\item Prepare you to begin authoring and maintaining GDL
applications, or porting apps from similar KB systems into GDL.
266 267 268

\end{itemize}

Dave Cooper's avatar
Dave Cooper committed
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 
275
\underline{\index{Basic Lisp Techniques}Basic Lisp Techniques}\footnote{
Dave Cooper's avatar
Dave Cooper committed
276
\underline{BLT} is available at \texttt{http://www.franz.com/resources/educational\_resources/cooper.book.pdf}}, which was prepared by the author. 
277

Dave Cooper's avatar
Dave Cooper committed
278
\section{What is GDL?}
279

Dave Cooper's avatar
Dave Cooper committed
280
\label{sec:whatisgdl?}
281

Dave Cooper's avatar
Dave Cooper committed
282
GDL is an acronym for
283 284
``General-purpose Declarative Language.'' 

Dave Cooper's avatar
Dave Cooper committed
285
GDL is a superset of ANSI Common Lisp, and consists largely of
286
automatic code-expanding extensions to Common Lisp implemented in the
Dave Cooper's avatar
Dave Cooper committed
287
form of macros. When you write, for example, 20 lines in GDL, you
288
might be writing the equivalent of 200 lines of Common Lisp. Of
Dave Cooper's avatar
Dave Cooper committed
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.
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's avatar
Dave Cooper committed
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.
300

Dave Cooper's avatar
Dave Cooper committed
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
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's avatar
Dave Cooper committed
318 319
\item The ability to ``use'' an object without concern for
	its ``under-the-hood'' complexities
320 321 322

\end{itemize}

Dave Cooper's avatar
Dave Cooper committed
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 
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's avatar
Dave Cooper committed
371 372 373
\item An Artificial Intelligence system (although it is an
excellent environment for developing capabilities which could be
considered as such);
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}

385
Follow Section 
Dave Cooper's avatar
Dave Cooper committed
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 
390
\ref{sec:installationofopen-sourcegendl}.
391

Dave Cooper's avatar
Dave Cooper committed
392
\section{Installation of pre-packaged GDL}
393

Dave Cooper's avatar
Dave Cooper committed
394
\label{sec:installationofpre-packagedgdl}
395

Dave Cooper's avatar
Dave Cooper committed
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).
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's avatar
Dave Cooper committed
409
\item Visit the Downloads section of the \href{http://genworks.com}{Genworks Website}
410 411 412

\item Enter your email address\footnote{if your address is not on file, send mail to licensing@genworks.com}.

Dave Cooper's avatar
Dave Cooper committed
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.}
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's avatar
Dave Cooper committed
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.}
431 432

\item Copy the license key file as gdl.lic (for Trial,
Dave Cooper's avatar
Dave Cooper committed
433 434
	 Student, Professional editions), or devel.lic (for Enterprise edition) into the \texttt{program/} directory within the 
\textt{gdl/gdl/program/} directory.
435

Dave Cooper's avatar
Dave Cooper committed
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).
}
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's avatar
Dave Cooper committed
445
you have received a pre-packaged Gendl distribution, then you may skip
446
this section. In case you want to use the open-source Gendl, you will
Dave Cooper's avatar
Dave Cooper committed
447
use your own Common Lisp installation and obtain Gendl (Genworks-GDL)
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's avatar
Dave Cooper committed
463 464
\item Clozure CL (free CL engine from Clozure Associates, free for all use)

465 466 467 468
\item Steel Bank Common Lisp (SBCL) (free open-source project with permissive license)

\end{itemize}

Dave Cooper's avatar
Dave Cooper committed
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.
475

Dave Cooper's avatar
Dave Cooper committed
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}.
477 478 479 480 481

\subsection{Load and Configure Quicklisp}

\label{subsec:loadandconfigurequicklisp}

Dave Cooper's avatar
Dave Cooper committed
482 483
Quicklisp is the defacto standard library manager for Common
Lisp.
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's avatar
Dave Cooper committed
495
\subsection{Load and Start Gendl}
496

Dave Cooper's avatar
Dave Cooper committed
497
\label{subsec:loadandstartgendl}
498

Dave Cooper's avatar
Dave Cooper committed
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!)}}}
503

Dave Cooper's avatar
Dave Cooper committed
504
\section{System Testing}
505

Dave Cooper's avatar
Dave Cooper committed
506
\label{sec:systemtesting}
507 508 509



Dave Cooper's avatar
Dave Cooper committed
510
\subsection{Basic Sanity Test}
511

Dave Cooper's avatar
Dave Cooper committed
512
\label{subsec:basicsanitytest}
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:
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.

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}
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).

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}.
567

Dave Cooper's avatar
Dave Cooper committed
568 569
\item Select ``PNG'' from the View menu. You will see the
	 wireframe view of the robot as a PNG image.
570

Dave Cooper's avatar
Dave Cooper committed
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.
574 575 576 577 578

\end{enumerate}



579 580 581 582
\subsection{Full Regression Test}

\label{subsec:fullregressiontest}

Dave Cooper's avatar
Dave Cooper committed
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.
589

Dave Cooper's avatar
Dave Cooper committed
590
In Emacs at the \texttt{gdl-user>} prompt in the \texttt{*slime-repl...*} buffer, type the following commands:
591 592 593

\begin{enumerate}

Dave Cooper's avatar
Dave Cooper committed
594
\item \texttt{(ql:quickload :regression)}
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*)}

602 603 604 605
\end{enumerate}



606
\section{Getting Help and Support}
607

608
\label{sec:gettinghelpandsupport}
609

Dave Cooper's avatar
Dave Cooper committed
610 611
If you encounter unexplained errors in the installation and
startup process, please contact the following resources:
612

613
\begin{enumerate}
614

615
\item Make a posting to the \href{http://groups.google.com/group/genworks}{Genworks Google Group}
616

Dave Cooper's avatar
Dave Cooper committed
617 618
\item Join the \#gendl IRC (Internet Relay Chat) channel on
	irc.freenode.net and discuss issues there.
619

Dave Cooper's avatar
Dave Cooper committed
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.
626

627
\item If you are a supported Genworks customer, send email to \href{mailto:support@genworks.com}{support@genworks.com}
628

Dave Cooper's avatar
Dave Cooper committed
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 
633

634
\end{enumerate}
635 636 637



Dave Cooper's avatar
Dave Cooper committed
638
\chapter{Basic Operation of the GDL Environment}
639

Dave Cooper's avatar
Dave Cooper committed
640
\label{chap:basicoperationofthegdlenvironment}
641

Dave Cooper's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
648

Dave Cooper's avatar
Dave Cooper committed
649
\section{What is Different about GDL?}
Dave Cooper's avatar
Dave Cooper committed
650

Dave Cooper's avatar
Dave Cooper committed
651
\label{sec:whatisdifferentaboutgdl?}
Dave Cooper's avatar
Dave Cooper committed
652

Dave Cooper's avatar
Dave Cooper committed
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.
659

Dave Cooper's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
663
 
Dave Cooper's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
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.''
675

Dave Cooper's avatar
Dave Cooper committed
676
\section{Startup, ``Hello, World!'' and Shutdown}
677

Dave Cooper's avatar
Dave Cooper committed
678
\label{sec:startup,hello,world!andshutdown}
679 680


Dave Cooper's avatar
Dave Cooper committed
681

Dave Cooper's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
684
such as Firefox, Google Chrome, Safari, Opera, or Internet
Dave Cooper's avatar
Dave Cooper committed
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.
686 687 688 689



As introduced in Chapter 
Dave Cooper's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
695
\ref{subsec:makeadesktopshortcut}. Your installation executable may also have created a
Dave Cooper's avatar
Dave Cooper committed
696
Windows ``Start'' menu item for Genworks GDL. Of course you can also 
Dave Cooper's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
706
 Startup of a typical GDL development session consists of
Dave Cooper's avatar
Dave Cooper committed
707
two fundamental steps: (1) starting the Emacs editing environment,
Dave Cooper's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
711 712 713

\begin{enumerate}

Dave Cooper's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
721
\item (MS Windows): Look for the Genworks GDL Console
Dave Cooper's avatar
Dave Cooper committed
722
window, or (Linux, Mac) use the Emacs ``Buffer'' menu to visit the
Dave Cooper's avatar
Dave Cooper committed
723
``*inferior-lisp*'' buffer. Note that the Genworks GDL Console
Dave Cooper's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
729
few seconds to several minutes for the Genworks GDL Console (or
Dave Cooper's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
737 738
\ref{chapter:tasty}

Dave Cooper's avatar
Dave Cooper committed
739
\item To ensure that the GDL command prompt is up and running, type: \texttt{(+ 2 3)} and press [Enter].
Dave Cooper's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
747
\subsection{Developing and Testing a  ``Hello World'' application}
Dave Cooper's avatar
Dave Cooper committed
748

Dave Cooper's avatar
Dave Cooper committed
749
\label{subsec:developingandtestingahelloworldapplication}
Dave Cooper's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
774
\item You are now editing a (presumably new) file of GDL
Dave Cooper's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
840
 To shut down a development session gracefully, you should first shut down the GDL process,
Dave Cooper's avatar
Dave Cooper committed
841 842 843 844
then shut down your Emacs.

\begin{itemize}

Dave Cooper's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
846

Dave Cooper's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
934 935
\begin{verbatim}("package" "parameters")
\end{verbatim}
Dave Cooper's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
945
\ref{fig:yoyodyne-with-file-ordering-isc}.
Dave Cooper's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
969

Dave Cooper's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
1028 1029 1030 1031 1032

\end{enumerate}



Dave Cooper's avatar
Dave Cooper committed
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}
1044

Dave Cooper's avatar
Dave Cooper committed
1045
\label{sec:savingtheworld}
1046

Dave Cooper's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
1109
\item Move the custom saved dxl image to \texttt{gdl.dxl} in the Gendl application \texttt{"program/"} directory.
Dave Cooper's avatar
Dave Cooper committed
1110

Dave Cooper's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
1113 1114 1115 1116

\end{enumerate}


1117

1118 1119 1120 1121 1122 1123
\chapter{Understanding Common Lisp}

\label{chap:understandingcommonlisp}



Dave Cooper's avatar
Dave Cooper committed
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
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's avatar
Dave Cooper committed
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.
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's avatar
Dave Cooper committed
1162 1163
string, or literal symbol), it simply returns itself as its evaluated
value. Examples: 
1164 1165 1166

\begin{itemize}

Dave Cooper's avatar
Dave Cooper committed
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}

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's avatar
Dave Cooper committed
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
1214 1215
arguments, and can return zero or more return-values. Some operators
evaluate their arguments immediately and work directly on those
Dave Cooper's avatar
Dave Cooper committed
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
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's avatar
Dave Cooper committed
1268
Regarding data types, CL follows a system called dynamic
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's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
1333
tilde character (\~).  The format-directive \texttt{~a} indicates that the printed representation of the corresonding argument should simpy be 
Dave Cooper's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
1340
\ref{chapter:understandinggdlcoregdlsyntax}.
Dave Cooper's avatar
Dave Cooper committed
1341 1342 1343



1344 1345 1346 1347 1348 1349
\subsection{Symbols}

\label{subsec:symbols}



Dave Cooper's avatar
Dave Cooper committed
1350
Symbols are such an important data structure in CL that people
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's avatar
Dave Cooper committed
1353
capacity to store and retrieve values and functions, as well as being
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's avatar
Dave Cooper committed
1367
plist slots is one fundamental distinction between Common Lisp and most
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's avatar
Dave Cooper committed
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 
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's avatar
Dave Cooper committed
1411
\subsection{List Basics}
1412

Dave Cooper's avatar
Dave Cooper committed
1413
\label{subsec:listbasics}
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's avatar
Dave Cooper committed
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,
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's avatar
Dave Cooper committed
1441
in this case). Don't concern yourself about analyzing the function definition
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's avatar
Dave Cooper committed
1461
\end{verbatim}The two quoted symbols evaluate to symbols, and the function
1462 1463 1464 1465
call \texttt{(+ 2 2)} evaluates to the number 4.



Dave Cooper's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
1540
a number, a string, or even a GDL object representing something
Dave Cooper's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
1566
 gdl-user> (defparameter my-slides '(introduction welcome lists functions))
Dave Cooper's avatar
Dave Cooper committed
1567 1568
 (introduction welcome lists functions)

Dave Cooper's avatar
Dave Cooper committed
1569
 gdl-user> (append my-slides '(numbers))
Dave Cooper's avatar
Dave Cooper committed
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's avatar
Dave Cooper committed
1576
\chapter{Understanding GDL --- Core GDL Syntax}
1577

Dave Cooper's avatar
Dave Cooper committed
1578
\label{chap:understandinggdl---coregdlsyntax}
1579 1580 1581



Dave Cooper's avatar
Dave Cooper committed
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).
1586 1587 1588



Dave Cooper's avatar
Dave Cooper committed
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.
1595 1596 1597



Dave Cooper's avatar
Dave Cooper committed
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.
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's avatar
Dave Cooper committed
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
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's avatar
Dave Cooper committed
1621
The macro \texttt{gdl:define-package}is used to set up a new working package in GDL.
1622 1623 1624 1625 1626 1627



Example:

\begin{verbatim}(gdl:define-package :yoyodyne)
Dave Cooper's avatar
Dave Cooper committed
1628
\end{verbatim} will establish a new package called \texttt{:yoyodyne} which has all the GDL operators available.
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's avatar
Dave Cooper committed
1638
GDL package, defined as above with \texttt{gdl:define-package}.
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