UW STAT 220 - A simple Database for typesetting documentation

Unformatted text preview:

DEFINITIONS: A SIMPLE DATABASEFORTYPESETTING DOCUMENTATIONbyJohnAlan McDonaldTECHNICAL REPORTNo.220October 1991DepartmentofStatistics, GN·22UniversityofWashingtonSeattle,Washington 98195USADefinitions: a simple database for typesetting documentationJOHNALANMcDoNALD'"Dept.ofStatistics, WashingtonOctober1991AbstractThis report describes the Definition module, which providesthebeginnings of a database forCommon Lisp source code objects.Themajor useofthis databaseatpresent is in automaticallytypsettingreference manuals,anexampleofwhich is section 4.*Thiswork wassupportedinparttheDept.ofEnergyundercontrad;FG0085-ER25006andbyNIHgrantLM04174fromtheNationalLibraryofMedicine.2LISTOFFIGURESContents33445V"'''UUl;con,vel1ltio]£lS.. . . . . . .(Jrleatlllg Rel:erellce Manuals . . . .1Je(~lartngretl1rn~ldvalues1.2.2Typecheckiug forms .1Introduction1.11.22DefinitionProtocol2.1 Classes .2.2Reading.2.3Building.2.4 Parsing .2.5Filtering.2.6 Sorting..2.7Printing.I)56678883 'Extendingthebasicsystem3.1 ,t\g.ditionstotheprotocol .3.1.1 Expected Additions3.1.2 Censoring .3.1.3Groupingrelated definitions .3.2 New definitions .3.2.1 Conventions .899999104ReferenceManual11ListofFiguresHierarchyofbuiltin definition dasses.631Introductionm~Lpilredinpartbe~:imlill~~sof a database for Com-Definitionsm()dULle,source code objects.refe.ren'cemanuals (using Latex [5]),Detinit;ionGroupsofBobrow et. al[IJTheDefinitions moduleis a componentofa system called Arizona, now under developmentattheU.ofWashington. Arizona is intendedtobe a portable, public-domaincollectionoftools supportingscientific computing, quantitative graphics, anddataanalysis, implemented in Common Lisp andCLOS (the Common LispObject System)[9J.This document assumes the reader is familiar withCommon Lisp and CLOS. An overviewofArizona is given in[6Jand an introductiontothe currentrelease is in[8J.Po.SSllt>1eCOlIV€~ni<mtrUlltilrneaccesstoinformationthe reading, evaluating,Theprimary purposeofDefinitionsistoavail(l.bl<')inC()mmon Lisp source code,and/orcompiling.EvaluatillgsomeLililpdefinitionlil,suchasdefclass,resultsinafirliltclassLililpobject with areasonable and reasonably portableprotocol for extracting useful information, such as the directsub-and super-classes. (At least, this should be true once the MOPisstable[2J.)However,most Lisp definitions, suchas defun, while producing identifiable objects, have limited facilities forextracting useful information; usually the documentation stringisallthatisavailable. And otherdefinitions,such as defstruct, do not even produce an identifiable object.The Definitions module provides functionstoread sourcefilesand create a Definition object foreach lisp definition in those files, retaining the complete original defining lisp form. Notethatthe"defining lisp form"isnot quite the same thing as the original source code. The "defining lisp form"isavalilereturnedbyread,whichmeans,fore:x'alllple,thatall comlllentsarerellloved.Thereasollfor simplyusing;readisthatitis much easierthanp(l.rsingthesourcelllyself,decidingwheretoputtop level comments, etc. Inthefuture, I may replace the read functions by onesthatcaptured allthe free text source, comments, white space, and all, aswellas applyingreadtothis source text toa readily analyzable lisp object.1.1CreatingReference'.Manualsintert'ace!tocrE~atjlngarl~tel'.en,ce1IIancualfr,::>mDefinitions.consistsofthe func-can with exported-pl'lnte.ctin a withthecurl:ent envirorlmentTheuser interface is documented morelormaLllyin section4,which was prl)dllCed by41"definition.lisp""pack.lisp""global.lisp""fun.lisp""type.lisp""build.lisp""read.lisp""filter.lisp""sort.lisp""print.lisp"»(defp<gameter*defs*(df:read-definitions-from-files*def-files*»(df:print-definitions(sort(remove-if-not#'df:exported"'definition?*defs*)#'df:definition-alpna<)"doc/reference-manual.tex")1.2CodingconventionsUsingtheabove functionsontypical lisp code will produce referencemanualentriesthatarenotveryinformative.Themanualentries will be more worthyofthepaper they consumeiftheprogrammerfollows certain coding conventions.Allimportantdefinitions should have a substa.'ltialdocumentationstring, which should emphasizedescribingtheconceptualandshouldnotcontain informationthatcan beextracted fromtheform (such as thelambdalistofa function).(n()n-Spt~CI2lJlzed)arguments should specifiedina declaration. Generally speak-1.2.1DeclaringreturnedvalueslU<:ltl(:l1l1ga :returnsde.claraliio][ljISA :retlJrnSdeclarl!ttic~ncan be usedtothenamesoftheval'larlle{s) whoseva:lue{slthatareortheactual returned value!lsl. whenitis constant.oftheuse :returns declarations are:5( :returnsnil)(:returnsresult)(:returns(typeList)}(:ret~s(typeListresult)}(:re'turns(valuesxyz)}(:returns(values(typeBoolean)(typeBoolean}»(:returns(values(typeFixnumleft)(typeFixnumtop)(typePositive-Fixnumleft)(typePositive-Fixnum width)}}In ordertoescape compiler warnings,theprogrammer should place(declaim(declara.tion:returns»somewherethatwill cause·ittobeevaluatedany codethatcontains a :returns declaration.1.2.2TypecheckingformsSometimes one would prefertohave type checking formsatthetopofa function,ratherthandeclarations.TheArizona-Tools package[8]provides a macro called az:declare-check whichhasthesamesyntaxas declarebutexpands into check-type expressions. (Unfortunatelyitisnoteasytoalso haveitexpandintotheequivalent declarations as well.)TheDefinitionstreatsanyform whosefirstitemis a symbol whoseprintnameis string-equalto"DECLARE-CHECK"thesameasittreatsdeclare forms. Usingthesymbol'sprintname makesitpossible for programmers who donothaveaccesstotheArizona-Tools packagetodefine their own declare-check macrosandhavethemtreatedappropriately.2DefinitionProtocolIn this section we discussthebuiltin Definition classesandtheir protocoLThepurpose istoallowrelatively sophisticated Lisp programmerstocustomizeandextendTheDefinitionObjects.module.ThemajorwaytoextendtheDefinitionObjectsmoduleistodefinenewsubcl~esofdf:Definitionor oneofthesubclasses listedinsedion2.1thatcorrespondtonew definition macros (eg. defan-2.1TheDefinitions modulepr(WH1esclassesCOl'fe£.pondJlnj(tothefollo\lvingCommondefinitionmacros1:defconstant, defpackage, defparameter,62 DEFINITION PROTOCOLFigure1:Hierarchy of built in definition classes.defsetf, defstruct, deftype, and defun.Atpresent, itismissing classes for the following definitionmacros: define-compiler-macro, define-condition, define-declaration, define-method-combination,define-modify-macro, and


View Full Document

UW STAT 220 - A simple Database for typesetting documentation

Download A simple Database for typesetting documentation
Our administrator received your request to download this document. We will send you the file to your email shortly.
Loading Unlocking...
Login

Join to view A simple Database for typesetting documentation and access 3M+ class-specific study document.

or
We will never post anything without your permission.
Don't have an account?
Sign Up

Join to view A simple Database for typesetting documentation 2 2 and access 3M+ class-specific study document.

or

By creating an account you agree to our Privacy Policy and Terms Of Use

Already a member?