avram.texinfo 520 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117311831193120312131223123312431253126312731283129313031313132313331343135313631373138313931403141314231433144314531463147314831493150315131523153315431553156315731583159316031613162316331643165316631673168316931703171317231733174317531763177317831793180318131823183318431853186318731883189319031913192319331943195319631973198319932003201320232033204320532063207320832093210321132123213321432153216321732183219322032213222322332243225322632273228322932303231323232333234323532363237323832393240324132423243324432453246324732483249325032513252325332543255325632573258325932603261326232633264326532663267326832693270327132723273327432753276327732783279328032813282328332843285328632873288328932903291329232933294329532963297329832993300330133023303330433053306330733083309331033113312331333143315331633173318331933203321332233233324332533263327332833293330333133323333333433353336333733383339334033413342334333443345334633473348334933503351335233533354335533563357335833593360336133623363336433653366336733683369337033713372337333743375337633773378337933803381338233833384338533863387338833893390339133923393339433953396339733983399340034013402340334043405340634073408340934103411341234133414341534163417341834193420342134223423342434253426342734283429343034313432343334343435343634373438343934403441344234433444344534463447344834493450345134523453345434553456345734583459346034613462346334643465346634673468346934703471347234733474347534763477347834793480348134823483348434853486348734883489349034913492349334943495349634973498349935003501350235033504350535063507350835093510351135123513351435153516351735183519352035213522352335243525352635273528352935303531353235333534353535363537353835393540354135423543354435453546354735483549355035513552355335543555355635573558355935603561356235633564356535663567356835693570357135723573357435753576357735783579358035813582358335843585358635873588358935903591359235933594359535963597359835993600360136023603360436053606360736083609361036113612361336143615361636173618361936203621362236233624362536263627362836293630363136323633363436353636363736383639364036413642364336443645364636473648364936503651365236533654365536563657365836593660366136623663366436653666366736683669367036713672367336743675367636773678367936803681368236833684368536863687368836893690369136923693369436953696369736983699370037013702370337043705370637073708370937103711371237133714371537163717371837193720372137223723372437253726372737283729373037313732373337343735373637373738373937403741374237433744374537463747374837493750375137523753375437553756375737583759376037613762376337643765376637673768376937703771377237733774377537763777377837793780378137823783378437853786378737883789379037913792379337943795379637973798379938003801380238033804380538063807380838093810381138123813381438153816381738183819382038213822382338243825382638273828382938303831383238333834383538363837383838393840384138423843384438453846384738483849385038513852385338543855385638573858385938603861386238633864386538663867386838693870387138723873387438753876387738783879388038813882388338843885388638873888388938903891389238933894389538963897389838993900390139023903390439053906390739083909391039113912391339143915391639173918391939203921392239233924392539263927392839293930393139323933393439353936393739383939394039413942394339443945394639473948394939503951395239533954395539563957395839593960396139623963396439653966396739683969397039713972397339743975397639773978397939803981398239833984398539863987398839893990399139923993399439953996399739983999400040014002400340044005400640074008400940104011401240134014401540164017401840194020402140224023402440254026402740284029403040314032403340344035403640374038403940404041404240434044404540464047404840494050405140524053405440554056405740584059406040614062406340644065406640674068406940704071407240734074407540764077407840794080408140824083408440854086408740884089409040914092409340944095409640974098409941004101410241034104410541064107410841094110411141124113411441154116411741184119412041214122412341244125412641274128412941304131413241334134413541364137413841394140414141424143414441454146414741484149415041514152415341544155415641574158415941604161416241634164416541664167416841694170417141724173417441754176417741784179418041814182418341844185418641874188418941904191419241934194419541964197419841994200420142024203420442054206420742084209421042114212421342144215421642174218421942204221422242234224422542264227422842294230423142324233423442354236423742384239424042414242424342444245424642474248424942504251425242534254425542564257425842594260426142624263426442654266426742684269427042714272427342744275427642774278427942804281428242834284428542864287428842894290429142924293429442954296429742984299430043014302430343044305430643074308430943104311431243134314431543164317431843194320432143224323432443254326432743284329433043314332433343344335433643374338433943404341434243434344434543464347434843494350435143524353435443554356435743584359436043614362436343644365436643674368436943704371437243734374437543764377437843794380438143824383438443854386438743884389439043914392439343944395439643974398439944004401440244034404440544064407440844094410441144124413441444154416441744184419442044214422442344244425442644274428442944304431443244334434443544364437443844394440444144424443444444454446444744484449445044514452445344544455445644574458445944604461446244634464446544664467446844694470447144724473447444754476447744784479448044814482448344844485448644874488448944904491449244934494449544964497449844994500450145024503450445054506450745084509451045114512451345144515451645174518451945204521452245234524452545264527452845294530453145324533453445354536453745384539454045414542454345444545454645474548454945504551455245534554455545564557455845594560456145624563456445654566456745684569457045714572457345744575457645774578457945804581458245834584458545864587458845894590459145924593459445954596459745984599460046014602460346044605460646074608460946104611461246134614461546164617461846194620462146224623462446254626462746284629463046314632463346344635463646374638463946404641464246434644464546464647464846494650465146524653465446554656465746584659466046614662466346644665466646674668466946704671467246734674467546764677467846794680468146824683468446854686468746884689469046914692469346944695469646974698469947004701470247034704470547064707470847094710471147124713471447154716471747184719472047214722472347244725472647274728472947304731473247334734473547364737473847394740474147424743474447454746474747484749475047514752475347544755475647574758475947604761476247634764476547664767476847694770477147724773477447754776477747784779478047814782478347844785478647874788478947904791479247934794479547964797479847994800480148024803480448054806480748084809481048114812481348144815481648174818481948204821482248234824482548264827482848294830483148324833483448354836483748384839484048414842484348444845484648474848484948504851485248534854485548564857485848594860486148624863486448654866486748684869487048714872487348744875487648774878487948804881488248834884488548864887488848894890489148924893489448954896489748984899490049014902490349044905490649074908490949104911491249134914491549164917491849194920492149224923492449254926492749284929493049314932493349344935493649374938493949404941494249434944494549464947494849494950495149524953495449554956495749584959496049614962496349644965496649674968496949704971497249734974497549764977497849794980498149824983498449854986498749884989499049914992499349944995499649974998499950005001500250035004500550065007500850095010501150125013501450155016501750185019502050215022502350245025502650275028502950305031503250335034503550365037503850395040504150425043504450455046504750485049505050515052505350545055505650575058505950605061506250635064506550665067506850695070507150725073507450755076507750785079508050815082508350845085508650875088508950905091509250935094509550965097509850995100510151025103510451055106510751085109511051115112511351145115511651175118511951205121512251235124512551265127512851295130513151325133513451355136513751385139514051415142514351445145514651475148514951505151515251535154515551565157515851595160516151625163516451655166516751685169517051715172517351745175517651775178517951805181518251835184518551865187518851895190519151925193519451955196519751985199520052015202520352045205520652075208520952105211521252135214521552165217521852195220522152225223522452255226522752285229523052315232523352345235523652375238523952405241524252435244524552465247524852495250525152525253525452555256525752585259526052615262526352645265526652675268526952705271527252735274527552765277527852795280528152825283528452855286528752885289529052915292529352945295529652975298529953005301530253035304530553065307530853095310531153125313531453155316531753185319532053215322532353245325532653275328532953305331533253335334533553365337533853395340534153425343534453455346534753485349535053515352535353545355535653575358535953605361536253635364536553665367536853695370537153725373537453755376537753785379538053815382538353845385538653875388538953905391539253935394539553965397539853995400540154025403540454055406540754085409541054115412541354145415541654175418541954205421542254235424542554265427542854295430543154325433543454355436543754385439544054415442544354445445544654475448544954505451545254535454545554565457545854595460546154625463546454655466546754685469547054715472547354745475547654775478547954805481548254835484548554865487548854895490549154925493549454955496549754985499550055015502550355045505550655075508550955105511551255135514551555165517551855195520552155225523552455255526552755285529553055315532553355345535553655375538553955405541554255435544554555465547554855495550555155525553555455555556555755585559556055615562556355645565556655675568556955705571557255735574557555765577557855795580558155825583558455855586558755885589559055915592559355945595559655975598559956005601560256035604560556065607560856095610561156125613561456155616561756185619562056215622562356245625562656275628562956305631563256335634563556365637563856395640564156425643564456455646564756485649565056515652565356545655565656575658565956605661566256635664566556665667566856695670567156725673567456755676567756785679568056815682568356845685568656875688568956905691569256935694569556965697569856995700570157025703570457055706570757085709571057115712571357145715571657175718571957205721572257235724572557265727572857295730573157325733573457355736573757385739574057415742574357445745574657475748574957505751575257535754575557565757575857595760576157625763576457655766576757685769577057715772577357745775577657775778577957805781578257835784578557865787578857895790579157925793579457955796579757985799580058015802580358045805580658075808580958105811581258135814581558165817581858195820582158225823582458255826582758285829583058315832583358345835583658375838583958405841584258435844584558465847584858495850585158525853585458555856585758585859586058615862586358645865586658675868586958705871587258735874587558765877587858795880588158825883588458855886588758885889589058915892589358945895589658975898589959005901590259035904590559065907590859095910591159125913591459155916591759185919592059215922592359245925592659275928592959305931593259335934593559365937593859395940594159425943594459455946594759485949595059515952595359545955595659575958595959605961596259635964596559665967596859695970597159725973597459755976597759785979598059815982598359845985598659875988598959905991599259935994599559965997599859996000600160026003600460056006600760086009601060116012601360146015601660176018601960206021602260236024602560266027602860296030603160326033603460356036603760386039604060416042604360446045604660476048604960506051605260536054605560566057605860596060606160626063606460656066606760686069607060716072607360746075607660776078607960806081608260836084608560866087608860896090609160926093609460956096609760986099610061016102610361046105610661076108610961106111611261136114611561166117611861196120612161226123612461256126612761286129613061316132613361346135613661376138613961406141614261436144614561466147614861496150615161526153615461556156615761586159616061616162616361646165616661676168616961706171617261736174617561766177617861796180618161826183618461856186618761886189619061916192619361946195619661976198619962006201620262036204620562066207620862096210621162126213621462156216621762186219622062216222622362246225622662276228622962306231623262336234623562366237623862396240624162426243624462456246624762486249625062516252625362546255625662576258625962606261626262636264626562666267626862696270627162726273627462756276627762786279628062816282628362846285628662876288628962906291629262936294629562966297629862996300630163026303630463056306630763086309631063116312631363146315631663176318631963206321632263236324632563266327632863296330633163326333633463356336633763386339634063416342634363446345634663476348634963506351635263536354635563566357635863596360636163626363636463656366636763686369637063716372637363746375637663776378637963806381638263836384638563866387638863896390639163926393639463956396639763986399640064016402640364046405640664076408640964106411641264136414641564166417641864196420642164226423642464256426642764286429643064316432643364346435643664376438643964406441644264436444644564466447644864496450645164526453645464556456645764586459646064616462646364646465646664676468646964706471647264736474647564766477647864796480648164826483648464856486648764886489649064916492649364946495649664976498649965006501650265036504650565066507650865096510651165126513651465156516651765186519652065216522652365246525652665276528652965306531653265336534653565366537653865396540654165426543654465456546654765486549655065516552655365546555655665576558655965606561656265636564656565666567656865696570657165726573657465756576657765786579658065816582658365846585658665876588658965906591659265936594659565966597659865996600660166026603660466056606660766086609661066116612661366146615661666176618661966206621662266236624662566266627662866296630663166326633663466356636663766386639664066416642664366446645664666476648664966506651665266536654665566566657665866596660666166626663666466656666666766686669667066716672667366746675667666776678667966806681668266836684668566866687668866896690669166926693669466956696669766986699670067016702670367046705670667076708670967106711671267136714671567166717671867196720672167226723672467256726672767286729673067316732673367346735673667376738673967406741674267436744674567466747674867496750675167526753675467556756675767586759676067616762676367646765676667676768676967706771677267736774677567766777677867796780678167826783678467856786678767886789679067916792679367946795679667976798679968006801680268036804680568066807680868096810681168126813681468156816681768186819682068216822682368246825682668276828682968306831683268336834683568366837683868396840684168426843684468456846684768486849685068516852685368546855685668576858685968606861686268636864686568666867686868696870687168726873687468756876687768786879688068816882688368846885688668876888688968906891689268936894689568966897689868996900690169026903690469056906690769086909691069116912691369146915691669176918691969206921692269236924692569266927692869296930693169326933693469356936693769386939694069416942694369446945694669476948694969506951695269536954695569566957695869596960696169626963696469656966696769686969697069716972697369746975697669776978697969806981698269836984698569866987698869896990699169926993699469956996699769986999700070017002700370047005700670077008700970107011701270137014701570167017701870197020702170227023702470257026702770287029703070317032703370347035703670377038703970407041704270437044704570467047704870497050705170527053705470557056705770587059706070617062706370647065706670677068706970707071707270737074707570767077707870797080708170827083708470857086708770887089709070917092709370947095709670977098709971007101710271037104710571067107710871097110711171127113711471157116711771187119712071217122712371247125712671277128712971307131713271337134713571367137713871397140714171427143714471457146714771487149715071517152715371547155715671577158715971607161716271637164716571667167716871697170717171727173717471757176717771787179718071817182718371847185718671877188718971907191719271937194719571967197719871997200720172027203720472057206720772087209721072117212721372147215721672177218721972207221722272237224722572267227722872297230723172327233723472357236723772387239724072417242724372447245724672477248724972507251725272537254725572567257725872597260726172627263726472657266726772687269727072717272727372747275727672777278727972807281728272837284728572867287728872897290729172927293729472957296729772987299730073017302730373047305730673077308730973107311731273137314731573167317731873197320732173227323732473257326732773287329733073317332733373347335733673377338733973407341734273437344734573467347734873497350735173527353735473557356735773587359736073617362736373647365736673677368736973707371737273737374737573767377737873797380738173827383738473857386738773887389739073917392739373947395739673977398739974007401740274037404740574067407740874097410741174127413741474157416741774187419742074217422742374247425742674277428742974307431743274337434743574367437743874397440744174427443744474457446744774487449745074517452745374547455745674577458745974607461746274637464746574667467746874697470747174727473747474757476747774787479748074817482748374847485748674877488748974907491749274937494749574967497749874997500750175027503750475057506750775087509751075117512751375147515751675177518751975207521752275237524752575267527752875297530753175327533753475357536753775387539754075417542754375447545754675477548754975507551755275537554755575567557755875597560756175627563756475657566756775687569757075717572757375747575757675777578757975807581758275837584758575867587758875897590759175927593759475957596759775987599760076017602760376047605760676077608760976107611761276137614761576167617761876197620762176227623762476257626762776287629763076317632763376347635763676377638763976407641764276437644764576467647764876497650765176527653765476557656765776587659766076617662766376647665766676677668766976707671767276737674767576767677767876797680768176827683768476857686768776887689769076917692769376947695769676977698769977007701770277037704770577067707770877097710771177127713771477157716771777187719772077217722772377247725772677277728772977307731773277337734773577367737773877397740774177427743774477457746774777487749775077517752775377547755775677577758775977607761776277637764776577667767776877697770777177727773777477757776777777787779778077817782778377847785778677877788778977907791779277937794779577967797779877997800780178027803780478057806780778087809781078117812781378147815781678177818781978207821782278237824782578267827782878297830783178327833783478357836783778387839784078417842784378447845784678477848784978507851785278537854785578567857785878597860786178627863786478657866786778687869787078717872787378747875787678777878787978807881788278837884788578867887788878897890789178927893789478957896789778987899790079017902790379047905790679077908790979107911791279137914791579167917791879197920792179227923792479257926792779287929793079317932793379347935793679377938793979407941794279437944794579467947794879497950795179527953795479557956795779587959796079617962796379647965796679677968796979707971797279737974797579767977797879797980798179827983798479857986798779887989799079917992799379947995799679977998799980008001800280038004800580068007800880098010801180128013801480158016801780188019802080218022802380248025802680278028802980308031803280338034803580368037803880398040804180428043804480458046804780488049805080518052805380548055805680578058805980608061806280638064806580668067806880698070807180728073807480758076807780788079808080818082808380848085808680878088808980908091809280938094809580968097809880998100810181028103810481058106810781088109811081118112811381148115811681178118811981208121812281238124812581268127812881298130813181328133813481358136813781388139814081418142814381448145814681478148814981508151815281538154815581568157815881598160816181628163816481658166816781688169817081718172817381748175817681778178817981808181818281838184818581868187818881898190819181928193819481958196819781988199820082018202820382048205820682078208820982108211821282138214821582168217821882198220822182228223822482258226822782288229823082318232823382348235823682378238823982408241824282438244824582468247824882498250825182528253825482558256825782588259826082618262826382648265826682678268826982708271827282738274827582768277827882798280828182828283828482858286828782888289829082918292829382948295829682978298829983008301830283038304830583068307830883098310831183128313831483158316831783188319832083218322832383248325832683278328832983308331833283338334833583368337833883398340834183428343834483458346834783488349835083518352835383548355835683578358835983608361836283638364836583668367836883698370837183728373837483758376837783788379838083818382838383848385838683878388838983908391839283938394839583968397839883998400840184028403840484058406840784088409841084118412841384148415841684178418841984208421842284238424842584268427842884298430843184328433843484358436843784388439844084418442844384448445844684478448844984508451845284538454845584568457845884598460846184628463846484658466846784688469847084718472847384748475847684778478847984808481848284838484848584868487848884898490849184928493849484958496849784988499850085018502850385048505850685078508850985108511851285138514851585168517851885198520852185228523852485258526852785288529853085318532853385348535853685378538853985408541854285438544854585468547854885498550855185528553855485558556855785588559856085618562856385648565856685678568856985708571857285738574857585768577857885798580858185828583858485858586858785888589859085918592859385948595859685978598859986008601860286038604860586068607860886098610861186128613861486158616861786188619862086218622862386248625862686278628862986308631863286338634863586368637863886398640864186428643864486458646864786488649865086518652865386548655865686578658865986608661866286638664866586668667866886698670867186728673867486758676867786788679868086818682868386848685868686878688868986908691869286938694869586968697869886998700870187028703870487058706870787088709871087118712871387148715871687178718871987208721872287238724872587268727872887298730873187328733873487358736873787388739874087418742874387448745874687478748874987508751875287538754875587568757875887598760876187628763876487658766876787688769877087718772877387748775877687778778877987808781878287838784878587868787878887898790879187928793879487958796879787988799880088018802880388048805880688078808880988108811881288138814881588168817881888198820882188228823882488258826882788288829883088318832883388348835883688378838883988408841884288438844884588468847884888498850885188528853885488558856885788588859886088618862886388648865886688678868886988708871887288738874887588768877887888798880888188828883888488858886888788888889889088918892889388948895889688978898889989008901890289038904890589068907890889098910891189128913891489158916891789188919892089218922892389248925892689278928892989308931893289338934893589368937893889398940894189428943894489458946894789488949895089518952895389548955895689578958895989608961896289638964896589668967896889698970897189728973897489758976897789788979898089818982898389848985898689878988898989908991899289938994899589968997899889999000900190029003900490059006900790089009901090119012901390149015901690179018901990209021902290239024902590269027902890299030903190329033903490359036903790389039904090419042904390449045904690479048904990509051905290539054905590569057905890599060906190629063906490659066906790689069907090719072907390749075907690779078907990809081908290839084908590869087908890899090909190929093909490959096909790989099910091019102910391049105910691079108910991109111911291139114911591169117911891199120912191229123912491259126912791289129913091319132913391349135913691379138913991409141914291439144914591469147914891499150915191529153915491559156915791589159916091619162916391649165916691679168916991709171917291739174917591769177917891799180918191829183918491859186918791889189919091919192919391949195919691979198919992009201920292039204920592069207920892099210921192129213921492159216921792189219922092219222922392249225922692279228922992309231923292339234923592369237923892399240924192429243924492459246924792489249925092519252925392549255925692579258925992609261926292639264926592669267926892699270927192729273927492759276927792789279928092819282928392849285928692879288928992909291929292939294929592969297929892999300930193029303930493059306930793089309931093119312931393149315931693179318931993209321932293239324932593269327932893299330933193329333933493359336933793389339934093419342934393449345934693479348934993509351935293539354935593569357935893599360936193629363936493659366936793689369937093719372937393749375937693779378937993809381938293839384938593869387938893899390939193929393939493959396939793989399940094019402940394049405940694079408940994109411941294139414941594169417941894199420942194229423942494259426942794289429943094319432943394349435943694379438943994409441944294439444944594469447944894499450945194529453945494559456945794589459946094619462946394649465946694679468946994709471947294739474947594769477947894799480948194829483948494859486948794889489949094919492949394949495949694979498949995009501950295039504950595069507950895099510951195129513951495159516951795189519952095219522952395249525952695279528952995309531953295339534953595369537953895399540954195429543954495459546954795489549955095519552955395549555955695579558955995609561956295639564956595669567956895699570957195729573957495759576957795789579958095819582958395849585958695879588958995909591959295939594959595969597959895999600960196029603960496059606960796089609961096119612961396149615961696179618961996209621962296239624962596269627962896299630963196329633963496359636963796389639964096419642964396449645964696479648964996509651965296539654965596569657965896599660966196629663966496659666966796689669967096719672967396749675967696779678967996809681968296839684968596869687968896899690969196929693969496959696969796989699970097019702970397049705970697079708970997109711971297139714971597169717971897199720972197229723972497259726972797289729973097319732973397349735973697379738973997409741974297439744974597469747974897499750975197529753975497559756975797589759976097619762976397649765976697679768976997709771977297739774977597769777977897799780978197829783978497859786978797889789979097919792979397949795979697979798979998009801980298039804980598069807980898099810981198129813981498159816981798189819982098219822982398249825982698279828982998309831983298339834983598369837983898399840984198429843984498459846984798489849985098519852985398549855985698579858985998609861986298639864986598669867986898699870987198729873987498759876987798789879988098819882988398849885988698879888988998909891989298939894989598969897989898999900990199029903990499059906990799089909991099119912991399149915991699179918991999209921992299239924992599269927992899299930993199329933993499359936993799389939994099419942994399449945994699479948994999509951995299539954995599569957995899599960996199629963996499659966996799689969997099719972997399749975997699779978997999809981998299839984998599869987998899899990999199929993999499959996999799989999100001000110002100031000410005100061000710008100091001010011100121001310014100151001610017100181001910020100211002210023100241002510026100271002810029100301003110032100331003410035100361003710038100391004010041100421004310044100451004610047100481004910050100511005210053100541005510056100571005810059100601006110062100631006410065100661006710068100691007010071100721007310074100751007610077100781007910080100811008210083100841008510086100871008810089100901009110092100931009410095100961009710098100991010010101101021010310104101051010610107101081010910110101111011210113101141011510116101171011810119101201012110122101231012410125101261012710128101291013010131101321013310134101351013610137101381013910140101411014210143101441014510146101471014810149101501015110152101531015410155101561015710158101591016010161101621016310164101651016610167101681016910170101711017210173101741017510176101771017810179101801018110182101831018410185101861018710188101891019010191101921019310194101951019610197101981019910200102011020210203102041020510206102071020810209102101021110212102131021410215102161021710218102191022010221102221022310224102251022610227102281022910230102311023210233102341023510236102371023810239102401024110242102431024410245102461024710248102491025010251102521025310254102551025610257102581025910260102611026210263102641026510266102671026810269102701027110272102731027410275102761027710278102791028010281102821028310284102851028610287102881028910290102911029210293102941029510296102971029810299103001030110302103031030410305103061030710308103091031010311103121031310314103151031610317103181031910320103211032210323103241032510326103271032810329103301033110332103331033410335103361033710338103391034010341103421034310344103451034610347103481034910350103511035210353103541035510356103571035810359103601036110362103631036410365103661036710368103691037010371103721037310374103751037610377103781037910380103811038210383103841038510386103871038810389103901039110392103931039410395103961039710398103991040010401104021040310404104051040610407104081040910410104111041210413104141041510416104171041810419104201042110422104231042410425104261042710428104291043010431104321043310434104351043610437104381043910440104411044210443104441044510446104471044810449104501045110452104531045410455104561045710458104591046010461104621046310464104651046610467104681046910470104711047210473104741047510476104771047810479104801048110482104831048410485104861048710488104891049010491104921049310494104951049610497104981049910500105011050210503105041050510506105071050810509105101051110512105131051410515105161051710518105191052010521105221052310524105251052610527105281052910530105311053210533105341053510536105371053810539105401054110542105431054410545105461054710548105491055010551105521055310554105551055610557105581055910560105611056210563105641056510566105671056810569105701057110572105731057410575105761057710578105791058010581105821058310584105851058610587105881058910590105911059210593105941059510596105971059810599106001060110602106031060410605106061060710608106091061010611106121061310614106151061610617106181061910620106211062210623106241062510626106271062810629106301063110632106331063410635106361063710638106391064010641106421064310644106451064610647106481064910650106511065210653106541065510656106571065810659106601066110662106631066410665106661066710668106691067010671106721067310674106751067610677106781067910680106811068210683106841068510686106871068810689106901069110692106931069410695106961069710698106991070010701107021070310704107051070610707107081070910710107111071210713107141071510716107171071810719107201072110722107231072410725107261072710728107291073010731107321073310734107351073610737107381073910740107411074210743107441074510746107471074810749107501075110752107531075410755107561075710758107591076010761107621076310764107651076610767107681076910770107711077210773107741077510776107771077810779107801078110782107831078410785107861078710788107891079010791107921079310794107951079610797107981079910800108011080210803108041080510806108071080810809108101081110812108131081410815108161081710818108191082010821108221082310824108251082610827108281082910830108311083210833108341083510836108371083810839108401084110842108431084410845108461084710848108491085010851108521085310854108551085610857108581085910860108611086210863108641086510866108671086810869108701087110872108731087410875108761087710878108791088010881108821088310884108851088610887108881088910890108911089210893108941089510896108971089810899109001090110902109031090410905109061090710908109091091010911109121091310914109151091610917109181091910920109211092210923109241092510926109271092810929109301093110932109331093410935109361093710938109391094010941109421094310944109451094610947109481094910950109511095210953109541095510956109571095810959109601096110962109631096410965109661096710968109691097010971109721097310974109751097610977109781097910980109811098210983109841098510986109871098810989109901099110992109931099410995109961099710998109991100011001110021100311004110051100611007110081100911010110111101211013110141101511016110171101811019110201102111022110231102411025110261102711028110291103011031110321103311034110351103611037110381103911040110411104211043110441104511046110471104811049110501105111052110531105411055110561105711058110591106011061110621106311064110651106611067110681106911070110711107211073110741107511076110771107811079110801108111082110831108411085110861108711088110891109011091110921109311094110951109611097110981109911100111011110211103111041110511106111071110811109111101111111112111131111411115111161111711118111191112011121111221112311124111251112611127111281112911130111311113211133111341113511136111371113811139111401114111142111431114411145111461114711148111491115011151111521115311154111551115611157111581115911160111611116211163111641116511166111671116811169111701117111172111731117411175111761117711178111791118011181111821118311184111851118611187111881118911190111911119211193111941119511196111971119811199112001120111202112031120411205112061120711208112091121011211112121121311214112151121611217112181121911220112211122211223112241122511226112271122811229112301123111232112331123411235112361123711238112391124011241112421124311244112451124611247112481124911250112511125211253112541125511256112571125811259112601126111262112631126411265112661126711268112691127011271112721127311274112751127611277112781127911280112811128211283112841128511286112871128811289112901129111292112931129411295112961129711298112991130011301113021130311304113051130611307113081130911310113111131211313113141131511316113171131811319113201132111322113231132411325113261132711328113291133011331113321133311334113351133611337113381133911340113411134211343113441134511346113471134811349113501135111352113531135411355113561135711358113591136011361113621136311364113651136611367113681136911370113711137211373113741137511376113771137811379113801138111382113831138411385113861138711388113891139011391113921139311394113951139611397113981139911400114011140211403114041140511406114071140811409114101141111412114131141411415114161141711418114191142011421114221142311424114251142611427114281142911430114311143211433114341143511436114371143811439114401144111442114431144411445114461144711448114491145011451114521145311454114551145611457114581145911460114611146211463114641146511466114671146811469114701147111472114731147411475114761147711478114791148011481114821148311484114851148611487114881148911490114911149211493114941149511496114971149811499115001150111502115031150411505115061150711508115091151011511115121151311514115151151611517115181151911520115211152211523115241152511526115271152811529115301153111532115331153411535115361153711538115391154011541115421154311544115451154611547115481154911550115511155211553115541155511556115571155811559115601156111562115631156411565115661156711568115691157011571115721157311574115751157611577115781157911580115811158211583115841158511586115871158811589115901159111592115931159411595115961159711598115991160011601116021160311604116051160611607116081160911610116111161211613116141161511616116171161811619116201162111622116231162411625116261162711628116291163011631116321163311634116351163611637116381163911640116411164211643116441164511646116471164811649116501165111652116531165411655116561165711658116591166011661116621166311664116651166611667116681166911670116711167211673116741167511676116771167811679116801168111682116831168411685116861168711688116891169011691116921169311694116951169611697116981169911700117011170211703117041170511706117071170811709117101171111712117131171411715117161171711718117191172011721117221172311724117251172611727117281172911730117311173211733117341173511736117371173811739117401174111742117431174411745117461174711748117491175011751117521175311754117551175611757117581175911760117611176211763117641176511766117671176811769117701177111772117731177411775117761177711778117791178011781117821178311784117851178611787117881178911790117911179211793117941179511796117971179811799118001180111802118031180411805118061180711808118091181011811118121181311814118151181611817118181181911820118211182211823118241182511826118271182811829118301183111832118331183411835118361183711838118391184011841118421184311844118451184611847118481184911850118511185211853118541185511856118571185811859118601186111862118631186411865118661186711868118691187011871118721187311874118751187611877118781187911880118811188211883118841188511886118871188811889118901189111892118931189411895118961189711898118991190011901119021190311904119051190611907119081190911910119111191211913119141191511916119171191811919119201192111922119231192411925119261192711928119291193011931119321193311934119351193611937119381193911940119411194211943119441194511946119471194811949119501195111952119531195411955119561195711958119591196011961119621196311964119651196611967119681196911970119711197211973119741197511976119771197811979119801198111982119831198411985119861198711988119891199011991119921199311994119951199611997119981199912000120011200212003120041200512006120071200812009120101201112012120131201412015120161201712018120191202012021120221202312024120251202612027120281202912030120311203212033120341203512036120371203812039120401204112042120431204412045120461204712048120491205012051120521205312054120551205612057120581205912060120611206212063120641206512066120671206812069120701207112072120731207412075120761207712078120791208012081120821208312084120851208612087120881208912090120911209212093120941209512096120971209812099121001210112102121031210412105121061210712108121091211012111121121211312114121151211612117121181211912120121211212212123121241212512126121271212812129121301213112132121331213412135121361213712138121391214012141121421214312144121451214612147121481214912150121511215212153121541215512156121571215812159121601216112162121631216412165121661216712168121691217012171121721217312174121751217612177121781217912180121811218212183121841218512186121871218812189121901219112192121931219412195121961219712198121991220012201122021220312204122051220612207122081220912210122111221212213122141221512216122171221812219122201222112222122231222412225122261222712228122291223012231122321223312234122351223612237122381223912240122411224212243122441224512246122471224812249122501225112252122531225412255122561225712258122591226012261122621226312264122651226612267122681226912270122711227212273122741227512276122771227812279122801228112282122831228412285122861228712288122891229012291122921229312294122951229612297122981229912300123011230212303123041230512306123071230812309123101231112312123131231412315123161231712318123191232012321123221232312324123251232612327123281232912330123311233212333123341233512336123371233812339123401234112342123431234412345123461234712348123491235012351123521235312354123551235612357123581235912360123611236212363123641236512366123671236812369123701237112372123731237412375123761237712378123791238012381123821238312384123851238612387123881238912390123911239212393123941239512396123971239812399124001240112402124031240412405124061240712408124091241012411124121241312414124151241612417124181241912420124211242212423124241242512426124271242812429124301243112432124331243412435124361243712438124391244012441124421244312444124451244612447124481244912450124511245212453124541245512456124571245812459124601246112462124631246412465124661246712468124691247012471124721247312474124751247612477124781247912480124811248212483124841248512486124871248812489124901249112492124931249412495124961249712498124991250012501125021250312504125051250612507125081250912510125111251212513125141251512516
  1. \input texinfo @c -*-texinfo-*-
  2. @c %**start of header
  3. @setfilename avram.info
  4. @settitle avram - a virtual machine code interpreter
  5. @finalout
  6. @setchapternewpage odd
  7. @c %**end of header
  8. @set VERSION 0.13.0
  9. @ifinfo
  10. This file documents the @code{avram} command which is a virtual machine code interpreter
  11. Copyright (C) 2000, 2003, 2006-2010, 2012 Dennis Furey
  12. Permission is granted to make and distribute verbatim copies of
  13. this manual provided the copyright notice and this permission notice
  14. are preserved on all copies.
  15. @ignore
  16. Permission is granted to process this file through TeX and print the
  17. results, provided the printed document carries copying permission
  18. notice identical to this one except for the removal of this paragraph
  19. (this paragraph not being relevant to the printed manual).
  20. @end ignore
  21. Permission is granted to copy and distribute modified versions of this
  22. manual under the conditions for verbatim copying, provided that the entire
  23. resulting derived work is distributed under the terms of a permission
  24. notice identical to this one.
  25. Permission is granted to copy and distribute translations of this manual
  26. into another language, under the above conditions for modified versions,
  27. except that this permission notice may be stated in a translation approved
  28. by the Free Software Foundation.
  29. @end ifinfo
  30. @titlepage
  31. @title Avram
  32. @subtitle a virtual machine code interpreter
  33. @subtitle for avram Version @value{VERSION}
  34. @author by Dennis Furey
  35. @page
  36. @vskip 0pt plus 1filll
  37. Copyright @copyright{} 2000, 2003, 2006-2010, 2012 Dennis Furey
  38. Permission is granted to make and distribute verbatim copies of
  39. this manual provided the copyright notice and this permission notice
  40. are preserved on all copies.
  41. Permission is granted to copy and distribute modified versions of this
  42. manual under the conditions for verbatim copying, provided that the entire
  43. resulting derived work is distributed under the terms of a permission
  44. notice identical to this one.
  45. Permission is granted to copy and distribute translations of this manual
  46. into another language, under the above conditions for modified versions,
  47. except that this permission notice may be stated in a translation approved
  48. by the Free Software Foundation.
  49. @end titlepage
  50. @shortcontents
  51. @contents
  52. @c All the nodes can be updated using the EMACS command
  53. @c texinfo-every-node-update, which is normally bound to C-c C-u C-e.
  54. @node Top, Preface, (dir), (dir)
  55. @ifinfo
  56. This file documents @code{avram} version @value{VERSION}, which is a virtual
  57. machine code interpreter.
  58. @end ifinfo
  59. @c All the menus can be updated with the EMACS command
  60. @c texinfo-all-menus-update, which is normally bound to C-c C-u C-a.
  61. @menu
  62. * Preface:: project aims and scope
  63. * User Manual:: command line options and usage
  64. * Virtual Machine Specification:: a guide for compiler writers
  65. * Library Reference:: how to reuse or enhance @code{avram}
  66. * Character Table:: representations for ASCII characters
  67. * Reference Implementations:: constructive computability proofs
  68. * Changes:: recent updates to the manual
  69. * External Libraries:: specifications and calling conventions
  70. * Copying:: license terms
  71. * Function Index:: for the shared library API
  72. * Concept Index::
  73. @end menu
  74. @node Preface, User Manual, Top, Top
  75. @unnumbered Preface
  76. @code{avram} is a virtual machine code interpreter. It reads an input
  77. file containing a user-supplied application expressed in virtual machine
  78. code, and executes it on the host machine. The name is a quasi-acronym
  79. for ``Applicative ViRtuAl Machine''. Notable features are
  80. @cindex functional programming
  81. @cindex environment
  82. @cindex Unix
  83. @itemize @bullet
  84. @item strong
  85. support for functional programming operations (e.g., list processing)
  86. @item
  87. interfaces to selected functions from mathematical libraries, such as
  88. @itemize @bullet
  89. @item
  90. @code{gsl} (numerical integration, differentiation, and series acceleration)
  91. @url{http://www.gnu.org/software/gsl/}
  92. @item
  93. @code{mpfr} (arbitrary precision arithmetic)
  94. @url{http://www.mpfr.org}
  95. @item
  96. @code{minpack} (non-linear optimization)
  97. @url{http://www.netlib.org/minpack}
  98. @item
  99. @code{lapack} (linear algebra)
  100. @url{http://www.netlib.org/lapack}
  101. @item
  102. @code{fftw} (fast fourier transforms)
  103. @url{http://www.fftw.org}
  104. @item
  105. @code{Rmath} (statistical and transcendental functions)
  106. @url{http://www.r-project.org}
  107. @item
  108. @code{ufsparse} (sparse matrices)
  109. @url{http://www.cise.ufl.edu/research/sparse/SuiteSparse/current/SuiteSparse/}
  110. @item
  111. @code{glpk} (linear programming by the simplex method)
  112. @url{http://www.gnu.org/software/glpk}
  113. @item
  114. @code{lpsolve} (mixed integer linear programming)
  115. @url{http://sourceforge.net/projects/lpsolve/}
  116. @item
  117. @code{kinsol} (constrained non-linear optimization)
  118. @url{http://www.llnl.gov/CASC/sundials/}
  119. @end itemize
  120. @item interoperability of virtual code applications with other console
  121. applications or shells through the @code{expect} library
  122. @item a simple high-level
  123. interface to files, environment variables and command line parameters
  124. @item support for various styles of stateless or persistent stream
  125. processors (a.k.a. Unix filters)
  126. @end itemize
  127. The reason for writing @code{avram} was that I wanted to do some work
  128. using a functional programming language, didn't like any functional
  129. programming languages that already existed, and felt that it would be
  130. less trouble to write a virtual machine emulator than the back end of
  131. a compiler. As of version 0.1.0, the first public release of
  132. @code{avram} as such in 2000, most of the code base had been in heavy
  133. use by me for about four years, running very reliably. At this writing
  134. some six years later, it has seen even more use with rarely any
  135. reliability issues, in some cases attacking large combinatorial
  136. problems for weeks or months at a time. These problems have involved
  137. both long running continuous execution, and batches of thousands of
  138. shorter jobs.
  139. Although the virtual machine is biased toward functional programming,
  140. it is officially language agnostic, so @code{avram} may be useful to
  141. anyone involved in the development of compilers for other programming,
  142. scripting, or special purpose languages. The crucial advantage of
  143. using it in your own project is that rather than troubling over
  144. address modes, register allocation, and other hassles inherent in
  145. generating native code, your compiler can just dump a fairly high
  146. level intermediate code representation of the source text to a file,
  147. and let the virtual machine emulator deal with the details. The
  148. tradeoff for using a presumably higher level interpreted language is that the
  149. performance is unlikely to be competitive with native code, but this
  150. issue is mitigated in the case of numerical applications whose heavy
  151. lifting is done by the external libraries mentioned above.
  152. Portability is an added bonus. The virtual code is binary compatible
  153. across all platforms. Versions of @code{avram} as of 0.1.0 and later are
  154. packaged using GNU autotools and should be possible to build on any
  155. platform supporting them. In particular, the package is known to have
  156. built successfully on MacOS, FreeBSD, Solaris (thanks to the compile
  157. farm at Sourceforge.net) Digital Unix, and Debian GNU/Linux for i386 and
  158. Alpha platforms, although it has not been extensively tested on all of
  159. them. Earlier versions were compiled and run successfully on Irix and
  160. even Windows-NT (with @command{gcc}).
  161. This document is divided into three main parts, with possibly three
  162. different audiences, but they all depend on a basic familiarity with
  163. @cindex Unix
  164. Unix or GNU/Linux systems.
  165. @table @asis
  166. @item @ref{User Manual}
  167. essentially reproduces the information found in
  168. the manpage that is distributed with @code{avram} with a few extra
  169. examples and longer explanations. Properly deployed,
  170. @code{avram} should be almost entirely hidden from end users by wrapper
  171. scripts, so the ``users'' to whom this part is relevant would be
  172. those involved in preparing these scripts (a matter of choosing the right
  173. command line options). Depending on the extent to which this task is
  174. automated by a compiler, that may include the compiler writer or the
  175. developers of applications.
  176. @item @ref{Virtual Machine Specification}
  177. documents much of what one would need to know in order to write a
  178. compiler that generates code executable by @code{avram}. That includes
  179. the complete virtual machine code semantics and file formats. It would
  180. also be possible to implement a compatible replacement for @code{avram}
  181. from scratch based on the information in this chapter, in case anyone
  182. has anything against C, my coding style, or the GPL. (A few patches to
  183. make it @command{lint} cleanly or a new implementation in good
  184. pedagogical Java without pointers would both be instructive
  185. exercises. ;-))
  186. @cindex pointers
  187. @cindex Java
  188. @item @ref{Library Reference}
  189. includes documentation on the application program interface and
  190. recommended entry points for the C library distributed with
  191. @code{avram}. This information would be of use to those wishing to
  192. develop applications incorporating similar features, or to reuse the
  193. code for unrelated purposes. It might also be useful to anyone wishing
  194. to develop C or C++ applications that read or write data files in the
  195. format used by @code{avram}.
  196. @end table
  197. @node User Manual, Virtual Machine Specification, Preface, Top
  198. @chapter User Manual
  199. This chapter provides the basic information on how to use @code{avram}
  200. to execute virtual machine code applications.
  201. @code{avram} is invoked
  202. by typing a command at a shell prompt in one of these three forms.
  203. @display
  204. @kbd{avram} [@emph{general options}]
  205. @kbd{avram} [@emph{filter mode options}] @var{codefile}[@kbd{.avm}]
  206. @kbd{avram} [@emph{parameter mode options}] @var{codefile}[@kbd{.avm}] [@emph{parameters}]
  207. @end display
  208. @noindent
  209. In the second case, @code{avram} reads from standard input, and may
  210. of course appear as part of commands such as
  211. @cindex standard input
  212. @display
  213. @kbd{avram} [@emph{filter mode options}] @var{codefile}[@kbd{.avm}] < @var{inputfile}
  214. @var{anothercommand} | @kbd{avram} [@emph{filter mode options}] @var{codefile}[@kbd{.avm}]
  215. @end display
  216. @noindent
  217. When @code{avram} is invoked with the name of an input file (with a
  218. default extension @kbd{.avm}), it reads virtual machine code from the
  219. file and executes it on the host machine.
  220. @cindex functional programming
  221. The virtual code format used by @code{avram} is designed
  222. to support the features of functional or applicative programming
  223. languages. Although this chapter documents only the usage of
  224. @code{avram} and not the internals, it will be helpful to keep in mind
  225. that the virtual machine code expresses a mathematical function rather
  226. than a program in the conventional sense. As such, it performs no action
  227. directly, but may be applied in a choice of ways by the user of
  228. @code{avram} according to the precise operation required.
  229. The following sections provide information in greater detail about
  230. usage and diagnostics.
  231. @menu
  232. * General Options:: getting help and version information
  233. * Modes of Operation:: stream processing or file oriented
  234. * Filter Mode Options:: how to run a stream processor
  235. * Parameter Mode Options:: how to have an application use files
  236. * Command Line Syntax:: application-independent conventions
  237. * Diagnostics:: explanation of error messages
  238. * Security:: running untrusted applications
  239. * Example Script:: how to unburden the end users
  240. * Files:: miscellaneous files used
  241. * Environment:: environment variables
  242. * Bugs:: hall of shame
  243. @end menu
  244. @node General Options, Modes of Operation, User Manual, User Manual
  245. @section General Options
  246. Regardless of whatever other command line parameters are given,
  247. @code{avram} accepts the following parameters:
  248. @cindex help
  249. @cindex emulation
  250. @cindex @code{help} command line option
  251. @cindex @code{emulation} command line option
  252. @table @code
  253. @item -h, --help
  254. Show a summary of options and exit.
  255. @item -V,-v, --version
  256. Show the version of program and a short copyleft message and exit.
  257. @item --emulation=@var{version}
  258. Be backward compatible with an older version of @code{avram}. This
  259. option should include a valid version number, for example
  260. @kbd{@value{VERSION}}, which is the version of @code{avram} to be
  261. emulated. It can make virtual code applications future proof, assuming
  262. that future versions of @code{avram} correctly support backward
  263. compatibility. It may be used in conjunction with any other option in
  264. any mode of operation.
  265. @cindex web page
  266. @cindex home page
  267. @cindex url
  268. This copy of the user manual has not been updated since version @value{VERSION} of
  269. @code{avram}, so it is unable to document incompatibilities with later
  270. versions. The latest version of the manual may be found at
  271. @url{http://www.lsbu.ac.uk/~fureyd/avram}.
  272. @item -e, --external-libraries
  273. @cindex @code{external-libraries}
  274. Show a list of libraries with which @code{avram} has been linked and
  275. whose functions therefore could be called from virtual machine
  276. programs. This growing list currently includes selected functions from
  277. @code{fftw}, @code{glpk}, @code{gsl}, @code{kinsol}, @code{lapack},
  278. @code{minpack}, @code{mpfr}, @code{lpsolve}, @code{Rmath} and @code{ufsparse}
  279. (see @ref{Preface}) which are documented further in @ref{External Libraries}.
  280. @item -j, --jail
  281. @cindex @code{jail}
  282. This option disables execution of shell commands by virtual code
  283. applications, which is normally possible by default even for nominally
  284. non-interactive applications (see @ref{Parameter Mode Options}). A
  285. virtual code application attempting to spawn a shell (using the
  286. @code{interact} combinator) when this option is selected will
  287. encounter an exception rather than successful completion of the
  288. operation. This option is provided as a security feature for running
  289. untrusted code (see @ref{Security}), and is incompatible with
  290. @option{-i}, @option{-t}, and @option{-s}.
  291. @item -f, --force-text-input
  292. @cindex @code{force-text-input} command line option
  293. Normally @code{avram} will try to guess by looking at a file whether it
  294. is an ordinary text file or one that has been written in the virtual
  295. code file format, and choose a different internal representation
  296. accordingly. An application may require one representation or the
  297. other. This option tells @code{avram} to treat all input files other
  298. than the virtual code file (named in the first command line parameter)
  299. as text files regardless of whether or not it would be possible to
  300. interpret them otherwise. This option may be used in combination with
  301. any other option.
  302. @end table
  303. @node Modes of Operation, Filter Mode Options, General Options, User Manual
  304. @section Modes of Operation
  305. Apart from to the capability to print brief help messages and exit,
  306. there are two main modes of operation, depending on which options
  307. are specified on the command line before the virtual code file name.
  308. @cindex modes
  309. @cindex modes
  310. For the purpose of choosing the mode of operation, the virtual
  311. code filename is taken to be the first command line argument not
  312. beginning with a dash. Other conventions relevant to application
  313. specific parameters are detailed in @ref{Command Line Syntax}.
  314. @menu
  315. * Filter Mode::
  316. * Parameter Mode::
  317. @end menu
  318. @node Filter Mode, Parameter Mode, Modes of Operation, Modes of Operation
  319. @subsection Filter Mode
  320. @cindex filter mode
  321. @cindex modes
  322. In filter mode, the argument to the function given by the virtual code
  323. is taken from standard input, and the result is written to standard
  324. output, except for error messages resulting from a failure to evaluate
  325. the function, which are written to standard error.
  326. @xref{Diagnostics}. Filter mode is indicated whenever these three
  327. conditions are all met.
  328. @itemize @bullet
  329. @item
  330. Either at least one of the filter mode options appears on the command
  331. line preceding the first filename parameter, or there are no options at
  332. all. @xref{Filter Mode Options}.
  333. @item
  334. Exactly one filename parameter appears on the command line,
  335. which is the name of the virtual machine code file.
  336. @item
  337. Either the filename comes last on the command line, or the
  338. @option{--unparameterized} option precedes it, causing
  339. everything following it to be ignored.
  340. @end itemize
  341. @noindent
  342. Examples:
  343. @table @kbd
  344. @item avram mynewapp < inputfilename
  345. @cindex standard input
  346. In this example, filter mode is recognized by default because there are
  347. no options or input files on the command line to indicate
  348. otherwise. (The input file redirected into standard input is not treated
  349. by the shell as a command line argument.)
  350. @item cat somefile | avram -r coolprog > outputfile
  351. In this example, the @option{-r} option gives it away, being one of the
  352. filter mode options, in addition to the fact that there are no input
  353. file parameters or application-specific options.
  354. @item avram -u devilmaycare.avm --bogusoption ignoredparameter
  355. In this case, filter mode is forced by the @option{-u}
  356. option despite indications to the contrary.
  357. @end table
  358. @node Parameter Mode, , Filter Mode, Modes of Operation
  359. @subsection Parameter Mode
  360. @cindex parameter mode
  361. In parameter mode, the argument to the function given by the virtual
  362. code is a data structure containing environment variables and command
  363. line parameters including files, application specific options, and
  364. possibly standard input. The result obtained by evaluating the
  365. function is either a data structure representing a set of files to be
  366. written, which may include standard output, or a sequence of shell
  367. commands to be executed, or a combination of both. Parameter mode is
  368. indicated whenever either of these conditions is met.
  369. @itemize @bullet
  370. @item
  371. Any of the parameter mode options appears on the
  372. command line preceding the first filename parameter.
  373. @ifinfo
  374. @*
  375. @end ifinfo
  376. @xref{Parameter Mode Options}.
  377. @item
  378. At least one additional filename parameter or option follows the first
  379. filename parameter, and the option @option{--unparameterized} does not
  380. precede it.
  381. @end itemize
  382. @noindent
  383. Examples:
  384. @table @kbd
  385. @item avram --map-to-each-file prettyprinter.avm *.c *.h --extra-pretty
  386. In this example, parameter mode is indicated both by the parameter
  387. mode option @option{--map-to-each-file} and by the presence of input
  388. file names and the @option{--extra-pretty} option. The latter is
  389. specific to the hypothetical @code{prettyprinter.avm} virtual code
  390. application, as indicated by its position on the command line, and is
  391. therefore passed to it by @code{avram}.
  392. @item cat ~/specfile | avram reportgenerator -v - /var/log/syslog
  393. In this example, a hypothetical parameter mode application
  394. @code{reportgenerator} is able to read @file{~/specfile} from standard
  395. input because of the @code{-} used as a parameter.
  396. @item avram --parameterized grepenv
  397. In this example, a hypothetical application that searches shell
  398. variables is invoked in parameter mode even with no input files or
  399. application specific options, because of the @option{--parameterized}
  400. option. Parameter mode invocation is required by the application to give
  401. it access to the environment.
  402. @item avram grepenv --search-targets=PATH,MANPATH
  403. This example shows an application specific option with both a keyword
  404. and a parameter list. They suffice to indicate parameter mode without
  405. an explicit @option{--parameterized} option.
  406. @end table
  407. @node Filter Mode Options, Parameter Mode Options, Modes of Operation, User Manual
  408. @section Filter Mode Options
  409. The options available in filter mode are listed below. Except as
  410. otherwise noted, all options are mutually exclusive. Ordinarily a
  411. given application will require certain fixed settings of these options
  412. and will not work properly if they are set inappropriately.
  413. @table @code
  414. @item -r, @code{--raw-output}
  415. @cindex raw-output command line option
  416. Normally the result obtained by evaluating the function in the virtual
  417. code file must be a list of character strings, which is written as
  418. such to standard output. However, if this option is selected, the form
  419. of the result is unconstrained, and it will be written in a data file
  420. format that is not human readable but can be used by other
  421. applications. This option is incompatible with any other options
  422. except @option{-u}.
  423. @item -c, --choice-of-output
  424. @cindex @code{choice-of-output} command line option
  425. When this option is used, the evaluation of the function given by the
  426. virtual machine code will be expected to yield a data structure from
  427. which @code{avram} will ascertain whether standard output should be
  428. written in text or raw data format. This option should be used only
  429. if application is aware of it. It is incompatible with any other options
  430. except @option{-u}.
  431. @item -l, --line-map
  432. @cindex @code{line-map} command line option
  433. Normally the entire contents of standard input up to @code{EOF} are
  434. loaded into memory and used as the argument to the function in the
  435. virtual code file. However, this option causes standard input to be read
  436. a line at a time, with the function applied individually to each line,
  437. and its result in each case written immediately to standard output. A
  438. given application either requires this option or does not, and will not
  439. work properly in the alternative. This option implies
  440. @option{--force-text-input} and is incompatible with any other option except
  441. @option{-u}.
  442. @item -b, --byte-transducer
  443. @cindex @code{byte-transducer} command line option
  444. This option causes standard input to be read one character at a time,
  445. evaluating the function given by the virtual code file each time. The
  446. function is used as a state transition function that takes a state and
  447. input to a next state and output. The output is written concurrently
  448. with the input operations. A given application will not work properly
  449. with an inappropriate setting of this option. This option implies
  450. @option{--force-text-input} and is incompatible with any other option
  451. except @option{-u}.
  452. @item -u, --unparameterized
  453. @cindex @code{unparameterized} command line option
  454. Normally @code{avram} guesses whether to use filter mode or parameter
  455. mode depending on whether there are any parameters. Selecting this
  456. option forces it to operate in filter mode regardless. Any parameters
  457. that may appear on the command line after the virtual code file name
  458. are ignored. This option may be used in conjunction with any other
  459. filter mode option.
  460. @end table
  461. @node Parameter Mode Options, Command Line Syntax, Filter Mode Options, User Manual
  462. @section Parameter Mode Options
  463. @cindex parameter mode
  464. The parameter mode options are listed below. Except as otherwise
  465. noted, any combination of parameter mode options may be selected
  466. together, and except as noted, the settings of these options can be
  467. varied without breaking the application.
  468. @table @code
  469. @item -q, --quiet
  470. @cindex @code{quiet} command line option
  471. @code{avram} normally informs the user when writing an output file with
  472. a short message to standard output. This option suppresses such
  473. messages. This option is compatible with any application and any other
  474. parameter mode option except @option{-a}.
  475. @item -a, --ask-to-overwrite
  476. @cindex @code{ask-to-overwrite} command line option
  477. Selecting this option will cause @code{avram} to ask permission
  478. interactively before overwriting an existing file, and to refrain from
  479. overwriting it without permission, in which case the contents that
  480. were to be written will be lost. This option overrides @option{-q} and is
  481. compatible with any other parameter mode option or application.
  482. @item -.EXT
  483. @cindex @code{EXT} command line option
  484. @cindex default file extensions
  485. @cindex extensions
  486. @cindex file name extensions
  487. @cindex file name suffixes
  488. An option beginning with a dash followed by a period specifies a
  489. default extension for input file names. If @code{avram} doesn't find a
  490. file named on the command line, and the filename doesn't already
  491. contain a period, @code{avram} will try to find a file having a similar
  492. name but with the default extension appended. The default extension given
  493. by this option takes precedence over the hard coded default extensions
  494. of @kbd{.fun} and @kbd{.avm}. At most one default extension can be supplied. This
  495. option is compatible with any other parameter mode option and
  496. compatible with any application.
  497. @item -d, --default-to-stdin
  498. @cindex @code{default-to-stdin} command line option
  499. @cindex standard input
  500. If no filename parameter appears on the command line (other than the
  501. name of the virtual code file), this option directs @code{avram} to read
  502. the contents of standard input as if it were specified as a command line
  503. parameter. (Standard input can also be specified explicitly as a
  504. dash. See @ref{Command Line Syntax}.) This option is compatible with any
  505. application and any other parameter mode option except @option{-m}.
  506. @item -m, --map-to-each-file
  507. @cindex @code{map-to-each-file} command line option
  508. Normally @code{avram} loads the entire contents of all files named on
  509. the command line into memory so as to evaluate the virtual machine
  510. code application on all of them together. This option can be used to
  511. save memory in the case of applications that operate on multiple files
  512. independently. It causes @code{avram} to load only one file at a time
  513. and to perform the relevant evaluation and output before loading the
  514. next one. Application specific options and standard input (if
  515. specified) are read only once and reused. This option is incompatible
  516. with @option{-d}, and not necessarily compatible with all applications,
  517. although some may work both with and without it.
  518. @item -i, --interactive
  519. @cindex @code{interactive} command line option
  520. @cindex interactive applications
  521. This option is used in the case of applications that interact with
  522. other programs through shell commands. An application that is meant to
  523. be invoked in this way requires this option and will not work without
  524. it, nor will applications that are not of this type work with it. This
  525. option is implied by @option{-t} and @option{-s}, and is compatible with any
  526. other parameter mode option.
  527. @item -s, --step
  528. @cindex @code{step} command line option
  529. This option is used in the case of applications that interact with
  530. other programs through shell commands, similarly to @option{-i}, and
  531. can substitute for it (see above). The option has the additional
  532. effect of causing shell commands issued by @code{avram} on behalf of
  533. the application to be written with their results to standard output,
  534. and to cause @code{avram} to pause after displaying each shell command
  535. until a key is pressed. This capability may be useful for debugging
  536. or auditing purposes but does not otherwise alter the effects of the
  537. application. This option is compatible with any other parameter mode
  538. option.
  539. @item -t, --trace
  540. @cindex @code{trace} command line option
  541. This option is used in the case of applications that interact with
  542. other programs through shell commands, but only by way of the
  543. @code{interact} combinator, for which it provides developers a means
  544. of low level debugging, particularly deadlock detection. When this
  545. option is selected, a verbose trace of all characters exchanged
  546. between the functional transducer and the external application are
  547. written to standard output, along with some additional control flow
  548. diagnostics. This option is compatible with any other parameter mode
  549. option.
  550. @item -p, --parameterized
  551. @cindex @code{parameterized} command line option
  552. Normally @code{avram} tries to guess whether to operate in filter mode
  553. or parameter mode based on the options used and the parameters. If
  554. there are no parameters and no options, it will default to filter
  555. mode, and try to read standard input. However, if this option is
  556. selected, it will use parameter mode (and therefore not try to read
  557. standard input unless required).
  558. @end table
  559. @node Command Line Syntax, Diagnostics, Parameter Mode Options, User Manual
  560. @section Command Line Syntax
  561. @cindex command line
  562. The command line parameters that follow the virtual code file name
  563. when @code{avram} is used in parameter mode (@ref{Parameter Mode}) are dependent on the
  564. specific application. However, all supported applications are
  565. constrained for implementation reasons to observe certain uniform
  566. conventions regarding their command line parameters, which are
  567. documented here to avoid needless duplication.
  568. @cindex shell
  569. @cindex file parameters
  570. @cindex input files
  571. The shell divides the command line into "arguments" separated by white
  572. space. Arguments containing white space or special characters used by
  573. the shell must be quoted or protected as usual. File names with wild
  574. cards in them are expanded by the shell before @code{avram} sees them.
  575. @code{avram} then extracts from the sequence of arguments a sequence of
  576. filenames and a sequence of options. Each option consists of a keyword and an
  577. optional parameter list. Filenames, keywords, and parameter lists are
  578. distinguished according to the following criteria.
  579. @enumerate
  580. @item
  581. An argument is treated as a keyword iff it meets these three
  582. conditions.
  583. @enumerate a
  584. @item
  585. It starts with a dash.
  586. @item
  587. It doesn't contain an equals sign.
  588. @item
  589. It doesn't consist solely of a dash.
  590. @end enumerate
  591. @item
  592. An argument is treated as a parameter list iff it meets these four
  593. conditions.
  594. @enumerate a
  595. @item
  596. It doesn't begin with a dash.
  597. @item
  598. It either begins with an equals sign or doesn't contain one.
  599. @item
  600. It immediately follows an argument beginning with a dash, not
  601. containing an equals sign and not consisting solely of a dash.
  602. @item
  603. At least one of the following is true.
  604. @enumerate
  605. @item
  606. It doesn't contain a period, tilde, or path separator.
  607. @cindex path separators
  608. @item
  609. It contains a comma.
  610. @item
  611. It can be interpreted as a C formatted floating point number.
  612. @end enumerate
  613. @end enumerate
  614. @item
  615. An argument is treated as an input file name iff it meets these four
  616. conditions.
  617. @enumerate a
  618. @item
  619. It doesn't begin with a dash.
  620. @item
  621. It doesn't contain an equals sign.
  622. @item
  623. It doesn't contain a comma.
  624. @item
  625. At least one of the following is true.
  626. @enumerate
  627. @item
  628. It contains a period, tilde, or path separator.
  629. @item
  630. It doesn't immediately follow an argument beginning with a dash, not
  631. consisting solely of a dash, and not containing an equals sign.
  632. @end enumerate
  633. @end enumerate
  634. @item
  635. If an argument contains an equals sign but doesn't begin with one,
  636. the part on the left of the first equals sign is treated as a
  637. keyword and the part on the right is treated as a parameter list.
  638. @item
  639. An argument consisting solely of a dash is taken to represent the
  640. standard input file.
  641. @item
  642. An argument not fitting any of the above classifications is an error.
  643. @end enumerate
  644. These conventions are needed for @code{avram} to detect input file names
  645. in a general, position independent way, so that it can preload the files
  646. on behalf of the application. Many standard Unix utilities follow these
  647. @cindex Unix
  648. conventions to a large extent, the exceptions being those that employ
  649. non-filename arguments without distinguishing syntax, and use positional
  650. or other ad hoc methods of command line interpretation. A drop-in
  651. replacement for such an application could nevertheless be implemented
  652. using @code{avram} with an appropriate wrapper script, similar to the
  653. approach recommended in @ref{Example Script}, but with suitable keywords
  654. inserted prior to the ambiguous arguments.
  655. @node Diagnostics, Security, Command Line Syntax, User Manual
  656. @section Diagnostics
  657. @cindex diagnostics
  658. @cindex error messages
  659. @cindex run time errors
  660. The means exists for virtual code applications to have run time error
  661. messages written to standard error on their behalf by
  662. @code{avram}. Any error messages not documented here originate with an
  663. application and should be documented by it.
  664. Most error messages originating from @code{avram} are prefaced by the
  665. application name (i.e., the name of the file containing the virtual
  666. machine code), but will be prefaced by @code{avram:} if the error is
  667. caused by a problem loading this file itself. Error messages originating
  668. from virtual code applications are the responsibility of their
  669. respective authors and might not be prefaced by the application name.
  670. The run time errors not specifically raised by the application can be
  671. classified as internal errors, i/o errors, overflow errors, file
  672. format errors, application programming errors, and configuration related
  673. errors.
  674. Some error messages include a code number. The number identifies
  675. the specific point in the source code where the condition was
  676. detected, for the benefit of the person maintaining it.
  677. @menu
  678. * Internal Errors::
  679. * i/o Errors::
  680. * Overflow Errors::
  681. * File Format Errors::
  682. * Application Programming Errors::
  683. * Configuration Related Errors::
  684. * Other Diagnostics and Warnings::
  685. @end menu
  686. @node Internal Errors, i/o Errors, Diagnostics, Diagnostics
  687. @subsection Internal Errors
  688. @cindex internal errors
  689. Internal errors should never occur unless the
  690. @code{avram} source code has been carelessly modified, except as noted
  691. in @ref{Bugs}. There are two kinds.
  692. @table @code
  693. @item @var{application-name}: virtual machine internal error (code @var{nn})
  694. Most internal errors would be reported by a message of this form
  695. if they were to occur. It indicates that some required invariant was
  696. not maintained. In such cases, the program terminates immediately, and
  697. any results already produced are suspect.
  698. @item @var{application-name}: @var{nn} unreclaimed @var{struct-names}
  699. A message of this form could be printed at the end of an otherwise successful
  700. run. @code{avram} maintains a count of the number of units allocated
  701. for various data structures, and checks that they are all reclaimed
  702. eventually as a safeguard against memory leaks. This message indicates
  703. that some memory remains unaccounted for.
  704. @end table
  705. @cindex bug reports
  706. @cindex email
  707. @cindex author
  708. If a repeatable internal error is discovered, please email a bug
  709. report and a small representative test case to
  710. @email{ursala-users@@freelists.org} or file an issue on the Avram
  711. github page. Include the version number of @code{avram}, which you can
  712. get by running @kbd{avram --version}.
  713. @node i/o Errors, Overflow Errors, Internal Errors, Diagnostics
  714. @subsection i/o Errors
  715. @cindex i/o errors
  716. These error messages are prefaced with the name of the
  717. application. A further explanation as to the
  718. @cindex @code{strerror}
  719. reason, obtained from the standard @code{strerror()} utility, is
  720. appended to the messages below if possible.
  721. @table @code
  722. @item @var{application-name}: can't read @var{filename}
  723. @cindex file names
  724. @cindex @code{can't read}
  725. @cindex environment
  726. @cindex @code{AVMINPUTS}
  727. A file was not able to be opened for reading, typically because it was
  728. not found or because the user does not have permission. The file name is
  729. displayed with special characters expanded but without any default
  730. extensions or search paths that may have been tried. If you think a file
  731. exists and should have been found, there may be a problem with your
  732. @env{AVMINPUTS} environment variable (@ref{Environment}).
  733. @item @var{application-name}: can't write @var{filename}
  734. @cindex @code{can't write}
  735. A file was not able to be opened for writing.
  736. @item @var{application-name}: can't write to @var{filename}
  737. A file was successfully opened for writing but became impossible to
  738. write thereafter.
  739. @item @var{application-name}: can't spawn @var{command}
  740. @cindex shell
  741. @cindex expect
  742. @cindex libexpect
  743. @cindex @code{can't spawn}
  744. @cindex @code{exp_popen}
  745. @cindex spawning processes
  746. An attempt to execute a shell command on behalf of an interactive
  747. application failed during the @code{exp_popen()} call to the
  748. @code{libexpect} library.
  749. @item @var{application-name}: can't close @var{filename}
  750. @cindex @code{can't close}
  751. A call to the standard C procedure @code{fclose()} failed due to
  752. unforeseen circumstances. The error is non-fatal but the file should be
  753. checked for missing data.
  754. @end table
  755. @node Overflow Errors, File Format Errors, i/o Errors, Diagnostics
  756. @subsection Overflow Errors
  757. These errors are reported by the application name prefacing one of the
  758. following messages, except as noted below.
  759. @cindex overflow
  760. @cindex counter overflow
  761. @cindex memory overflow
  762. @table @code
  763. @item @var{application-name}: counter overflow (code @var{nn})
  764. An overflow occurred in an unsigned long integer being used as a reference
  765. counter or something similar. This situation is very unlikely.
  766. @item @var{application-name}: memory overflow (code @var{nn})
  767. There wasn't enough memory to build an internal data structure. The
  768. most likely cause is an attempt to operate on input
  769. files that are too large. Standard remedies apply.
  770. @end table
  771. The memory overflow or counter overflow messages can also be reported
  772. without the application name preface or a code number. In these cases,
  773. they arise in the course of evaluating the function given by the
  774. application, rather than by loading the input files.
  775. A counter overflow in this case is possible if the application
  776. attempts to compute the size of a very large, shared structure using
  777. native integer arithmetic.
  778. @cindex @command{ulimit}
  779. Memory overflows are possible due to insufficient memory for a valid
  780. purpose, but may also occur due to a non-terminating recursion in the
  781. virtual machine code. To prevent thrashing or other bad effects from
  782. runaway code, the @command{ulimit} shell command is your friend.
  783. @node File Format Errors, Application Programming Errors, Overflow Errors, Diagnostics
  784. @subsection File Format Errors
  785. Certain application crashes result from an application not adhering
  786. to the required conventions about data and file formats, or because the
  787. application was invoked in the wrong mode (@ref{Modes of Operation}). These
  788. are the following.
  789. @table @code
  790. @item @var{application-name}: invalid text format (code @var{nn})
  791. @cindex @code{invalid text format}
  792. An application that was expected to return a string of characters to
  793. be written to a text file returned data that did not correspond to any
  794. valid character representation.
  795. @item @var{application-name}: null character in prompt
  796. An interactive application (invoked rightly or wrongly with @option{-i},
  797. @option{-t}, or @option{-s}) is required to exchange strings of non-null
  798. characters internally with @code{avram}, and used a null.
  799. @item @var{application-name}: invalid file name (code @var{nn})
  800. The data structure representing a file obtained from an application
  801. has a name consisting of something other than character strings. This
  802. error could be the result of a filter mode application (@ref{Filter
  803. Mode}) being invoked in parameter mode.
  804. @ifinfo
  805. @*
  806. @end ifinfo
  807. (@ref{Parameter Mode})
  808. @item @var{application-name}: null character in file name
  809. @cindex @code{null character in file name}
  810. Similar to the above errors.
  811. @item @var{application-name}: bad character in file name
  812. @cindex @code{bad character in file name}
  813. Slashes, backslashes, and unprintable characters other than spaces are
  814. also prohibited in file names.
  815. @item @var{application-name}: invalid output preamble format
  816. @cindex @code{invalid output preamble format}
  817. According the format used by @code{avram} for data files, a data file
  818. may contain an optional text portion, known as the preamble. This
  819. error occurs when a data file obtained from an application can not be
  820. written because the preamble is something other than a list of
  821. character strings.
  822. @item @var{application-name}: invalid file specification
  823. @cindex @code{invalid file specification}
  824. This error occurs in situations where the data structure for a file
  825. obtained by evaluating the application is too broken to permit any
  826. more specific diagnosis.
  827. @item avram: invalid raw file format in @var{application-name}
  828. @cindex @code{invalid raw file format}
  829. The file containing the virtual machine code was not able to be
  830. loaded, because the code was not in a recognizable format. Either the
  831. file has become corrupted, the compiler that generated it has a
  832. bug in it, or the wrong file was used as a virtual code file.
  833. @end table
  834. @node Application Programming Errors, Configuration Related Errors, File Format Errors, Diagnostics
  835. @subsection Application Programming Errors
  836. A further class of application crashes results from miscellaneous bugs
  837. in the application. These require the application to be debugged and
  838. have no user level explanation or workaround, but are listed here for
  839. reference. These messages are not normally prefaced by the application
  840. name when reported unless the application elects to do so, except for
  841. the @code{invalid profile identifier} message.
  842. @itemize @bullet
  843. @item @code{invalid recursion}
  844. @cindex @code{invalid recursion}
  845. @item @code{invalid comparison}
  846. @cindex @code{invalid comparison}
  847. @item @code{invalid deconstruction}
  848. @cindex @code{invalid deconstruction}
  849. @item @code{invalid transpose}
  850. @cindex @code{invalid transpose}
  851. @item @code{invalid membership}
  852. @cindex @code{invalid membership}
  853. @item @code{invalid distribution}
  854. @cindex @code{invalid distribution}
  855. @item @code{invalid concatenation}
  856. @cindex @code{invalid concatenation}
  857. @item @code{invalid assignment}
  858. @cindex @code{invalid assignment}
  859. @item @code{unrecognized combinator (code @var{nn})}
  860. @cindex @code{unrecognized combinator}
  861. @item @code{@var{application-name}: invalid profile identifier}
  862. @cindex @code{invalid profile identifier}
  863. @item @code{unsupported hook}
  864. @cindex @code{unsupported hook}
  865. @end itemize
  866. @node Configuration Related Errors, Other Diagnostics and Warnings, Application Programming Errors, Diagnostics
  867. @subsection Configuration Related Errors
  868. The source code distribution of @code{avram} incorporates a flexible
  869. configuration script allowing it to be installed on a variety of
  870. platforms. Not all platforms allow support for all features. It is also
  871. anticipated that new features may be added to @code{avram} from time to
  872. time. Some problems may therefore occur due to features not being
  873. supported at your site for either of these reasons. The following error
  874. messages are relevant to these situations.
  875. @table @code
  876. @item unsupported hook
  877. @cindex @code{unsupported hook}
  878. If it's not simply due to an application programming error
  879. (@ref{Application Programming Errors}) this message may be the result of
  880. trying to use an application that requires a newer version of
  881. @code{avram} than the one installed, even though applications should
  882. avoid this problem by checking the version number at run time. If this
  883. is the reason, the solution would be to install the latest version.
  884. @item @var{application-name}: I need avram linked with @var{foo}, @var{bar} and @var{baz}.
  885. @cindex @code{I need avram linked with}
  886. A message of the this form indicates that a new installation may be
  887. needed. At this writing (11/11/1), @code{avram} may report this message
  888. with respect to @code{libexpect5.32}, @code{tcl8.3}, and @code{libutil}
  889. if any of the @option{-i}, @option{-t}, or @option{-s} options is used on a
  890. system where not all of these libraries were detected when @code{avram}
  891. was installed from a source distribution. (See @ref{Parameter Mode Options}.)
  892. Because @code{avram} is useful even without interactive applications,
  893. these libraries are not considered absolute prerequisites by the
  894. configuration script.
  895. @item avram: can't emulate version @var{version}
  896. @cindex @code{can't emulate version}
  897. @cindex @code{emulation} command line option
  898. @cindex versions
  899. @cindex backward compatibility
  900. The @option{--emulation=@var{version}} option obviously won't work if
  901. the requested version is newer than the installed version, or if it is
  902. not a valid version number (@ref{General Options}). When that happens,
  903. this message is printed instead and @code{avram} terminates.
  904. @item avram: multiple version specifications
  905. @cindex @code{multiple version specifications}
  906. The @option{--emulation=@var{version}} option can be used at most once
  907. on a command line. This message is printed if it is used more than
  908. once. If you only typed it once and got this message, check your aliases
  909. and wrapper scripts before reporting a bug.
  910. @item avram: unrecognized option: @var{option-name}
  911. @cindex @code{unrecognized option}
  912. may mean that a command line option has been misspelled, or may be another
  913. sign of an obsolete version of @code{avram}. This message will be followed
  914. by a usage summary similar to that of the @option{--help} option.
  915. (@ref{General Options}).
  916. @item @var{application-name}: warning: search paths not supported
  917. @cindex search paths
  918. @cindex paths
  919. @cindex environment
  920. @cindex @code{AVMINPUTS}
  921. @cindex @code{search paths not supported}
  922. @cindex @file{argz.h}
  923. If the @file{argz.h} header file was not detected during configuration,
  924. @code{avram} will not be able to support search paths in the
  925. @env{AVMINPUTS} environment variable (@ref{Environment}). This message
  926. is a warning that the environment variable is being ignored. If the
  927. warning is followed by an i/o error
  928. @ifinfo
  929. @*
  930. @end ifinfo
  931. (@ref{i/o Errors}), the latter may be due to a file being in a path that
  932. was not searched for this reason. A workaround is to specify the full
  933. path names of all input files outside the current working directory. If
  934. you don't need search paths, you can get rid of this message by
  935. undefining @env{AVMINPUTS}.
  936. @end table
  937. @node Other Diagnostics and Warnings, , Configuration Related Errors, Diagnostics
  938. @subsection Other Diagnostics and Warnings
  939. @table @asis
  940. @item @code{avram: multiple -.EXT options; all but last ignored}
  941. @cindex @code{multiple -.EXT options}
  942. @cindex extensions
  943. @cindex file extensions
  944. @cindex extensions
  945. @cindex file name extensions
  946. @cindex file name suffixes
  947. This message is written when more than one default extension is given as
  948. a command line parameter. At most one default extension is allowed. If
  949. more than one is given, only the last one is used. The error is
  950. non-fatal and @code{avram} will try to continue. If you need more
  951. than one default extension, consider using the hard coded default
  952. extensions of @file{.fun} and @file{.avm}, or hacking the shell script
  953. in which the @code{avram} command line appears.
  954. @item @code{@var{application name}: empty operator}
  955. This message probably means that the virtual code file is corrupt or
  956. invalid.
  957. @item usage summary
  958. @cindex @code{help} command line option
  959. For any errors in usage not covered by other diagnostics, such as
  960. incompatible combinations of options, @code{avram} prints a message to
  961. standard error giving a brief summary of options, similar to the output
  962. from @kbd{avram --help}. (See @ref{General Options}.)
  963. @end table
  964. @node Security, Example Script, Diagnostics, User Manual
  965. @section Security
  966. @cindex security
  967. A few obvious security considerations are relevant to running untrusted
  968. virtual code applications. These points are only as reliable as the
  969. assumption that the @code{avram} executable has not been modified to the
  970. contrary.
  971. @itemize @bullet
  972. @cindex filter mode
  973. @item The applications with the best protection from malicious code are
  974. those that run in filter mode, because they have no access to any
  975. information not presented to them in standard input, nor the ability to
  976. affect anything other than the contents of standard output (provided that
  977. the @code{--jail} command line option is used). The worst
  978. they can do is use up a lot of memory, which can be prevented with the
  979. @command{ulimit} command. Unfortunately, not all applications are usable
  980. in this mode.
  981. @item Parameter mode applications that do not involve the @option{-i},
  982. @cindex parameter mode
  983. @cindex standard input
  984. @option{-t} or @option{-s} options are almost as safe (also assuming
  985. @code{--jail}). They have (read-only) access to environment variables, and to the files that are
  986. indicated explicitly on the command line. If standard input is one of
  987. the files (as indicated by the use of @code{-} as a parameter), the
  988. virtual code application may infer the current date and time. However,
  989. a parameter mode application may write any file that the user has
  990. permission to write. The @option{--ask-to-overwrite} option should be
  991. used for better security, or at least the @option{--quiet} option should
  992. not be used. The virtual code can neither override nor detect the use
  993. of these options.
  994. @item Interactive parameter mode applications (those that use either the
  995. @cindex interactive applications
  996. @option{-i}, @option{-t} or @option{-s} options) are the least secure
  997. because they can execute arbitrary shell commands on behalf of the
  998. user. This statement also applies to filter mode and parameter mode
  999. applications where the @option{--jail} option is not used. Use of
  1000. @option{--step} is preferable to @option{-i} for making an audit
  1001. trail of all commands executed, but the application could probably
  1002. subvert it. The @option{--step} option may be slightly better because
  1003. it can allow the user to inspect each command and interrupt it if
  1004. appropriate. However, in most cases a command will not be displayed
  1005. until it is already executed. Commands executed by non-interactive
  1006. applications normally will display no output to that effect. A
  1007. @command{chroot} environment may be the only secure way of running
  1008. untrusted interactive applications.
  1009. @end itemize
  1010. @node Example Script, Files, Security, User Manual
  1011. @section Example Script
  1012. @cindex script
  1013. @cindex shell script
  1014. It is recommended that the application developer (or the compiler)
  1015. package virtual machine code applications as shell scripts with the
  1016. @code{avram} command line embedded in them. This style relieves the user
  1017. of the need to remember the appropriate virtual machine options for
  1018. invoking the application, which are always the same for a given
  1019. application, or even to be aware of the virtual machine at all.
  1020. @cindex @code{cat}
  1021. @cindex @code{default-to-stdin} command line option
  1022. Here is a script that performs a similar operation to the standard
  1023. @cindex Unix
  1024. Unix @command{cat} utility.
  1025. @example
  1026. #!/bin/sh
  1027. #\
  1028. exec avram --force-text-input --default-to-stdin "$0" "$@@"
  1029. sKYQNTP\
  1030. @end example
  1031. @noindent
  1032. That is, it copies the contents of a file whose
  1033. name is given on the command line to standard output, or copies
  1034. standard input to standard output if no file name is given. This
  1035. script can be marked executable
  1036. @cindex executable files
  1037. (with @command{chmod}) and run by any user
  1038. @cindex @code{chmod}
  1039. @cindex paths
  1040. with the directory of the @code{avram} executable in his or her
  1041. @code{PATH} environment variable, even if @code{avram} had to be
  1042. installed in a non-standard directory such as
  1043. @cindex non-standard installation
  1044. @file{~/bin}.
  1045. The idea for this script is blatantly lifted from the @command{wish}
  1046. @cindex @code{wish}
  1047. manpage. The first line of the script invokes a shell to process
  1048. what follows. The shell treats the second line as a comment and
  1049. ignores it. Based on the third line, the shell invokes @code{avram}
  1050. with the indicated options, the script itself as the next argument, and
  1051. whatever command line parameters were initially supplied by the user
  1052. as the remaining arguments. The rest of the script after
  1053. that line is never processed by the shell.
  1054. When @code{avram} attempts to load the shell script as a virtual
  1055. machine code file, which happens as a result of it being executed by
  1056. the shell, it treats the first line as a comment and ignores it. It
  1057. also treats the second line as a comment, but takes heed of the
  1058. trailing backslash, which is interpreted as a comment continuation
  1059. character. It therefore also treats the third line as a comment and
  1060. ignores it. Starting with the fourth line, it reads the virtual code,
  1061. which is in a binary data format encoded with printable characters,
  1062. and evaluates it.
  1063. @node Files, Environment, Example Script, User Manual
  1064. @section Files
  1065. @table @code
  1066. @item ./profile.txt
  1067. @cindex @file{profile.txt}
  1068. This file is written automatically by @code{avram} on behalf of
  1069. applications that include profile annotations. It lists the number of
  1070. invocations for each annotated part of the application, the total
  1071. amount of time spent on it (in relative units), the average amount of
  1072. time for each invocation, and the percentage of time relative to the
  1073. remainder of the application. The exact format is undocumented and
  1074. subject to change.
  1075. @end table
  1076. @node Environment, Bugs, Files, User Manual
  1077. @section Environment
  1078. @cindex environment
  1079. @cindex @code{AVMINPUTS}
  1080. @cindex paths
  1081. An environment variable @env{AVMINPUTS} can be made to store a list of
  1082. directories (using the @command{set} or @command{export} commands) that
  1083. @code{avram} will search for input files. The directories should be
  1084. separated by colons, similarly to the @env{PATH} environment variable.
  1085. @cindex search paths
  1086. The search paths in @env{AVMINPUTS} apply only to the names of input
  1087. files given on the command line (@ref{Command Line Syntax}) when
  1088. @code{avram} is invoked in parameter mode (@ref{Parameter Mode}). They
  1089. do not apply to the name of the virtual code file, which is always
  1090. assumed to be either absolute or relative to the current working
  1091. directory (this assumption being preferable in the case of a script like
  1092. that of @ref{Example Script}).
  1093. @cindex shell script
  1094. Starting in the first directory in the list of @env{AVMINPUTS},
  1095. @code{avram} searches for a file exactly as its name appears on
  1096. the command line (subject to the expansion of special characters
  1097. by the shell). If it is not found and the name does not contain a
  1098. period, but a command line option of @option{-.EXT} has been used,
  1099. @code{avram} will then search for a file with that name combined with
  1100. the extension @code{.EXT}. If @option{-.EXT} has not been used or if no
  1101. @cindex @code{EXT} command line option
  1102. matching file is found with it, @code{avram} tries the extensions of
  1103. @kbd{.avm} and @kbd{.fun} in that order, provided the given file name
  1104. contained no periods. If no match is found for any of those cases,
  1105. @code{avram} proceeds to search the next directory in the list obtained
  1106. from @env{AVMINPUTS}, and so on. It stops searching when the first
  1107. match is found. For subsequent input files, the search begins again at
  1108. the first directory.
  1109. If @env{AVMINPUTS} is defined, the current working directory is not
  1110. searched for input files unless it is listed. If it is empty or not
  1111. @cindex search paths
  1112. defined, a default list of search paths is used, currently
  1113. @example
  1114. .:/usr/local/lib/avm:/usr/lib/avm:/lib/avm:/opt/avm:/opt/lib/avm\
  1115. :/usr/local/share/avm:/usr/share/avm:/share/avm:/opt/avm:/opt/share/avm
  1116. @end example
  1117. @noindent
  1118. These paths are defined in @code{avram.c} and can be changed
  1119. by recompiling it.
  1120. @node Bugs, , Environment, User Manual
  1121. @section Bugs
  1122. @cindex internal errors
  1123. @cindex bugs
  1124. @cindex exceptions
  1125. There are no known bugs outstanding, except for any that may be
  1126. inherent in the external library functions. However, @code{avram} has
  1127. been used most extensively on GNU/Linux systems, and the prospect
  1128. of portability issues with new or lesser used features on other
  1129. systems can't be excluded.
  1130. Though not observed in practice, it's theoretically possible to blow
  1131. the stack by passing enough functions as arguments to library
  1132. functions that pass more functions to library functions (e.g., by
  1133. using nested calls to the gsl integration functions meant for a single
  1134. variable to evaluate a very high dimensional multiple integral). In
  1135. all other cases only dynamic heap storage or a constant amount of
  1136. stack space is used. In particular, this issue is @emph{not} relevant
  1137. to virtual code applications that don't use external libraries, or
  1138. that don't pass functions to them as arguments.
  1139. @code{avram} is designed to recover gracefully from memory overflows
  1140. by always checking for @code{NULL} results from @code{malloc()} or
  1141. otherwise trapping functions that allocate memory. In the event of an
  1142. overflow, it conveys an appropriate error message to the virtual code
  1143. application to be handled by the usual exception handling
  1144. mechanisms. However, there is currently no way for a virtual code
  1145. application to detect in advance whether sufficient memory is
  1146. available, nor for it to resume normal operation once an exception
  1147. occurs. Furthermore, it has been observed on some systems including
  1148. Irix and 2.4 series Linux kernels that the @code{avram} process is
  1149. killed automatically for attempting to allocate too much memory rather
  1150. than given the chance to recover.
  1151. Please send bug reports to @email{ursala-users@@freelists.org} or file
  1152. an issue on the Avram github page.
  1153. @node Virtual Machine Specification, Library Reference, User Manual, Top
  1154. @chapter Virtual Machine Specification
  1155. This chapter contains a description of the virtual machine implemented
  1156. by @code{avram}, from the point of view of a person wishing to write a
  1157. compiler that generates code for it. Before reading this chapter,
  1158. readers should at least skim @ref{User Manual} in order to see the big
  1159. picture. Topics covered in this chapter include data representations,
  1160. virtual code semantics, and file formats. A toy programming language is
  1161. introduced for illustrative purposes. The sections in this chapter might
  1162. not make sense if read out of order the first time through.
  1163. @ifinfo
  1164. The last section, @ref{Virtual Code Semantics}, contains many equations
  1165. that may be difficult to read in the info or html renderings. The
  1166. printed version is recommended for anyone who really wants to comprehend
  1167. this material.
  1168. @end ifinfo
  1169. @menu
  1170. * Raw Material::
  1171. * Concrete Syntax::
  1172. * File Format::
  1173. * Representation of Numeric and Textual Data::
  1174. * Filter Mode Interface::
  1175. * Parameter Mode Interface::
  1176. * Virtual Code Semantics::
  1177. @end menu
  1178. @node Raw Material, Concrete Syntax, Virtual Machine Specification, Virtual Machine Specification
  1179. @section Raw Material
  1180. The purpose of this section is to instill some basic concepts about the
  1181. way information is stored or communicated by the virtual machine, which
  1182. may be necessary for an understanding of subsequent sections.
  1183. The virtual machine represents both programs and data as members of a
  1184. semantic domain that is straightforward to describe. Lisp users and
  1185. functional programmers may recognize familiar concepts of atoms and
  1186. @cindex lists
  1187. lists in this description. However, these terms are avoided for the
  1188. moment, in order to keep this presentation self contained and to prevent
  1189. knowledgeable readers from inferring any unintended meanings.
  1190. As a rule, it is preferable to avoid overspecifying any theoretical
  1191. artifact. In this spirit, the set of entities with which the virtual
  1192. machine is concerned can be defined purely in terms of the properties we
  1193. need it to have.
  1194. @table @emph
  1195. @item A distinguished element
  1196. A particular element of the set is designated, arbitrarily or otherwise,
  1197. as a distinguished element. Given any element of the set, it is
  1198. always possible to decide whether or not it is the distinguished
  1199. element. The set is non-empty and such an element exists.
  1200. @item A binary operator
  1201. A map from pairs of elements of the set to elements of the set exists
  1202. and meets these conditions.
  1203. @itemize @bullet
  1204. @item It associates a @emph{unique} element of the set with any given
  1205. ordered pair of elements from the set.
  1206. @item It does not associate the distinguished element with any pair of elements.
  1207. @end itemize
  1208. @end table
  1209. For the sake of concreteness, an additional constraint is needed:
  1210. @emph{the set has no proper subset satisfying the above conditions}. Any
  1211. number of constructions remain within these criteria, but there is no
  1212. need to restrict them further, because they are all equivalent for our
  1213. purposes.
  1214. To see that these properties provide all the structure we need for
  1215. general purpose computation, we may suppose some given set @code{S} and
  1216. an operator @code{cons} having them are fixed, and infer the following
  1217. points.
  1218. @itemize @bullet
  1219. @item @code{S} contains at least one element, the distinguished
  1220. element. Call it @code{nil}.
  1221. @cindex @code{nil}
  1222. @item The pair @code{(nil,nil)} is a pair of
  1223. elements of @code{S}, so there must be an element of @code{S} that
  1224. @code{cons} associates with it. We can denote this element
  1225. @code{cons(nil,nil)}.
  1226. @cindex @code{cons}
  1227. @item As no pair of elements is associated with the
  1228. distinguished element, @code{cons(nil,nil)} must differ from @code{nil}, so
  1229. @code{S} contains at least two distinct elements.
  1230. @item The pair @code{(nil,cons(nil,nil))} therefore differs from @code{(nil,nil)},
  1231. but because it is yet another pair of elements from @code{S}, there
  1232. must be an element associated with it by the operator. We can denote
  1233. this element as @code{cons(nil,cons(nil,nil))}.
  1234. @item Inasmuch as the operator
  1235. associates every pair of elements with a @emph{unique} element,
  1236. @code{cons(nil,cons(nil,nil))} must differ from the element associated
  1237. with any other pair of elements, so it must differ from
  1238. @code{cons(nil,nil)}, and we conclude that @code{nil},
  1239. @code{cons(nil,nil)} and @code{cons(nil,cons(nil,nil))} constitute three
  1240. distinct elements of the set @code{S}.
  1241. @item By defining @code{cons(cons(nil,nil),nil)}
  1242. and @code{cons(cons(nil,nil),cons(nil,nil))} analogously and following a
  1243. similar line of reasoning, one may establish the existence of two more
  1244. distinct elements of @code{S}.
  1245. @end itemize
  1246. It is not difficult to see that an argument in more general terms could
  1247. show that the inclusion of infinitely many elements in @code{S} is
  1248. mandated by the properties of the @code{cons} operator. Furthermore,
  1249. every element of @code{S} other than @code{nil} owes its inclusion to
  1250. being associated with some other pair of elements by @code{cons},
  1251. because if it were not, its exclusion would permit a proper subset of
  1252. @code{S} to meet all of the above conditions. We can conclude that
  1253. @code{S} contains exactly @code{nil} and the countable infinitude of
  1254. elements of the form @code{cons(x,y)}, where @code{x} and @code{y} are
  1255. either @code{nil} or something of the form @code{cons(@dots{})} themselves.
  1256. Some specific examples of sets and operators that have the required
  1257. properties are as follows.
  1258. @itemize @bullet
  1259. @item the set of natural numbers, with @code{0} as the distinguished element,
  1260. and the @code{cons} operator defined by @code{cons(@var{x},@var{y}) =
  1261. ((@var{x}+@var{y})(@var{x}+@var{y}+1))/2 + @var{y} + 1}
  1262. @item a set of balanced strings of parentheses, with @code{()} as the
  1263. distinguished element, and @code{cons} defined as string concatenation
  1264. followed by enclosure in parentheses
  1265. @item a set of ordered binary trees, with the empty tree as the distinguished
  1266. element, and the @code{cons} operator as that which takes an ordered
  1267. pair of trees to the tree having them as its descendents
  1268. @item a set containing only its own Cartesian product and an arbitrary
  1269. but fixed element @code{nil}, with @code{cons} being the identity
  1270. function
  1271. @end itemize
  1272. Each of these models may suggest a different implementation, some of which
  1273. are more practical than others. The remainder of this document is
  1274. phrased somewhat imprecisely in terms of a combination of the latter
  1275. two. The nature of the set in question is not considered further, and
  1276. elements of the set are described as ``trees'' or ``lists''. The
  1277. @cindex trees
  1278. @cindex lists
  1279. distinguished element is denoted by @code{nil} and the operator by
  1280. @code{cons}. Where no ambiguity results, @code{cons(x,y)} may be written
  1281. simply as @code{(x,y)}. These terms should not be seen as constraints
  1282. on the implementation.
  1283. @node Concrete Syntax, File Format, Raw Material, Virtual Machine Specification
  1284. @section Concrete Syntax
  1285. The previous section has developed a basic vocabulary for statements
  1286. such as ``the virtual machine code for the identity function is
  1287. @cindex identity function
  1288. @code{(nil,(nil,nil))}'', which are elaborated extensively in the
  1289. subsequent sections on code and data formats. However, a description in
  1290. this style would be inadequate without an explanation of how such an
  1291. entity as @code{(nil,(nil,nil))} is communicated to @code{avram} in a
  1292. virtual machine code file. The purpose of this section is to fill the
  1293. gap by explaining exactly how any given tree would be transformed to its
  1294. concrete representation.
  1295. The syntax is based on a conversion of the trees to bit strings,
  1296. @cindex bit strings
  1297. followed by grouping the bits into blocks of six, which are then encoded
  1298. by printable characters. Although anyone is free to modify @code{avram},
  1299. it is recommended that the concrete syntax described here be maintained
  1300. for the sake of portability of virtual machine code applications.
  1301. Building a tree by reading the data from a file requires a more
  1302. difficult algorithm than the one presented in this section, and is not
  1303. considered because it's not strictly necessary for a
  1304. compiler. Procedures for both reading and writing are available to C and
  1305. C++ users as part of the @code{avram} library, and are also easily
  1306. invoked on the virtual code level.
  1307. @menu
  1308. * Bit String Encoding::
  1309. * Blocking::
  1310. @end menu
  1311. @node Bit String Encoding, Blocking, Concrete Syntax, Concrete Syntax
  1312. @subsection Bit String Encoding
  1313. The conversion from trees to bit strings might have been done in several
  1314. @cindex trees
  1315. ways, perhaps the most obvious being based on a preorder traversal with
  1316. each vertex printed as it is traversed. By this method, the entire
  1317. encoding of the left descendent would precede that of the right in the
  1318. bit string. This alternative is therefore rejected because it imposes
  1319. unnecessary serialization on communication.
  1320. It is preferable for the encodings of both descendents of a tree to be
  1321. interleaved to allow concurrent transmission. Although there is
  1322. presently no distributed implementation of the virtual machine and hence
  1323. @cindex distributed implementation
  1324. none that takes advantage of this possibility, it is better to plan
  1325. ahead than to be faced with backward compatibility problems later.
  1326. The preferred algorithm for encoding a tree as a bit string employs a
  1327. queue. The queue contains trees and allows them to be processed in a
  1328. @cindex queues
  1329. first-in first-out order. Intuitively, the algorithm works by traversing
  1330. @cindex printing algorithm
  1331. the tree in level order. To print a tree @code{T} as a string of
  1332. @code{1}s and @code{0}s, it performs the following steps.
  1333. @display
  1334. Initialize the queue to contain only @code{T}
  1335. while the queue is not empty do
  1336. if the front element of the queue is @code{nil} then
  1337. print @code{0}
  1338. else if the front element of the queue is of the form @code{cons(x,y)} then
  1339. print @code{1}
  1340. append @code{x} to the back of the queue
  1341. append @code{y} to the back of the queue
  1342. end if
  1343. remove the front element of the queue
  1344. end while
  1345. @end display
  1346. This algorithm presupposes that any given tree
  1347. @cindex deconstruction
  1348. @code{cons(x,y)} can be ``deconstructed'' to obtain @code{x} and
  1349. @code{y}. The computability of such an operation is assured in theory by
  1350. the uniqueness property of the @code{cons} operator, regardless of the
  1351. representation chosen. If the trees are implemented with pointers in the
  1352. obvious way, their deconstruction is a trivial constant time operation.
  1353. As an example, running the following tree through the above algorithm
  1354. results in the bit string @code{111111101011110010001001100010100010100100100}.
  1355. @example
  1356. cons(
  1357. cons(
  1358. cons(nil,cons(nil,cons(nil,nil))),
  1359. cons(nil,cons(nil,nil))),
  1360. cons(
  1361. cons(
  1362. cons(nil,cons(nil,cons(nil,cons(nil,nil)))),
  1363. cons(nil,nil)),
  1364. cons(
  1365. cons(
  1366. cons(nil,cons(nil,cons(cons(nil,cons(nil,nil)),nil))),
  1367. cons(nil,nil)),
  1368. nil)))
  1369. @end example
  1370. @node Blocking, , Bit String Encoding, Concrete Syntax
  1371. @subsection Blocking
  1372. After the bit string is obtained as described above, it is grouped into
  1373. blocks of six. Continuing with the example, the string
  1374. @example
  1375. 111111101011110010001001100010100010100100100
  1376. @end example
  1377. @noindent
  1378. would be grouped as
  1379. @example
  1380. 111111 101011 110010 001001 100010 100010 100100 100
  1381. @end example
  1382. @noindent
  1383. Because the number of bits isn't a multiple of six, the last group has to
  1384. be padded with zeros, to give
  1385. @example
  1386. 111111 101011 110010 001001 100010 100010 100100 100000
  1387. @end example
  1388. @noindent
  1389. Each of these six bit substrings is then treated as a binary number,
  1390. with the most significant bit on the left. The numbers expressed in
  1391. decimal are
  1392. @example
  1393. 63 43 50 9 34 34 36 32
  1394. @end example
  1395. @noindent
  1396. @cindex character codes
  1397. The character codes for the characters to be written are obtained by
  1398. adding sixty to each of these numbers, so as to ensure that they will be
  1399. printable characters. The resulting character codes are
  1400. @example
  1401. 123 103 110 69 94 94 96 92
  1402. @end example
  1403. @noindent
  1404. which implies that the tree in the example could be written to a file as
  1405. @code{@{gnE^^`\}.
  1406. @node File Format, Representation of Numeric and Textual Data, Concrete Syntax, Virtual Machine Specification
  1407. @section File Format
  1408. @cindex file format
  1409. A virtual code file consists of an optional text preamble, followed by
  1410. the concrete representation for a tree. The latter uses the
  1411. syntax described in the previous section. The purpose of this section is
  1412. to specify the remaining details of the file format.
  1413. The format for virtual code files may also be used for other purposes
  1414. by virtual code applications, as it is automatically detected and parsed
  1415. by @code{avram} when used in an input file, and can be automatically
  1416. written to output files at the discretion of the application.
  1417. Other than virtual code files, input files not conforming to this format
  1418. are not an error as far as @code{avram} is concerned, because they are
  1419. @cindex text files
  1420. assumed to be text files. Applications can detect in virtual code
  1421. the assumption that is made and report an error if appropriate.
  1422. Although the data file format includes no checksums or other explicit
  1423. @cindex checksums
  1424. methods of error detection, the concrete syntax itself provides a
  1425. good measure of protection against undetected errors. The probability is
  1426. vanishingly small that a random alteration to any valid encoding leaves
  1427. it intact, because every bit in the sequence either mandates or
  1428. prohibits the occurrence of two more bits somewhere after it. Errors in
  1429. different parts of the file would have to be consistent with one another
  1430. to go unnoticed.
  1431. @menu
  1432. * Preamble Section::
  1433. * Data Section::
  1434. @end menu
  1435. @node Preamble Section, Data Section, File Format, File Format
  1436. @subsection Preamble Section
  1437. @cindex preamble
  1438. @itemize @bullet
  1439. @item A file may contain at most one preamble.
  1440. @item The preamble, if any, is a consecutive sequence of lines beginning
  1441. with the first line in the file.
  1442. @item The first line of the preamble must begin with a hash (@code{#})
  1443. character.
  1444. @item Subsequent lines of the preamble must either begin with a hash, or
  1445. immediately follow a line that ends with a backslash (@code{\})
  1446. character (or both).
  1447. @end itemize
  1448. @node Data Section, , Preamble Section, File Format
  1449. @subsection Data Section
  1450. @itemize @bullet
  1451. @item The data or virtual code section of the file begins on the first
  1452. line of the file that isn't part of the preamble.
  1453. @item The data section may not contain any hashes, white space, or other
  1454. extraneous characters other than line breaks.
  1455. @item If line breaks are ignored, the data section contains a sequence
  1456. of characters expressing a single tree in the concrete syntax described
  1457. in @ref{Concrete Syntax}.
  1458. @end itemize
  1459. @node Representation of Numeric and Textual Data, Filter Mode Interface, File Format, Virtual Machine Specification
  1460. @section Representation of Numeric and Textual Data
  1461. As noted already, virtual code applications are specified by functions
  1462. operating on elements of a set having the properties described in
  1463. @ref{Raw Material}, which are convenient to envision as ordered binary trees or
  1464. @cindex trees
  1465. @cindex @code{nil}
  1466. pairs of @code{nil}. However, virtual code applications normally deal
  1467. with numeric or textual data, for example when they refer to the
  1468. contents of a text file. It is therefore necessary for the application
  1469. and the virtual machine emulator to agree on a way of describing textual
  1470. or numeric data with these trees.
  1471. The purpose of this section is to explain the basic data structures used
  1472. in the exchange of information between @code{avram} and a virtual code
  1473. application. For example, an explanation is needed for statements like
  1474. ``an application invoked with the @option{--baz} option is expected to
  1475. return a pair @code{(@var{foo},@var{bar})}, where @code{@var{foo}} is a
  1476. @cindex strings
  1477. @cindex character strings
  1478. @cindex lists
  1479. list of character strings @dots{}'', that are made subsequently in this
  1480. document. Such statements should be understood as referring to the trees
  1481. representing the pairs, lists, character strings, etc., according to the
  1482. conventions explained below.
  1483. @table @emph
  1484. @item Characters
  1485. @cindex character codes
  1486. An arbitrarily chosen set of 256 trees is used to represent the
  1487. character set. They are listed in @ref{Character Table}. For example,
  1488. the letter @code{A} is represented by
  1489. @code{(nil,(((nil,(nil,(nil,nil))),nil),(nil,nil)))}. That means that
  1490. when an application wants the letter @code{A} written to a text file, it
  1491. returns something with this tree in it.
  1492. @item Booleans
  1493. @cindex booleans
  1494. The value of @code{false} is represented by @code{nil}, and the value of
  1495. @code{true} is represented by @code{(nil,nil)}.
  1496. @item Pairs
  1497. @cindex pairs
  1498. Given any two items of data @var{x1} and @var{x2}, having the respective
  1499. representations @var{r1} and @var{r2}, the pair @code{(@var{x1},@var{x2})} has the
  1500. representation @code{cons(@var{r1},@var{r2})}.
  1501. @item Lists
  1502. @cindex lists
  1503. A list of the items @var{x1}, @var{x2} @dots{} @var{xn} with respective
  1504. representations @var{r1} through @var{rn} is represented by the tree
  1505. @code{cons(@var{r1},cons(@var{r2}@dots{}cons(@var{rn},nil)@dots{}))}. In other words,
  1506. lists are represented as pairs whose left sides are the heads and whose
  1507. right sides are the tails. The empty list is identified with
  1508. @code{nil}. Lists of arbitrary finite length can be accommodated.
  1509. @item Naturals
  1510. @cindex naturals
  1511. A number of the form @code{@var{b0} + 2@var{b1} + 4@var{b2} + @dots{} +
  1512. 2^n @var{bn}}, where each @code{@var{b}i} is @code{0} or @code{1}, is
  1513. represented by a tree of the form
  1514. @code{cons(@var{t0},cons(@var{t1}@dots{}cons(@var{tn},nil)@dots{}))}
  1515. where each @code{@var{t}i} is @code{nil} if the corresponding
  1516. @code{@var{b}i} is @code{0}, and @code{(nil,nil)} otherwise. Note that
  1517. the numbers @code{@var{b}i} are exactly the bits written in the binary
  1518. expansion of the number, with @code{@var{b0}} being the least significant
  1519. bit.
  1520. @item Strings
  1521. @cindex strings
  1522. @cindex character strings
  1523. are represented as lists of characters.
  1524. @end table
  1525. @cindex types
  1526. @code{avram} imposes no more of a ``type discipline'' than necessary to
  1527. a workable interface between it and an application. This selection of
  1528. types and constructors should not be seen as constraining what a
  1529. compiler writer may wish to have in a source language.
  1530. @node Filter Mode Interface, Parameter Mode Interface, Representation of Numeric and Textual Data, Virtual Machine Specification
  1531. @section Filter Mode Interface
  1532. @cindex filter mode
  1533. @cindex parameter mode
  1534. @cindex modes
  1535. From the point of view of the application developer or compiler writer,
  1536. there are parameter mode applications, which are discussed in
  1537. @ref{Parameter Mode Interface}, and filter mode applications,
  1538. which are discussed in this section. Of the latter, there are mainly
  1539. three kinds: those that read one character at a time, those that read a
  1540. line at a time, and those that read the whole standard input file at
  1541. @cindex standard input
  1542. once. Each of them is invoked with different options and expected to
  1543. follow different calling conventions. This section summarizes these
  1544. conventions.
  1545. @menu
  1546. * Loading All of Standard Input at Once::
  1547. * Line Maps::
  1548. * Byte Transducers::
  1549. @end menu
  1550. @node Loading All of Standard Input at Once, Line Maps, Filter Mode Interface, Filter Mode Interface
  1551. @subsection Loading All of Standard Input at Once
  1552. Unless @option{--line-map} or @option{--byte-transducer} is used as a
  1553. @cindex @code{line-map} command line option
  1554. @cindex @code{byte-transducer} command line option
  1555. @cindex standard input
  1556. command line option when the application is invoked, the contents of
  1557. standard input are loaded entirely into memory by @code{avram} before
  1558. evaluation of the virtual code begins. This interface is obviously not
  1559. @cindex infinite streams
  1560. appropriate for infinite streams.
  1561. The virtual code application in this mode of operation is treated as a
  1562. single function taking the entire contents of standard input as its argument,
  1563. and returning the entire contents of standard output as its result.
  1564. Hence, this interface is one of the simplest available.
  1565. @menu
  1566. * Standard Input Representation::
  1567. * Standard Output Representation::
  1568. @end menu
  1569. @node Standard Input Representation, Standard Output Representation, Loading All of Standard Input at Once, Loading All of Standard Input at Once
  1570. @subsubsection Standard Input Representation
  1571. @cindex standard input
  1572. The representation for the standard input file used as the argument to
  1573. the function depends both on the file format and on the command line
  1574. options specified when the application is invoked. The
  1575. @cindex @code{unparameterized} command line option
  1576. @cindex @code{raw-mode} command line option
  1577. @option{--unparameterized} and @option{--raw-output} options make no
  1578. difference to the input representation, and the @option{--line-map}
  1579. and @option{--byte-transducer} options are not relevant to this mode of
  1580. operation. That leaves four possible combined settings of the
  1581. @cindex @code{choice-of-output} command line option
  1582. @cindex @code{force-text-input} command line option
  1583. @option{--choice-of-output} and @option{--force-text-input} options. If
  1584. standard input conforms to the data file format specification @ref{File Format},
  1585. the following effects are possible.
  1586. @itemize @bullet
  1587. @item If neither @option{--choice-of-output} nor
  1588. @option{--force-text-input} is used, the argument to the function will
  1589. be given directly by the tree encoded in the data section of the
  1590. file. The preamble of the file will be ignored.
  1591. @item If the @option{--choice-of-output} option is used
  1592. and the @option{--force-text-input} option is not used, the argument to
  1593. the function will be a pair @code{(@var{preamble},@var{contents})},
  1594. where @var{preamble} is a list of character strings taken from the
  1595. preamble of the file (with leading hashes stripped), and @var{contents}
  1596. is the tree represented in the data section of the file.
  1597. @item If the @option{--choice-of-output} option is not used
  1598. and the @option{--force-text-input} option is used, the argument to the
  1599. function will be the whole file as a list of character strings. I.e.,
  1600. both the preamble and the data sections are included, hashes are not
  1601. stripped from the preamble, and the data section is not converted to the
  1602. tree it represents.
  1603. @item If the @option{--choice-of-output} option is used
  1604. and the @option{--force-text-input} option is also used, the argument to the
  1605. the function will be a pair @code{(nil,@var{contents})}, where the
  1606. contents are the list of character strings as in the previous case.
  1607. @end itemize
  1608. @cindex file format
  1609. If standard input does not conform to the data file format specification
  1610. in @ref{File Format}, then it is assumed to be a text file. The
  1611. @option{--force-text-input} option makes no difference, and there are
  1612. only two possible effects, depending on whether
  1613. @option{--choice-of-output} is used. They correspond to the latter two
  1614. cases above, where @option{--force-text-input} is used.
  1615. @cindex preamble
  1616. @cindex text files
  1617. The idea of the @option{--choice-of-output} option is that it is used
  1618. only for applications that are smart enough to be aware of the
  1619. @code{(@var{preamble},@var{contents})} convention. A non-empty preamble
  1620. implies a data file whose contents could be any type, but an empty
  1621. preamble implies a text file whose contents can only be a list of
  1622. character strings. (In the case of a data file with no preamble, the
  1623. list of the empty string is used for the preamble to distinguish it from
  1624. a text file.)
  1625. Dumb applications that never want to deal with anything but text files
  1626. should be invoked with @option{--force-text-input}. Otherwise, they have
  1627. to be prepared for either text or data as arguments.
  1628. The use of both options at once is unproductive as far as the input
  1629. format is concerned, but may be justified when the output is to be a
  1630. data file and the input is text only.
  1631. @node Standard Output Representation, , Standard Input Representation, Loading All of Standard Input at Once
  1632. @subsubsection Standard Output Representation
  1633. @cindex standard output
  1634. @cindex @code{raw-output} command line option
  1635. @cindex @code{choice-of-output} command line option
  1636. As in the case of standard input, the representation for standard output
  1637. that the function is expected to return depends on the command line
  1638. options with which the application is invoked. The only relevant options
  1639. are @option{--raw-output} and @option{--choice-of-output}, which are
  1640. mutually exclusive.
  1641. @itemize @bullet
  1642. @item If neither option is selected, the result returned by the function must
  1643. be a list of character strings.
  1644. @item If @option{--raw-output} is used, the result returned by the
  1645. function is unconstrained, and it will be written as a data file with no
  1646. preamble, following the format specified in @ref{File Format}.
  1647. @item If @option{--choice-of-output} is used, the result returned by the
  1648. function must be a pair @code{(@var{preamble},@var{contents})}.
  1649. @end itemize
  1650. @cindex preamble
  1651. In the last case, the preamble determines how the file will be written.
  1652. If it is meant to be a text file, the preamble should be @code{nil}, and
  1653. the contents should be a list of character strings. If it is meant to be
  1654. a data file, the preamble should be a non-empty list of character
  1655. strings, and the format of the contents is unconstrained. To express a
  1656. data file with no preamble, the preamble should be the list containing
  1657. the empty string, rather than being empty.
  1658. In the result returned by the function, the preamble lines should not
  1659. include leading hash characters, because they are automatically added to
  1660. the output to enforce consistency with the data file format. However,
  1661. they should include trailing backslashes as continuation characters
  1662. where appropriate. The hashes that are automatically added will be
  1663. automatically stripped by @code{avram} on behalf of whatever application
  1664. uses the file.
  1665. @cindex character strings
  1666. @cindex printing algorithm
  1667. Any file can be written as a list of character strings, even ``text''
  1668. files that are full of unprintable characters, and even ``text'' files
  1669. that happen to conform to the format used for data files. However, if
  1670. the application intends to write a data file in the standard format used
  1671. by other virtual code applications, it can do so more quickly and easily
  1672. by having the virtual machine do the formatting automatically with the
  1673. @option{--choice-of-output} option than by implementing the algorithm in
  1674. @ref{Concrete Syntax}, from scratch in virtual code.
  1675. @node Line Maps, Byte Transducers, Loading All of Standard Input at Once, Filter Mode Interface
  1676. @subsection Line Maps
  1677. @cindex @code{line-map} command line option
  1678. Virtual code applications invoked with the @option{--line-map} option
  1679. (with or without the @option{--unparameterized} option) adhere to a very
  1680. simple interface.
  1681. @itemize @bullet
  1682. @item The argument to the function is a character string, and the result
  1683. must also be a character string.
  1684. @item The function is applied to each line of the standard input file
  1685. @cindex standard input
  1686. and the result in each case is written to standard output followed by a
  1687. @cindex standard output
  1688. line break.
  1689. @end itemize
  1690. @cindex infinite streams
  1691. This kind of application may be used on finite or infinite streams,
  1692. provided that the lengths of the lines are finite, but preserves no state
  1693. information from one line to the next.
  1694. @node Byte Transducers, , Line Maps, Filter Mode Interface
  1695. @subsection Byte Transducers
  1696. The interface used when the @code{--byte-transducer} option is selected
  1697. @cindex @code{byte-transducer} command line option
  1698. allows an application to serve as a persistent stream processor suitable
  1699. @cindex infinite streams
  1700. for finite or infinite streams. The interface can be summarized by the
  1701. following points.
  1702. @itemize @bullet
  1703. @item When it is first invoked, the function in the virtual code file is
  1704. applied to an argument of @code{nil}, and is expected to return a pair
  1705. @code{(@var{state},@var{output})}. The @var{state} format is
  1706. unconstrained. The @var{output} must be a character string that will
  1707. be written to standard output, but it may be the empty string.
  1708. @item For each byte read from standard input, @code{avram} applies the function
  1709. to the pair @code{(@var{state},@var{character})}, using the state
  1710. obtained from previous evaluation, and the character whose code is the
  1711. byte. The purpose of the @var{state} field is therefore to provide a
  1712. way for the application to remember something from one invocation to
  1713. the next.
  1714. @item The function is usually expected to return a pair
  1715. @code{(@var{state},@var{output})} for each input byte, so that the state
  1716. can be used on the next iteration, and the output can be written to standard
  1717. output as a character string.
  1718. @item If the function ever returns a value of @code{nil}, the computation
  1719. terminates.
  1720. @item If standard input comes to an end before the computation terminates,
  1721. the function will be applied to a pair of the form
  1722. @code{(@var{state},nil)} thereafter, but may continue to return
  1723. @code{(@var{state},@var{output})} pairs for arbitrarily many more iterations.
  1724. The @code{EOF} character is not explicitly passed to the function, but
  1725. the end is detectable insofar as @code{nil} is not a representation for
  1726. any character.
  1727. @end itemize
  1728. Unlike the situation with line maps, the output character strings
  1729. do not have line breaks automatically appended, and the application must
  1730. include them explicitly if required. The convention for
  1731. @cindex Unix
  1732. line breaks is system dependent. On Unix and GNU/Linux systems, character
  1733. code 10 indicates a line break, but other systems may use character code
  1734. 13 followed by character code 10. See @ref{Character Table} for the
  1735. @cindex character codes
  1736. representations of characters having these codes.
  1737. @node Parameter Mode Interface, Virtual Code Semantics, Filter Mode Interface, Virtual Machine Specification
  1738. @section Parameter Mode Interface
  1739. @cindex parameter mode
  1740. The virtual code file for a parameter mode application contains a tree
  1741. representing a single function, which takes as its argument a data
  1742. structure in the format described below. The format of the result
  1743. returned by the function depends on the virtual machine options used on
  1744. the command line, and the various alternatives are explained
  1745. subsequently.
  1746. @menu
  1747. * Input Data Structure::
  1748. * Input for Mapped Applications::
  1749. * Output From Non-interactive Applications::
  1750. * Output From Interactive Applications::
  1751. @end menu
  1752. @node Input Data Structure, Input for Mapped Applications, Parameter Mode Interface, Parameter Mode Interface
  1753. @subsection Input Data Structure
  1754. The data structure that is used as the argument to the parameter mode
  1755. application incorporates all the information about the command line and
  1756. @cindex environment
  1757. @cindex command line
  1758. the environment variables. It is in the form of a triple
  1759. @code{((@var{files},@var{options}),@var{environs})}. The fields have
  1760. these interpretations.
  1761. @table @var
  1762. @item files
  1763. is a list of quadruples
  1764. @code{((@var{date},@var{path}),(@var{preamble},@var{contents}))}, with
  1765. one quadruple for each input file named on the command line (but not the
  1766. virtual code file or the @code{avram} executable). The list will be in
  1767. the same order as the filenames on the command line, and is not affected
  1768. by options interspersed with them. The fields in each item have the
  1769. following interpretations.
  1770. @table @var
  1771. @item date
  1772. is the time stamp of the file in as a character string in the usual
  1773. @cindex time stamp
  1774. @cindex date
  1775. @cindex system time
  1776. @cindex current time
  1777. @cindex Unix
  1778. Unix format, for example, @code{Fri Jan 19 14:34:44 GMT 2001}. If the
  1779. file corresponds to standard input, the current system time and date are
  1780. used.
  1781. @item path
  1782. is the full path of the file, expressed as a list of strings. If the
  1783. @cindex file names
  1784. @cindex paths
  1785. @cindex absolute path
  1786. @cindex relative path
  1787. file corresponds to standard input, the list is empty. Otherwise, the
  1788. first string in the list is the file name. The next is the name of the
  1789. file's parent directory, if any. The next is the parent of the parent,
  1790. and so on. The root directory is indicated by the empty string, so that
  1791. any path ending with the empty string is an absolute path, while any path
  1792. ending with a non-empty string is relative to the current working
  1793. directory. Path separators (i.e., slashes) are omitted.
  1794. @item preamble
  1795. In the case of a text file, or any file not conforming to the format in
  1796. @cindex preamble
  1797. @ref{File Format}, this field is @code{nil}. Otherwise, this field contains
  1798. the preamble of the file expressed as a list of strings, or contains
  1799. just the empty string if the file has no preamble. Any leading hashes in
  1800. the preamble of the file are stripped.
  1801. @item contents
  1802. In the case of a text file (as indicated by the @var{preamble} field), this
  1803. @cindex text files
  1804. field will contain a list of character strings, with each line of the file
  1805. contained in a character string. Otherwise, it can contain data in any
  1806. format, which are obtained by converting the data section of the file
  1807. to a tree.
  1808. @end table
  1809. @item options
  1810. is a list of quadruples of the form
  1811. @code{((@var{position},@var{longform}),(@var{keyword},@var{params}))}
  1812. with one quadruple for each option appearing on the command line after
  1813. the name of the virtual code file.
  1814. @table @var
  1815. @item position
  1816. is a natural number indicating the position of the option on the command
  1817. @cindex naturals
  1818. @cindex command line
  1819. line. The position numbers of all the options will form an ascending
  1820. sequence, but not necessarily consecutive nor starting with zero. The
  1821. missing numbers in the sequence will correspond to the positions of the
  1822. file names on the command line, allowing their positions to be inferred by
  1823. applications for which the position matters.
  1824. @item longform
  1825. is a boolean value which is true if the option starts with two or more
  1826. @cindex booleans
  1827. dashes but false otherwise.
  1828. @item keyword
  1829. is the key word of the option expressed as a character string. For example
  1830. in the case of a command line option @kbd{--foo=bar,baz}, the keyword is
  1831. @code{foo}. Leading dashes are stripped.
  1832. @item params
  1833. is a list of character strings identifying the parameters for the
  1834. command line option in question. In the case of an option of the form
  1835. @kbd{--foo=bar,baz}, the first character string in the list will be
  1836. @code{bar} and the next will be @code{baz}. The same applies if the
  1837. option is written @kbd{--foo bar,baz} or @kbd{--foo =bar,baz}. If there
  1838. are no parameters associated with the option, the list is empty.
  1839. @end table
  1840. @item environs
  1841. is a list of pairs of character strings, with one pair in the list for
  1842. @cindex environment
  1843. each environment variable. The identifier is the left string in the
  1844. pair, and the value is the right. For example, if the environment
  1845. contains the definition @code{OSTYPE=linux-gnu}, there will be a pair in
  1846. the list whose left side is the string @code{OSTYPE} and whose
  1847. right side is the string @code{linux-gnu}.
  1848. @end table
  1849. @node Input for Mapped Applications, Output From Non-interactive Applications, Input Data Structure, Parameter Mode Interface
  1850. @subsection Input for Mapped Applications
  1851. Applications invoked using the @option{--map-to-each-file} option
  1852. @cindex @code{map-to-each-file} command line option
  1853. benefit from a slightly different interface than the one described
  1854. above. As the purpose of this option is to save memory by loading only
  1855. one file at a time, the application does not have access to all input
  1856. files named on the command line simultaneously within the same data
  1857. structure. Although the data structure is of the type already described,
  1858. the @var{files} field is not a list of arbitrary length. Instead, it is
  1859. a list containing exactly one item for an input file. If @kbd{-}
  1860. is used as a command line parameter, indicating standard input, then
  1861. @var{files} will have another item pertaining to standard
  1862. input. In no event will it have other than one or two items.
  1863. The mapped application is expected to work by being applied individually
  1864. to each of any number of separately constructed data structures, doing
  1865. the same in each case as it would if that case were the only one. To make
  1866. that possible, copies of the environment variables, the contents of standard
  1867. input, and the list of application specific options are contained in the
  1868. data structure used for every invocation.
  1869. @cindex command line
  1870. The position numbers in the options are adjusted for each invocation to
  1871. reflect the position of the particular input file associated with it.
  1872. For example, in the following command
  1873. @display
  1874. @kbd{avram --map-to-each-file mapster.avm fa.txt --data fb.dat --code fc.o}
  1875. @end display
  1876. @noindent
  1877. the function in the virtual code file @file{mapster.avm} would be
  1878. applied to each of three data structures, corresponding to the commands
  1879. @display
  1880. @kbd{avram mapster.avm fa.txt --data --code}
  1881. @kbd{avram mapster.avm --data fb.dat --code}
  1882. @kbd{avram mapster.avm --data --code fc.o}
  1883. @end display
  1884. @noindent
  1885. If the relative positions of the options and filenames were important to
  1886. the application, they could be reliably inferred from the position
  1887. numbers. In the first case, they would be 1 and 2, implying that the
  1888. file is in position 0. In the second case they would be 0 and 2,
  1889. implying that the file is in position 1, and in the third case they
  1890. would be 0 and 1, implying that the file is in position 2. (Of course,
  1891. nothing compels an application to concern itself with the positions of
  1892. its parameters, and the alternative might be preferable.)
  1893. For the most part, any application that can operate on one file at a
  1894. time without needing information from any others can be executed more
  1895. economically with the @option{--map-to-each-file} option and few if any
  1896. changes to the code. The effect will normally be analogous to the above
  1897. example, subject to a few possible differences.
  1898. @itemize @bullet
  1899. @item If an application is supposed to do something by default when
  1900. there are no file parameters or only standard input, it won't work as a
  1901. mapped application, because if there are no file parameters it won't be
  1902. executed at all.
  1903. @item If a mapped application causes any output files to be generated, they
  1904. may be written before other input files are read, possibly causing the
  1905. input files to be overwritten if they have the same names, and causing
  1906. subsequent invocations to use the overwritten versions. This behavior
  1907. differs from that of loading all input files at the outset, which
  1908. ensures the application seeing all of the original versions. The latter may be
  1909. more convenient for maintaining a group of files in some sort of
  1910. consistent state.
  1911. @item If an application causes standard output to be written along with
  1912. output files, normally standard output is written last as a security
  1913. measure against malicious code altering the @option{--ask-to-overwrite}
  1914. prompts by subtly clobbering the console. In a mapped application,
  1915. standard output isn't always last because there may be more invocations
  1916. to come.
  1917. @end itemize
  1918. @node Output From Non-interactive Applications, Output From Interactive Applications, Input for Mapped Applications, Parameter Mode Interface
  1919. @subsection Output From Non-interactive Applications
  1920. @cindex @code{interactive} command line option
  1921. @cindex @code{step} command line option
  1922. If a parameter mode application is not invoked with either of the
  1923. @option{--interactive} or @option{--step} options,
  1924. then it is deemed to be non-interactive, and therefore does not concern
  1925. itself with executing shell commands. Instead, it simply specifies a
  1926. list of output files to be created or updated on its behalf by @code{avram}.
  1927. The files are described by a list of quadruples
  1928. @code{((@var{overwrite},@var{path}),(@var{preamble},@var{contents}))},
  1929. with one quadruple for each file.
  1930. @cindex preamble
  1931. @cindex paths
  1932. @cindex standard input
  1933. @cindex standard output
  1934. In each quadruple, the @var{path}, @var{preamble}, and @var{contents}
  1935. fields have the same interpretations as in the list of files in the
  1936. input data structure described in @ref{Input Data Structure}, except that a
  1937. @code{nil} path refers to standard output rather than to standard input.
  1938. The @var{overwrite} field in each quadruple tells whether the file
  1939. @cindex appending to files
  1940. should be overwritten or appended. If the @var{overwrite} field is
  1941. @code{nil} (i.e., the representation for the Boolean value of
  1942. @code{false}) and a file already exists at the given path, the new
  1943. contents will be appended to it. If the @var{overwrite} field is
  1944. anything other than @code{nil} and/or no file exists with the given
  1945. path, a new file is written or the extant one is overwritten. Note that
  1946. the data file format specified in @ref{File Format} precludes appending
  1947. anything to it, but the format of existing output files is not checked
  1948. and nothing prevents data or text from being appended to one.
  1949. @node Output From Interactive Applications, , Output From Non-interactive Applications, Parameter Mode Interface
  1950. @subsection Output From Interactive Applications
  1951. @cindex @code{interactive} command line option
  1952. @cindex @code{step} command line option
  1953. Parameter mode applications invoked with either of the
  1954. @option{--interactive} or @option{--step} options are
  1955. required to take the data structure described in @ref{Input Data Structure} as an
  1956. argument but to return the virtual code for a function that will observe
  1957. @cindex shell
  1958. a certain protocol allowing shell commands to be executed on its
  1959. behalf. The intent is that the virtual code file doesn't contain the
  1960. real application @emph{per se}, but only something that builds the real
  1961. one on the fly using configuration information from the input files and
  1962. command line options.
  1963. The format of the result returned by an interactive application, being a
  1964. virtual code application itself, requires a full exposition of the
  1965. virtual machine code semantics. This subject is deferred to @ref{Virtual Code Semantics}.
  1966. The remainder of this section describes the protocol followed by the
  1967. function returned by the interactive application rather than the
  1968. application itself.
  1969. Similarly to the case of a byte transducer described in @ref{Byte Transducers},
  1970. the basic pattern of interaction between @code{avram} and the function
  1971. is a cycle of invocations. In general terms, the function is applied to
  1972. a @code{nil} argument initially, and expected to return an initial state
  1973. and initial output. Thereafter, the function is applied to a pair of the
  1974. state returned on the previous iteration, and the next installment of
  1975. input. The function returns further output and a new state, and the
  1976. cycle continues until the function returns a value of @code{nil}, at
  1977. which time the computation terminates.
  1978. @menu
  1979. * Line Oriented Interaction::
  1980. * Character Oriented Interaction::
  1981. * Mixed Modes of Interaction::
  1982. @end menu
  1983. @node Line Oriented Interaction, Character Oriented Interaction, Output From Interactive Applications, Output From Interactive Applications
  1984. @subsubsection Line Oriented Interaction
  1985. Within this general pattern, more specific styles of interaction are
  1986. possible. In the simplest one to explain first, the result returned by
  1987. the function is always a data structure of the form
  1988. @cindex command line
  1989. @code{(@var{state},(@var{command lines},@var{prompts}))}, wherein the
  1990. fields have these interpretations.
  1991. @table @var
  1992. @item state
  1993. is a tree incorporating any data in any format that the application
  1994. needs to remember from one invocation to the next.
  1995. @item command lines
  1996. is a list of character strings that are piped to the standard input
  1997. stream of a separately spawned process. The process may persist from one
  1998. invocation of the function to the next, or may be spawned each time.
  1999. @item prompts
  2000. is a non-empty list of character strings containing a suffix of the text
  2001. expected from the standard output stream of the process as a result of
  2002. sending the command lines to it.
  2003. @end table
  2004. On each iteration, @code{avram} sends the command line character strings
  2005. @cindex spawning processes
  2006. to a separately spawned process, with line breaks between them if there
  2007. are more than one command. If a process remains from the previous iteration that
  2008. has not terminated itself, the list of command lines is sent to the same
  2009. process. If no such process already exists, the first string in the list
  2010. of command lines is treated as a shell command and used to spawn the
  2011. @cindex @code{exp_popen}
  2012. process (using the @code{exp_popen} library function), and the remaining
  2013. strings are sent to the newly spawned process.
  2014. Normally processes spawned with commands that invoke interactive command
  2015. line interpreters of their own, such as @command{bash}, @command{ftp} or
  2016. @command{bc}, will persist indefinitely unless the command causing them
  2017. to exit is issued or some other event kills them. Processes spawned with
  2018. non-interactive commands, such as @command{ls} or @command{pwd}, will
  2019. terminate when the last of their initial output has been received.
  2020. In the case of processes that persist after being spawned, @code{avram}
  2021. needs some way of knowing when to stop waiting for more output from them
  2022. so that it doesn't get stuck waiting forever. This purpose is served by
  2023. the @var{prompts} field. This field could contain a single string
  2024. holding the last thing the process will send before becoming quiescent,
  2025. such as the strings @code{bash$ } or @code{ftp> } in the above
  2026. examples. Alternatively, a sequence of more than one prompt string can
  2027. be used to indicate that the corresponding sequence of lines must be
  2028. detected. An empty string followed by @code{ftp> } would indicate that
  2029. the @code{ftp> } prompt is expected to be immediately preceded by a line
  2030. @cindex prompts
  2031. break. There is also the option of using prompt strings to indicate a
  2032. pattern that does not necessarily imply quiescence, but is a more
  2033. convenient point at which to stop reading the output from the process.
  2034. For processes spawned with commands that do not start their own
  2035. interactive command line interpreters, such as @command{ls} or
  2036. @command{pwd}, it may be preferable to read all the output from them
  2037. until they terminate. To achieve this effect, the list of prompt strings
  2038. should contain only the single string containing only the single
  2039. @code{EOF} character (usually code 4) or any other character that is
  2040. certain not to occur in the output of the process. This technique is
  2041. based on the assumption that the process was spawned originally with the
  2042. command in question, not that such a command is sent to an existing
  2043. shell process.
  2044. In any case, when enough output has been received from the process, it
  2045. is collected into a list of received strings including the prompt
  2046. strings at the end (if they were received), and the function is applied
  2047. to the pair @code{(@var{state},@var{received strings})}. If the cycle is
  2048. to continue, the result returned by the function will include a new
  2049. state, a new list of command lines, and a new list of prompt strings. A
  2050. result of @code{nil} will cause the computation to terminate.
  2051. There are some unusual situations that could occur in the course of line
  2052. oriented interaction, and are summarized as follows.
  2053. @itemize @bullet
  2054. @item If the process terminates before any pattern matching the prompt
  2055. strings is received from it, all of the output from the process up to
  2056. the point where it terminated is collected into the @var{received
  2057. strings} list and passed to the function. This situation includes cases
  2058. where the process terminates immediately upon being spawned, but not
  2059. abnormal completion of the @code{exp_popen} library function, which is
  2060. a fatal error. This feature of the interface is what allows @code{EOF}
  2061. to be used for collecting all the output at once from a non-interactive
  2062. command.
  2063. @item If the list of @var{command lines} is empty, and no process
  2064. currently exists due to a previous iteration, the effect is the same as
  2065. if the process terminates unexpectedly before outputting anything. I.e.,
  2066. the function is applied to a pair containing an empty list of received
  2067. strings. There is no good reason for an application to get into this
  2068. situation.
  2069. @item If the list of @var{command lines} is empty but a process persists
  2070. from a previous iteration, no output is sent to it, but receiving from
  2071. it proceeds normally. This feature of the interface could be used
  2072. effectively by applications intended to process the received data in
  2073. @cindex deadlock
  2074. parts, but will cause deadlock if the process is already quiescent.
  2075. @item All character strings have to consist of lists of valid
  2076. representations of non-null characters according to @ref{Character
  2077. Table}, or else there will be some fatal error messages.
  2078. @item If the list of @var{prompt strings} contains only the empty
  2079. string, @code{avram} will not wait to receive anything from the process,
  2080. but will proceed with the next iteration immediately. If this effect is
  2081. intended, care must be taken not to confuse the empty list
  2082. of @var{prompt strings} with the list containing the empty string. The former
  2083. indicates character oriented interaction, which is explained next.
  2084. @end itemize
  2085. @node Character Oriented Interaction, Mixed Modes of Interaction, Line Oriented Interaction, Output From Interactive Applications
  2086. @subsubsection Character Oriented Interaction
  2087. A character oriented style of interaction involves the function always
  2088. returning a data structure of the form @code{(@var{state},(@var{command
  2089. lines},nil))}. The @var{state} and @var{command lines} fields serve
  2090. @cindex command line
  2091. exactly the same purposes respectively as they do in the case of line
  2092. oriented interaction. The field that would be occupied by the
  2093. @var{prompt strings} list in the case of line oriented interaction is
  2094. identically @code{nil} in this style.
  2095. When this style is used, @code{avram} spawns a process and/or sends
  2096. @cindex spawning processes
  2097. command lines to it as in the case of line oriented interaction, but
  2098. attempts to read only a single character from it per iteration. When the
  2099. character is received, @code{avram} applies the function to the pair
  2100. @code{(@var{state},@var{character})} in order to obtain the next state
  2101. and the next list of command lines. If the process has terminated, a
  2102. @code{nil} value is used in place of the character. If the process is
  2103. quiescent, deadlock ensues.
  2104. The character oriented style is a lower level protocol that shifts more
  2105. of the burden of analyzing the process's output to the virtual code
  2106. application. It can do anything line oriented interaction can do except
  2107. proceeding immediately without waiting to receive any output from the
  2108. process. It may also allow more general criteria (in effect) than the
  2109. matching of a fixed prompt string to delimit the received data, for
  2110. those pathological processes that may require such things.
  2111. Applications using character oriented interaction need to deal with line
  2112. @cindex line breaks
  2113. breaks explicitly among the received characters, unlike the case with
  2114. line oriented interaction, where the line breaks are implicit in the
  2115. @cindex Unix
  2116. list of received strings. Contrary to the convention for Unix text
  2117. files, line breaks in the output of a process are indicated by character
  2118. code 13 followed by character code 10.
  2119. @node Mixed Modes of Interaction, , Character Oriented Interaction, Output From Interactive Applications
  2120. @subsubsection Mixed Modes of Interaction
  2121. An application is not confined exclusively to line oriented or character
  2122. oriented interaction, but may switch from one style to the other between
  2123. iterations, and signal its choice simply by the format of the data
  2124. structure it returns. If the @var{prompt strings} field is non-empty,
  2125. the interaction is line oriented, and if the field is empty, the
  2126. interaction is character oriented. A function using both styles has to
  2127. be prepared for whichever type of data it indicates, either a character or
  2128. a list of character strings as the case may be.
  2129. Another alternative is possible if the function returns a data structure
  2130. in the form @code{(@var{files},nil)}. This structure includes neither a
  2131. list of command lines nor a list of prompt strings, empty or otherwise,
  2132. but does include a list of quadruples in the @var{files} field. The
  2133. quadruples are of the form
  2134. @code{((@var{overwrite},@var{path}),(@var{preamble},@var{contents}))}.
  2135. The fields have the same interpretations as in the output from a
  2136. non-interactive parameter mode application, as described in
  2137. @ref{Output From Non-interactive Applications}, and will cause a list of files to be written in the same way.
  2138. As an interactive application is able cause the execution of arbitrary
  2139. shell commands, it doesn't need @code{avram} to write files for it the
  2140. way a non-interactive application does, so this feature does not provide
  2141. any additional capabilities. However, it may be helpful as a matter of
  2142. convenience.
  2143. After the files are written, the function will be applied to the same
  2144. result it returned, @code{(@var{files},nil)}. There is no direct means
  2145. of preserving unconstrained state information from previous iterations
  2146. in this style of interaction. A likely scenario might therefore be that
  2147. the function returns a file list after finishing its other business, and
  2148. then returns @code{nil} on the next iteration to terminate.
  2149. @node Virtual Code Semantics, , Parameter Mode Interface, Virtual Machine Specification
  2150. @section Virtual Code Semantics
  2151. As the previous sections explain, virtual code applications are defined
  2152. in terms of mathematical functions. Up until this point, the discussion
  2153. has focused on the interface between the function and the virtual
  2154. machine interpreter, by detailing the arguments passed to the functions under
  2155. various circumstances and the results they are expected to return in
  2156. order to achieve various effects.
  2157. The purpose of this section is to complete the picture by explaining how
  2158. a given computable function can be expressed in virtual code,
  2159. considering only functions operating on the trees described in @ref{Raw Material}.
  2160. Functions manipulating trees of @code{nil} are undoubtedly a frivolous
  2161. and abstract subject in themselves. One is obliged to refer back to the
  2162. previous sections if in need of motivation.
  2163. @menu
  2164. * A New Operator::
  2165. * On Equality::
  2166. * A Minimal Set of Properties::
  2167. * A Simple Lisp Like Language::
  2168. * How @code{avram} Thinks::
  2169. * Variable Freedom::
  2170. * Metrics and Maintenance::
  2171. * Deconstruction::
  2172. * Recursion::
  2173. * Assignment::
  2174. * Predicates::
  2175. * Iteration::
  2176. * List Combinators::
  2177. * List Functions::
  2178. * Exception Handling::
  2179. * Interfaces to External Code::
  2180. * Vacant Address Space::
  2181. @end menu
  2182. @node A New Operator, On Equality, Virtual Code Semantics, Virtual Code Semantics
  2183. @subsection A New Operator
  2184. With regard to a set of trees as described in @ref{Raw Material}, we can define
  2185. a new binary operator. Unlike the @code{cons} operator, this one is not
  2186. required to associate an element of the set with every possible pair
  2187. of elements. For very many pairs of operands we will have nothing to
  2188. say about its result. In fact, we require nothing of it beyond
  2189. a few simple properties to be described presently.
  2190. Because this is the only other operator than @code{cons}, there is no
  2191. @cindex @code{cons}
  2192. need to have a special notation for it, so it will be denoted by empty
  2193. space. The tree associated by the operator with a pair of trees @code{@var{x}}
  2194. and @code{@var{y}}, if any, will be expressed in the infix notation
  2195. @code{@var{x} @var{y}}. For convenience, the operator is regarded as
  2196. being right associative, so that @code{@var{a} @var{b} @var{c}} can be
  2197. written for @code{@var{a} (@var{b} @var{c})}.
  2198. @node On Equality, A Minimal Set of Properties, A New Operator, Virtual Code Semantics
  2199. @subsection On Equality
  2200. @cindex equality
  2201. One example of a property this operator should have, for reasons that
  2202. will not be immediately clear, is that for any trees @code{@var{x}} and
  2203. @code{@var{k}}, the equality @code{cons(cons(nil,@code{@var{k}),nil) @var{x}} =
  2204. @code{@var{k}}} always holds.
  2205. Even though the present exposition opts for readability over formality,
  2206. statements like these demand clarification of the notion of
  2207. equality. Some of the more pedantic points in @ref{Raw Material} may be needed
  2208. for the following ideas to hold water.
  2209. @itemize @bullet
  2210. @item As originally stipulated, it is always possible to distinguish
  2211. @code{nil} from any member of the set. We can therefore decide on this
  2212. basis whether @code{@var{a} = @var{b}} whenever at least one of them is @code{nil}.
  2213. @item Where neither @code{@var{a}} nor @code{@var{b}} is @code{nil} in an expression
  2214. @code{@var{a} = @var{b}}, but rather something of the form
  2215. @code{cons(@var{x},@var{y})}, the equality holds if and only
  2216. if both pairs of corresponding subexpressions are equal. If at least one
  2217. member of each pair of corresponding subexpressions is @code{nil}, the
  2218. question is settled, but otherwise there is recourse to their respective
  2219. subexpressions, and so on. This condition follows from the uniqueness property
  2220. of the @code{cons} operator.
  2221. @item If one side of an equality is of the form
  2222. @code{@var{x} @var{y}}, or is defined in terms of such an expression,
  2223. but @code{(@var{x},@var{y})} is one of those pairs with which the operator
  2224. associates no result, then the equality holds if and only if the other
  2225. side is similarly ill defined.
  2226. @item Statements involving universal quantification (i.e.,
  2227. @cindex universal quantification
  2228. @cindex undefined expressions
  2229. beginning with words similar to ``for any tree @code{@var{x}} @dots{}'')
  2230. obviously do not apply to instances of a variable (@code{@var{x}}) outside
  2231. the indicated set (trees). Hence, they are not refuted by any
  2232. consequence of identifying a variable with an undefined expression.
  2233. @end itemize
  2234. Readers who are aware of such issues as pointer equality or intensional
  2235. @cindex pointer equality
  2236. @cindex pointers
  2237. versus extensional equality of functions are urged to forget all about
  2238. them in the context of this document, and abide only by what is
  2239. stated. Other readers should ignore this paragraph.
  2240. @node A Minimal Set of Properties, A Simple Lisp Like Language, On Equality, Virtual Code Semantics
  2241. @subsection A Minimal Set of Properties
  2242. For any trees @code{@var{x}}, @code{@var{y}}, and @code{@var{k}}, and any non-@code{nil}
  2243. trees @code{@var{p}}, @code{@var{f}}, and @code{@var{g}}, the new invisible operator satisfies these
  2244. conditions. In these expressions and hereafter, increasing abuse of
  2245. notation is perpetrated by not writing the @code{cons} in expressions of the form
  2246. @code{cons(@var{x},@var{y})}.
  2247. @table @emph
  2248. @item P0
  2249. @code{(nil,(nil,nil)) @var{x}} = @code{@var{x}}
  2250. @item P1
  2251. @code{(nil,((nil,nil),nil)) (@var{x},@var{y})} = @code{@var{x}}
  2252. @item P2
  2253. @code{(nil,(nil,(nil,nil))) (@var{x},@var{y})} = @code{@var{y}}
  2254. @item P3
  2255. @code{((nil,@var{k}),nil) @var{x}} = @code{@var{k}}
  2256. @item P4
  2257. @code{(((nil,(nil,nil)),nil),nil) (@var{f},@var{x})} = @code{@var{f} (@var{f},@var{x})}
  2258. @item P5
  2259. @code{((@var{f},@var{g}),nil) @var{x}} = @code{@var{f} @var{g} @var{x}}
  2260. @item P6
  2261. @code{((@var{f},nil),@var{g}) @var{x}} = @code{(@var{f} @var{x},@var{g} @var{x})}
  2262. @item P7
  2263. @code{((@var{p},@var{f}),@var{g}) @var{x}} = @code{@var{f} @var{x}} if
  2264. @code{@var{p} @var{x}} is a non-@code{nil} tree,
  2265. but @code{@var{g} @var{x}} if @code{@var{p} @var{x}} = @code{nil}
  2266. @end table
  2267. @cindex properties
  2268. @cindex operator properties
  2269. Although other properties remain to be described, it is worth pausing at
  2270. this point because there is ample food for thought in the ones already
  2271. given. An obvious question would be that of their origin. The short
  2272. answer is that they have been chosen arbitrarily to be true by
  2273. definition of the operator. At best, the completion of the construction
  2274. may lead to a more satisfactory answer based on aesthetic or engineering
  2275. grounds.
  2276. A more important question would be that of the relevance of the mystery
  2277. operator and its properties to the stated purpose of this section, which
  2278. is to specify the virtual machine code semantics. The answer lies in
  2279. that the operator induces a function for any given tree @code{@var{t}},
  2280. such that the value returned by the function when given an argument
  2281. @var{x} is @code{@var{t} @var{x}}. This function is the one that is
  2282. implemented by the virtual code @var{t}, which is to say the way an
  2283. application will behave if we put @var{t} in its virtual code file. An
  2284. equivalent way of looking at the situation is that the virtual machine
  2285. does nothing but compute the result of this operator, taking the tree in
  2286. the virtual code file as its left operand and the input data as the
  2287. right operand. By knowing what the operator will do with a given pair of
  2288. operands, we know what to put into the virtual code file to get the
  2289. function we want.
  2290. @cindex universality
  2291. @cindex Turing equivalence
  2292. @cindex exceptions
  2293. @cindex lists
  2294. It is worthwhile to note that properties @emph{P0} to @emph{P7} are
  2295. sufficient for universality in the sense of Turing equivalence. That
  2296. means that any computable function could be implemented by the suitable
  2297. choice of a tree @var{t} without recourse to any other properties of the
  2298. operator. A compiler writer who finds this material boring could
  2299. therefore stop reading at this point and carry out the task of targeting
  2300. any general purpose programming language to the virtual machine based on
  2301. the specifications already given. However, such an implementation would
  2302. not take advantage of the features for list processing, exception
  2303. handling, or profiling that are also built into the virtual
  2304. machine and have yet to be described.
  2305. @node A Simple Lisp Like Language, How @code{avram} Thinks, A Minimal Set of Properties, Virtual Code Semantics
  2306. @subsection A Simple Lisp Like Language
  2307. @cindex @code{silly}
  2308. With a universal computational model already at our disposal, it will be
  2309. easier to use the virtual machine to specify itself than to define all
  2310. of it from scratch. For this purpose, we use the @code{silly}
  2311. programming language, whose name is an acronym for SImple Lisp-like
  2312. Language (Yeah right). The language serves essentially as a thin layer
  2313. of symbolic names on top of the virtual machine code. Due to its poor
  2314. support for modularity and abstraction, @code{silly} is not recommended
  2315. for serious application development, but at least it has a shallow
  2316. learning curve.@footnote{Previous releases of @code{avram} included a
  2317. working @code{silly} compiler, but this has now been superseded
  2318. by the Ursala programming language. Ursala includes @code{silly} as a subset
  2319. for the most part, and the examples in this manual should compile and
  2320. execute with very little modification.}
  2321. @menu
  2322. * Syntax::
  2323. * Semantics::
  2324. * Standard Library::
  2325. @end menu
  2326. @node Syntax, Semantics, A Simple Lisp Like Language, A Simple Lisp Like Language
  2327. @subsubsection Syntax
  2328. @code{silly} has no reserved words, but it has equals signs, commas and
  2329. parentheses built in. A concise but ambiguous grammar for it can be given
  2330. as follows.
  2331. @cindex syntax
  2332. @cindex grammar
  2333. @display
  2334. @var{program} ::= @var{declaration}*
  2335. @var{declaration} ::= @var{identifier} @code{=} @var{expression}
  2336. @iftex
  2337. @var{expression} ::= @code{()} | @var{identifier} | @code{(@var{expression})} | @code{(@var{expression},@var{expression})}
  2338. | @var{expression} @var{expression} | @var{expression}@code{(}@var{expression}@code{)}
  2339. | @var{expression}@code{(}@var{expression}@code{,}@var{expression}@code{)}
  2340. @end iftex
  2341. @ifinfo
  2342. @var{expression} ::= () | @var{identifier}
  2343. | (@var{expression})
  2344. | (@var{expression},@var{expression})
  2345. | @var{expression} @var{expression}
  2346. | @var{expression}(@var{expression})
  2347. | @var{expression}(@var{expression},@var{expression})
  2348. @end ifinfo
  2349. @end display
  2350. @noindent
  2351. @cindex precedence
  2352. @cindex operator precedence
  2353. The real grammar is consistent with this one but enforces right
  2354. associativity for binary operations and higher precedence for juxtaposition
  2355. without intervening white space.
  2356. The declaration of any identifier must be unique and must precede its
  2357. occurrence in any expression. Hence, cyclic dependences between
  2358. declarations and ``recursive'' declarations are not allowed.
  2359. @node Semantics, Standard Library, Syntax, A Simple Lisp Like Language
  2360. @subsubsection Semantics
  2361. Declarations in @code{silly} should be understood in the obvious way as
  2362. preprocessor directives to perform parenthetic textual substitutions (similar to
  2363. @code{#define id (exp)} in C). All identifiers in expressions are thereby
  2364. eliminated during the preprocessing phase.
  2365. @cindex semantic function
  2366. The overall meaning of the program is the meaning of the expression in
  2367. the last declaration. A denotational semantics for expressions is given
  2368. by the following equations, where [[@code{@var{x}}]] should be read as
  2369. ``the meaning of @code{@var{x}}'', and @code{@var{x}}, @code{@var{y}} and @code{@var{z}}
  2370. are metavariables. (That is, they stand for any source code fragment
  2371. that could fit there subject to the constraint, informally speaking,
  2372. that it has to correspond to a connected subtree of the parse tree as enforced
  2373. by the unambiguous grammar in the context of the rest of the program.)
  2374. @display
  2375. [[@code{()}]] = @code{nil}
  2376. [[@code{(@var{x})}]] = [[@code{@var{x}}]]
  2377. [[@code{(@var{x},@var{y})}]] = @code{cons(}[[@code{@var{x}}]]@code{,}[[@code{@var{y}}]]@code{)}
  2378. [[@code{@var{x} @var{y}}]] = [[@code{@var{x}(@var{y})}]] = [[@code{@var{x}}]] [[@code{@var{y}}]]
  2379. [[@code{@var{x} (@var{y},@var{z})}]] = [[@code{@var{x}(@var{y},@var{z})}]] = [[@code{@var{x}}]] [[@code{(@var{y},@var{z})}]]
  2380. @end display
  2381. @noindent
  2382. Toy languages like this are among the few situations a
  2383. @cindex denotational semantics
  2384. denotational semantics stands a chance of clarifying more than it
  2385. obfuscates, so the reader is invited to take a moment to savor it.
  2386. @node Standard Library, , Semantics, A Simple Lisp Like Language
  2387. @subsubsection Standard Library
  2388. @code{silly} programs may be linked with library modules, which consist
  2389. of @code{silly} source text to be concatenated with the user
  2390. @cindex library modules
  2391. @cindex standard prelude
  2392. program prior to the preprocessing phase. Most @code{silly} programs are
  2393. linked with the standard @code{silly} prelude, which contains the
  2394. following declarations among others.
  2395. @cindex @code{nil}
  2396. @cindex @code{identity}
  2397. @cindex @code{left}
  2398. @cindex @code{right}
  2399. @cindex @code{meta}
  2400. @cindex @code{constant}
  2401. @cindex @code{couple}
  2402. @cindex @code{compose}
  2403. @cindex @code{conditional}
  2404. @example
  2405. nil = ()
  2406. identity = (nil,(nil,nil))
  2407. left = (nil,((nil,nil),nil))
  2408. right = (nil,(nil,(nil,nil)))
  2409. meta = (((nil,(nil,nil)),nil),nil)
  2410. constant_nil = ((nil,nil),nil)
  2411. couple = ((((left,nil),constant_nil),nil),right)
  2412. compose = couple(identity,constant_nil)
  2413. constant = couple(couple(constant_nil,identity),constant_nil)
  2414. conditional =
  2415. couple(couple(left,compose(left,right)),compose(right,right))
  2416. @end example
  2417. There is a close correspondence between these declarations and the
  2418. properties described in @ref{A Minimal Set of Properties}. A fitting analogy would be that
  2419. the properties of the operator specify the virtual machine instruction
  2420. set in a language independent way, and the @code{silly} library defines
  2421. the instruction mnemonics for a virtual assembly language. The
  2422. @cindex mnemonics
  2423. relationship of some mnemonics to their corresponding instructions may
  2424. be less clear than that of others, so they are all discussed next.
  2425. @node How @code{avram} Thinks, Variable Freedom, A Simple Lisp Like Language, Virtual Code Semantics
  2426. @subsection How @code{avram} Thinks
  2427. The definitions in the standard @code{silly} library pertaining to the
  2428. basic properties of the operator can provide a good intuitive
  2429. illustration of how computations are performed by @code{avram}. This
  2430. task is approached in the guise of a few trivial correctness proofs
  2431. about them. Conveniently, as an infeasibly small language, @code{silly}
  2432. is an ideal candidate for analysis by formal methods.
  2433. Technically the semantic function [[@dots{}]] has not been defined on
  2434. identifiers, but we can easily extend it to them by stipulating that the
  2435. meaning of an identifier @code{@var{x}} is the meaning of the program
  2436. @cindex identifiers
  2437. @code{@var{main} = @var{x}} when linked with a library containing the
  2438. declaration of @code{@var{x}}, where @code{@var{main}} is an identifier
  2439. not appearing elsewhere in the library.
  2440. With this idea in mind, the following ``theorems'' can be stated,
  2441. all of which have a similar proof. The variables @var{x} and @var{y}
  2442. stand for any tree, and the variable @var{f} stands for any tree other
  2443. than @code{nil}.
  2444. @table @emph
  2445. @item T0
  2446. [[@code{identity}]] @code{@var{x}} = @code{@var{x}}
  2447. @item T1
  2448. [[@code{left}]] @code{(@var{x},@var{y})} = @code{@var{x}}
  2449. @item T2
  2450. [[@code{right}]] @code{(@var{x},@var{y})} = @code{@var{y}}
  2451. @item T4
  2452. [[@code{meta}]] @code{(@var{f},@var{x})} = @code{@var{f} (@var{f},@var{x})}
  2453. @item T5
  2454. [[@code{constant_nil}]] @code{@var{x}} = @code{nil}
  2455. @end table
  2456. @noindent
  2457. Replacing each identifier with its defining expression directly
  2458. demonstrates a logical equivalence between the relevant theorem and one
  2459. of the basic operator properties postulated in @ref{A Minimal Set of Properties}.
  2460. For more of a challenge, it is possible to prove the next theorem.
  2461. @table @emph
  2462. @item T6
  2463. For non-@code{nil} @code{@var{f}} and @code{@var{g}},
  2464. ([[@code{couple}]] @code{(@var{f},@var{g})}) @code{@var{x}} =
  2465. @code{(@var{f} @var{x},@var{g} @var{x})}
  2466. @end table
  2467. @noindent
  2468. The proof is a routine calculation. Beware of the distinction between
  2469. the mathematical @code{nil} and the @code{silly} identifier @code{nil}.
  2470. @ifnotinfo
  2471. @format
  2472. ([[@code{couple}]] @code{(@var{f},@var{g})}) @code{@var{x}} = ([[@code{((((left,nil),constant_nil),nil),right)}]] @code{(@var{f},@var{g})}) @code{@var{x}}
  2473. by substitution of @code{couple} with its definition in the standard library
  2474. = (@code{((((}[[@code{left}]]@code{,}[[@code{nil}]]@code{),}[[@code{constant_nil}]]@code{),}[[@code{nil}]])@code{,}[[@code{right}]]@code{)} @code{(@var{f},@var{g})}) @code{@var{x}}
  2475. by definition of the semantic function [[@dots{}]] regarding pairs
  2476. = (@code{((((}[[@code{left}]]@code{,}[[@code{()}]]@code{),}[[@code{constant_nil}]]@code{),}[[@code{()}]])@code{,}[[@code{right}]]@code{)} @code{(@var{f},@var{g})}) @code{@var{x}}
  2477. by substitution of @code{nil} from its definition in the standard library
  2478. = (@code{((((}[[@code{left}]]@code{,}@code{nil}@code{),}[[@code{constant_nil}]]@code{),}@code{nil})@code{,}[[@code{right}]]@code{)} @code{(@var{f},@var{g})}) @code{@var{x}}
  2479. by definition of the semantic function in the case of [[@code{()}]]
  2480. = (@code{(}[[@code{left}]] @code{(@var{f},@var{g}),}[[@code{constant_nil}]] @code{(@var{f},@var{g})),}[[@code{right}]] @code{(@var{f},@var{g})}) @code{@var{x}}
  2481. by property @emph{P6} (twice)
  2482. = @code{((@var{f},nil),@var{g}) @var{x}}
  2483. by theorems @emph{T1}, @emph{T2}, and @emph{T5}
  2484. = @code{(@var{f} @var{x},@var{g} @var{x})}
  2485. by property @emph{P6} again.
  2486. @end format
  2487. @end ifnotinfo
  2488. @ifinfo
  2489. @ifnothtml
  2490. @format
  2491. ([[@code{couple}]] @code{(@var{f},@var{g})}) @code{@var{x}}
  2492. = ([[@code{((((left,nil),constant_nil),nil),right)}]] @code{(@var{f},@var{g})}) @code{@var{x}}
  2493. by substitution of @code{couple} with its definition in the standard library
  2494. = (
  2495. @code{(
  2496. (((}[[@code{left}]]@code{,}[[@code{nil}]]@code{),}[[@code{constant_nil}]]@code{),}[[@code{nil}]])@code{,}
  2497. [[@code{right}]]@code{)}
  2498. @code{(@var{f},@var{g})})
  2499. @code{@var{x}}
  2500. by definition of the semantic function [[@dots{}]] regarding pairs
  2501. = (
  2502. @code{(
  2503. (((}[[@code{left}]]@code{,}[[@code{()}]]@code{),}[[@code{constant_nil}]]@code{),}[[@code{()}]])@code{,}
  2504. [[@code{right}]]@code{)}
  2505. @code{(@var{f},@var{g})})
  2506. @code{@var{x}}
  2507. by substitution of @code{nil} from its definition in the standard library
  2508. = (
  2509. @code{(
  2510. (((}[[@code{left}]]@code{,}[[@code{nil}]]@code{),}[[@code{constant_nil}]]@code{),}[[@code{nil}]])@code{,}
  2511. [[@code{right}]]@code{)}
  2512. @code{(@var{f},@var{g})})
  2513. @code{@var{x}}
  2514. by definition of the semantic function in the case of [[@code{()}]]
  2515. = (
  2516. @code{(}
  2517. [[@code{left}]] @code{(@var{f},@var{g}),}[[@code{constant_nil}]] @code{(@var{f},@var{g})),}
  2518. [[@code{right}]] @code{(@var{f},@var{g})})
  2519. @code{@var{x}}
  2520. by property @emph{P6} (twice)
  2521. = @code{((@var{f},nil),@var{g}) @var{x}}
  2522. by theorems @emph{T1}, @emph{T2}, and @emph{T5}
  2523. = @code{(@var{f} @var{x},@var{g} @var{x})}
  2524. by property @emph{P6} again.
  2525. @end format
  2526. @end ifnothtml
  2527. @end ifinfo
  2528. Something to observe about this proof is that it might just as well have
  2529. been done automatically. Every step is either the substitution of an
  2530. identifier or a pattern match against existing theorems and properties
  2531. of the operator. Another thing to note is that the use of identifiers
  2532. and previously established theorems helps to make the proof human
  2533. readable, but is not a logical necessity. An equivalent proof could have
  2534. been expressed entirely in terms of the properties of the operator. If
  2535. one envisions a proof like this being performed blindly and
  2536. mechanically, without the running commentary or other amenities, that
  2537. would not be a bad way of thinking about what takes place when
  2538. @code{avram} executes virtual code.
  2539. Three more theorems have similar proofs. For non-@code{nil}
  2540. trees @code{@var{p}}, @code{@var{f}} and @code{@var{g}}, and any trees
  2541. @code{@var{x}} and @code{@var{k}}:
  2542. @cindex @code{compose}
  2543. @cindex @code{constant}
  2544. @cindex @code{conditional}
  2545. @table @emph
  2546. @item T7
  2547. ([[@code{compose}]] @code{(@var{f},@var{g})}) @var{x} = @var{f} @var{g} @var{x}
  2548. @item T8
  2549. ([[@code{constant}]] @code{@var{k}}) @var{x} = @var{k}
  2550. @item T9
  2551. ([[@code{conditional}]] @code{(@var{p},(@var{f},@var{g})}) @var{x} =
  2552. @code{@var{f} @var{x}} if
  2553. @code{@var{p} @var{x}} is non-@code{nil},
  2554. but @code{@var{g} @var{x}} if @code{@var{p} @var{x}} = @code{nil}
  2555. @end table
  2556. @noindent
  2557. The proofs of these theorems are routine calculations analogous to the
  2558. proof of @emph{T6}. Here is a proof of theorem @emph{T7} for good
  2559. measure.
  2560. @ifnotinfo
  2561. @format
  2562. ([[@code{compose}]] @code{(@var{f},@var{g})}) @code{@var{x}} = ([[@code{couple(identity,constant_nil)}]] @code{(@var{f},@var{g})}) @code{@var{x}}
  2563. @end format
  2564. @end ifnotinfo
  2565. @ifinfo
  2566. @ifnothtml
  2567. @format
  2568. ([[@code{compose}]] @code{(@var{f},@var{g})}) @code{@var{x}}
  2569. = ([[@code{couple(identity,constant_nil)}]] @code{(@var{f},@var{g})}) @code{@var{x}}
  2570. @end format
  2571. @end ifnothtml
  2572. @end ifinfo
  2573. @iftex
  2574. @display
  2575. @end display
  2576. @noindent
  2577. @end iftex
  2578. by substitution of @code{compose} with its definition in the standard library
  2579. @format
  2580. = (@code{(}[[@code{couple}]] @code{(}[[@code{identity}]]@code{,}[[@code{constant_nil}]]@code{))(@var{f},@var{g})}) @code{@var{x}}
  2581. by definition of the semantic function
  2582. = @code{(}[[@code{identity}]] @code{(@var{f},@var{g}),}[[@code{constant_nil}]]@code{ (@var{f},@var{g})) @var{x}}
  2583. by theorem @emph{T6}
  2584. = @code{((@var{f},@var{g}),nil) @var{x}}
  2585. by theorems @emph{T0} and @emph{T5}
  2586. = @code{@var{f} @var{g} @var{x}}
  2587. by property @emph{P5} of the operator.
  2588. @end format
  2589. @node Variable Freedom, Metrics and Maintenance, How @code{avram} Thinks, Virtual Code Semantics
  2590. @subsection Variable Freedom
  2591. The virtual code semantics is easier to specify using the
  2592. @code{silly} language than it would be without it, but still awkward in
  2593. some cases. An example is the following declaration from the standard
  2594. library,
  2595. @cindex @code{hired}
  2596. @example
  2597. hired = compose(
  2598. compose,
  2599. couple(
  2600. constant compose,
  2601. compose(couple,couple(constant,constant couple))))
  2602. @end example
  2603. @noindent
  2604. which is constructed in such a way as to imply the following theorem,
  2605. provable by routine computation.
  2606. @table @emph
  2607. @item T9
  2608. @code{(}[[@code{hired}]] @code{@var{h}) (@var{f},@var{g})} = [[@code{compose}]]@code{(@var{h},}[[@code{couple}]]@code{(@var{f},@var{g}))}
  2609. @end table
  2610. @noindent
  2611. Intuitively, @code{hired} represents a function that takes a given
  2612. function to a higher order function. For example, if @code{f} were a
  2613. function that adds two real numbers, @code{hired f} would be a function that
  2614. takes two real valued functions to their pointwise sum.
  2615. Apart from its cleverness, such an opaque way of defining a function has
  2616. little to recommend it. The statement of the theorem about the function
  2617. is more readable than the function definition itself, probably because
  2618. the theorem liberally employs mathematical variables, whereas the
  2619. @code{silly} language is variable free. On the other hand, it is not
  2620. worthwhile to linger over further enhancements to the language, such as
  2621. adding variables to it. The solution will be to indicate informally a
  2622. general method of inferring a variable free function definition from an
  2623. expression containing variables, and hereafter omit the more
  2624. cumbersome definitions.
  2625. @cindex @code{isolate}
  2626. @cindex variables
  2627. An algorithm called @code{isolate} does the job.
  2628. The input to @code{isolate} is a pair @code{(@var{e},@var{x})}, where
  2629. @code{@var{e}} is a syntactically correct @code{silly} expression in
  2630. which the identifier @code{@var{x}} may occur, but no other identifiers
  2631. dependent on @code{@var{x}} may occur (or else it's
  2632. garbage-in/garbage-out). Output is a syntactically correct @code{silly}
  2633. expression @code{@var{f}} in which the identifier @code{@var{x}} does
  2634. not occur, such that [[@code{@var{e}}]] = [[@code{@var{f} @var{x}}]].
  2635. The algorithm is as follows,
  2636. @display
  2637. if @code{@var{e}} = @code{@var{x}} then
  2638. return @code{identity}
  2639. else if @code{@var{e}} is of the form @code{(@var{u},@var{v})}
  2640. return @code{couple(isolate(@var{u},@var{x}),isolate(@var{v},@var{x}))}
  2641. else if @code{@var{e}} is of the form @code{@var{u} @var{v}}
  2642. return @code{(hired apply)(isolate(@var{u},@var{x}),isolate(@var{v},@var{x}))}
  2643. else
  2644. return @code{constant @var{e}}
  2645. @end display
  2646. @noindent
  2647. @cindex equality
  2648. where equality is by literal comparison of expressions, and the
  2649. definition of @code{apply} is
  2650. @cindex @code{apply}
  2651. @example
  2652. apply = (hired meta)((hired compose)(left,constant right),right)
  2653. @end example
  2654. @noindent
  2655. which represents a function that does the same thing as the invisible
  2656. operator.
  2657. @table @emph
  2658. @item T10
  2659. [[@code{apply}]] @code{(@var{f},@var{x})} = @code{@var{f} @var{x}}
  2660. @end table
  2661. The @code{isolate} algorithm can be generalized to functions of
  2662. arbitrarily many variables, but in this document we will need
  2663. only a unary and a binary version. The latter takes an expression
  2664. @code{@var{e}} and a pair of identifiers @code{(@var{x},@var{y})} as
  2665. input, and returns an expression @code{@var{f}} such that
  2666. [[@code{@var{e}}]] = [[@code{@var{f} (@var{x},@var{y})}]].
  2667. @display
  2668. if @code{@var{e}} = @code{@var{x}} then
  2669. return @code{left}
  2670. else if @code{@var{e}} = @code{@var{y}} then
  2671. return @code{right}
  2672. else if @code{@var{e}} is of the form @code{(@var{u},@var{v})}
  2673. return @code{couple(isolate(@var{u},(@var{x},@var{y})),isolate(@var{v},(@var{x},@var{y})))}
  2674. else if @code{@var{e}} is of the form @code{@var{u} @var{v}}
  2675. return @code{(hired apply)(isolate(@var{u},(@var{x},@var{y})),isolate(@var{v},(@var{x},@var{y})))}
  2676. else
  2677. return @code{constant @var{e}}
  2678. @end display
  2679. It might be noted in passing that something similar to these algorithms
  2680. would be needed in a compiler targeted to @code{avram} if the source
  2681. were a functional language with variables.
  2682. @node Metrics and Maintenance, Deconstruction, Variable Freedom, Virtual Code Semantics
  2683. @subsection Metrics and Maintenance
  2684. Certain features of the virtual machine pertain to software development
  2685. and maintenance more than to implementing any particular function. The
  2686. operations with the mnemonics @code{version}, @code{note},
  2687. @code{profile}, and @code{weight} are in this category.
  2688. @menu
  2689. * Version::
  2690. * Note::
  2691. * Profile::
  2692. * Weight::
  2693. @end menu
  2694. @node Version, Note, Metrics and Maintenance, Metrics and Maintenance
  2695. @subsubsection Version
  2696. A virtual code application with exactly the following definition
  2697. implements a function that returns a constant character string
  2698. regardless of its argument.
  2699. @cindex @code{version}
  2700. @example
  2701. version = ((nil,nil),((nil,nil),(nil,((nil,nil),nil))))
  2702. @end example
  2703. @noindent
  2704. The character string encodes the version number of the installed
  2705. @code{avram} executable, for example @code{@value{VERSION}}, using the standard
  2706. representation for characters.
  2707. Although such an application is useless by itself, the intended use for
  2708. this feature is to cope with the possibility that future versions of
  2709. @code{avram} may include enhancements. Ideally, the maintainer of
  2710. @code{avram} will update the version number when new enhancements are
  2711. added. Applications can then detect whether they are available in the
  2712. installed version by using this feature. If a needed enhancement is not
  2713. available, the application can either make allowances or at least
  2714. terminate gracefully.
  2715. @node Note, Profile, Version, Metrics and Maintenance
  2716. @subsubsection Note
  2717. This operation allows arbitrary information or comments to be embedded
  2718. in a virtual code application in such a way that it will be ignored by
  2719. @code{avram} when executing it. For the @code{silly} language, a
  2720. @code{note} function is defined in the standard prelude so as to imply
  2721. the following theorem.
  2722. @cindex @code{note}
  2723. @cindex annotations
  2724. @table @emph
  2725. @item T11
  2726. [[@code{note}]] @code{(@var{f},@var{c})} = @code{((nil,nil),((nil,nil),(nil,(nil,(@var{f},@var{c})))))}
  2727. @end table
  2728. @noindent
  2729. Intuitively, the argument @code{@var{f}} represents a function, and the
  2730. argument @code{c} represents the comment, annotation, or whatever, that
  2731. will be embedded but ignored in the virtual code.
  2732. Semantically, a function with a note attached is the same as the
  2733. function by itself, as the following property stipulates for
  2734. any non-@code{nil} @code{@var{f}}.
  2735. @table @emph
  2736. @item P8
  2737. ([[@code{note}]] @code{(@var{f},@var{c})}) @code{@var{x}} = @code{@var{f} @var{x}}
  2738. @end table
  2739. A possible reason for using this feature might be to support a language
  2740. that performs run-time type checking by hanging type tags on
  2741. @cindex type tags
  2742. everything. Another possible use would be to include symbolic
  2743. information needed by a debugger.
  2744. @node Profile, Weight, Note, Metrics and Maintenance
  2745. @subsubsection Profile
  2746. The virtual machine supports a profiling capability by way of this
  2747. @cindex @file{profile.txt}
  2748. feature. Profiling an application causes run time statistics about it to
  2749. be written to a file @file{./profile.txt}. Profiled applications are of
  2750. the form indicated in the following theorem
  2751. @table @emph
  2752. @item T12
  2753. [[@code{profile}]] @code{(@var{f},@var{s})} = @code{((nil,nil),((nil,nil),(nil,((@var{f},@var{s}),nil))))}
  2754. @end table
  2755. @noindent
  2756. where @code{@var{f}} stands for the virtual code of the application, and
  2757. @code{@var{s}} stands for the name of it to be written to the file.
  2758. The semantics of a profiled function is identical to the unprofiled
  2759. form for any non-@code{nil} @code{@var{f}}.
  2760. @table @emph
  2761. @item P9
  2762. ([[@code{profile}]] @code{(@var{f},@var{s})}) @code{@var{x}} = @code{@var{f} @var{x}}
  2763. @end table
  2764. Unlike the situation with @code{note}, the annotation @code{@var{s}} of
  2765. @cindex @code{note}
  2766. used in profiled code is not in an unrestricted format but must be a
  2767. character string in the standard representation (as in
  2768. @ref{Representation of Numeric and Textual Data}),
  2769. because this string needs to be written by @code{avram} to the file
  2770. @file{./profile.txt}. Ordinarily this string will be the source code
  2771. identifier of the function being profiled.
  2772. When profiles are used in many parts of an application, an informative
  2773. table is generated showing the time spent in each part.
  2774. @node Weight, , Profile, Metrics and Maintenance
  2775. @subsubsection Weight
  2776. The following virtual code implements a function that returns the weight
  2777. of its argument in the standard representation for natural numbers.
  2778. @cindex @code{weight}
  2779. @example
  2780. weight = ((nil,nil),((nil,nil),(nil,(nil,nil))))
  2781. @end example
  2782. @noindent
  2783. The weight of a tree is zero if the tree is @code{nil}, and otherwise
  2784. the sum of the weights of the two subtrees plus one.
  2785. An algorithm to compute the weight of a tree would be trivial to
  2786. implement without being built in to the virtual machine. The built in
  2787. capability could also be used for purposes unrelated to code
  2788. maintenance. Nevertheless, it is built in for the following reasons.
  2789. @itemize @bullet
  2790. @item Computing weights happened to be a bottleneck for a particular
  2791. aspect of code generation that was of interest to the author,
  2792. @cindex compression
  2793. namely the compression of generated code.
  2794. @item A built in implementation in C runs at least an order of magnitude
  2795. faster than the equivalent implementation in virtual code.
  2796. @item It runs even faster when repeated on the same data, by retrieving
  2797. previously calculated weights rather than recalculating them.
  2798. @end itemize
  2799. The only disadvantage of using this feature instead of implementing a
  2800. function in virtual code to compute weights is that it relies on native
  2801. @cindex native integer arithmetic
  2802. @cindex overflow
  2803. integer arithmetic and could overflow, causing a fatal error. It has
  2804. never occurred in practice, but is possible due to sharing, whereby the
  2805. nominal weight of a tree could be exponentially larger than the actual
  2806. amount of memory occupied by it.
  2807. @node Deconstruction, Recursion, Metrics and Maintenance, Virtual Code Semantics
  2808. @subsection Deconstruction
  2809. Much of the time required for evaluating a function is devoted to
  2810. @cindex deconstruction
  2811. performing deconstruction operations, e.g., taking the left side of a
  2812. pair, the tail of a list, the right side of the head of the tail, etc..
  2813. Because these operations are so frequent, there are some features of the
  2814. virtual machine to make them as efficient as possible.
  2815. @menu
  2816. * Field::
  2817. * Fan::
  2818. @end menu
  2819. @node Field, Fan, Deconstruction, Deconstruction
  2820. @subsubsection Field
  2821. The virtual machine supports a generalization of the @code{left} and
  2822. @cindex @code{left}
  2823. @cindex @code{right}
  2824. @code{right} deconstruction operations that is applicable to deeply nested
  2825. structures. Use of this feature is conducive to code that is faster and
  2826. more compact than is possible by relying on the primitive deconstructors
  2827. alone. It may also be easier for a code optimizer to recognize and
  2828. transform.
  2829. The general form of a virtual code application to perform deconstruction
  2830. is that it is a pair with a @code{nil} left side, and a non-@code{nil}
  2831. right side. The right side indicates the nature of the deconstruction to
  2832. be performed when the function is evaluated on an argument.
  2833. To make the expression of deconstruction functions more readable in
  2834. @code{silly}, the standard library contains the declaration
  2835. @example
  2836. field = couple(constant nil,identity)
  2837. @end example
  2838. @noindent
  2839. which implies the following theorem.
  2840. @table @emph
  2841. @item T13
  2842. [[@code{field}]] @code{@var{w}} = @code{(nil,@var{w})}
  2843. @end table
  2844. @cindex @code{field}
  2845. The virtual machine recognizes an application in this form and evaluates
  2846. it according to the following properties, where @code{@var{u}} and
  2847. @code{@var{v}} are other than @code{nil}, but @code{@var{x}},
  2848. @code{@var{y}}, and @code{@var{z}} are unrestricted.
  2849. @table @emph
  2850. @item P10
  2851. ([[@code{field}]] @code{(@var{u},nil)}) @code{(@var{x},@var{y})} = ([[@code{field}]] @code{@var{u}}) @code{@var{x}}
  2852. @item P11
  2853. ([[@code{field}]] @code{(nil,@var{v})}) @code{(@var{x},@var{y})} = ([[@code{field}]] @code{@var{v}}) @code{@var{y}}
  2854. @item P12
  2855. ([[@code{field}]] @code{(@var{u},@code{v})}) @code{@var{z}} = @code{((}[[@code{field}]] @code{@var{u}) @var{z},(}[[@code{field}]] @code{@var{v}) @var{z})}
  2856. @end table
  2857. @noindent
  2858. One might also add that ([[@code{field}]] @code{(nil,nil)})
  2859. @code{@var{z}} = @code{@var{z}}, but this statement would be equivalent to
  2860. @emph{P0}.
  2861. A suitable choice of the @code{field} operand permits the implementation
  2862. of any deconstruction function expressible in terms of @code{compose},
  2863. @code{couple}, @code{identity}, @code{left} and @code{right}. For
  2864. example, the application @code{couple(compose(right,right),left)} has an
  2865. equivalent representation in
  2866. @code{field((nil,(nil,(nil,nil))),((nil,nil),nil))}. The latter looks
  2867. longer in @code{silly} but is smaller and faster in virtual code.
  2868. @node Fan, , Field, Deconstruction
  2869. @subsubsection Fan
  2870. @cindex @code{fan}
  2871. In cases where a deconstructions would be needed to apply the same
  2872. function to both sides of a pair, the overhead can be avoided by means
  2873. of a property of the virtual machine intended for that purpose.
  2874. A @code{silly} definition of @code{fan} implying the following theorem is
  2875. helpful in expressing such an application.
  2876. @table @emph
  2877. @item T14
  2878. [[@code{fan}]] @code{@var{f}} = @code{((nil,nil),((nil,@var{f}),(nil,nil)))}
  2879. @end table
  2880. @noindent
  2881. The virtual machine recognizes when an application has the form shown
  2882. above, and uses @code{@var{f}} as a function to be applied to both sides
  2883. of the argument.
  2884. @table @emph
  2885. @item P13
  2886. ([[@code{fan}]] @code{@var{f}}) @code{(@var{x},@var{y})} = @code{(@var{f} @var{x},@var{f} @var{y})}
  2887. @end table
  2888. @node Recursion, Assignment, Deconstruction, Virtual Code Semantics
  2889. @subsection Recursion
  2890. @cindex recursion
  2891. Defining functions or programs self referentially is sometimes
  2892. informally known as recursion. In functional languages, the clever use
  2893. @cindex combinators
  2894. @cindex functional programming
  2895. of ``combinators'' is often preferred to this practice, and is in fact well
  2896. supported by the virtual machine. However, some computations may be
  2897. inexpressible without an explicitly ``recursive'' formulation, so there
  2898. is some support for that as well.
  2899. @menu
  2900. * Recur::
  2901. * Refer::
  2902. @end menu
  2903. @node Recur, Refer, Recursion, Recursion
  2904. @subsubsection Recur
  2905. @cindex @code{meta}
  2906. @cindex @code{recur}
  2907. A generalization of the form denoted by @code{meta} in @code{silly} is
  2908. recognized by the virtual machine and allows a slightly more efficient
  2909. encoding of recursive applications. An expression @code{recur @var{p}}
  2910. has the representation indicated by this theorem,
  2911. @table @emph
  2912. @item T15
  2913. [[@code{recur}]] @code{@var{p}} = @code{(((nil,@var{p}),nil),nil)}
  2914. @end table
  2915. @noindent
  2916. which implies that [[@code{meta}]] = [[@code{recur}]] @code{(nil,nil)}.
  2917. If @code{@var{p}} is non-@code{nil}, a tree of the form [[@code{recur}]]
  2918. @code{@var{p}} is interpreted as follows. Note that @emph{P4} is
  2919. equivalent to the special case of this property for which @code{@var{p}}
  2920. is @code{(nil,nil)}.
  2921. @table @emph
  2922. @item P14
  2923. ([[@code{recur}]] @code{@var{p}}) @code{@var{x}} = [[@code{meta}]] ([[@code{field}]] @code{@var{p}}) @code{@var{x}}
  2924. @end table
  2925. The rationale is that @code{meta} would very frequently be composed with
  2926. a deconstruction @code{field @var{p}}, so the virtual machine saves some
  2927. time and space by allowing the two of them to be encoded in a smaller
  2928. tree with the combined meaning.
  2929. @node Refer, , Recur, Recursion
  2930. @subsubsection Refer
  2931. @cindex @code{refer}
  2932. In the style of recursive programming compelled by the available
  2933. @code{meta} primitive, a function effectively requires a copy of its own
  2934. machine code as its left argument. Bringing about that state of
  2935. affairs is an interesting party trick.
  2936. @cindex @code{bu}
  2937. If we had a definition of @code{bu} in the standard library implying
  2938. @table @emph
  2939. @item T16
  2940. ([[@code{bu}]] @code{(@var{f},@var{k})}) @code{@var{x}} = @code{@var{f}(@var{k},@var{x})}
  2941. @end table
  2942. @noindent
  2943. which for the sake of concreteness can be done like this,
  2944. @example
  2945. bu = (hired compose)(
  2946. left,
  2947. (hired couple)(compose(constant,right),constant identity))
  2948. @end example
  2949. @noindent
  2950. then a definition of @code{refer} as
  2951. @example
  2952. refer = (hired bu)(identity,identity)
  2953. @end example
  2954. @noindent
  2955. would be consistent with the following property of the operator.
  2956. @table @emph
  2957. @item P15
  2958. ([[@code{refer}]] @code{@var{f}}) @code{@var{x}} = @code{@var{f} (@var{f},@var{x})}
  2959. @end table
  2960. @noindent
  2961. The proof, as always, is a matter of routine calculation in the manner
  2962. of the section on how @code{avram} thinks.
  2963. However, this pattern would occur so frequently in recursively defined
  2964. functions as to be a significant waste of space and time. Therefore,
  2965. rather than requiring it to be defined in terms of other operations, the
  2966. virtual machine specification recognizes a pattern of the form below with
  2967. respect to property @emph{P15},
  2968. @table @emph
  2969. @item T17
  2970. [[@code{refer}]] @code{@var{f}} = @code{(((@var{f},nil),nil),nil)}
  2971. @end table
  2972. @noindent
  2973. and takes the property to be true by definition of the operator. A
  2974. definition of @code{refer} consistent with @emph{T17} is therefore to
  2975. @cindex standard library
  2976. be found in the standard library, not the definition proposed above.
  2977. @node Assignment, Predicates, Recursion, Virtual Code Semantics
  2978. @subsection Assignment
  2979. @cindex assignment
  2980. @cindex imperative programming
  2981. In an imperative programming paradigm, a machine consists partly of an
  2982. ensemble of addressable storage locations, whose contents are changed
  2983. over time by assignment statements. An assignment statement includes
  2984. some computable function of the global machine state, and the address of
  2985. the location whose contents will be overwritten with the value computed
  2986. from the function when it is evaluated.
  2987. Compiling a language containing assignment statements into virtual
  2988. machine code suitable for @code{avram} might be facilitated by
  2989. exploiting the following property.
  2990. @table @emph
  2991. @item P16
  2992. ([[@code{assign}]] @code{(@var{p},@var{f})}) @code{@var{x}} = [[@code{replace}]] @code{((@var{p},@var{f} @var{x}),@var{x})}
  2993. @end table
  2994. @noindent
  2995. The identifier @code{assign} is used in @code{silly} to express a
  2996. virtual code fragment having the form shown below, and @code{replace}
  2997. corresponds to a further operation to be explained presently.
  2998. @cindex @code{assign}
  2999. @table @emph
  3000. @item T18
  3001. [[@code{assign}]] @code{(@var{p},@var{f})} = @code{(((@var{p},@var{f}),nil),nil)}
  3002. @end table
  3003. This feature simulates assignment statements in the following way. The
  3004. variable @code{@var{x}} in @emph{P16} corresponds intuitively to the set
  3005. of addressable locations in the machine. The variable @code{@var{f}}
  3006. corresponds to the function whose value will be stored in the location
  3007. addressed by @code{@var{p}}. The result of a function expressed using
  3008. @code{assign} is a new store similar to the argument @code{@var{x}}, but
  3009. with the part of it in location @code{@var{p}} replaced by @code{@var{f}
  3010. @var{x}}. A source text with a sequence of assignment statements could
  3011. therefore be translated directly into a functional composition of trees
  3012. in this form.
  3013. @cindex storage locations
  3014. The way storage locations are modeled in virtual code using this feature
  3015. would be as nested pairs, and the address @code{@var{p}} of a location
  3016. is a tree interpreted similarly to the trees used as operands to the
  3017. @code{field} operator described in @ref{Field}, to specify
  3018. deconstructions. In fact, @code{replace} can be defined as a minimal
  3019. solution to the following equation.
  3020. @cindex @code{replace}
  3021. @table @emph
  3022. @item E0
  3023. ([[@code{field}]] @code{@var{p}}) [[@code{replace}]] @code{((@var{p},@var{y}),@var{x})} = @code{@var{y}}
  3024. @end table
  3025. This equation regrettably does
  3026. not lend itself to inferring the @code{silly} source for @code{replace}
  3027. @cindex @code{isolate}
  3028. using the @code{isolate} algorithm in @ref{Variable Freedom}, so an explicit
  3029. construction is given in @ref{Replace}. This construction need not concern a
  3030. reader who considers the equation a sufficiently precise specification
  3031. in itself.
  3032. In view of the way addresses for deconstruction are represented as
  3033. trees, it would be entirely correct to infer from this equation that a
  3034. tuple of values computed together can be assigned to a tuple of
  3035. locations. The locations don't even have to be ``contiguous'', but could
  3036. be anywhere in the tree representing the store, and the function is
  3037. computed from the contents of all of them prior to the update. Hence,
  3038. this simulation of assignment fails to capture the full inconvenience of
  3039. imperative programming except in the special case of a single value
  3040. assigned to a single location, but fortunately this case is the only one
  3041. most languages allow.
  3042. There is another benefit to this feature besides running languages with
  3043. assignment statements in them, which is the support of abstract or
  3044. opaque data structures. A function that takes an abstract data structure
  3045. as an argument and returns something of the same type can be coded in a
  3046. way that is independent of the fields it doesn't use. For example, a
  3047. data structure with three fields having the field identifiers
  3048. @code{foo}, @code{bar}, and @code{baz} in some source language might be
  3049. represented as a tuple @code{((@var{foo contents},@var{bar
  3050. contents}),@var{baz contents})} on the virtual code level. Compile time
  3051. constants like @code{bar = ((nil,(nil,nil)),nil)} could be defined in an
  3052. effort to hide the details of the representation, so that the virtual
  3053. code @code{field bar} is used instead of @code{compose(right,left)}.
  3054. Using field identifiers appropriately, a function that transforms such a
  3055. structure by operating on the @code{bar} field could have the virtual
  3056. @cindex @code{field}
  3057. code @code{couple(couple(field foo,compose(f,field bar)),field
  3058. baz)}. However, this code does not avoid depending on the representation
  3059. of the data structure, because it relies on the assumption of the @code{foo}
  3060. field being on the left of the left, and the @code{baz} field being on
  3061. the right. On the other hand, the code @code{assign(bar,compose(f,field
  3062. bar))} does the same job without depending on anything but the position
  3063. of the @code{bar} field. Furthermore, if this position were to change
  3064. relative to the others, the code maintenance would be limited to a
  3065. recompilation.
  3066. @node Predicates, Iteration, Assignment, Virtual Code Semantics
  3067. @subsection Predicates
  3068. @cindex predicates
  3069. A couple of operations are built into the virtual machine for performing
  3070. tests efficiently. These functions return either @code{nil} for false or
  3071. @code{(nil,nil)} for true, and are useful for example as a predicate
  3072. @code{@var{p}} in programs of the form
  3073. @code{conditional(@var{p},(@var{f},@var{g}))} among other things. In
  3074. this example, the predicate is applied to the argument, a result of
  3075. @code{(nil,nil)} causes @code{@var{f}} to be applied to it, and a result
  3076. of @code{nil} causes @code{@var{g}} to be applied to it.
  3077. @menu
  3078. * Compare::
  3079. * Member::
  3080. @end menu
  3081. @node Compare, Member, Predicates, Predicates
  3082. @subsubsection Compare
  3083. @cindex @code{compare}
  3084. A function that performs comparison has a the following very simple
  3085. virtual code representation.
  3086. @table @emph
  3087. @item T19
  3088. [[@code{compare}]] = @code{(nil,nil)}
  3089. @end table
  3090. @noindent
  3091. The proof of theorem @emph{T19} is that the standard @code{silly} prelude
  3092. contains the declaration @code{compare = (nil,nil)}. Code in this form
  3093. has the following semantics.
  3094. @table @emph
  3095. @item P17
  3096. For distinct trees @code{@var{x}} and @code{@var{y}}, [[@code{compare}]] @code{(@var{x},@var{y})} = @code{nil}
  3097. @item P18
  3098. [[@code{compare}]] @code{(@var{x},@var{x})} = @code{(nil,nil)}
  3099. @end table
  3100. @noindent
  3101. @cindex equality
  3102. In other words, the virtual code @code{(nil,nil)} implements a function
  3103. that takes a pair of trees and returns true if and only if they are
  3104. equal.
  3105. It would be fairly simple to write an equivalent virtual code
  3106. application that implements this function if it were not realizable in
  3107. this form by definition of the operator. However, this method is
  3108. preferable because it saves space in virtual code and has a highly
  3109. optimized implementation in C.
  3110. @node Member, , Compare, Predicates
  3111. @subsubsection Member
  3112. Another built in predicate function has the virtual code shown below.
  3113. @cindex @code{member}
  3114. @table @emph
  3115. @item T20
  3116. [[@code{member}]] = @code{((nil,nil),((nil,nil),nil))}
  3117. @end table
  3118. @noindent
  3119. As the mnemonic suggests, the function implemented by this code detects
  3120. whether a given item is a member of a list. The left side of its
  3121. argument is the item to be detected, and the right side is the list that
  3122. may or may not contain it. Lists are represented as explained in
  3123. @ref{Representation of Numeric and Textual Data}.
  3124. The virtual code semantics can be specified by these three properties of
  3125. the operator.
  3126. @table @emph
  3127. @item P19
  3128. [[@code{member}]] @code{(@var{x},nil)} = @code{nil}
  3129. @item P20
  3130. [[@code{member}]] @code{(@var{x},(@var{x},@var{y}))} = @code{(nil,nil)}
  3131. @item P21
  3132. For distinct trees @code{@var{x}} and @code{@var{y}}, [[@code{member}]] @code{(@var{x},(@var{y},@var{z}))} =
  3133. [[@code{member}]] @code{(@var{x},@code{z})}
  3134. @end table
  3135. As in the case of @code{compare}, the implementation of @code{member} is
  3136. well optimized in C, so this form is to be preferred over an ad hoc
  3137. construction of a membership testing function in virtual code.
  3138. @node Iteration, List Combinators, Predicates, Virtual Code Semantics
  3139. @subsection Iteration
  3140. @cindex recursion
  3141. @cindex @code{iterate}
  3142. One of many alternatives to recursion provided by the virtual machine is
  3143. iteration, which allows an operation to be repeated until a condition is
  3144. met. If the source language is imperative, this feature provides an easy
  3145. means of translating loop statements to virtual code. In languages that allow
  3146. functions to be treated as data, iteration can be regarded as a function
  3147. that takes a predicate and a function as arguments, and returns a
  3148. function that applies the given function repeatedly to its argument
  3149. until the predicate is refuted.
  3150. Iterative applications are expressed in virtual code by the pattern shown below.
  3151. @table @emph
  3152. @item T21
  3153. [[@code{iterate}]] @code{(@var{p},@var{f})} = @code{((nil,nil),(nil,(@var{p},@var{f})))}
  3154. @end table
  3155. @noindent
  3156. In the @code{silly} language, the @code{iterate} mnemonic plays the role
  3157. of the function that takes the virtual code for a predicate
  3158. @code{@var{p}} and a function @code{@var{f}} as arguments, and returns
  3159. the virtual code for an iterating function.
  3160. The code for an iterating function is recognized as such by the virtual
  3161. machine emulator only if the subtrees @code{@var{f}} and @code{@var{p}} are other
  3162. than @code{nil}. The resulting function tests the argument
  3163. @code{@var{x}} with @code{@var{p}} and returns @code{@var{x}} if the
  3164. predicate is false.
  3165. @table @emph
  3166. @item P22
  3167. ([[@code{iterate}]] @code{(@var{p},@var{f})}) @code{@var{x}} = @code{@var{x}} if @code{@var{p} @var{x}} = @code{nil}
  3168. @end table
  3169. @noindent
  3170. If the predicate turns out to be true, @code{@var{f}} is applied to
  3171. @code{@var{x}}, and then another iteration is performed.
  3172. @table @emph
  3173. @item P23
  3174. ([[@code{iterate}]] @code{(@var{p},@var{f})}) @code{@var{x}} =
  3175. ([[@code{iterate}]] @code{(@var{p},@var{f})}) @code{@var{f} @var{x}} if @code{@var{p} @var{x}} is a non-@code{nil} tree
  3176. @end table
  3177. @node List Combinators, List Functions, Iteration, Virtual Code Semantics
  3178. @subsection List Combinators
  3179. @cindex lists
  3180. @cindex imperative programming
  3181. @cindex functional programming
  3182. There is extensive support for operations on lists in the virtual code
  3183. format. Use of these features is encouraged because they are conducive
  3184. to tight code with explicit concurrency. Within an imperative
  3185. programming paradigm, these features might perhaps have to be understood
  3186. as design patterns or algorithmic skeletons. The present exposition
  3187. takes a functional view, describing them in terms of operators that take
  3188. functions as their arguments and return functions as their result.
  3189. @menu
  3190. * Map::
  3191. * Filter::
  3192. * Reduce::
  3193. * Sort::
  3194. * Transfer::
  3195. * Mapcur::
  3196. @end menu
  3197. @node Map, Filter, List Combinators, List Combinators
  3198. @subsubsection Map
  3199. A virtual code application in the following form causes a function with
  3200. non-@code{nil} virtual code @code{@var{f}} to be applied to every item
  3201. in a list.
  3202. @table @emph
  3203. @item T22
  3204. [[@code{map}]] @code{@var{f}} = @code{((nil,nil),((nil,@var{f}),nil))}
  3205. @end table
  3206. @noindent
  3207. @cindex @code{map}
  3208. The @code{map} mnemonic is used in @code{silly} to express applications
  3209. in this form as @code{map @var{f}}. This operation is also well known to
  3210. lisp users and functional programmers. The semantics is determined by
  3211. these two operator properties (for non-@code{nil} @code{@var{f}}).
  3212. @table @emph
  3213. @item P24
  3214. ([[@code{map}]] @code{@var{f}}) @code{nil} = @code{nil}
  3215. @item P25
  3216. ([[@code{map}]] @code{@var{f}}) @code{(@var{x},@var{y})} = @code{(@var{f} @var{x},(}[[@code{map}]] @code{@var{f}) @var{y})}
  3217. @end table
  3218. @noindent
  3219. Note that the representation of lists described in
  3220. @ref{Representation of Numeric and Textual Data}, is assumed.
  3221. @node Filter, Reduce, Map, List Combinators
  3222. @subsubsection Filter
  3223. @cindex @code{filter}
  3224. Another well known list operation is that which applies a predicate to
  3225. every item of a list, and deletes those for which the predicate is
  3226. false. For a predicate with virtual code @code{@var{p}}, such an
  3227. application can be coded conveniently in this form,
  3228. @table @emph
  3229. @item T23
  3230. [[@code{filter}]] @code{@var{p}} = @code{((nil,nil),(nil,(@var{p},nil)))}
  3231. @end table
  3232. @noindent
  3233. which is to say that writing @code{((nil,nil),(nil,(@var{p},nil)))} in
  3234. @code{silly} is the same as writing @code{filter @var{p}}.
  3235. The virtual machine detects code of this form provided that
  3236. @code{@var{p}} is other than @code{nil}, and evaluates it consistently
  3237. with the following properties, causing it to have the meaning that it
  3238. does.
  3239. @table @emph
  3240. @item P26
  3241. ([[@code{filter}]] @code{@var{p}}) @code{nil} = @code{nil}
  3242. @item P27
  3243. ([[@code{filter}]] @code{@var{p}}) @code{(@var{x},@var{y})} =
  3244. ([[@code{filter}]] @code{@var{p}}) @code{@var{y}} if @code{@var{p} @code{@var{x}}} = @code{nil}
  3245. @item P28
  3246. ([[@code{filter}]] @code{@var{p}}) @code{(@var{x},@var{y})} =
  3247. @code{(@var{x},}([[@code{filter}]] @code{@var{p}}) @code{@var{y})} if @code{@var{p} @var{x}} is a non-@code{nil} tree
  3248. @end table
  3249. @node Reduce, Sort, Filter, List Combinators
  3250. @subsubsection Reduce
  3251. @cindex @code{reduce}
  3252. In the virtual code fragment shown below, @code{@var{f}} should be
  3253. regarded as the virtual code for a binary operator, and @code{@var{k}}
  3254. is a constant.
  3255. @table @emph
  3256. @item T24
  3257. [[@code{reduce}]] @code{(@var{f},@var{k})} = @code{((nil,nil),((@var{f},@var{k}),nil))}
  3258. @end table
  3259. @noindent
  3260. By constructing a tree in the form shown, the @code{silly}
  3261. mnemonic @code{reduce} effectively constructs the code for a function
  3262. operating on lists in a particular way.
  3263. The effect of evaluating an application in this form with an argument
  3264. representing a list can be broken down into several cases.
  3265. @itemize @bullet
  3266. @item If the list is empty, then the value of @code{@var{k}} is the
  3267. result.
  3268. @item If the list has only one item, then that item is the result.
  3269. @item if the list has exactly two items, the first being @code{@var{x}} and the
  3270. second being @code{@var{y}}, then the result is @code{@var{f}
  3271. (@var{x},@var{y})}.
  3272. @item If the list has more than two items and an even number of them, the
  3273. result is that of evaluating the application with the list of values
  3274. obtained by partitioning the list into pairs of adjacent items, and
  3275. evaluating @code{@var{f}} with each pair.
  3276. @item If the list has more than two items and an odd number of them, the
  3277. result is that of evaluating the application with the list of values
  3278. obtained by partitioning the list into pairs of adjacent items excluding
  3279. the last one, evaluating @code{@var{f}} with each pair, and then
  3280. appending the last item to the list of values.
  3281. @end itemize
  3282. @noindent
  3283. In the last two cases, evaluation of the application is not necessarily
  3284. finished after just one traversal of the list, because it has to carry
  3285. on until the list is reduced to a single item.
  3286. Some care has been taken to describe this operation in detail because it
  3287. differs from comparable operations common to functional programming
  3288. @cindex fold
  3289. languages, variously known as fold or reduce. All of these operations
  3290. could be used, for example, to compute the summation of a list of
  3291. numbers. The crucial differences are as follows.
  3292. @itemize @bullet
  3293. @item Whereas a fold or a reduce is conventionally either of the left or
  3294. right variety, this @code{reduce} is neither.
  3295. @item The vacuous case result @code{@var{k}} is never used at all unless
  3296. the argument is the empty list.
  3297. @item This @code{reduce} is not very useful if the operator
  3298. @code{@var{f}} is not associative.
  3299. @end itemize
  3300. The reason for defining the semantics of @code{reduce} in this way
  3301. instead of the normal way is that a distributed implementation of this
  3302. @cindex distributed implementation
  3303. one could work in logarithmic time, so it's worth making it easy for a
  3304. language processor to detect the pattern in case the virtual code is
  3305. ever going to be targeted to such an implementation. Of course, nothing
  3306. prevents the conventional left or right reduction semantics from being
  3307. translated to virtual code by explicit recursion.
  3308. @cindex recursion
  3309. The precise semantics of this operation are as follows, where
  3310. @code{@var{f}} is not @code{nil}, @code{@var{k}} is unconstrained, and
  3311. @code{pairwise} represents a function to be explained presently.
  3312. @cindex @code{iterate}
  3313. @cindex @code{pairwise}
  3314. @cindex @code{bu}
  3315. @cindex @code{right}
  3316. @table @emph
  3317. @item P29
  3318. ([[@code{reduce}]] @code{(@var{f},@var{k})}) @code{nil} = @code{@var{k}}
  3319. @item P30
  3320. ([[@code{reduce}]] @code{(@var{f},@var{k})}) @code{(@var{x},@var{y})} = @*
  3321. @w{ }@w{ }@w{ }
  3322. [[@code{left}]] ([[@code{bu(iterate,right)}]] [[@code{pairwise}]] @code{@var{f}}) @code{(@var{x},@var{y})}
  3323. @end table
  3324. @noindent
  3325. The latter property leverages off some virtual machine features and
  3326. @code{silly} code that has been defined already. The function
  3327. implemented by [[@code{pairwise}]] @code{@var{f}} is the one that
  3328. partitions its argument into pairs and evaluates @code{@var{f}} with
  3329. each pair as described above. The combination of that with
  3330. @code{bu(iterate,right)} results in an application that repeatedly
  3331. performs [[@code{pairwise}]] @code{@var{f}} while the resulting list
  3332. still has a tail (i.e., a @code{right} side), and stops when the list
  3333. has only a single item (i.e., when @code{right} is false). The
  3334. @code{left} operation then extracts the item.
  3335. For the sake of completeness, it is tedious but straightforward to
  3336. give an exact definition for @code{pairwise}. The short version is that
  3337. it can be anything that satisfies these three equations.
  3338. @table @emph
  3339. @item E1
  3340. ([[@code{pairwise}]] @code{@var{f}}) @code{nil} = @code{nil}
  3341. @item E2
  3342. ([[@code{pairwise}]] @code{@var{f}}) @code{(@var{x},nil)} = @code{(@var{x},nil)}
  3343. @item E3
  3344. ([[@code{pairwise}]] @code{@var{f}}) @code{(@var{x},(@var{y},@var{z}))} =
  3345. @code{(@var{f} (@var{x},@var{y}),}([[@code{pairwise}]] @code{@var{f}}) @code{@var{z})}
  3346. @end table
  3347. @noindent
  3348. For the long version, see @ref{Pairwise}.
  3349. @node Sort, Transfer, Reduce, List Combinators
  3350. @subsubsection Sort
  3351. @cindex @code{sort}
  3352. Sorting is a frequently used operation that has the following standard
  3353. representation in virtual code.
  3354. @table @emph
  3355. @item T25
  3356. [[@code{sort}]] @code{@var{p}} = @code{((nil,nil),((@var{p},nil),(nil,nil)))}
  3357. @end table
  3358. @noindent
  3359. When an application in this form is evaluated with an operand
  3360. representing a list, the result is a sorted version of the list.
  3361. The way a list is sorted depends on what order is of interest. For
  3362. example, numbers could be sorted in ascending or descending order,
  3363. character strings could be sorted lexically or by length, etc.. The
  3364. value of @code{@var{p}} is therefore needed in sorting applications to
  3365. specify the order. It contains the virtual code for a partial order
  3366. relational operator. This operator can be evaluated with any pair of
  3367. items selected from a list, and should have a value of true if the left
  3368. one should precede the right under the ordering. For example, if numbers
  3369. were to be sorted in ascending order, then @code{@var{p}} would compute
  3370. the ``less or equal'' relation, returning true if its operand were a
  3371. pair of numbers in which the left is less or equal to the right.
  3372. The virtual code semantics for sorting applications is given by these
  3373. two properties, wherein @code{@var{p}} is a non-@code{nil} tree, and
  3374. @code{insert} is a @code{silly} mnemonic to be defined next.
  3375. @cindex @code{insert}
  3376. @table @emph
  3377. @item P31
  3378. ([[@code{sort}]] @code{@var{p}}) @code{nil} = @code{nil}
  3379. @item P32
  3380. ([[@code{sort}]] @code{@var{p}}) @code{(@var{x},@var{y})} = ([[@code{insert}]] @code{@var{p}})
  3381. @code{(@var{x},}([[@code{sort}]] @code{@var{p}}) @code{@var{y})}
  3382. @end table
  3383. @noindent
  3384. These properties say that the empty list is already sorted, and
  3385. a non-empty list is sorted if its tail is sorted and the head is then
  3386. inserted in the proper place. This specification of sorting has nothing
  3387. to do with the sorting algorithm that @code{avram} really uses.
  3388. The meaning of insertion is convenient to specify in virtual code
  3389. itself. It should satisfy these three equations.
  3390. @table @emph
  3391. @item E4
  3392. ([[@code{insert}]] @code{@var{p}}) @code{(@var{x},nil)} = @code{(@var{x},nil)}
  3393. @item E5
  3394. ([[@code{insert}]] @code{@var{p}}) @code{(@var{x},(@var{y},@var{z}))} =
  3395. @code{(@var{y},}([[@code{insert}]] @code{@var{p}}) @code{(@var{x},@var{z}))}
  3396. if @code{@var{p}(@var{x},@var{y})} = @code{nil}
  3397. @item E6
  3398. ([[@code{insert}]] @code{@var{p}}) @code{(@var{x},(@var{y},@var{z})}) =
  3399. @code{(@var{x},(@var{y},@var{z}))} if @code{@var{p}(@var{x},@var{y})} is a non-@code{nil} tree
  3400. @end table
  3401. @noindent
  3402. Intuitively, the right argument, whether @code{nil} or
  3403. @code{(@var{y},@var{z})}, represents a list that is already sorted. The
  3404. left argument @code{@var{x}} therefore only needs to be compared to the
  3405. head element, @code{@var{y}} to ascertain whether or not it belongs at
  3406. the beginning. If not, it should be inserted into the tail.
  3407. A possible implementation of @code{insert} in @code{silly} is given in
  3408. @ref{Insert}.
  3409. @node Transfer, Mapcur, Sort, List Combinators
  3410. @subsubsection Transfer
  3411. @cindex @code{transfer}
  3412. A particular interpretation is given to virtual code in the following form.
  3413. @table @emph
  3414. @item T26
  3415. [[@code{transfer}]] @code{@var{f}} = @code{((nil,nil),(nil,(nil,@var{f})))}
  3416. @end table
  3417. @noindent
  3418. When code in this form is evaluated with an argument, the tree
  3419. @cindex state transition function
  3420. @code{@var{f}} is used as a state transition function, and the argument
  3421. is used as a list to be traversed. The traversal begins with
  3422. @code{@var{f}} being evaluated on @code{nil} to get the initial state
  3423. and the initial output. Thereafter, each item of the list is paired with
  3424. the current state to be evaluated with @code{@var{f}}, resulting in a
  3425. list of output and the next state. The output resulting from the entire
  3426. application is the cumulative concatenation of all outputs obtained in
  3427. the course of evaluating @code{@var{f}}. The computation
  3428. terminates when @code{@var{f}} yields a @code{nil} result. If the list
  3429. of inputs runs out before the computation terminates, @code{nil} values
  3430. are used as inputs.
  3431. This behavior is specified more precisely in the following property
  3432. of the operator, which applies in the case of non-@code{nil} @code{@var{f}}.
  3433. @cindex @code{transition}
  3434. @table @emph
  3435. @item P33
  3436. ([[@code{transfer}]] @code{@var{f}}) @code{@var{x}} =
  3437. ([[@code{transition}]] @code{@var{f}}) @code{(nil,(@var{f} nil,@var{x}))}
  3438. @end table
  3439. Much of the @code{transfer} semantics is implicit in the meaning of
  3440. @code{transition}. For any given application @code{@var{f}},
  3441. [[@code{transition}]] @code{@var{f}} is the virtual code for a function
  3442. that takes the list traversal from one configuration to the next.
  3443. A configuration is represented as a tuple, usually in the form
  3444. @code{(@var{previous outputs},((@var{state},@var{output}),(@var{next input},@var{subsequent
  3445. inputs})))}. A terminal configuration has the form
  3446. @code{(@var{previous outputs},(nil,(@var{next input},@var{subsequent
  3447. inputs})))}. A configuration may also have @code{nil} in place of the
  3448. pair @code{(@var{next input},@var{subsequent inputs})} if no more input
  3449. remains.
  3450. In the non-degenerate case, the meaning of [[@code{transition}]]
  3451. @code{@var{f}} is consistent with the following equation.
  3452. @table @emph
  3453. @item E7
  3454. ([[@code{transition}]] @code{@var{f}}) @code{(@var{y},((@var{s},@var{o}),(@var{i},@var{x})))} =@*
  3455. @w{ }@w{ }@w{ }@w{ }([[@code{transition}]] @code{@var{f}}) @code{((@var{o},@var{y}),(@var{f} (@var{s},@var{i}),@var{x}))}
  3456. @end table
  3457. @noindent
  3458. That is, the current output @code{@var{o}} is stored with previous outputs @code{@var{y}}, the next
  3459. input @code{@var{i}} is removed from the configuration, and the next state and output
  3460. are obtained from the evaluation of @code{@var{f}} with the state @code{@var{s}} and
  3461. the next input @code{@var{i}}.
  3462. In the case where no input remains, the transition function is
  3463. consistent with the following equation.
  3464. @table @emph
  3465. @item E8
  3466. ([[@code{transition}]] @code{@var{f}}) @code{(@var{y},((@var{s},@var{o}),nil))} = @*
  3467. @w{ }@w{ }@w{ }@w{ }([[@code{transition}]] @code{@var{f}}) @code{((@var{o},@var{y}),(@var{f} (@var{s},nil),nil))}
  3468. @end table
  3469. @noindent
  3470. This case is similar to the previous one except that the @code{nil}
  3471. value is used in place of the next input. Note that in either case,
  3472. nothing about @code{@var{f}} depends on the particular way
  3473. configurations are represented, except that it should have a state as
  3474. its left argument and an input as its right argument.
  3475. Finally, in the case of a terminal configuration, the transition
  3476. function returns the cumulative output.
  3477. @table @emph
  3478. @item E9
  3479. ([[@code{transition}]] @code{@var{f}}) @code{(@var{y},(nil,@var{x}))} =
  3480. [[@code{reduce(cat,nil)}]] [[@code{reverse}]] @code{@var{y}}
  3481. @end table
  3482. @noindent
  3483. The @code{silly} code @code{reduce(cat,nil)} has the effect of
  3484. @cindex @code{cat}
  3485. @cindex concatenation
  3486. flattening a list of lists into one long list, which is necessary
  3487. insofar as the transition function will have generated not necessarily a
  3488. single output but a list of outputs on each iteration. The @code{cat}
  3489. mnemonic stands for list concatenation and is explained in @ref{Cat}.
  3490. The reversal is necessary to cause the first generated output to be at
  3491. the head of the list. List reversal is a built in operation of the
  3492. virtual machine and is described in @ref{Reverse}.
  3493. If such a function as @code{transition} seems implausible, its
  3494. implementation in @code{silly} can be found in @ref{Transition}.
  3495. It is usually more awkward to express a function in terms of
  3496. a @code{transfer} than to code it directly using recursion or other list
  3497. operations. However, this feature is provided by the virtual machine for
  3498. several reasons.
  3499. @itemize @bullet
  3500. @item Functions in this form may be an easier translation target if the
  3501. source is an imperative language.
  3502. @item Translating from virtual code to asynchronous circuits or process
  3503. @cindex asynchronous circuits
  3504. networks has been a research interest of the author, and code in this
  3505. @cindex author
  3506. form lends itself to easy recognition and mapping onto discrete components.
  3507. @item The @option{--byte-transducer} and @option{--interactive} command
  3508. line options to @code{avram} cause an application to be invoked in a
  3509. @cindex state transition function
  3510. similar manner to the transition function in a @code{transfer}
  3511. function, so this feature allows for easy simulation and troubleshooting
  3512. of these applications without actually deploying them.
  3513. @end itemize
  3514. @node Mapcur, , Transfer, List Combinators
  3515. @subsubsection Mapcur
  3516. An alternative form of recursive definition is the following.
  3517. @cindex @code{mapcur}
  3518. @table @emph
  3519. @item T27
  3520. [[@code{mapcur}]] @code{@var{p}} = @code{((nil,nil),((nil,nil),(@var{p},nil)))}
  3521. @end table
  3522. @noindent
  3523. This form is convenient for applications that cause themselves to be
  3524. @cindex recursion
  3525. applied recursively to a list of arguments. It has this semantics.
  3526. @table @emph
  3527. @item P34
  3528. ([[@code{mapcur}]] @code{@var{p}}) @code{@var{x}} =
  3529. [[@code{map meta}]] [[@code{distribute}]] ([[@code{field}]] @code{@var{p}}) @code{@var{x}}
  3530. @end table
  3531. @node List Functions, Exception Handling, List Combinators, Virtual Code Semantics
  3532. @subsection List Functions
  3533. In addition to the foregoing list operations, the virtual machine
  3534. @cindex lists
  3535. provides a number of canned functions operating on lists, namely
  3536. concatenation, reversal, distribution, and transposition. These
  3537. functions could be coded by other means if they were not built in, but
  3538. the built in versions are faster and smaller.
  3539. @menu
  3540. * Cat::
  3541. * Reverse::
  3542. * Distribute::
  3543. * Transpose::
  3544. @end menu
  3545. @node Cat, Reverse, List Functions, List Functions
  3546. @subsubsection Cat
  3547. The list concatenation operation has this representation in virtual code.
  3548. @cindex @code{cat}
  3549. @cindex concatenation
  3550. @table @emph
  3551. @item T28
  3552. [[@code{cat}]] = @code{((nil,nil),(nil,nil))}
  3553. @end table
  3554. @noindent
  3555. This function takes a pair of lists as an argument, an returns the list
  3556. obtained by appending the right one to the left. The semantics of
  3557. concatenation is what one would expect.
  3558. @table @emph
  3559. @item P35
  3560. [[@code{cat}]] @code{(nil,@var{z})} = @code{@var{z}}
  3561. @item P36
  3562. [[@code{cat}]] @code{((@var{x},@var{y}),@var{z})} = @code{(@var{x},}[[@code{cat}]] @code{(@var{y},@code{z}))}
  3563. @end table
  3564. @node Reverse, Distribute, Cat, List Functions
  3565. @subsubsection Reverse
  3566. @cindex @code{reverse}
  3567. The function that reverses a list has the following representation in
  3568. virtual code.
  3569. @table @emph
  3570. @item T29
  3571. [[@code{reverse}]] = @code{((nil,nil),(nil,(nil,nil)))}
  3572. @end table
  3573. @noindent
  3574. This function takes a list as an argument, and returns a the list
  3575. consisting of the same items in the reverse order. The semantics is
  3576. given by the following properties.
  3577. @table @emph
  3578. @item P37
  3579. [[@code{reverse}]] @code{nil} = @code{nil}
  3580. @item P38
  3581. [[@code{reverse}]] @code{(@var{x},@var{y})} = [[@code{cat}]] ([[@code{reverse}]] @code{@var{y},(@var{x},nil)})
  3582. @end table
  3583. @node Distribute, Transpose, Reverse, List Functions
  3584. @subsubsection Distribute
  3585. The function with the following virtual code representation is
  3586. frequently useful for manipulating lists.
  3587. @cindex @code{distribute}
  3588. @table @emph
  3589. @item T30
  3590. @code{distribute} = @code{(((nil,nil),nil),nil)}
  3591. @end table
  3592. @noindent
  3593. This function takes a pair whose right side represents a list, and
  3594. returns a list of pairs, with one pair for each item in the list. The
  3595. left side of each pair is the left side of the original argument, and
  3596. the right side is the corresponding item of the list. A semantics for
  3597. this operation is specified by the following properties.
  3598. @table @emph
  3599. @item P39
  3600. [[@code{distribute}]] @code{(@var{x},nil)} = @code{nil}
  3601. @item P40
  3602. [[@code{distribute}]] @code{(@var{x},(@var{y},@var{z}))} =
  3603. @code{((@var{x},@var{y}),}[[@code{distribute}]] @code{(@var{x},@var{z}))}
  3604. @end table
  3605. @node Transpose, , Distribute, List Functions
  3606. @subsubsection Transpose
  3607. The @code{transpose} operation has the following representation in
  3608. virtual code.
  3609. @table @emph
  3610. @item T31
  3611. [[@code{transpose}]] = @code{((nil,nil),((nil,nil),(nil,nil)))}
  3612. @end table
  3613. @noindent
  3614. @cindex @code{transpose}
  3615. This function takes a list of equal length lists as an argument, and
  3616. returns a list of lists as a result. In the resulting list, the first
  3617. item is the list of all first items of lists in the argument. The next
  3618. item is the list of all second items, and so on.
  3619. In the specification of the semantics, the @code{silly} mnemonic
  3620. @cindex @code{flat}
  3621. @code{flat} is defined by @code{flat = reduce(cat,nil)} in the standard
  3622. @code{silly} prelude, which means that it flattens a list of lists into
  3623. one long list.
  3624. @table @emph
  3625. @item P41
  3626. [[@code{transpose}]] @code{@var{x}} = @code{nil} if [[@code{flat}]] @code{@var{x}} = @code{nil}
  3627. @item P42
  3628. [[@code{transpose}]] @code{@var{x}} =
  3629. @code{(}[[@code{map left}]] @code{@var{x},}[[@code{transpose}]] [[@code{map right}]] @code{@var{x})}@*
  3630. @w{ }@w{ }@w{ } if [[@code{flat}]] @code{@var{x}} is a non-@code{nil} tree
  3631. @end table
  3632. @node Exception Handling, Interfaces to External Code, List Functions, Virtual Code Semantics
  3633. @subsection Exception Handling
  3634. @cindex exceptions
  3635. In quite a few cases, the properties given for the operator up to this
  3636. point do not imply any particular result. A good example would be an
  3637. expression such as [[@code{left}]] @code{nil}, which appears to
  3638. represent the left side of an empty pair. It can be argued that
  3639. expressions like this have no sensible interpretation and should never
  3640. be used, so it would be appropriate to leave them undefined. On the
  3641. other hand, attempts to evaluate such expressions occur frequently by
  3642. mistake, and in any case, the virtual machine emulator should be
  3643. designed to do something reasonable about them if only for the sake of
  3644. reporting the error. The chosen remedy for this situation addresses the
  3645. need for error reporting, and also turns out to be useful in other ways.
  3646. @menu
  3647. * A Hierarchy of Sets::
  3648. * Operator Generalization::
  3649. * Error Messages::
  3650. * Expedient Error Messages::
  3651. * Computable Error Messages::
  3652. * Exception Handler Usage::
  3653. @end menu
  3654. @node A Hierarchy of Sets, Operator Generalization, Exception Handling, Exception Handling
  3655. @subsubsection A Hierarchy of Sets
  3656. As indicated already, the virtual machine represents all functions and
  3657. data as members of a set satisfying the properties in @ref{Raw Material},
  3658. namely a @code{nil} element and a @code{cons} operator for constructing
  3659. trees or nested pairs of @code{nil}. However, it will be necessary to
  3660. distinguish the results of computations that go wrong for exceptional
  3661. reasons from normal results. Because any tree in the set could conceivably
  3662. represent a normal result, we need to go outside the set to find an
  3663. unambiguous representation of exceptional results.
  3664. Because there may be many possible exceptional conditions, it will be helpful
  3665. to have a large set of possible ways to encode them, and in fact there
  3666. is no need to refrain from choosing a countably infinite
  3667. set. Furthermore, it will be useful to distinguish between different
  3668. levels of severity among exceptional conditions, so for this purpose a
  3669. countably infinite hierarchy of mutually disjoint sets is used.
  3670. In order to build on the theory already developed, the set that has been
  3671. used up to this point will form the bottom level of the hierarchy, and
  3672. its members will represent normal computational results. The members of
  3673. sets on the higher levels in the hierarchy represent exceptional
  3674. results. To avoid ambiguity, the term ``trees'' is reserved for members
  3675. @cindex trees
  3676. of the bottom set, as in ``for any tree @code{@var{x}} @dots{}''.
  3677. Unless otherwise stated, variables like @code{@var{x}} and
  3678. @code{@var{y}} are universally quantified over the bottom set only.
  3679. @cindex universal quantification
  3680. Because each set in the hierarchy is countably infinite, it is
  3681. isomorphic to the bottom set. With respect to an arbitrary but fixed
  3682. bijection between them, let @code{@var{x}_@var{n}} denote the image in
  3683. the @code{@var{n}}th level set of a tree @code{@var{x}} in the bottom
  3684. set. The level numbers in this notation start with zero, and we take
  3685. @code{@var{x}_0} to be synonymous with @code{@var{x}}. For good measure,
  3686. let @code{(@var{x}_@var{n})_@var{m}} = @code{@var{x}_(@var{n}+@var{m})}.
  3687. @node Operator Generalization, Error Messages, A Hierarchy of Sets, Exception Handling
  3688. @subsubsection Operator Generalization
  3689. Each set in the hierarchy induces a structure preserving @code{cons}
  3690. @cindex @code{cons}
  3691. operator, denoted @code{cons_@var{n}} for the @code{@var{n}}th level
  3692. set, and satisfying this equation.
  3693. @table @emph
  3694. @item E10
  3695. @code{cons_@var{n}(@var{x}_@var{n},@var{y}_@var{n})} =
  3696. @code{(cons(@var{x},@var{y}))_@var{n}}
  3697. @end table
  3698. @noindent
  3699. It will be convenient to generalize all of these @code{cons} operators to be
  3700. defined on members of other sets than their own.
  3701. @table @emph
  3702. @item E11
  3703. For @code{@var{m}} greater than @code{@var{n}},
  3704. @w{ } @w{ } @w{ } @code{cons_@var{n}(@var{x}_@var{m},@var{y}_@var{p})} =
  3705. @code{@var{x}_@var{m}}
  3706. @end table
  3707. @noindent
  3708. In this equation, @code{@var{p}} is unrestricted. The intuition is that
  3709. if the left operand of a @code{cons} is the result of a computation that
  3710. went wrong due to an exceptional condition (more exceptional than
  3711. @code{@var{n}}, the level already in effect), then the exceptional
  3712. result becomes the whole result.
  3713. It is tempting to hazard a slightly stronger statement, which is that
  3714. this equation holds even if @code{@var{y}_@var{p}} is equal to some
  3715. expression @code{@var{f} @var{x}} that is undefined according to the
  3716. operator semantics. This stipulation would correspond to an
  3717. implementation in which the right operand isn't evaluated after an error
  3718. is detected in the left, but there are two problems with it.
  3719. @itemize @bullet
  3720. @item This semantics might unreasonably complicate a concurrent
  3721. implementation of the virtual machine. If evaluation leads to
  3722. non-termination in some cases where the result is undefined (as it certainly
  3723. would in any possible implementation consistent with cases where it's
  3724. defined), then the mechanism that evaluates the right side of a pair
  3725. must be interruptible in case an exception is detected in the left.
  3726. @item It is beyond the expressive power of the present mathematical
  3727. framework to make such a statement, because it entails universal
  3728. quantification over non-members of the constructed sets, which includes
  3729. @cindex universal quantification
  3730. almost everything.
  3731. @end itemize
  3732. @noindent
  3733. Nevertheless, the implementation in @code{avram} is sequential and does
  3734. indeed behave as proposed, with no practical difficulty. As for any
  3735. deficiency in the theory, it could be banished by recasting the
  3736. semantics in terms of a calculus of expressions with formal rules of
  3737. manipulation. An operand to the @code{cons} operator would be identified
  3738. not with a member of a semantic domain, but with the expression used to
  3739. write it down, and then even ``undefinedness'' could be
  3740. @cindex undefined expressions
  3741. defined. However, the present author's preference in computing as in
  3742. @cindex author
  3743. life is to let some things remain a mystery rather than to abandon the
  3744. quest for meaning entirely.
  3745. A comparable condition applies in cases where the right side of a pair
  3746. represents an exceptional result.
  3747. @table @emph
  3748. @item E12
  3749. For @code{@var{m}} greater than @code{@var{n}},
  3750. @w{ } @w{ } @code{cons_@var{n}(@var{x}_@var{n},@var{y}_@var{m})} =
  3751. @code{@var{y}_@var{m}}
  3752. @end table
  3753. Whereas an infinitude of @code{cons} operators has been needed, it will
  3754. @cindex @code{cons}
  3755. be possible to get by with only one invisible operator, as before, by
  3756. generalizing it in the following way to operands on any level of the
  3757. hierarchy.
  3758. @table @emph
  3759. @item P43
  3760. @code{@var{f}_@var{n} @var{x}_@var{n}} = @code{(@var{f} @var{x})_@var{n}}
  3761. @item P44
  3762. For distinct @code{@var{n}} and @code{@var{m}}, @w{ }@code{@var{f}_@var{n} @var{x}_@var{m}} = @code{@var{x}_@var{m}}
  3763. @end table
  3764. @noindent
  3765. That is, the result of evaluating two operands on the same level is the
  3766. image relative to that level of the result of their respective images on
  3767. the bottom level, but the result of evaluating two operands on different
  3768. levels is the same as the right operand.
  3769. @node Error Messages, Expedient Error Messages, Operator Generalization, Exception Handling
  3770. @subsubsection Error Messages
  3771. The basic strategy for representing the results of exceptional
  3772. conditions arising from the evaluation of operands on a given level of
  3773. the hierarchy will be to use an error message corresponding to the image
  3774. of a list of character strings on the level above.
  3775. Unfortunately, the official @code{silly} standard does not
  3776. define character constants, but they are available as a vendor specific
  3777. extension in @code{silly-me} (millennium edition), where character strings
  3778. @cindex @code{silly-me}
  3779. @cindex strings
  3780. @cindex character strings
  3781. may be enclosed in single quotes. The value of the semantic
  3782. @cindex semantic function
  3783. function [[@dots{}]] in the case of a character string is the list
  3784. of representations of the characters, based on @ref{Character Table}
  3785. and @ref{Representation of Numeric and Textual Data}.
  3786. For the sake of consistency, each standard error message is a list of
  3787. character strings, even though the list has only one string in it. If
  3788. any exceptional condition is the result of a computation, it is written
  3789. to standard error by @code{avram} as the list of character strings it
  3790. represents.
  3791. @table @emph
  3792. @item P45
  3793. ([[@code{compare}]] @code{nil})@code{_@var{n}} = [[@code{('invalid comparison',nil)}]]@code{_(@var{n}+1)}
  3794. @item P46
  3795. ([[@code{left}]] @code{nil})@code{_@var{n}} = [[@code{('invalid deconstruction',nil)}]]@code{_(@var{n}+1)}
  3796. @item P47
  3797. ([[@code{right}]] @code{nil})@code{_@var{n}} = [[@code{('invalid deconstruction',nil)}]]@code{_(@var{n}+1)}
  3798. @item P48
  3799. (([[@code{fan}]] @code{@var{f}})
  3800. @code{nil})@code{_@var{n}} = [[@code{('invalid deconstruction',nil)}]]@code{_(@var{n}+1)}
  3801. @item P49
  3802. ([[@code{member}]] @code{nil})@code{_@var{n}} = [[@code{('invalid membership',nil)}]]@code{_(@var{n}+1)}
  3803. @item P50
  3804. ([[@code{distribute}]] @code{nil})@code{_@var{n}} = [[@code{('invalid distribution',nil)}]]@code{_(@var{n}+1)}
  3805. @item P51
  3806. ([[@code{cat}]] @code{nil})@code{_@var{n}} = [[@code{('invalid concatenation',nil)}]]@code{_(@var{n}+1)}
  3807. @item P52
  3808. ([[@code{meta}]] @code{nil})@code{_@var{n}} = [[@code{('invalid recursion',nil)}]]@code{_(@var{n}+1)}
  3809. @end table
  3810. Note that by virtue of property @emph{P44}, there is no need for an
  3811. application to make explicit checks for exceptional results at any
  3812. point, because the exceptional result propagates through to the output
  3813. of any function composed with the one that incurred it. For example, an
  3814. application of the form @code{h = compose(f,right)}, which will cause an
  3815. invalid deconstruction error if applied in filter mode to an empty file,
  3816. imposes no requirement that @code{f} be written to accommodate that
  3817. possibility (i.e., by checking for it) in order for the error to be
  3818. reported properly. The following proof demonstrates that the meaning of @code{f}
  3819. is irrelevant to the result.
  3820. @format
  3821. [[@code{compose(f,right)}]]@code{_0} @code{nil_0}
  3822. = [[@code{f}]]@code{_0} [[@code{right}]]@code{_0} @code{nil}@code{_0}
  3823. = [[@code{f}]]@code{_0} [[@code{('invalid deconstruction',nil)}]]@code{_1}
  3824. = [[@code{('invalid deconstruction',nil)}]]@code{_1}
  3825. @end format
  3826. @noindent
  3827. In an application @code{h = compose(f,g)}, the input
  3828. validation therefore may be confined to the ``front @w{end'', @code{g}.}
  3829. It will be recalled from the discussions of @code{recur} (@ref{Recur})
  3830. @cindex @code{recur}
  3831. @cindex @code{transpose}
  3832. and @code{transpose} (@ref{Transpose}) that the semantics of
  3833. virtual code involving these forms is defined in terms of the
  3834. @code{field} format for deconstruction functions (@ref{Field}),
  3835. @cindex @code{field}
  3836. which depends implicitly on the semantics of @code{left} and
  3837. @code{right}, being a generalization of them. An invalid deconstruction
  3838. @cindex @code{left}
  3839. @cindex @code{right}
  3840. message could therefore result from applications incorporating any of
  3841. the forms of @code{recur}, @code{transpose}, or @code{field}. Invalid
  3842. deconstructions could also arise from the @code{replace} operation
  3843. @cindex @code{replace}
  3844. @cindex assignment
  3845. (@ref{Replace}), which is used for assignment (@ref{Assignment}), because
  3846. @code{replace} is defined by virtual code, except as noted next.
  3847. @node Expedient Error Messages, Computable Error Messages, Error Messages, Exception Handling
  3848. @subsubsection Expedient Error Messages
  3849. @cindex error messages
  3850. Because there are so many ways to cause an invalid deconstruction, this
  3851. message is the most common in practice and therefore the least
  3852. informative. As a matter of convenience, @code{avram} takes the liberty
  3853. of a slight departure from the virtual machine specification as written
  3854. hitherto, and employs the following messages when invalid
  3855. deconstructions occur respectively in the cases of recursion,
  3856. transposition, and assignment.
  3857. @itemize @bullet
  3858. @item @code{invalid recursion}
  3859. @item @code{invalid transpose}
  3860. @item @code{invalid assignment}
  3861. @end itemize
  3862. @noindent
  3863. That is, this section contradicts and supersedes what is stated at the
  3864. end of @ref{Error Messages} and implied by the operator properties
  3865. @emph{P14}, @emph{P16}, and @emph{P42}. It is also possible that user
  3866. applications may modify the error messages by methods described in
  3867. @ref{Computable Error Messages}.
  3868. Whereas these three cases constitute an expedient variation on the
  3869. semantics, there is another sense in which no possible implementation
  3870. could conform faithfully to the specification. When an evaluation can
  3871. not be carried out because of insufficient space on the host machine,
  3872. one of the following error messages may be the result.
  3873. @itemize @bullet
  3874. @item @code{memory overflow}
  3875. @item @code{counter overflow}
  3876. @end itemize
  3877. @noindent
  3878. These messages are treated in the same way as those that are caused by
  3879. programming errors, and propagate to the final result written to
  3880. standard error without any specific consideration by the application
  3881. developer. The latter occurs only in connection with the built in weight
  3882. function (@ref{Weight}). Other messages listed in
  3883. @ref{Application Programming Errors} are also of this ilk.
  3884. @node Computable Error Messages, Exception Handler Usage, Expedient Error Messages, Exception Handling
  3885. @subsubsection Computable Error Messages
  3886. The automatic generation and reporting of error messages provides a
  3887. reasonable default behavior for applications that do not consider
  3888. exceptional conditions. All applications and their input data are
  3889. ordinarily members of the bottom level set in the hierarchy
  3890. (@ref{A Hierarchy of Sets}). The error messages caused by invalid
  3891. operations on this level are on the first level above the bottom, which
  3892. are recognized as such and written to standard error without
  3893. intervention from the application. However, there are two drawbacks to
  3894. this style of dealing with exceptions.
  3895. @cindex exceptions
  3896. @itemize @bullet
  3897. @item
  3898. An application developer may wish to translate error messages
  3899. into terms that are meaningful to the user, not only by literally
  3900. translating them from English to the local vernacular, but perhaps by
  3901. relating the particular exceptional condition to application specific
  3902. causes. While it is convenient for the ``back end'' code not to be
  3903. required to intervene in the error reporting, it would be most
  3904. inconvenient for it not to be able to do so.
  3905. @item
  3906. Some application specific errors might not correspond directly to any of
  3907. the particular conditions detected automatically due to invalid
  3908. operations, for example a semantic error in a syntactically correct
  3909. input file. It might be convenient in such cases for an application to
  3910. be able to define its own error messages but still have them reported
  3911. automatically like the built in messages.
  3912. @end itemize
  3913. These situations suggest a need for some ability on the part of an
  3914. application to operate on error messages themselves. Based on the
  3915. operator semantics given so far, such an application is inexpressible,
  3916. because for any application @code{@var{f}_0} and error message
  3917. @w{@code{@var{x}_1}}, property @emph{P44} stipulates @code{@var{f}_0 @var{x}_1} =
  3918. @code{@var{x}_1}, meaning that the resulting error message is
  3919. unchanged. Therefore, we need to define another basic property of the
  3920. operator.
  3921. The following form of virtual code is used in applications that may need
  3922. to operate on error messages.
  3923. @cindex @code{guard}
  3924. @table @emph
  3925. @item T32
  3926. [[@code{guard}]] @code{(@var{f},@var{g})} = @code{((nil,@var{f}),@var{g})}
  3927. @end table
  3928. @noindent
  3929. Code in this form has the following semantics.
  3930. @table @emph
  3931. @item P53
  3932. ([[@code{guard}]] @code{(@var{f},@var{g})})@code{_@var{n}}
  3933. @code{@var{x}_@var{p}} =
  3934. @code{@var{g}_(@var{n}+1) @var{f}_@var{n} @var{x}_@var{p}}
  3935. @end table
  3936. @noindent
  3937. The intuitive explanation is that @code{@var{f}} is the main part of the
  3938. application, and @code{@var{g}} is the part of the application that
  3939. operates on the error message that comes from @code{@var{f}} if an
  3940. exception occurs while it is being evaluated (i.e., the ``exception
  3941. handler''). Typically the exception handler code implements a function
  3942. that takes an error message as an argument and returns an error message
  3943. as a result.
  3944. Where there is no exception, the exception handler
  3945. @code{@var{g}_(@var{n}+1)} is never used, because its argument will be
  3946. on level @code{@var{n}}, and therefore unaffected by an application on
  3947. level @code{@var{n}+1}.
  3948. Exception handlers may have their own exception handlers, which will be
  3949. invoked if the evaluation of the exception handler causes a further
  3950. exception. Such an exception corresponds semantically to a value on the
  3951. next level of the hierarchy of sets.
  3952. @node Exception Handler Usage, , Computable Error Messages, Exception Handling
  3953. @subsubsection Exception Handler Usage
  3954. One way for this feature of the virtual machine to be used is to
  3955. intercept and translate error messages to a more meaningful form. An
  3956. application guarded as shown below causes messages of invalid deconstruction
  3957. to be changed to @code{'syntax error'}.
  3958. @display
  3959. @code{main = guard(
  3960. application,
  3961. conditional(
  3962. bu(compare,('invalid deconstruction',nil)),
  3963. (constant ('syntax error',nil),identity)))}
  3964. @end display
  3965. @noindent
  3966. The conditional compares its argument to the error message for an
  3967. @cindex deconstruction
  3968. invalid deconstruction, and if it matches, the syntax error message is
  3969. returned, but otherwise the original message is returned. Note that an
  3970. error message must be in the form of a list of character strings, so
  3971. that it can be printed. Although the message of @code{'syntax error'}
  3972. might not be very informative, at least it looks less like a crash.
  3973. A real application should of course strive to do better than that.
  3974. Exception handling features of the virtual machine can also be adapted
  3975. by applications to raise their own exceptions with customized messages.
  3976. @example
  3977. error_messenger =
  3978. guard(compose(compare,constant nil),constant ('syntax error',nil))
  3979. @end example
  3980. @noindent
  3981. This code fragment implements a function that causes a message of
  3982. @code{'syntax error'} to be reported for any possible input. This code
  3983. works by first causing an invalid comparison and then substituting its
  3984. own error message. A function that always causes an error is not useful
  3985. in itself, but might be used as part of an application in the following
  3986. form.
  3987. @example
  3988. main = conditional(validation,(application,error_messenger))
  3989. @end example
  3990. @noindent
  3991. In this case, the application checks the validity of the input with a
  3992. predicate, and invokes the error messenger if it is invalid.
  3993. Although the previous examples return a fixed error message for each
  3994. possible kind of error, it is also possible to have error messages
  3995. that depend on the input data, as the next example shows.
  3996. @cindex @code{bu}
  3997. @cindex @code{guard}
  3998. @cindex @code{identity}
  3999. @cindex @code{apply}
  4000. @cindex @code{hired}
  4001. @example
  4002. main = (hired apply)(
  4003. compose(
  4004. bu(guard,some_application),
  4005. (hired constant)(constant 'invalid input was:',identity)),
  4006. identity)
  4007. @end example
  4008. @noindent
  4009. If the application causes an exception for any reason, the error message
  4010. returned will include a complete listing of the input, prefaced by the
  4011. words @code{'invalid input was:'}. This particular example works only if
  4012. the input is a list of character strings, but could be adapted for other
  4013. types of data by substituting an appropriate formatting function for the
  4014. first identity. The formatting function would take the relevant data
  4015. type to a list of character strings. Another possible variation would be to
  4016. concatenate the invalid input listing with the error message that was
  4017. generated, rather than just replacing it.
  4018. As the last example may suggest, exception handlers turn out to be an
  4019. @cindex debugging
  4020. @cindex functional programming
  4021. @cindex imperative programming
  4022. essential debugging tool for functional programs, making them as easy to
  4023. debug as imperative programs if not more so. This example forms the
  4024. basis for a higher order function that wraps any given function with an
  4025. exception handler that prints the argument causing it to crash. For
  4026. arguments not causing a crash, the behavior is unchanged. Alternatively,
  4027. code implementing a function that unconditionally reports its argument
  4028. in an error message can be inserted at a strategic point in the
  4029. application code similarly to a print statement. Finally, inspired use
  4030. of exception handlers that concatenate their messages with previously
  4031. generated messages can show something like a parameter stack dump when a
  4032. recursively defined function crashes. These are all matters for a language
  4033. designer and are not pursued further in this document.
  4034. @node Interfaces to External Code, Vacant Address Space, Exception Handling, Virtual Code Semantics
  4035. @subsection Interfaces to External Code
  4036. A few other combinators have been incorporated into the virtual
  4037. machine as alternatives to the style of interactive applications
  4038. described in @ref{Output From Interactive Applications}. These make it
  4039. possible to interface with external libraries and applications either
  4040. by a simple function call, or by executing a run-time generated
  4041. transducer as described previously. In either case, there is no need
  4042. for any particular command line options to specify interactive
  4043. invocation, nor for the application to be designed that way from the
  4044. outset. Existing virtual code applications may therefore be enhanced
  4045. to make use of these features without radical changes.
  4046. To account for these additional capabilities, it is not entirely
  4047. adequate to continue defining the virtual machine semantics in terms
  4048. of a mathematical function, but it is done nevertheless due to the
  4049. lack of any appealing alternative. Although most library functions are
  4050. in fact functions in the sense that their outputs are determined by
  4051. their arguments, they defy a concise specification within the present
  4052. mathematical framework, especially insofar as they may involve finite
  4053. precision floating point numbers. More problematically, the effect of
  4054. interaction with a shell is neither well defined nor deterministic.
  4055. The descriptions that follow presuppose a computational procedure
  4056. associated with the following definitions but leave its exact nature
  4057. unspecified.
  4058. @menu
  4059. * Library combinator::
  4060. * Have combinator::
  4061. * Interaction combinator::
  4062. @end menu
  4063. @node Library combinator, Have combinator, Interfaces to External Code, Interfaces to External Code
  4064. @subsubsection Library combinator
  4065. The simplest and fastest method of interfacing to an external library
  4066. is by way of a virtual machine combinator called @code{library}. It
  4067. takes two non-empty character strings as arguments to a virtual code
  4068. program of the form implied by the following property.
  4069. @table @emph
  4070. @item T33
  4071. [[@code{library}]] (@code{@var{x}},@code{@var{y}}) = @code{((nil,nil),((@var{x},@var{y}),(nil,nil)))}
  4072. @end table
  4073. @noindent
  4074. Intuitively, @var{x} is the name of a library and @var{y} is the name
  4075. of a function within the library. For example, if @var{x} is
  4076. @code{'math'} and @var{y} is @code{'sqrt'}, then
  4077. @code{library}(@var{x},@var{y}) represents the function that computes
  4078. the square root of a floating point number as defined by the host
  4079. machine's native C implementation, normally in IEEE double precision
  4080. format. Different functions and libraries may involve other argument
  4081. and result types, such as complex numbers, arrays, sparse matrices, or
  4082. arbitrary precision numbers. A list of currently supported external
  4083. library names with their functions and calling conventions is given in
  4084. @ref{External Libraries}.
  4085. On the virtual code side, all function arguments and results
  4086. regardless of their types are encoded as nested pairs of @code{nil},
  4087. as always, and may be manipulated or stored as any other data,
  4088. including storage and retrieval from files in @file{.avm} virtual
  4089. code format (@ref{File Format}). However, on the C side,
  4090. various memory management and caching techniques are employed to
  4091. maintain this facade while allowing the libraries to operate on data
  4092. in their native format. The details are given more fully in the API
  4093. documentation, particularly in @ref{Type Conversions} and
  4094. @ref{External Library Maintenance}.
  4095. While this style is fast and convenient, it is limited either to
  4096. libraries that have already been built into the virtual machine, or to
  4097. those for which the user is prepared to implement a new interface
  4098. module in C as described in @ref{Implementing new library
  4099. functions}.
  4100. @node Have combinator, Interaction combinator, Library combinator, Interfaces to External Code
  4101. @subsubsection Have combinator
  4102. As virtual machine interfaces to external libraries accumulate faster
  4103. than they can be documented and may vary from one installation to
  4104. another, it is helpful to have a way of interrogating the virtual
  4105. machine for an up to date list of the installed libraries and
  4106. functions. A combinator called @code{have} can be used to test for the
  4107. availability of a library function. It takes the form
  4108. @table @emph
  4109. @item T34
  4110. [[@code{have}]] (@code{@var{x}},@code{@var{y}}) = @code{((nil,nil),((nil,@var{x}),(nil,@var{y})))}
  4111. @end table
  4112. @noindent
  4113. where @var{x} is the name of a library and @var{y} is the name of a
  4114. function within the library encoded as character strings. For example,
  4115. if @var{x} is @code{'mtwist'} and @var{y} is @code{'u_disc'} (for the
  4116. natural random number generator function in the Mersenne twistor
  4117. library) then @code{have(@var{x},@var{y})} is a function that returns
  4118. a non-empty value if an only if that library is installed and that
  4119. function is available within it. The actual argument to the function
  4120. is ignored as the result depends only on the installed virtual machine
  4121. configuration. In this sense, it acts like a @code{constant} combinator.
  4122. One way for this combinator to be used is in code of the form
  4123. @example
  4124. portable_rng =
  4125. conditional(
  4126. have('mtwist','u_disc'),
  4127. library('mtwist','u_disc'),
  4128. some_replacement_function)
  4129. @end example
  4130. @noindent
  4131. which will use the library function if available but otherwise use a
  4132. replacement function. Code in this form makes the decision at run
  4133. time, but it is also possible to express the function such that the
  4134. check for library presence is made at compile time, as the following
  4135. example shows, which will imply a slight improvement in performance.
  4136. @example
  4137. non_portable_rng =
  4138. apply(
  4139. conditional(
  4140. have('mtwist','u_disc'),
  4141. constant library('mtwist','u_disc'),
  4142. constant some_replacement_function),
  4143. 0)
  4144. @end example
  4145. @noindent
  4146. This program would be non-portable in the sense that it would need to
  4147. be recompiled for each installation if there were a chance that some
  4148. of them might have the @code{mtwist} library and some might not,
  4149. whereas the previous example would be binary compatible across all of
  4150. them. @footnote{In practice both examples are equally portable because
  4151. the @code{mtwist} source is distributed with @code{avram} so all
  4152. installations will have it. Most libraries are distributed
  4153. separately.}
  4154. The actual value returned by a function @code{have(foo,bar)} is the
  4155. list of pairs of strings @code{<(foo,bar)>} if the function is
  4156. available, or the empty list otherwise. A non-empty list is
  4157. represented as a pair @code{(head,tail)}, and an empty list as
  4158. @code{nil}. The angle bracket notation @code{<a,b,c...>} used here is
  4159. an abbreviation for @code{(a,(b,(c...nil)))}.
  4160. Either or both arguments to the @code{have} combinator can be a
  4161. wildcard, which is the string containing a single asterisk,
  4162. @cindex wild cards
  4163. @code{'*'}. In that case, the list of all available matching library
  4164. names and function names will be returned. This feature can be used to
  4165. find out what library functions are available without already knowing
  4166. their names.
  4167. If a library had a function named @code{'*'}, which clashes with
  4168. the wild card string, the interpretation as a wild card would take
  4169. precedence.
  4170. @node Interaction combinator, , Have combinator, Interfaces to External Code
  4171. @subsubsection Interaction combinator
  4172. A further combinator allows virtual code applications to interact
  4173. directly with any interactive console application using the
  4174. @code{expect} library. The mechanism is similar to that of
  4175. interactive applications documented in the @ref{Output From
  4176. Interactive Applications}, but attempts to be more convenient.
  4177. Instead of being designed as an interactive application, any virtual
  4178. code application may use this combinator to spawn a shell and interact
  4179. with it in order to compute some desired result.
  4180. The advantage of this combinator over the @code{library} combinator is
  4181. that it requires no modification of the virtual machine to support new
  4182. applications. It can also interact with applications that may reside
  4183. on remote servers, that are implemented languages other than C, or
  4184. @cindex GNU R
  4185. whose source code is unavailable. For example, the GNU R statistical
  4186. package provides an interactive command to evaluate multivariate
  4187. @cindex multivariate normal distrubution
  4188. normal distribution functions with an arbitrary covariance matrix, but
  4189. @cindex covariance matrix
  4190. the corresponding function is not provided by the @code{Rmath} C
  4191. library (or any other free library, to the author's knowledge) because
  4192. it is implemented in interpreted code. This combinator makes it
  4193. callable by an @code{avram} virtual code application nevertheless. The
  4194. disadvantage compared to the @code{library} combinator is that there
  4195. is more overhead in spawning a process than simply making a call to a
  4196. built in function, and the programming interface is more complicated.
  4197. The combinator takes the form
  4198. @table @emph
  4199. @item T35
  4200. [[@code{interact}]] @var{f} = @code{((nil,nil),(((nil,nil),nil),((nil,@var{f}),nil)))}
  4201. @end table
  4202. @noindent
  4203. where @var{f} is the virtual code for a function that
  4204. follows the same protocol described in @ref{Output From Interactive Applications},
  4205. except that it does not allow file output as described in
  4206. @ref{Mixed Modes of Interaction}. The argument @code{x} is ignored when the
  4207. expression @code{(interact f) x} is evaluated, similarly to the way the argument
  4208. is ignored in an expression like @code{(constant k) x}. The result returned
  4209. is a transcript of the dialogue that took place between @code{f} and the
  4210. externally spawned shell, represented as a list of lists of strings for
  4211. line oriented interaction, or a list of characters alternating with lists of
  4212. strings in the case of character oriented interaction.
  4213. The following example demonstrates a trivial use of the @code{interact}
  4214. combinator to spawn an @code{ftp} client, do an @code{ls} command, and then
  4215. @cindex ftp
  4216. terminate the session.
  4217. @example
  4218. eof = <(nil,(nil,(((nil,nil),nil),(nil,nil))))>
  4219. demo =
  4220. interact conditional(
  4221. conditional(identity,constant false,constant true),
  4222. constant(0,<'ftp'>,<'ftp> '>),
  4223. conditional(
  4224. conditional(left,constant false,constant true),
  4225. constant(1,<'ls',''>,<'','ftp> '>),
  4226. conditional(
  4227. compose(compare,couple(left,constant 1)),
  4228. constant(2,<'bye',''>,<eof>),
  4229. constant nil)))
  4230. @end example
  4231. @noindent
  4232. Some liberties are taken with @code{silly} syntax in this example, in
  4233. the way of using angle brackets to denote lists, and numbers to
  4234. represent states.
  4235. @itemize @bullet
  4236. @item
  4237. The interacting transducer works by checking whether its argument is
  4238. empty (via the @code{identity} function used as a predicate in the
  4239. @code{conditional}, which is then negated). In that case it returns
  4240. the triple containing the initial state of 0, the @code{ftp} shell
  4241. command to spawn the client, and the @code{'ftp> '} prompt expected
  4242. when the client has been spawned, both of the latter being lists of
  4243. strings.
  4244. @item
  4245. If the argument is non-empty, then next it checks whether it is in the
  4246. initial state of 0, (via the @code{left} function used as a predicate,
  4247. referring to the state variable expected on the left of any given
  4248. @code{(state,input)} pair, also negated). If so, it returns the triple
  4249. containing the next state of 1, the @code{ls} command followed by an
  4250. empty string to indicate a line break, and the expected prompt
  4251. preceded by an empty string to match it only at the beginning of a
  4252. line.
  4253. @item
  4254. Finally, it checks for state 1, in which case it issues the
  4255. @code{bye} command to close the session, @code{eof} rather than a
  4256. @cindex eof
  4257. prompt to wait for termination of the client, and a state of 2.
  4258. @item
  4259. In the remaining state of 2, which needn't be explicitly tested
  4260. because it is the only remaining possibility, the program returns a
  4261. @code{nil} value to indicate that the computation has
  4262. terminated.
  4263. @end itemize
  4264. Deadlock would be possible at any point if either party did not follow
  4265. @cindex deadlock
  4266. this protocol, but for this example it is not an issue. If an
  4267. expression of the form @code{demo x} were to be evaluated, then
  4268. regardless of the value of @code{x}, the value of the result would be
  4269. as shown below.
  4270. @example
  4271. <
  4272. <'ftp'>,
  4273. <'ftp> '>,
  4274. <'ls',''>,
  4275. <'ls','Not connected.','ftp> '>,
  4276. <'bye',''>,
  4277. <'bye',''>>
  4278. @end example
  4279. @noindent
  4280. That is, it would be a list of lists of strings, alternating between the
  4281. output of the interactor and the output of the @code{ftp} client. If
  4282. the spawned application had been something non-trivial such as a
  4283. computer algebra system or a command line web search utility,
  4284. then it is easy to see how functions using this combinator can leverage
  4285. off a wealth of available resources.
  4286. @node Vacant Address Space, , Interfaces to External Code, Virtual Code Semantics
  4287. @subsection Vacant Address Space
  4288. Not every possible pattern has been used by the virtual machine as a way
  4289. of encoding a function. The following patterns, where @code{@var{a}},
  4290. @code{@var{b}}, and @code{@var{c}} are non-@code{nil} trees, do not
  4291. represent anything useful.
  4292. @table @asis
  4293. @item unary forms
  4294. @code{((nil,nil),((nil,nil),(nil,((nil,@var{a}),nil))))}@*
  4295. @code{((nil,nil),((nil,nil),(nil,(nil,(nil,@var{a})))))}
  4296. @item binary forms
  4297. @code{((nil,nil),((nil,nil),(@var{a},@var{b})))}@*
  4298. @code{((nil,nil),((@var{a},nil),(@var{b},nil)))}@*
  4299. @code{((nil,nil),((@var{a},nil),(nil,@var{b})))}
  4300. @item ternary forms
  4301. @code{((nil,nil),((@var{a},@var{b}),(@var{c},nil)))}@*
  4302. @code{((nil,nil),((@var{a},@var{b}),(nil,@var{c})))}@*
  4303. @code{((nil,nil),((@var{a},nil),(@var{b},@var{c})))}@*
  4304. @code{((nil,nil),((nil,@var{a}),(@var{b},@var{c})))}
  4305. @end table
  4306. @noindent
  4307. These patterns are detected by the virtual machine simply to avoid blowing
  4308. it up, but they always cause an error message to be reported.
  4309. @cindex @code{unsupported hook}
  4310. @cindex @code{unrecognized combinator}
  4311. @table @emph
  4312. @item P55
  4313. For @code{@var{f}} matching any of the first three trees in the above list,@*
  4314. @w{ }@w{ }@w{ }@code{@var{f}_@var{n} @var{x}_@var{n}} =
  4315. [[@code{('unsupported hook',nil)}]]@code{_(@var{n}+1)}
  4316. @item P56
  4317. For the remaining trees @code{@var{f}} in the above list,@*
  4318. @w{ }@w{ }@w{ }@code{@var{f}_@var{n} @var{x}_@var{n}} =
  4319. [[@code{('unrecognized combinator (code @var{m})',nil)}]]@code{_(@var{n}+1)}
  4320. @end table
  4321. @noindent
  4322. Here, @code{@var{m}} is a numeric constant dependent on which tree
  4323. @code{@var{f}} was used. The unsupported hook message is meant to be
  4324. more informative than the unrecognized combinator message, suggesting
  4325. that a feature intended for future use is not yet available.
  4326. This list has been assembled for the benefit of readers considering the
  4327. addition of backward compatible extensions to the virtual code
  4328. semantics, who are undeterred by the facts that
  4329. @itemize @bullet
  4330. @item
  4331. the computational model
  4332. @cindex universality
  4333. is already universal
  4334. @item
  4335. virtual code applications are already
  4336. interoperable with all kinds of high performance software having a text
  4337. based or console interface by way of the @code{interact} combinator
  4338. @item
  4339. an unlimited number of built in library functions can be added
  4340. by way of the @code{library} combinator as described in
  4341. @ref{Implementing new library functions}
  4342. @item
  4343. the C code in @code{avram} makes fairly
  4344. @cindex pointers
  4345. intricate use of pointers with a careful policy of reference counting
  4346. and storage reclamation
  4347. @item
  4348. there is also a performance penalty incurred by
  4349. @cindex reference count
  4350. further extensions to the semantics, even for applications that don't
  4351. use them, because a pattern recognition algorithm in the interpreter has
  4352. more cases to consider.
  4353. @end itemize
  4354. Nevertheless, a new functional form combining a pair of functions to be
  4355. interpreted in a new way by the virtual machine could be defined using
  4356. any of the binary forms above, for example, with @code{@var{a}} as the
  4357. virtual code for one of the functions and @code{@var{b}} as that of the
  4358. other. Such a form would not conflict with any existing applications,
  4359. provided that both @code{@var{a}} and @code{@var{b}} are not @code{nil},
  4360. which is true of any valid representation for a function.
  4361. Virtual machine architects, take note. There are infinitely many trees
  4362. @cindex trees
  4363. fitting these patterns, but it would be possible to use them up by
  4364. assigning them without adequate foresight. For example, if
  4365. interpretations were assigned to the four ternary forms, the three binary
  4366. forms, and one of the remaining unary forms, then the only
  4367. unassigned pattern could be of the form
  4368. @display
  4369. @code{((nil,nil),((nil,nil),(nil,(nil,(nil,@var{a})))))}
  4370. @end display
  4371. @noindent
  4372. Assigning an interpretation to it would leave no further room for
  4373. backward compatible expansion. On the other hand, any tree of the
  4374. following form also fits the above pattern,
  4375. @display
  4376. @code{((nil,nil),((nil,nil),(nil,(nil,(nil,(@var{b},@var{c}))))))}
  4377. @end display
  4378. @noindent
  4379. with any values for @code{@var{b}} and @code{@var{c}}. Different
  4380. meanings could be chosen for the case where both are @code{nil}, both
  4381. are non-@code{nil}, or one is @code{nil} and the other non-@code{nil},
  4382. allowing two unary forms, one binary, and one constant. If at least one
  4383. of these patterns is reserved for future enhancements, then a
  4384. potentially inexhaustible supply of address space remains and there will
  4385. be no need for incompatible changes later.
  4386. @node Library Reference, Character Table, Virtual Machine Specification, Top
  4387. @chapter Library Reference
  4388. Much of the code developed for @code{avram} may be reusable in other
  4389. projects, so it has been packaged into a library and documented in this
  4390. chapter. For ease of reference, this chapter is organized with a
  4391. separate section for each source file. For the most part, each source
  4392. file encapsulates an abstract type and a number of related functions,
  4393. except for a few cases where C makes such a design awkward. An attempt
  4394. has been made to present the sections in a readable order as far as
  4395. possible.
  4396. The documentation in this chapter is confined to the application program
  4397. interface (API), and does not delve unnecessarily into any details of the
  4398. @cindex API
  4399. implementation. A reader wishing to extend, modify, or troubleshoot the
  4400. library itself can find additional information in the source code
  4401. comments. These are more likely to be in sync with the code than this
  4402. document may be, and are more readily accessible to someone working with
  4403. the code.
  4404. Some general points pertaining to the library are the following.
  4405. @itemize @bullet
  4406. @item Unlike the previous chapter, this chapter uses the word
  4407. ``function'' in the C sense rather than the mathematical sense of the word.
  4408. @item Internal errors are internal from the user's point of view, not
  4409. the developer's (@ref{Internal Errors}). Invoking these functions in
  4410. ways that are contrary to their specifications can certainly cause
  4411. internal errors (not to mention segfaults).
  4412. @item The library is definitely not thread safe, and thread safety is
  4413. @cindex threads
  4414. not a planned enhancement. The amount of locking required to make it
  4415. thread safe would probably incur an objectionable performance penalty
  4416. due to the complexity of the shared data structures involved, in
  4417. addition to being very difficult to get right. If you need these
  4418. facilities in a concurrent application, consider spawning a process for
  4419. @cindex spawning processes
  4420. each client of the library so as to keep their address spaces separate.
  4421. @item The library files are built from the standard source
  4422. distribution using GNU @command{libtool}. In the default directory
  4423. hierarchy, they will be found
  4424. either in @file{/usr/lib/libavram.*} or in @file{/usr/local/lib/libavram.*}.
  4425. These directories will differ in a non-standard installation.
  4426. @item The header files will probably be
  4427. located in either @file{/usr/include/avm/*.h} or
  4428. @file{/usr/local/include/avm/*.h} for a standard installation.
  4429. @item All exported functions, macros and constants are
  4430. preceded with @code{avm_}, so as to reduce the chance of name clashes
  4431. with other libraries. Not all type declarations or field identifiers
  4432. follow this convention, because that would be far too tedious.
  4433. @item The library header files are designed to be compatible with C++
  4434. @cindex C++
  4435. but have been tested only with C. Please refer to platform specific
  4436. documentation for further information on how to link library modules
  4437. with your own code.
  4438. @end itemize
  4439. @menu
  4440. * Lists::
  4441. * Characters and Strings::
  4442. * File Manipulation::
  4443. * Invocation::
  4444. * Version Management::
  4445. * Error Reporting::
  4446. * Profiling::
  4447. * Emulation Primitives::
  4448. * External Library Maintenance::
  4449. @end menu
  4450. @node Lists, Characters and Strings, Library Reference, Library Reference
  4451. @section Lists
  4452. The basic data structure used for representing virtual code and data in
  4453. the @code{avram} library is declared as a @code{list}.
  4454. @cindex lists
  4455. @cindex @code{head} field
  4456. @cindex @code{tail} field
  4457. The @code{list} type is a pointer to a structure having a @code{head}
  4458. field and a @code{tail} field, which are also lists. The empty tree,
  4459. @code{nil}, is represented by the C constant @code{NULL}. A tree of the
  4460. form @code{cons(@var{a},@var{b})} is represented in C as a list whose
  4461. @code{head} is the representation of @code{@var{a}} and whose
  4462. @code{tail} is the representation of @code{@var{b}}.
  4463. A number of other fields in the structure are maintained automatically
  4464. and should not be touched. For that matter, even the @code{head} and
  4465. @code{tail} fields should be considered read-only. Because of sharing,
  4466. it is almost never valid to modify a list ``in place'', except for cases
  4467. that are already covered by library functions.
  4468. @menu
  4469. * Simple Operations::
  4470. * Recoverable Operations::
  4471. * List Transformations::
  4472. * Type Conversions::
  4473. * Comparison::
  4474. * Deconstruction Functions::
  4475. * Indirection::
  4476. * The Universal Function::
  4477. @end menu
  4478. @node Simple Operations, Recoverable Operations, Lists, Lists
  4479. @subsection Simple Operations
  4480. These functions are declared in the header file @code{lists.h}, which
  4481. should be included in any C source file that uses them with a directive
  4482. such as @code{@w{#include <avm/lists.h>}}. All of these functions except
  4483. the first three have the potential cause a memory overflow. In that
  4484. @cindex overflow
  4485. event, a brief message is written to standard error and the process is
  4486. killed rather than returning to the caller. It is possible for client
  4487. programs requiring more robust behavior to do their own error handling
  4488. by using the alternative versions of these operations described in the
  4489. next section.
  4490. @deftypefun void avm_initialize_lists ()
  4491. The function @code{avm_initialize_lists} should be called before any of
  4492. the other ones in this section is called, because it sets up some
  4493. internal data structures. Otherwise, the behavior of the other functions
  4494. is undefined.
  4495. @end deftypefun
  4496. @deftypefun void avm_dispose (list @var{front})
  4497. This function deallocates the memory associated with a given list,
  4498. either by consigning it to a cache maintained internally by the library,
  4499. or by the standard @code{free} function if the cache is full. Shared
  4500. lists are taken into account and handled properly according to a
  4501. reference counting scheme. Lists should be freed only by this function,
  4502. not by using @code{free} directly.
  4503. @end deftypefun
  4504. @deftypefun void avm_count_lists ()
  4505. If a client program aims to do its own storage reclamation, this
  4506. function can be called optionally at the end of a run when it is
  4507. believed that all lists have been freed. If any allocated lists remain
  4508. at large, a warning will be printed to standard error. This function
  4509. therefore provides a useful check for memory leaks. Overhead is small
  4510. enough that it is not infeasible to leave this check in the production
  4511. code.
  4512. @end deftypefun
  4513. @deftypefun list avm_copied (list @var{operand})
  4514. A copy of the argument list is returned by this function. The copy
  4515. remains intact after the original is reclaimed. A typical use might be
  4516. for retaining part of a list after the rest of it is no longer
  4517. needed. In this example, a list @code{x} is traversed by a hypothetical
  4518. @code{visit} function to each item, which is then immediately reclaimed.
  4519. @example
  4520. while(x)@{
  4521. visit(x->head);
  4522. old_x = x;
  4523. x = avm_copied(x->tail); /* the right way */
  4524. avm_dispose(old_x);
  4525. @}
  4526. @end example
  4527. This example allows each item in the list to be visited even as
  4528. previously visited items are reclaimed, because @code{x} is copied at
  4529. each iteration. This example contrasts with the next one, which will
  4530. probably cause a segmentation fault.
  4531. @cindex segmentation fault
  4532. @example
  4533. while(x)@{
  4534. visit(x->head);
  4535. old_x = x;
  4536. x = x->tail; /* the wrong way */
  4537. avm_dispose(old_x);
  4538. @}
  4539. @end example
  4540. In the second example, a reference is made to a part of a list which no
  4541. longer exists because it has been deallocated.
  4542. In fact, the @code{avm_copied} function does nothing but increment a
  4543. reference count, so it is a fast, constant time operation that requires
  4544. @cindex reference count
  4545. no additional memory allocation. Semantically this action is equivalent
  4546. to creating a fresh copy of the list, because all list operations in the
  4547. library deal with reference counts properly.
  4548. @end deftypefun
  4549. @deftypefun list avm_join (list @var{left}, list @var{right})
  4550. This function takes a pair of lists to a list in which the left is the
  4551. head and the right is the tail. It may need to use @code{malloc} to
  4552. allocate additional memory. If there is insufficient memory, an error
  4553. message is written to standard error and the program exits.
  4554. When the list returned by @code{avm_join} is eventually deallocated, the
  4555. lists from which it was built are taken with it and must not be
  4556. referenced again. For example, the following code is an error.
  4557. @example
  4558. z = avm_join(x,y);
  4559. @dots{}
  4560. avm_dispose(z);
  4561. avm_print_list(x); /* error here */
  4562. @end example
  4563. To accomplish something similar to this without an error, a copy of
  4564. @code{x} should be made, as in the next example.
  4565. @example
  4566. z = avm_join(avm_copied(x),y);
  4567. @dots{}
  4568. avm_dispose(z);
  4569. avm_print_list(x); /* original x still intact */
  4570. @end example
  4571. @end deftypefun
  4572. @deftypefun void avm_enqueue (list *@var{front}, list *@var{back}, list @var{operand})
  4573. @cindex queues
  4574. A fast simple way of building a list head first is provided by the
  4575. @code{enqueue} function. The @code{front} is a pointer to the beginning
  4576. of the list being built, and the @code{back} is a pointer to the last
  4577. item. The recommended way to use it would be something like this.
  4578. @example
  4579. front = back = NULL;
  4580. avm_enqueue(&front,&back,item);
  4581. avm_enqueue(&front,&back,next_item);
  4582. avm_enqueue(&front,&back,another_item);
  4583. @dots{}
  4584. @end example
  4585. It might be more typical for the calls to @code{avm_enqueue} to appear
  4586. within a loop. In any case, after the above code is executed, the
  4587. following postconditions will hold.
  4588. @example
  4589. front->head == item
  4590. front->tail->head == next_item
  4591. front->tail->tail->head == another_item
  4592. back->head == another_item
  4593. back->tail == NULL
  4594. @end example
  4595. The @code{avm_enqueue} function must never be used on a shared list, because
  4596. it modifies its arguments in place. The only practical way to guarantee
  4597. that a list is not shared is to initialize the @code{front} and @code{back} to
  4598. @code{NULL} as shown before the first call to @code{avm_enqueue}, and to
  4599. make no copies of @code{front} or @code{back} until after the last call
  4600. to @code{avm_enqueue}.
  4601. Because a list built with @code{avm_enqueue} is not shared, it is one of the
  4602. few instances of a list that can have something harmlessly appended to
  4603. it in place. For example, if the next line of code were
  4604. @example
  4605. back->tail = rest_of_list;
  4606. @end example
  4607. that would be acceptable assuming @code{rest_of_list} is not shared and
  4608. does not conceal a dangling or cyclic reference, and if nothing further
  4609. were enqueued.
  4610. The items that are enqueued into a list are not copied and will be
  4611. deallocated when the list is deallocated, so they must not be referenced
  4612. thereafter. A non-obvious violation of this convention is implicit in
  4613. the following code.
  4614. @example
  4615. @dots{}
  4616. avm_enqueue(&front,&back,x->head);
  4617. @dots{}
  4618. avm_dispose(front);
  4619. avm_print_list(x); /* error here */
  4620. @end example
  4621. This code might cause a segmentation fault because of the reference to
  4622. @cindex segmentation fault
  4623. @code{x} after its head has been deallocated. The following code is
  4624. subject to the same problem,
  4625. @example
  4626. @dots{}
  4627. avm_enqueue(&front,&back,x->head);
  4628. @dots{}
  4629. avm_dispose(x);
  4630. avm_print_list(front); /* error here */
  4631. @end example
  4632. as is the following.
  4633. @example
  4634. @dots{}
  4635. avm_enqueue(&front,&back,x->head);
  4636. @dots{}
  4637. avm_dispose(x); /* front is now impossible to reclaim */
  4638. avm_dispose(front);
  4639. @end example
  4640. The problem with the last example is that it is not valid even to
  4641. dispose of the same list more than once, albeit indirectly.
  4642. If part of a list is intended to be enqueued temporarily or
  4643. independently of its parent, the list should be copied explicitly, as
  4644. the following code demonstrates.
  4645. @example
  4646. @dots{}
  4647. avm_enqueue(&front,&back,avm_copied(x->head)); /* correct */
  4648. @dots{}
  4649. avm_dispose(front);
  4650. avm_print_list(x);
  4651. @end example
  4652. @end deftypefun
  4653. @deftypefun counter avm_length (list @var{operand})
  4654. A @code{counter} is meant to be the longest unsigned integer available
  4655. @cindex @code{counter}
  4656. on the host machine, and is defined in @code{common.h}, which is
  4657. automatically included whenever @code{lists.h} is included. The
  4658. @code{avm_length} function returns the number of items in a list. If a
  4659. list is @code{NULL}, a value of zero is returned. There is a possibility
  4660. of a counter overflow error from this function (@ref{Overflow Errors}),
  4661. but only on a platform where the @code{counter} type is shorter than the
  4662. address length.
  4663. @end deftypefun
  4664. @deftypefun counter avm_area (list @var{operand})
  4665. This function is similar to @code{avm_length}, but it treats its
  4666. argument as a list of lists and returns the summation of their lengths.
  4667. @end deftypefun
  4668. @deftypefun list avm_natural (counter @var{number})
  4669. @cindex naturals
  4670. This function takes a @code{counter} to its representation as a list, as
  4671. described in @ref{Representation of Numeric and Textual Data}. That is,
  4672. the number is represented as a list of bits, least significant bit
  4673. first, with each zero bit represented by @code{NULL} and each one bit
  4674. represented by a list whose @code{head} and @code{tail} are @code{NULL}.
  4675. @end deftypefun
  4676. @deftypefun void avm_print_list (list @var{operand})
  4677. The @code{avm_print_list} function is not used in any production code
  4678. but retained in the library for debugging purposes. It prints a list to
  4679. @cindex standard output
  4680. standard output using an expression involving only commas and parentheses,
  4681. as per the @code{silly} syntax (@ref{A Simple Lisp Like Language}). The
  4682. results quickly become unintelligible for lists of any significant size.
  4683. The function is recursively defined and will crash in the event of a
  4684. stack overflow, which will occur in the case of very large or cyclic
  4685. lists.
  4686. @end deftypefun
  4687. @deftypefun list avm_position (list @var{key}, list @var{table}, int *@var{fault})
  4688. This function searches for a @var{key} in a short @var{table} where
  4689. each item is a possible key.
  4690. If it's not found, a @code{NULL} value is returned. If it's
  4691. found, a list representing a character encoding according to
  4692. @ref{Character Table} is returned.
  4693. The ascii code of the character corresponding to the returned list is
  4694. the position of the @var{key} in the @var{table}, assuming position
  4695. numbers start with 1.
  4696. The table should have a length of 255 or less. If it's longer and the
  4697. @var{key} is found beyond that range, the higher order bits of the
  4698. position number are ignored.
  4699. The integer referenced by @var{fault} is set to a non-zero value in
  4700. the event of a memory overflow, which could happen in the course of
  4701. the list comparisons necessary for the search.
  4702. @end deftypefun
  4703. @node Recoverable Operations, List Transformations, Simple Operations, Lists
  4704. @subsection Recoverable Operations
  4705. The functions in this section are similar to the ones in the previous
  4706. section except with regard to error handling. Whereas the other ones
  4707. cause an error message to be printed and the process to exit in the
  4708. event of an overflow, these return to the caller, whose responsibility
  4709. it is to take appropriate action. The functions in both sections are
  4710. declared in @file{lists.h}, and should be preceded by a call to
  4711. @code{avm_initialize_lists}.
  4712. @deftypefun list avm_recoverable_join (list @var{left}, list @var{right})
  4713. This function is similar to @code{avm_join}, but will return a
  4714. @code{NULL} pointer if memory that was needed can not be allocated. A
  4715. @code{NULL} pointer would never be the result of a join under normal
  4716. circumstances, so the overflow can be detected by the caller. Regardless
  4717. of whether overflow occurs, the arguments are deallocated by this function
  4718. and should not be referenced thereafter.
  4719. @end deftypefun
  4720. @deftypefun void avm_recoverable_enqueue (list *@var{front}, list *@var{back}, list @var{operand}, int *@var{fault})
  4721. This version of the enqueue function will dispose of the @code{@var{operand}} if there
  4722. isn't room to append another item and set @code{*@var{fault}} to a non-zero
  4723. value. Other than that, it does the same as @code{avm_enqueue}.
  4724. @end deftypefun
  4725. @deftypefun counter avm_recoverable_length (list @var{operand})
  4726. This function checks for arithmetic overflow when calculating the length
  4727. of a list, and returns a zero value if overflow occurs. The caller can
  4728. detect the error by noting that zero is not the length of any list other
  4729. than @code{NULL}. This kind of overflow is impossible unless the host
  4730. does not have long enough integers for its address space.
  4731. @end deftypefun
  4732. @deftypefun counter avm_recoverable_area (list @var{operand}, int *@var{fault})
  4733. This function is similar to @code{avm_area}, except that it reacts
  4734. differently to arithmetic overflow. The @code{fault} parameter should be
  4735. the address of an integer known to the caller, which will be set to a
  4736. non-zero value if overflow occurs. In that event, the value of zero will
  4737. also be returned for the area. Note that it is possible for non-empty
  4738. lists to have an area of zero, so this condition alone is not indicative
  4739. of an error.
  4740. @end deftypefun
  4741. @deftypefun list avm_recoverable_natural (counter @var{number})
  4742. This function returns the @code{list} representation of a native
  4743. unsigned long integer, provided that there is enough memory, similarly to the
  4744. @code{avm_natural} function. Unlike that function, this one will return
  4745. a value of @code{NULL} rather than exiting the program in the event of a
  4746. memory overflow. The overflow can be detected by the caller insofar as a
  4747. @code{NULL} @code{list} does not represent any number other than zero.
  4748. @end deftypefun
  4749. @node List Transformations, Type Conversions, Recoverable Operations, Lists
  4750. @subsection List Transformations
  4751. Some functions declared in @file{listfuns.h} are used to implement the
  4752. operations described in @ref{List Functions}. These functions are able
  4753. to report error messages in the event of overflow or other exceptional
  4754. @cindex overflow
  4755. @cindex exceptions
  4756. @cindex error messages
  4757. conditions, as described in @ref{Error Messages}. The error messages are
  4758. represented as lists and returned to the caller. The occurrence of an
  4759. error can be detected by the @code{*@var{fault}} flag being set to a
  4760. non-zero value. None of these functions ever causes a program exit except
  4761. in the event of an internal error.
  4762. @deftypefun void avm_initialize_listfuns ()
  4763. This has to be called before any of the other functions in this section
  4764. is called. It initializes the error message lists, among other things.
  4765. @end deftypefun
  4766. @deftypefun void avm_count_listfuns ()
  4767. At the end of a run, a call to this function can verify that no
  4768. unreclaimed storage attributable to these functions persists. If it
  4769. does, a warning is printed to standard error. If @code{avm_count_lists}
  4770. is also used, it must be called after this function.
  4771. @end deftypefun
  4772. @deftypefun list avm_reversal (list @var{operand}, int *@var{fault})
  4773. The reversal of the list is returned by this function if no overflow
  4774. occurs. A non-zero @code{*@var{fault}} and an error message are returned
  4775. otherwise. The original @code{@var{operand}} still exists in its original
  4776. order after this function is called. The amount of additional storage
  4777. allocated is proportional only to the length of the list, not the size
  4778. of its contents.
  4779. @end deftypefun
  4780. @deftypefun list avm_distribution (list @var{operand}, int *@var{fault})
  4781. This function performs the operation described in @ref{Distribute}. The
  4782. invalid distribution message is returned in the event of a @code{NULL}
  4783. operand. Otherwise, the returned value is the distributed list. In any event,
  4784. the @code{@var{operand}} is unaffected.
  4785. @end deftypefun
  4786. @deftypefun list avm_concatenation (list @var{operand}, int *@var{fault})
  4787. @cindex concatenation
  4788. The @code{@var{operand}} is treated as a pair of lists to be concatenated, with the
  4789. left one in the @code{head} field and the right one in the @code{tail}
  4790. field. The invalid concatenation message is returned in the event of a
  4791. @code{NULL} @code{@var{operand}}. The result returned otherwise is the concatenation
  4792. of the lists, but the given @code{@var{operand}} still exists unchanged.
  4793. @end deftypefun
  4794. @deftypefun list avm_transposition (list @var{operand}, int *@var{fault})
  4795. The operation performed by this function corresponds to that of
  4796. @ref{Transpose}. Unlike other functions in this section, the operand
  4797. passed to this function is deallocated, and must not be referenced
  4798. @cindex @code{transpose}
  4799. thereafter. The transposed list is accessible as the returned value of
  4800. this function. If the original @code{@var{operand}} is still needed
  4801. after a call to @code{avm_transposition}, only a copy of it should be
  4802. passed to it, obtained from @code{avm_copied}. The invalid transpose
  4803. error message is the result if the operand does not represent a list of equal
  4804. length lists.
  4805. @end deftypefun
  4806. @deftypefun list avm_membership (list @var{operand}, int *@var{fault})
  4807. This function computes the membership predicate described in
  4808. @cindex @code{member}
  4809. @ref{Member}. The operand is a list in which the @code{tail} field is
  4810. a list that will be searched for the item in the @code{head}. If the
  4811. item is not found, a @code{NULL} list is returned, but otherwise a list
  4812. with @code{NULL} @code{head} and @code{tail} fields is returned. If the
  4813. operand is @code{NULL}, an error message of invalid membership is
  4814. returned and @code{*@var{fault}} is set to a non-zero value.
  4815. The @code{avm_membership} function calls @code{avm_binary_comparison}
  4816. in order to compare lists, so the same efficiency and side-effect
  4817. considerations are relevant to both (@ref{Comparison}). It is not
  4818. necessary to @code{#include} the header file @code{compare.h} or to
  4819. call @code{avm_initialize_compare} in order to use
  4820. @code{avm_membership}, because they will be done automatically.
  4821. @end deftypefun
  4822. @deftypefun list avm_binary_membership (list @var{operand}, list @var{members}, int *@var{fault});
  4823. This function is the same as @code{avm_membership} except that it
  4824. allows the element and the set of members to be passed as separate
  4825. lists instead of being the head and the tail of the same list.
  4826. @end deftypefun
  4827. @deftypefun list avm_measurement (list @var{operand}, int *@var{fault})
  4828. This function implements the operation described in @ref{Weight}, which
  4829. pertains to the weight of a tree. The returned value of this function is
  4830. a list encoding the weight as a binary number, unless a counter overflow
  4831. occurs, in which case it's an error message. As noted previously, the
  4832. weight of a tree can easily be exponentially larger than the amount of
  4833. @cindex native integer arithmetic
  4834. memory it occupies, but this function uses native integer arithmetic for
  4835. performance reasons. Hence, a counter overflow is a real
  4836. possibility.
  4837. @end deftypefun
  4838. @node Type Conversions, Comparison, List Transformations, Lists
  4839. @subsection Type Conversions
  4840. External library functions accessed by the @code{library} combinator
  4841. as explained in @ref{Library combinator} may operate on data other
  4842. than the @code{list} type usually used by @code{avram}, such as
  4843. floating point numbers and arrays, but a virtual code application must
  4844. be able to represent the arguments and results of these functions in
  4845. order to use them. As a matter of convention, a data structure
  4846. occupying @var{size} bytes of contiguous storage on the host machine
  4847. appears as a list of length @var{size} to a virtual code application,
  4848. in which each item corresponds to a byte, and is represented according
  4849. to @ref{Character Table}.
  4850. In principle, a virtual code application invoking a library function
  4851. to operate on a contiguous block of data, such as an IEEE double
  4852. precision number, for example, would construct a list of eight
  4853. character representations (one for each byte in a double precision
  4854. number), and pass this list as an argument to the library
  4855. function. The virtual machine would transparently convert this
  4856. representation to the native floating point format, evaluate the
  4857. function, and convert the result back to a list. In practice, high
  4858. level language features beyond the scope of this document would
  4859. insulate the programmer from some of the details on the application
  4860. side as well.
  4861. To save the time of repeatedly converting between the list
  4862. representation and the contiguous native binary representation, the
  4863. structure referenced by a @code{list} pointer contains a @code{value}
  4864. @cindex value field
  4865. field which is a @code{void} pointer to a block of memory of
  4866. unspecified type, and serves as a persistent cache of the value
  4867. represented by the list. This field normally should be managed by the
  4868. API rather than being accessed directly by client modules, but see the
  4869. code in @file{mpfr.c} for an example of a situation in which it's
  4870. appropriate to break this rule. (Generally these situations involve
  4871. library functions operating on non-contiguous data.)
  4872. @menu
  4873. * Primitive types::
  4874. * One dimensional arrays::
  4875. * Two dimensional arrays::
  4876. * Related utility functions::
  4877. @end menu
  4878. @node Primitive types, One dimensional arrays, Type Conversions, Type Conversions
  4879. @subsubsection Primitive types
  4880. A pair of functions in support of this abstraction is prototyped in
  4881. @file{listfuns.h}. These functions will be of interest mainly to
  4882. developers wishing to implement an interface to a new library module
  4883. and make it accessible on the virtual side by way of the
  4884. @code{library} combinator (@ref{Library combinator}).
  4885. @deftypefun void *avm_value_of_list (list @var{operand}, list *@var{message}, int *@var{fault})
  4886. This function takes an @var{operand} representing a value used by a
  4887. library function in the format described above (@ref{Type
  4888. Conversions}) and returns a pointer to the value.
  4889. The @code{value} field in the @var{operand} normally will point to the
  4890. block of memory holding the value, and the @var{operand} itself will
  4891. be a list of character representations whose binary encodings spell
  4892. out the value as explained above.
  4893. The @code{value} field need not be initialized on entry but it will be
  4894. initialized as a side effect of being computed by this function. If it
  4895. has been initialized due to a previous call with the same
  4896. @var{operand}, this function is a fast constant time operation.
  4897. The caller should not free the pointer returned by this function
  4898. because a reference to its value will remain in the
  4899. @var{operand}. When the @var{operand} itself is freed by
  4900. @code{avm_dispose} (@ref{Simple Operations}), the value will go with it.
  4901. If an error occurs during the evaluation of this function, the integer
  4902. referenced by @var{fault} will be set to a non-zero value, and the
  4903. list referenced by @var{message} will be assigned a representation of
  4904. a list of strings describing the error. The @var{message} is freshly
  4905. created and should be freed by the caller with @code{avm_dispose}
  4906. when no longer needed.
  4907. Possible error messages are @code{<'missing value'>}, in the case of
  4908. @cindex missing value
  4909. an empty @var{operand}, @code{<'invalid value'>} in the case of an
  4910. @cindex invalid value
  4911. @var{operand} that is not a list of character representations, and
  4912. @code{<'memory overflow'>} if there was insufficient space to allocate
  4913. the result.
  4914. @end deftypefun
  4915. @deftypefun list avm_list_of_value (void *@var{contents}, size_t @var{size}, int *@var{fault})
  4916. This function performs the inverse operation of
  4917. @code{avm_value_of_list}, taking the address of an area of
  4918. contiguously stored data and its @var{size} in bytes to a list
  4919. representation. The length of the list returned is equal to the number
  4920. of bytes of data, @var{size}, and each item of the list is a character
  4921. representation for the corresponding byte as given by @ref{Character
  4922. Table}.
  4923. A copy of the memory area is made so that the original is no longer
  4924. needed and may be freed by the caller. A pointer to this copy is
  4925. returned by subsequent calls to @code{avm_value_of_list} when the
  4926. result returned by this function is used as the @var{operand}
  4927. parameter.
  4928. If there is insufficient memory to allocate the result, the integer
  4929. referenced by @var{fault} is set to a non-zero value, and a copy of
  4930. the message @code{<'memory overflow'>} represented as a list is
  4931. returned. This function could also cause a segmentation fault if it is
  4932. @cindex segmentation fault
  4933. passed an invalid pointer or a @var{size} that overruns the storage
  4934. area. However, it is acceptable to specify a @var{size} that is less
  4935. than the actual size of the given memory area to construct a list
  4936. representing only the first part of it. The @var{size} must always be
  4937. greater than zero.
  4938. @end deftypefun
  4939. @node One dimensional arrays, Two dimensional arrays, Primitive types, Type Conversions
  4940. @subsubsection One dimensional arrays
  4941. A couple of functions declared in @file{matcon.h} are concerned mainly
  4942. with one dimensional arrays or vectors. They have been used for
  4943. @cindex arrays
  4944. vectors of double precision and complex numbers, but are applicable to
  4945. @cindex vectors
  4946. any base type that is contiguous and of a fixed size.
  4947. The motivation for these functions is to enable a developer to present
  4948. an API to virtual code applications wherein external library functions
  4949. operating natively on one dimensional arrays of numbers are seen from
  4950. the virtual side to operate on lists of numbers. Lists are the
  4951. preferred container for interoperability with virtual code
  4952. applications.
  4953. @deftypefun void *avm_vector_of_list (list @var{operand}, size_t @var{item_size}, list *@var{message}, int *@var{fault})
  4954. This function calls @code{avm_value_of_list} (@ref{Primitive types})
  4955. for each item of the @var{operand} and puts all the values together
  4956. into one contiguous block, whose address is returned.
  4957. The given @var{item_size} is required to be the lengths of the items,
  4958. all necessarily equal, and is required only for validation. For
  4959. example, @var{item_size} is 8 for a list of double precision numbers,
  4960. because they occupy 8 bytes each and are represented as lists of length 8.
  4961. The total number of bytes allocated is the product of @var{item_size}
  4962. and the length of the @var{operand}. Unlike the case of
  4963. @code{avm_value_of_list} (@ref{Primitive types}), the result returned
  4964. by this function should be explicitly freed by the caller when no
  4965. longer needed.
  4966. Any errors such as insufficient memory cause the integer referenced by
  4967. @var{fault} to be assigned a non-zero value and the @var{message} to
  4968. be assigned an error message represented as a list of strings. An
  4969. error message of @code{<'bad vector specification'>} is possible in
  4970. the case of an empty @var{operand} or one whose item lengths don't
  4971. match the given @var{item_size}. Error messages caused by
  4972. @code{avm_value_of_list} can also be generated by this function. Any
  4973. non-empty error message should be reclaimed by the caller using
  4974. @code{avm_dispose} (@ref{Simple Operations}). If an error occurs, a
  4975. @code{NULL} pointer is returned.
  4976. @end deftypefun
  4977. @deftypefun list avm_list_of_vector (void *@var{vector}, int @var{num_items}, size_t @var{item_size}, int *@var{fault})
  4978. This function takes it on faith that an array of dimension
  4979. @var{num_items} in which each item occupies @var{item_size} bytes
  4980. begins at the address given by @var{vector}. A list representation of
  4981. each item in the array is constructed by the function
  4982. @code{avm_list_of_value} (@ref{Primitive types}), and a list of all of
  4983. the lists thus obtained in order of their position in the array is
  4984. returned.
  4985. In the event of any errors caused by @code{avm_list_of_value} or
  4986. errors due to insufficient memory, the error message is returned as
  4987. the function result, and the integer referenced by @var{fault} is
  4988. assigned a non-zero value. The error message is in the form of a list
  4989. of character string representations. A segmentation fault is possible
  4990. @cindex segmentation fault
  4991. if @var{vector} is not a valid pointer or if the array size implied by
  4992. misspecified values of @var{num_items} and @var{item_size}
  4993. exceeds its actual size.
  4994. @end deftypefun
  4995. @node Two dimensional arrays, Related utility functions, One dimensional arrays, Type Conversions
  4996. @subsubsection Two dimensional arrays
  4997. Several other functions in @file{matcon.h} are meant to support
  4998. conversions between matrices represented as lists of lists and arrays
  4999. in a variety of representations. Dense matrices either square or
  5000. @cindex matrices
  5001. rectangular are accommodated, and symmetric square matrices can be
  5002. stored with redundant entries omitted in either upper trangular or
  5003. lower triangular format.
  5004. Similarly to the vector operations (@ref{One dimensional arrays})
  5005. these functions are intended to allow a developer to present an
  5006. interface to external libraries based on lists rather than arrays.
  5007. The preferred convention for virtual code applications is to represent
  5008. a matrix as a list of lists of entities (typically numbers), with
  5009. one list for each row of the matrix. For example, a 3 by 3 matrix
  5010. containing a value of @code{aij} in the @code{i}-th row and the
  5011. @code{j}-th column would be represented by this list of three lists.
  5012. @example
  5013. <
  5014. <a11,a12,a13>,
  5015. <a21,a22,a23>,
  5016. <a31,a32,a33>>
  5017. @end example
  5018. @noindent
  5019. Such a representation is convenient for manipulation by
  5020. virtual machine combinators, for example @code{transpose}
  5021. (@ref{Transpose}), and is readily identified with the matrix
  5022. it represents.
  5023. If a matrix is symmetric (that is, with @code{aij} equal to
  5024. @code{aji} for all values of @code{i} and @code{j}), only the lower
  5025. triangular portion needs to be stored because the other entries are
  5026. @cindex triangular matrix
  5027. redundant. The list representatation would be something like this.
  5028. @example
  5029. <
  5030. <a11>,
  5031. <a21,a22>,
  5032. <a31,a32,a33>>
  5033. @end example
  5034. Another alternative for representing a symmetric matrix is to store only the
  5035. upper triangular portion. In this case, a list such as the following would be used.
  5036. @example
  5037. <
  5038. <a11,a12,a13>,
  5039. <a22,a23>,
  5040. <a33>>
  5041. @end example
  5042. @noindent
  5043. The upper and lower triangular representations are distinguishable by
  5044. whether or not the row lengths form an increasing sequence.
  5045. In addition to representing symmetric matrices, these upper and lower
  5046. @cindex symmetric matrix
  5047. triangular forms are also appropriate for representing matrices whose
  5048. remaining entries are zero, such as the factors in an LU
  5049. decomposition.
  5050. @cindex LU decomposition
  5051. @deftypefun void *avm_matrix_of_list (int @var{square}, int @var{upper_triangular}, int @var{lower_triangular}, int @var{column_major}, list @var{operand}, size_t @var{item_size}, list *@var{message}, int *@var{fault})
  5052. This function converts a matrix in one of the list representations
  5053. above to a contiguous array according to the given specifications.
  5054. The array can contain elements of any fixed sized type of size
  5055. @var{item_size}. The memory for it is allocated by this function and
  5056. it should be freed by the caller when no longer needed.
  5057. The input matrix is given by the list parameter, @var{operand}, and
  5058. its format is described by the integer parameters @var{square},
  5059. @var{upper_triangular}, and @var{lower_triangular}. The number of
  5060. bytes occupied by each entry is given by @var{item_size}.
  5061. To the extent these specifications are redundant, they are used for
  5062. validation. If any of the following conditions is not met, the integer
  5063. referenced by @var{fault} is assigned a non-zero value and a copy
  5064. of the message @code{<'bad matrix specification'>} represented as
  5065. a list is assigned to the list referenced by @var{message}. Errors
  5066. are also possible due to insufficient memory.
  5067. @itemize @bullet
  5068. @item
  5069. The @var{operand} must be a list of lists of lists such that
  5070. each item of each item is has a length of @var{item_size},
  5071. and its items consist of character representations as
  5072. required by @code{avm_value_of_list} (@ref{Primitive types}).
  5073. @item
  5074. If the lengths of the top level lists in the @var{operand} form an
  5075. increasing sequence, the lower triangular representation is assumed
  5076. and the @var{lower_triangular} parameter must have a non-zero value.
  5077. @item
  5078. If the lengths of the top level lists in the @var{operand} form a
  5079. decreasing sequence, the upper triangular representation is assumed
  5080. and the @var{upper_triangular} parameter must have a non-zero value.
  5081. @item
  5082. At least one of @var{upper_triangular} or @var{lower_triangular} must
  5083. be zero.
  5084. @item
  5085. If @var{square} has a non-zero value, then either all items of the
  5086. @var{operand} must have the same length as the operand, or if it's
  5087. triangular, then the longest one must have the same length as the
  5088. operand.
  5089. @item
  5090. If the @var{operand} is neither square nor a triangular form, all
  5091. items of it are required to have the same length.
  5092. @end itemize
  5093. The parameters @var{upper_triangular} or @var{lower_triangular} may be
  5094. set to non-zero values even if the @var{operand} is not in one of the
  5095. upper or lower triangular forms discussed above. In this case, the
  5096. @var{operand} must be square or rectangular (i.e., with all items the
  5097. same length), and the following interpretations apply.
  5098. @itemize @bullet
  5099. @item
  5100. If @var{upper_triangular} is non-zero, the diagonal elements and the
  5101. upper triangular portion of the input matrix are copied to the output.
  5102. The lower triangle of the input is ignored and the lower triangle of
  5103. the output is left uninitialized.
  5104. @item
  5105. If @var{lower_triangular} is non-zero, the diagonal elements and the
  5106. lower triangular portion of the input matrix are copied to the output.
  5107. The upper triangle of the input is ignored and the upper triangle of
  5108. the output is left uninitialized.
  5109. @end itemize
  5110. The @var{column_major} parameter affects the form of the output array.
  5111. If it is zero, then each row of the input matrix is stored in a
  5112. contiguous block of memory in the output array, and if it is non-zero,
  5113. each column is stored contiguously.
  5114. @cindex Fortran
  5115. The latter representation is also
  5116. known as Fortran order and may be required by library functions
  5117. written in Fortran.
  5118. In all cases when a triangular form is specified, part of the output
  5119. matrix is left uninitialized. The redundant entries may be assigned if
  5120. required by the @code{avm_reflect_matrix} function (@ref{Related
  5121. utility functions}).
  5122. @end deftypefun
  5123. @deftypefun list avm_list_of_matrix (void *@var{matrix}, int @var{rows}, int @var{cols}, size_t @var{item_size}, int *@var{fault})
  5124. This function performs an inverse operation to
  5125. @code{avm_matrix_of_list} by taking the address of a matrix stored as
  5126. a contiguous array in the parameter @var{matrix} and constructing the
  5127. list representation as discussed above. Only square and rectangular
  5128. matrices in row major order are supported, but see
  5129. @code{avm_matrix_transposition} for a way to convert between row major
  5130. @cindex column major order
  5131. and column major order (@ref{Related utility functions}).
  5132. The parameters @var{rows}, @var{cols}, and @var{item_size} describe
  5133. the form of the matrix. The list returned as a result will have a
  5134. length of @var{rows}, and each item will be a list of length
  5135. @var{cols}. Each item of the result corresponds to a row of the
  5136. matrix, and each item of the items represents the an entry of the
  5137. matrix as a list of length @var{item_size}. These items could be
  5138. passed to @code{avm_value_of_list}, for example, to obtain their
  5139. values (@ref{Primitive types}).
  5140. Memory is allocated by this function to create the list, which can be
  5141. reclaimed by @code{avm_dispose} (@ref{Simple Operations}). If there is
  5142. insufficient memory, the integer referenced by @var{fault} is assigned
  5143. a non-zero value and the result returned is a list representation of
  5144. the message @code{<'memory overflow'>}. The error message be reclaimed
  5145. by the caller as well using @code{avm_dispose}.
  5146. @end deftypefun
  5147. A packed storage representation for symmetric square matrices and
  5148. @cindex packed arrays
  5149. triangular matrices is of interest because it is used by some library
  5150. functions, notably those in @code{LAPACK}, to save memory and thereby
  5151. accommodate larger problems. In this representation, column major
  5152. @cindex column major order
  5153. order is assumed, and either the lower or the upper triangle of the
  5154. matrix is not explicitly stored. For example, a lower triangular
  5155. @cindex triangular matrix
  5156. matrix whose list representation corresponds to
  5157. @example
  5158. <
  5159. <a11>,
  5160. <a21,a22>,
  5161. <a31,a32,a33>,
  5162. <a41,a42,a43,a44>>
  5163. @end example
  5164. @noindent
  5165. would be stored according to the memory map
  5166. @cindex matrix memory map
  5167. @example
  5168. [a11 a21 a31 a41 a22 a32 a42 a33 a43 a44]
  5169. @end example
  5170. @noindent
  5171. with @code{a11} at the beginning address. An upper triangular matrix
  5172. @example
  5173. <
  5174. <a11,a12,a13,a14>,
  5175. <a22,a23,a24>,
  5176. <a33,a34>,
  5177. <a44>>
  5178. @end example
  5179. @noindent
  5180. would be stored according to the memory map
  5181. @example
  5182. [a11 a12 a22 a13 a23 a33 a14 a24 a34 a44].
  5183. @end example
  5184. A couple of functions converting between list representations and
  5185. packed array format are provided as described below.
  5186. @deftypefun void *avm_packed_matrix_of_list (int @var{upper_triangular}, list @var{operand}, int @var{n}, size_t @var{item_size}, list *@var{message}, int *@var{fault})
  5187. If the @var{operand} is a list in one of the triangular forms
  5188. explained above, then the @var{upper_triangular} parameter must be
  5189. consisitent with it, being non-zero if the @var{operand} is upper
  5190. triangular and zero otherwise.
  5191. If the @var{operand} is not in a triangular form, then each item of
  5192. the operand must be a list of length @var{n}. In this case, the
  5193. @var{upper_triangular} parameter indicates which triangle of the
  5194. operand should be copied to the result, and the other triangle is
  5195. ignored.
  5196. In either case, the operand must have a length of @var{n}, and the
  5197. items of its items must be lists of length @var{item_size} containing
  5198. character representations as required by @code{avm_value_of_list}
  5199. (@ref{Primitive types}).
  5200. If the input parameters are inconsistent or if there is insufficient
  5201. memory to allocate the result, the integer referenced by @var{fault}
  5202. is assigned a non-zero value, and the list referenced by @var{message}
  5203. is assigned a copy of the list representation of @code{<'bad matrix
  5204. specification'>} or @code{<'memory overflow'>}, respectively. A
  5205. non-empty message must be reclaimed by the caller using
  5206. @code{avm_dispose} (@ref{Simple Operations}).
  5207. If there are no errors, the result is a pointer to a packed array
  5208. representation of the @var{operand} as explained above. The memory for
  5209. this result is allocated by this function and should be freed by the
  5210. caller when no longer required. The number of bytes allocated will be
  5211. @var{item_size} * (@var{n} * (@var{n} + 1))/2.
  5212. @end deftypefun
  5213. @deftypefun list avm_list_of_packed_matrix (int @var{upper_trianguler},void *@var{operand}, int @var{n}, size_t @var{item_size}, int *@var{fault})
  5214. This function performs an inverse operation to that of
  5215. @code{avm_packed_matrix_of_list} given the address of a packed matrix
  5216. stored according to one of the memory maps discussed above. The
  5217. @var{operand} parameter holds the address, the parameter @var{n} gives
  5218. the number of rows, and the @var{upper_triangular} parameter specifies
  5219. which of the two possible memory maps to assume.
  5220. If there is sufficient memory, the result returned is a list in one of
  5221. the triangular forms described above, being upper triangular if the
  5222. @var{upper_triangular} parameter is non-zero, with values of length
  5223. @var{item_size} taken from the array.
  5224. In the event of a memory overflow, the integer referenced by
  5225. @var{fault} is assigned a non-zero value and the result is a copy of
  5226. the message @code{<'memory overflow'>} represented as a list. A
  5227. @cindex segmentation fault
  5228. segmentation fault is possible if this function is passed an invalid
  5229. pointer or dimension.
  5230. @end deftypefun
  5231. @node Related utility functions, , Two dimensional arrays, Type Conversions
  5232. @subsubsection Related utility functions
  5233. A small selection of additional functions that are likely to be of use
  5234. to developers concerned with matrix operations has been incorporated
  5235. into the API to save the trouble of reinventing them, although doing
  5236. so would be straightforward. They are described in this section
  5237. without further motivation.
  5238. @deftypefun void *avm_matrix_transposition (void *@var{matrix}, int @var{rows}, int @var{cols}, size_t @var{item_size})
  5239. This function takes the address of an arbitrary rectangular
  5240. @var{matrix} represented as a contiguous array (not a list) and
  5241. transposes it in place. That is, this function transforms
  5242. an @var{m} by @var{n} matrix to an @var{n} by @var{m} matrix
  5243. by exchanging the @var{i},@var{j}th element with the
  5244. @var{j},@var{i}th element for all values of @var{i} and @var{j}.
  5245. The numbers of rows and columns in the @var{matrix} are given by the
  5246. parameters @var{rows} and @var{cols}, respectively, and the size of
  5247. the entries in bytes is given by @var{item_size}.
  5248. The @var{matrix} is assumed to be in row major order, but this
  5249. function is applicable to matrices in column major order if the caller
  5250. @cindex column major order
  5251. passes the number of columns in @var{rows} and the number of rows in
  5252. @var{cols}.
  5253. Alternatively, this function can be seen as a conversion between the
  5254. row major and the column major representation of a matrix. An @var{m}
  5255. by @var{n} matrix in row major order will be transformed to the same
  5256. @var{m} by @var{n} matrix in column order, or from column order to row
  5257. order.
  5258. A notable feature of this function is that it allocates no memory so
  5259. there is no possibility of a memory overflow even for very large
  5260. matrices, unlike a naive implementation which would involve making a
  5261. temporary copy of the matrix. There is a possibility of a segmentation
  5262. @cindex segmentation fault
  5263. fault if invalid pointers or dimensions are given.
  5264. @end deftypefun
  5265. @deftypefun void *avm_matrix_reflection (int @var{upper_triangular}, void *@var{matrix}, int @var{n}, size_t @var{item_size})
  5266. This function takes a symmetric square @var{matrix} of dimension
  5267. @var{n} containing entries of @var{item_size} bytes each and fills in
  5268. the redundant entries.
  5269. If @var{upper_triangular} is non-zero, the
  5270. upper triangle of the @var{matrix} is copied to the lower triangle. If
  5271. @var{upper_triangular} is zero, the lower triangular entries are
  5272. copied to the upper triangle.
  5273. These conventions assume row major order. If the @var{matrix} is in
  5274. @cindex row major order
  5275. column major order, then the caller can either transpose it in place
  5276. @cindex column major order
  5277. before and after this function by @code{avm_matrix_transposition}, or
  5278. can complement the value of @var{upper_triangular}.
  5279. Note that this function may be unnecessary for @code{LAPACK} library
  5280. functions that ignore the redundant entries in a symmetric matrix,
  5281. because they can be left uninitialized, but it is included for the
  5282. sake of completeness.
  5283. @end deftypefun
  5284. @deftypefun list *avm_row_number_array (counter @var{m}, int *@var{fault})
  5285. A fast, memory efficient finite map from natural numbers to their list
  5286. representations can be obtained by using this function as an
  5287. alternative to @code{avm_natural} or @code{avm_recoverable_natural}
  5288. when repeated evaluations of numbers within a known range are
  5289. required (@ref{Simple Operations} and @ref{Recoverable Operations}).
  5290. Given a positive integer @var{m}, this function allocates and returns
  5291. an array of @var{m} lists whose @var{i}th entry is the list
  5292. representation of the number @var{i} as explained in
  5293. @ref{Representation of Numeric and Textual Data}.
  5294. An amount of memory proportional to @var{m} is used for the array and
  5295. its contents. If there is insufficient memory, a @code{NULL} value is
  5296. returned and the integer referenced by @var{fault} is set to a
  5297. non-zero value.
  5298. @end deftypefun
  5299. @deftypefun void avm_dispose_rows (counter @var{m}, list *@var{row_number})
  5300. This function reclaims an array @var{row_number} of size @var{m}
  5301. returned by @code{avm_row_number_array}, and its contents if any. A
  5302. @code{NULL} pointer is allowed as the @var{row_number} parameter and
  5303. will have no effect, but an uninitialized pointer will cause a
  5304. @cindex segmentation fault
  5305. segmentation fault.
  5306. @end deftypefun
  5307. @deftypefun void avm_initialize_matcon ();
  5308. This function initializes some static variables used by the functions
  5309. declared in @file{matcon.h} and should be called before any of them is
  5310. called or they might not perform according to specifications.
  5311. @end deftypefun
  5312. @deftypefun void avm_count_matcon ();
  5313. This function frees the static variables allocated by
  5314. @code{avm_initialize_matcon} and is used to verify the absence of
  5315. memory leaks. It should be called after the last call to any functions
  5316. in @file{matcon.h} but before @code{avm_count_lists} if the latter
  5317. is being used (@ref{Simple Operations}).
  5318. @end deftypefun
  5319. @node Comparison, Deconstruction Functions, Type Conversions, Lists
  5320. @subsection Comparison
  5321. The file @file{compare.h} contains a few function declarations
  5322. pertaining to the computation of the comparison predicate described in
  5323. @ref{Compare}. Some of the work is done by static functions in
  5324. @file{compare.c} that are not recommended entry points to the library.
  5325. @deftypefun void avm_initialize_compare ()
  5326. @cindex @code{compare}
  5327. This function should be called once before the first call to
  5328. @code{avm_comparison}, as it initializes some necessary internal data
  5329. structures.
  5330. @end deftypefun
  5331. @deftypefun void avm_count_compare ()
  5332. This function can be used to check for memory leaks, by detecting
  5333. unreclaimed storage at the end of a run. The data structures relevant to
  5334. comparison that could be reported as unreclaimed are known as ``decision''
  5335. nodes, but these should always be handled properly by the library
  5336. without intervention. If @code{avm_count_lists} is also being used, the
  5337. call to this function must precede it.
  5338. @end deftypefun
  5339. @deftypefun list avm_comparison (list @var{operand}, int *@var{fault})
  5340. This function takes a list operand representing a pair of trees and
  5341. returns a list representing the logical value of their equality. If the
  5342. operand is @code{NULL}, a message of invalid comparison is returned and
  5343. the @code{*@var{fault}} is set to a non-zero value. If the @code{head} of the
  5344. operand is unequal to the @code{tail}, a @code{NULL} value is
  5345. returned. If they are equal, a list is returned whose @code{head} and
  5346. @code{tail} are both @code{NULL}. The equality in question is structural
  5347. @cindex pointer equality
  5348. rather than pointer equality.
  5349. The list operand to this function may be modified by this function, but
  5350. not in a way that should make any difference to a client program. If two
  5351. lists are found to be equal, or if even two sublists are found to be
  5352. equal in the course of the comparison, one of them is deallocated and
  5353. made to point to the other. This action saves memory and may make
  5354. subsequent comparisons faster. However, it could disrupt client programs
  5355. @cindex pointers
  5356. that happen to be holding stale list pointers.
  5357. @cindex discontiguous field
  5358. As of @code{avram} version 0.6.0, a logical field called
  5359. @code{discontiguous} has been added to the @code{node} record type
  5360. declared in @code{lists.h}, which is checked by the comparison
  5361. function. If a list node has its @code{discontiguous} field set to a
  5362. non-zero value, and if it also has a non-null @code{value} field, then
  5363. it won't be deallocated in the course of comparison even if it is
  5364. found to be equal to something else. This feature can be used by
  5365. client modules to create lists in which value fields refer to data
  5366. structures that are meant to exist independently of them. See
  5367. @file{mpfr.c} for an example.
  5368. This function is likely to have better performance and memory usage than
  5369. a naive implementation of comparison, for the above reasons and also
  5370. because of optimizations pertaining to comparison of lists representing
  5371. characters. Moreover, it is not subject to stack overflow exceptions
  5372. @cindex recursion
  5373. because it is not written in a recursive style.
  5374. @end deftypefun
  5375. @deftypefun list avm_binary_comparison (list @var{left_operand}, list @var{right_operand}, int *@var{fault});
  5376. This function is the same as @code{avm_comparison} except that it
  5377. allows the left and right operands to be passed as separate lists
  5378. rather than taking them from the @code{head} and the @code{tail} of a
  5379. single list.
  5380. @end deftypefun
  5381. @node Deconstruction Functions, Indirection, Comparison, Lists
  5382. @subsection Deconstruction Functions
  5383. A fast native implementation of the deconstruction operation is provided
  5384. @cindex deconstruction
  5385. by the functions declared in @file{decons.h}.
  5386. @deftypefun void avm_initialize_decons ()
  5387. This should be called prior to the first call to
  5388. @code{avm_deconstruction}, so as to initialize some necessary internal
  5389. data structures. Results will be undefined if it is not.
  5390. @end deftypefun
  5391. @deftypefun void avm_count_decons ()
  5392. For ecologically sound memory management, this function should be called
  5393. at the end of a run to verify that there have been no leaks due to the
  5394. deconstruction functions, which there won't be unless the code in
  5395. @file{decons.c} has been ineptly modified. An error message to the
  5396. effect of unreclaimed ``points'' could be the result otherwise.
  5397. @end deftypefun
  5398. @deftypefun list avm_deconstruction (list @var{pointer}, list @var{operand}, int *@var{fault})
  5399. Deconstructions are performed by this function, as described in
  5400. @ref{Field}. In the @code{silly} program notation (@ref{A Simple Lisp
  5401. Like Language}), this function computes the value
  5402. of ([[@code{field}]] @code{@var{pointer}}) @code{@var{operand}}.
  5403. For example, using the fixed list @code{avm_join(NULL,NULL)} as the
  5404. @code{@var{pointer}} parameter will cause a copy of the operand itself
  5405. to be returned as the result. A @code{@var{pointer}} equal to
  5406. @code{avm_join(NULL,avm_join(NULL,NULL))} will cause a copy of
  5407. @code{operand->tail} to be returned, and so on. A @code{NULL}
  5408. @code{@var{pointer}} causes an internal error.
  5409. If the deconstruction is invalid, as in the case of the tail of an empty
  5410. list, the invalid deconstruction error message is returned as the
  5411. result, and the @code{*@var{fault}} parameter is set to a non-zero value.
  5412. The @code{*@var{fault}} parameter is also set to a non-zero value in the event
  5413. of a memory overflow, and the memory overflow message is returned.
  5414. @end deftypefun
  5415. @node Indirection, The Universal Function, Deconstruction Functions, Lists
  5416. @subsection Indirection
  5417. In some cases it is necessary to build a tree from the top down rather
  5418. @cindex pointers
  5419. than from the bottom up, when it is not known in advance what's on the
  5420. bottom. Although the @code{list} type is a pointer itself, these
  5421. situations call for a type of pointers to lists, which are declared as
  5422. the @code{branch} type in @file{branches.h}. For example, if @code{b} is
  5423. declared as a @code{branch} and @code{l} is declared as a @code{list},
  5424. it would be possible to write @code{b = &l}.
  5425. Facilities are also provided for maintaining queues of branches, which
  5426. @cindex queues
  5427. are declared as the @code{branch_queue} type. This type is a pointer to
  5428. a structure with two fields, @code{above} and @code{following}, where
  5429. @code{above} is a @code{branch} and @code{following} is a
  5430. @code{branch_queue}.
  5431. These functions are used internally elsewhere in the library and might
  5432. not be necessary for most client programs to use directly.
  5433. @deftypefun void avm_initialize_branches ()
  5434. This must be done once before any of the other branch related functions is
  5435. used, and creates some internal data structures. Results of the other
  5436. functions are undefined if this one isn't called first.
  5437. @end deftypefun
  5438. @deftypefun void avm_count_branches ()
  5439. This function can be used at the end of a run to detect unreclaimed
  5440. storage used for branches or branch queues. If any storage remains
  5441. unreclaimed, a message about unreclaimed branches is written to standard
  5442. error.
  5443. @end deftypefun
  5444. @deftypefun void avm_anticipate (branch_queue *@var{front}, branch_queue *@var{back}, branch @var{operand})
  5445. This function provides a simple queueing facility for
  5446. branches. Similarly to the case with @code{avm_enqueue}, @code{front}
  5447. and @code{back} should be initialized to @code{NULL} before the first
  5448. call. Each call to this function will enqueue one item to the back,
  5449. assuming enough memory is available, as the following example shows.
  5450. @example
  5451. front = NULL;
  5452. back = NULL;
  5453. l = avm_join(NULL,NULL);
  5454. anticipate(&front,&back,&(l->head));
  5455. anticipate(&front,&back,&(l->tail));
  5456. @end example
  5457. After the above code is executed, these postconditions will hold.
  5458. @example
  5459. front->above == &(l->head)
  5460. front->following->above == &(l->tail)
  5461. front->following == back
  5462. back->following == NULL
  5463. @end example
  5464. The name ``anticipate'' is used because ordinarily the queue contains
  5465. positions in a tree to be filled in later. As usual, only unshared trees should be
  5466. modified in place.
  5467. @end deftypefun
  5468. @deftypefun void avm_recoverable_anticipate (branch_queue *@var{front}, branch_queue *@var{back}, branch @var{operand}, int *@var{fault})
  5469. This function is similar to @code{avm_anticipate}, except that it will
  5470. not exit with an error message in the event of an overflow error, but
  5471. will simply set @code{*@var{fault}} to a non-zero value and return to the
  5472. caller. If an overflow occurs, nothing about the queue is changed.
  5473. @end deftypefun
  5474. @deftypefun void avm_enqueue_branch (branch_queue *@var{front}, branch_queue *@var{back}, int @var{received_bit})
  5475. A slightly higher level interface to the @code{avm_anticipate} function
  5476. is provided by this function, which is useful for building a tree from
  5477. @cindex trees
  5478. a string of input bits in a format similar to the one described in
  5479. @ref{Concrete Syntax}.
  5480. This function should be called the first time with @code{front} and
  5481. @code{back} having been initialized to represent a queue containing a
  5482. @cindex queues
  5483. single branch pointing to a list known to the caller. The list itself
  5484. need not be allocated or initialized. An easy way of doing so would be
  5485. the following.
  5486. @example
  5487. front = NULL;
  5488. back = NULL;
  5489. avm_anticipate(&front,&back,&my_list);
  5490. @end example
  5491. On each call to @code{avm_enqueue_branch}, the @code{@var{received_bit}}
  5492. parameter is examined. If it is zero, nothing will be added to the
  5493. queue, the list referenced by the front branch will be assigned
  5494. @code{NULL}, and the front branch will be removed from the queue. If
  5495. @code{@var{received_bit}} is a non-zero value, the list referenced by
  5496. the front branch will be assigned to point to a newly created unshared
  5497. list node, and two more branches will be appended to the queue. The
  5498. first branch to be appended will point to the head of the newly created
  5499. list node, and the second branch to be appended will point to the tail.
  5500. If the sequence of bits conforms to the required concrete syntax, this
  5501. function can be called for each of them in turn, and at the end of the
  5502. sequence, the queue will be empty and the list referenced by the initial
  5503. branch (i.e., @code{my_list}) will be the one specified by the bit
  5504. string. If the sequence of bits does not conform to the required
  5505. concrete syntax, the error can be detected insofar as the emptying of
  5506. the queue will not coincide exactly with the last bit.
  5507. The caller should check for the queue becoming prematurely empty due to
  5508. syntax errors, because no message is reported by
  5509. @code{avm_enqueue_branch} in that event, and subsequent attempts to
  5510. enqueue anything are ignored. However, in the event of a memory overflow,
  5511. an error message is reported and the process is terminated.
  5512. @end deftypefun
  5513. @deftypefun void avm_recoverable_enqueue_branch (branch_queue *@var{front}, branch_queue *@var{back}, int @var{received_bit}, int *@var{fault})
  5514. This function is similar to @code{avm_enqueue_branch} but will leave
  5515. error handling to the caller in the event of insufficient memory to
  5516. enqueue another branch. Instead of printing an error message and
  5517. exiting, it will dispose of the queue, set the @code{@var{fault}} flag
  5518. to a non-zero value, and return. Although the queue will be reclaimed,
  5519. the lists referenced by the branches in it will persist. The list nodes
  5520. themselves can be reclaimed by disposing of the list whose address was
  5521. stored originally in the front branch.
  5522. @end deftypefun
  5523. @deftypefun void avm_dispose_branch_queue (branch_queue @var{front})
  5524. This function deallocates a branch queue by chasing the @code{following}
  5525. fields in each one. It does nothing to the lists referenced by the
  5526. branches in the queue.
  5527. Rather than using @code{free} directly, client programs should use this
  5528. function for deallocating branch queues, because it allows better
  5529. performance by interacting with a local internal cache of free memory,
  5530. and because it performs necessary bookkeeping for
  5531. @code{avm_count_branches}.
  5532. @end deftypefun
  5533. @deftypefun void avm_dispose_branch (branch_queue @var{old})
  5534. This disposes of a single branch queue node rather than a whole queue.
  5535. Otherwise, the same comments as those above apply.
  5536. @end deftypefun
  5537. @node The Universal Function, , Indirection, Lists
  5538. @subsection The Universal Function
  5539. @cindex universal function
  5540. A function computing the result of the invisible operator used to
  5541. specify the virtual code semantics in @ref{Virtual Code Semantics}, is
  5542. easily available by way of a declaration in @file{apply.h}.
  5543. @deftypefun void avm_initialize_apply ()
  5544. This function should be called by the client program at least once prior
  5545. to the first call to @code{avm_apply} or
  5546. @code{avm_recoverable_apply}. It causes certain internal data structures
  5547. and error message texts to be initialized.
  5548. @end deftypefun
  5549. @deftypefun void avm_count_apply ()
  5550. This function should be used at the end of a run for the purpose of
  5551. detecting and reporting any unreclaimed storage associated with
  5552. functions in this section. If the function @code{avm_count_lists()} is
  5553. also being used, it should be called after this one.
  5554. @end deftypefun
  5555. @deftypefun list avm_apply (list @var{operator}, list @var{operand})
  5556. This is the function that evaluates the operator used to describe the
  5557. virtual code semantics. For example, the value of @code{@var{f} @var{x}}
  5558. can be obtained as the result returned by
  5559. @code{avm_apply(@var{f},@var{x})}.
  5560. Both parameters to this function are deallocated unconditionally and
  5561. should not be referenced again by the caller. If the parameters are
  5562. needed subsequently, then only copies of them should be passed to
  5563. @code{avm_apply} using @code{avm_copied}.
  5564. This function is not guaranteed to terminate, and may cause a memory
  5565. overflow error. In the event of an exceptional condition, the error
  5566. message is written to standard error and the program is halted. There is
  5567. no externally visible distinction between different levels of error
  5568. conditions.
  5569. @end deftypefun
  5570. @deftypefun list avm_recoverable_apply (list @var{operator}, list @var{operand}, int *@var{fault})
  5571. This function is similar to @code{avm_apply} but leaves the
  5572. responsibility of error handling with the caller. If any
  5573. overflow or exceptional condition occurs, the result returned is a list
  5574. representing the error message, and the @code{@var{fault}} flag is set to
  5575. a non-zero value. This behavior contrasts with that of @code{avm_apply},
  5576. which will display the message to standard error and kill the process.
  5577. @end deftypefun
  5578. @node Characters and Strings, File Manipulation, Lists, Library Reference
  5579. @section Characters and Strings
  5580. @cindex character strings
  5581. If a C program is to interact with a virtual code application by
  5582. exchanging text, it uses the representation for characters described in
  5583. @ref{Character Table}. This convention would be inconvenient without a
  5584. suitable API, so the functions in this section address the need. These
  5585. functions are declared in the header file @file{chrcodes.h}.
  5586. Some of these functions have two forms, with one of them having the
  5587. word @code{standard} as part of its name. The reason is to cope with
  5588. multiple character encodings. Versions of @code{avram} prior to 0.1.0
  5589. @cindex character encodings
  5590. @cindex multiple character encodings
  5591. used a different character encoding than the one documented in
  5592. @ref{Character Table}. The functions described in @ref{Version
  5593. Management} can be used to select backward compatible operation with
  5594. the older character encoding. The normal forms of the functions in
  5595. this section will use the older character set if a backward
  5596. compatibility mode is indicated, whereas the standard forms will use
  5597. the character encoding documented in @ref{Character Table} regardless.
  5598. Standard encodings should always be assumed for library and function
  5599. @cindex standard character encoding
  5600. names associated with the @code{library} combinator (@ref{Calling
  5601. existing library functions}), and for values of lists defined by
  5602. @code{avm_list_of_value} (@ref{Primitive types}), but version
  5603. dependent encodings should be used for all other purposes such as
  5604. error messages. Alternatively, the normal version dependent forms of
  5605. the functions below can be used safely in any case if backward
  5606. @cindex backward compatability
  5607. compatibility is not an issue. This distinction is viewed as a
  5608. transitional feature of the API that will be discontinued eventually
  5609. when support for the old character set is withdrawn and the
  5610. @code{standard} forms are be removed.
  5611. @deftypefun list avm_character_representation (int @var{character})
  5612. @end deftypefun
  5613. @deftypefun list avm_standard_character_representation (int @var{character})
  5614. This function takes an integer character code and returns a copy of
  5615. the list representing it, as per the table in @ref{Character
  5616. Table}. Because the copy is shared, no memory is allocated by this
  5617. function so there is no possibility of overflow. Nevertheless, it is
  5618. the responsibility of the caller dispose of the list when it is no
  5619. longer needed by @code{avm_dispose}, just as if the copy were not
  5620. shared (@ref{Simple Operations}). For performance reasons, this
  5621. function is implemented as a macro. If the argument is outside the
  5622. range of zero to 255, it is masked into that range.
  5623. @end deftypefun
  5624. @deftypefun int avm_character_code (list @var{operand})
  5625. @end deftypefun
  5626. @deftypefun int avm_standard_character_code (list @var{operand})
  5627. This function takes a list as an argument and returns the corresponding
  5628. character code, as per @ref{Character Table}. If the argument does not
  5629. represent any character, a value of @code{-1} is returned.
  5630. @end deftypefun
  5631. @deftypefun list avm_strung (char *@var{string})
  5632. @end deftypefun
  5633. @deftypefun list avm_standard_strung (char *@var{string})
  5634. This function takes a pointer to a null terminated character string and
  5635. returns the list obtained by translating each character into its list
  5636. representation and enqueuing them together. Memory needs to be allocated
  5637. for the result, and if there isn't enough available, an error message is
  5638. written to standard error and the process is terminated. This function
  5639. is useful to initialize lists from hard coded strings at the beginning
  5640. of a run, as in this example.
  5641. @example
  5642. hello_string = avm_strung("hello");
  5643. @end example
  5644. This form initializes a single string, but to initialize a one line
  5645. message suitable for writing to a file, it would have to be a list of
  5646. strings, as in this example.
  5647. @example
  5648. hello_message = avm_join(avm_strung("hello"),NULL);
  5649. @end example
  5650. The latter form is used internally by the library for initializing
  5651. most of the various error messages that can be returned by other functions.
  5652. @end deftypefun
  5653. @deftypefun list avm_recoverable_strung (char *@var{string}, int *@var{fault});
  5654. @end deftypefun
  5655. @deftypefun list avm_recoverable_standard_strung (char *@var{string}, int *@var{fault});
  5656. This function is like @code{avm_strung} except that if it runs out of memory
  5657. it sets the integer referenced by @var{fault} to a non-zero value and returns
  5658. instead of terminating the process.
  5659. @end deftypefun
  5660. @deftypefun char *avm_unstrung (list @var{string}, list *@var{message}, int *@var{fault})
  5661. @end deftypefun
  5662. @deftypefun char *avm_standard_unstrung (list @var{string}, list *@var{message}, int *@var{fault})
  5663. This function performs an inverse operation to
  5664. @code{avm_recoverable_strung}, taking a list representing a character
  5665. string to the character string in ASCII null terminated form as per
  5666. the standard C representation. Memory is allocated for the result by
  5667. this function which should be freed by the caller.
  5668. In the event of an exception, the integer referenced by @code{fault}
  5669. is assigned a non-zero value and an error message represented as a
  5670. list is assigned to the list referenced by @code{message}. The error
  5671. message should be reclaimed by the caller with @code{avm_dispose}
  5672. (@ref{Simple Operations} if it is non-empty. Possible error messages
  5673. are @code{<'memory overflow'>}, @code{<'counter overflow'>}, and
  5674. @code{<'invalid text format'>}.
  5675. @end deftypefun
  5676. @deftypefun list avm_scanned_list (char *@var{string})
  5677. An application that makes use of virtual code snippets or data that are
  5678. known at compile time can use this function to initialize them. The
  5679. argument is a string in the format described in @ref{Concrete Syntax},
  5680. and the result is the list representing it. For example, the program
  5681. discussed in @ref{Example Script} could be hard coded into a C program
  5682. by pasting the data from its virtual code file into an expression of
  5683. this form.
  5684. @example
  5685. cat_program = avm_scanned_list("sKYQNTP\\");
  5686. @end example
  5687. Note that the backslash character in the original data has to be
  5688. preceded by an extra backslash in the C source, because backslashes
  5689. usually mean something in C character constants.
  5690. The @code{avm_scanned_list} function needs to allocate memory. If there
  5691. isn't enough memory available, it writes a message to standard error and
  5692. causes the process to exit.
  5693. @end deftypefun
  5694. @deftypefun list avm_multiscanned (char **@var{strings})
  5695. Sometimes it may be useful to initialize very large lists from
  5696. strings, but some C compilers impose limitations on the maximum length
  5697. of a string constant, and the ISO standard for C requires only 512
  5698. bytes. This function serves a similar purpose to
  5699. @code{avm_scanned_list}, but allows the argument to be a pointer to a
  5700. null terminated array of strings instead of one long string, thereby
  5701. circumventing this limitation in the compiler.
  5702. @example
  5703. char *code[] = @{"sKYQ","NTP\\",NULL@};
  5704. ...
  5705. cat_program = avm_multiscanned(code);
  5706. @end example
  5707. If there is insufficient memory to allocate the list this function needs
  5708. to create, it causes an error message to be written to standard error,
  5709. and then kills the process.
  5710. @end deftypefun
  5711. @deftypefun char* avm_prompt (list @var{prompt_strings})
  5712. This function takes a list representing a list of character strings, and
  5713. returns its translation to a character string with the sequence 13 10
  5714. used as a separator. For example, given a tree of this form
  5715. @example
  5716. some_message = avm_join(
  5717. avm_strung("hay"),
  5718. avm_join(
  5719. avm_strung("you"),
  5720. NULL));
  5721. @end example
  5722. the result returned by @code{prompt_strings(some_message)} would be a
  5723. pointer to a null terminated character string equivalent to the C constant
  5724. @code{"hay\13\10you"}.
  5725. Error messages are printed and the process terminated in the event of
  5726. either a memory overflow or an invalid character representation.
  5727. This function is used by @code{avram} in the evaluation of interactive
  5728. @cindex interactive applications
  5729. virtual code applications, whose output has to be compared to the output
  5730. from a shell command in this format. The separator is chosen to be
  5731. compatible with the @code{expect} library.
  5732. @end deftypefun
  5733. @deftypefun char* avm_recoverable_prompt (list @var{prompt_strings}, list *@var{message}, int *@var{fault})
  5734. This function performs the same operation as @code{avm_prompt} but
  5735. allows the caller to handle exceptional conditions. If an exception
  5736. such as a memory overflow occurs, the integer referenced by
  5737. @code{fault} is assigned a non-zero value and a representation of the
  5738. error message as a list of strings is assigned to the list referenced
  5739. by @code{message}.
  5740. This function is used to by @code{avram} to evaluate the
  5741. @code{interact} combinator (@ref{Interaction combinator}), when
  5742. terminating in the event of an error would be inappropriate.
  5743. @end deftypefun
  5744. @deftypefun void avm_initialize_chrcodes ()
  5745. This function has to be called before any of the other character
  5746. conversion functions in this section, or else their results are
  5747. undefined. It performs the initialization of various internal data
  5748. structures.
  5749. @end deftypefun
  5750. @deftypefun void avm_count_chrcodes ()
  5751. This function can be called at the end of a run, after the last call to
  5752. any of the other functions in this section, but before
  5753. @code{avm_count_lists} if that function is also being used. The purpose
  5754. of this function is to detect and report memory leaks. If any memory
  5755. associated with any of these functions has not been reclaimed by the
  5756. client program, a message giving the number of unreclaimed lists will be
  5757. written to standard error.
  5758. @end deftypefun
  5759. @node File Manipulation, Invocation, Characters and Strings, Library Reference
  5760. @section File Manipulation
  5761. The functions described in this section provide an interface between
  5762. virtual code applications and the host file system by converting
  5763. between files or file names and their representations as lists. These
  5764. conversions are necessary when passing a file to a virtual code
  5765. application, or when writing a file received in the result of one.
  5766. @menu
  5767. * File Names::
  5768. * Raw Files::
  5769. * Formatted Input::
  5770. * Formatted Output::
  5771. @end menu
  5772. @node File Names, Raw Files, File Manipulation, File Manipulation
  5773. @subsection File Names
  5774. A standard representation is used by virtual code applications for the
  5775. @cindex file names
  5776. path names of files, following the description in @ref{Input Data
  5777. Structure}. The functions and constants declared in @code{fnames.h}
  5778. provide an API for operating on file names in this form.
  5779. @deftypefun list avm_path_representation (char *@var{path})
  5780. If a C program is to invoke a virtual code application and pass a path
  5781. name to it as a parameter, this function can be used to generate the
  5782. appropriate representation from a given character string.
  5783. @example
  5784. conf_path = avm_path_representation("/etc/resolve.conf");
  5785. @end example
  5786. In this example, @code{conf_path} is a @code{list}. For potentially
  5787. better portability, a C program can use the character constant
  5788. @code{avm_path_separator_character} in place of the slashes in hard
  5789. coded path names.
  5790. Other useful constants are @code{avm_current_directory_prefix} as a
  5791. @cindex @code{avm_path_separator_character}
  5792. @cindex @code{avm_path_separator}
  5793. @cindex @code{avm_current_directory_prefix}
  5794. @cindex @code{avm_parent_directory_prefix}
  5795. @cindex @code{avm_root_directory_prefix}
  5796. portable replacement for @code{"./"}, as well as
  5797. @code{avm_parent_directory_prefix} instead of @code{"../"}. There is
  5798. also @code{avm_root_directory_prefix} for @code{"/"}. These three
  5799. constants are null terminated strings, unlike
  5800. @code{avm_path_separator_character}, which is a character.
  5801. If a @code{NULL} pointer is passed as the @code{@var{path}}, a
  5802. @code{NULL} list is returned, which is the path representation for
  5803. standard input or standard output. If the address of an empty string is
  5804. passed to this function as the @code{@var{path}}, the list of the empty
  5805. string will be returned, which is the path representation for the root
  5806. directory. Trailing path separators are ignored, so @code{"/"} is the
  5807. same as the empty string.
  5808. Some memory needs to be allocated for the result of this function. If
  5809. the memory is not available, an error message is written to standard
  5810. error and the process is terminated.
  5811. @end deftypefun
  5812. @deftypefun list avm_date_representation (char *@var{path})
  5813. This function is essentially a wrapper around the standard
  5814. @code{ctime_r} function that not only gets the time stamp for a file at
  5815. a given path, but transforms it to a list representation according to
  5816. @ref{Character Table}. It needs to allocate memory for the result and
  5817. will cause the program to exit with an error message if there is not
  5818. enough memory available.
  5819. The time stamp will usually be in a format like @code{Sun Mar 4 10:56:40
  5820. GMT 2001}. If for some reason the time stamp can not be obtained, the
  5821. @cindex @code{unknown date}
  5822. result will be a representation of the string @code{unknown date}.
  5823. @end deftypefun
  5824. @deftypefun char* avm_path_name (list @var{path})
  5825. This function is the inverse of @code{avm_path_representation}, in that
  5826. it takes a list representing a path to the path name expressed as a character
  5827. string. This function can be used in C programs that invoke virtual code
  5828. applications returning paths as part of their results, so that the C
  5829. program can get the path into a character string in order to open the file.
  5830. If the @code{@var{path}} parameter is @code{NULL}, a @code{NULL} pointer
  5831. is returned as the result. The calling program should check for a
  5832. @cindex standard input
  5833. @cindex standard output
  5834. @code{NULL} result and interpret it as the path to standard input or
  5835. standard output.
  5836. The memory needed for the character string whose address is returned is
  5837. allocated by this function if possible. The given @code{@var{path}} is
  5838. not required to be consistent with the host file system, but it is
  5839. required to consist of representations of non-null printable characters
  5840. or spaces as lists per @ref{Character Table}. In the event of any error
  5841. or overflow, control does not return to the caller, but an error message
  5842. is printed and the program is aborted. The possible error messages from
  5843. this function are the following.
  5844. @cindex @code{counter overflow}
  5845. @cindex @code{memory overflow}
  5846. @cindex @code{null character in file name}
  5847. @cindex @code{bad character in file name}
  5848. @cindex @code{invalid file name}
  5849. @itemize @bullet
  5850. @item @code{@var{program-name}: counter overflow (code @var{nn})}
  5851. @item @code{@var{program-name}: memory overflow (code @var{nn})}
  5852. @item @code{@var{program-name}: null character in file name}
  5853. @item @code{@var{program-name}: bad character in file name}
  5854. @item @code{@var{program-name}: invalid file name (code @var{nn})}
  5855. @end itemize
  5856. @end deftypefun
  5857. @deftypefun void avm_initialize_fnames ()
  5858. A few housekeeping operations relevant to internal data structures are
  5859. performed by this function, making it necessary to be called by the
  5860. client program prior to using any of the other ones.
  5861. @end deftypefun
  5862. @deftypefun void avm_count_fnames ()
  5863. This function can be used after the the last call to any of the other
  5864. functions in this section during a run, and it will detect memory leaks
  5865. that may be attributable to code in these functions or misuse
  5866. thereof. If any unreclaimed storage remains when this function is
  5867. called, a warning message will be written to standard error. If the
  5868. function @code{avm_count_lists} is also being used by the client, it
  5869. should be called after this one.
  5870. @end deftypefun
  5871. @node Raw Files, Formatted Input, File Names, File Manipulation
  5872. @subsection Raw Files
  5873. Some low level operations involving lists and data files are provided by
  5874. these functions, which are declared in the header file @file{rawio.h}.
  5875. @deftypefun list avm_received_list (FILE *@var{object}, char *@var{filename})
  5876. This function is a convenient way of transferring data directly from a
  5877. raw format file into a list in memory. It might typically be used to
  5878. load the virtual code for an application that has been written to a file
  5879. by a compiler.
  5880. @table @code
  5881. @item @var{object}
  5882. is the address of a file which should
  5883. already be open for reading before this function is called, and will be
  5884. read from its current position.
  5885. @item @var{filename}
  5886. should be set by the caller to the address of a null terminated string
  5887. containing the name of the file, but is not used unless it needs to be
  5888. printed as part of an error message. If it is a null pointer, standard
  5889. input is assumed.
  5890. @end table
  5891. The result returned is a list containing data read from the file.
  5892. The file format is described in @ref{File Format}. The preamble section
  5893. of the file, if any, is ignored. If the file ends prematurely or
  5894. otherwise conflicts with the format, the program is aborted with a
  5895. message of
  5896. @cindex @code{invalid raw file format}
  5897. @display
  5898. @code{@var{program-name}: invalid raw file format in @var{filename}}
  5899. @end display
  5900. written to standard error. The program will also be aborted by this
  5901. function in the event of a memory overflow.
  5902. The file is left open when this function returns, and could therefore be
  5903. used to store other data after the end of the list. The end of a list is
  5904. detected automatically by this function, and it reads no further,
  5905. leaving the file position on the next character, if any.
  5906. @end deftypefun
  5907. @deftypefun void avm_send_list (FILE *@var{repository}, list @var{operand}, char *@var{filename})
  5908. This function can be used to transfer data from a list in memory to a
  5909. file, essentially by implementing the printing algorithm described in
  5910. @ref{Bit String Encoding}.
  5911. @table @code
  5912. @item @var{repository}
  5913. is the address of a file already open for writing, to which the data are
  5914. written starting from the current position.
  5915. @item @var{operand}
  5916. is the list containing the data to be written
  5917. @item @var{filename}
  5918. is the address of a null terminated string containing the name of the
  5919. file that will be reported in an error message if necessary.
  5920. @end table
  5921. No preamble section is written by this function, but one could be
  5922. @cindex preamble
  5923. written to the file by the caller prior to calling it. Error messages
  5924. are possible either because of i/o errors or because of insufficient
  5925. memory. I/o errors are not fatal and will result only in a warning
  5926. message being printed to standard error, but a memory overflow will
  5927. cause the process to abort. An i/o error message reported by this
  5928. function would be of the form
  5929. @cindex @code{can't write}
  5930. @display
  5931. @code{@var{program-name}: can't write to @var{filename}}
  5932. @end display
  5933. followed by the diagnostic obtained from the standard @code{strerror}
  5934. @cindex @code{strerror}
  5935. function if it exists on the host platform. The file is left open when
  5936. this function returns.
  5937. @end deftypefun
  5938. @deftypefun void avm_initialize_rawio ()
  5939. This function initializes some necessary data structures for the
  5940. functions in this section, and should be called prior to them at the
  5941. beginning of a run.
  5942. @end deftypefun
  5943. @deftypefun void avm_count_rawio ()
  5944. This function does nothing in the present version of the library, but
  5945. should be called after the last call to all of the other functions in
  5946. this section in order to maintain compatibility with future versions of
  5947. the library. Future versions may decide to use this function to do some
  5948. cleaning up of local data structures.
  5949. @end deftypefun
  5950. @node Formatted Input, Formatted Output, Raw Files, File Manipulation
  5951. @subsection Formatted Input
  5952. Some functions relating to the input of text files or data files with
  5953. preambles are declared in the header file @file{formin.h}. The usage of
  5954. these functions is as follows.
  5955. @deftypefun list avm_preamble_and_contents (FILE *@var{source}, char *@var{filename})
  5956. This function loads a file of either text or data format into memory.
  5957. @table @code
  5958. @item @var{source}
  5959. should be initialized by the caller as the address of a file
  5960. already open for reading that will be read from its current position.
  5961. @item @var{filename}
  5962. should be set by the caller to the address of a null terminated
  5963. character string giving the name of the file that will be used if an i/o
  5964. error message needs to be written about it. If it is a @code{NULL}
  5965. pointer, standard input is assumed.
  5966. @end table
  5967. The result returned by the function will be a list whose @code{head}
  5968. @cindex preamble
  5969. represents the preamble of the file and whose @code{tail} represents the
  5970. contents. As a side effect, the input file will be closed, unless the
  5971. @code{@var{filename}} parameter is @code{NULL}.
  5972. If the file conforms to the format described in @ref{File Format}, the
  5973. preamble is a list of character strings. In the result returned by the
  5974. function, the @code{head} field will be a list with one item for each
  5975. line in the file, and each item will be a list of character
  5976. representations as in @ref{Character Table}, but with the leading hashes
  5977. stripped. The @code{tail} will be the list specified by remainder of the
  5978. file according to @ref{Concrete Syntax}. If the file has an empty
  5979. preamble but is nevertheless a data file, the @code{head} will be a list
  5980. whose @code{head} and @code{tail} are both @code{NULL}.
  5981. If the file does not conform to the format in @ref{File Format}, then
  5982. the @code{head} of the result will be @code{NULL}, and the @code{tail}
  5983. will be a list of lists of character representations, with one for each
  5984. line.
  5985. Whether or not the file conforms to the format is determined on the fly,
  5986. so this function is useful for situations in which the format is not
  5987. known in advance. The conventions regarding the preamble and contents
  5988. maintained by this function are the same as those used by virtual code
  5989. applications as described in @ref{Standard Output Representation} and
  5990. @ref{Input Data Structure}.
  5991. The characters used for line breaks are not explicitly represented in
  5992. @cindex line breaks
  5993. the result. Depending on the host system, line breaks in text files may
  5994. be represented either by the character code 10, or by the sequence 13
  5995. 10. However, in order for the library to deal with binary files in a
  5996. portable way, a line break always corresponds to a 10 as far as this
  5997. function is concerned regardless of the host, and a 13 is treated like
  5998. any other character. Hence, if this function were used on binary files
  5999. that happened to have some 10s in them, the exact contents of a
  6000. file could be reconstructed easily by appending a 10 to all but the last
  6001. line and flattening the list.
  6002. A considerable amount of memory may need to be allocated by this
  6003. function in order to store the file as a list. If not enough memory is
  6004. available, the function prints an error message to standard error and
  6005. aborts rather than returning to the caller. However, i/o errors are not
  6006. fatal, and will cause the function to print a warning but attempt to
  6007. continue.
  6008. @end deftypefun
  6009. @deftypefun list avm_load (FILE *@var{source}, char *@var{filename}, int @var{raw})
  6010. Similarly to @code{avm_preamble_and_contents}, this function also loads
  6011. a file into memory, but the format is specified in advance.
  6012. @table @code
  6013. @item @var{source}
  6014. should be set by the caller to the address of an already open file for
  6015. reading, which will be read from its current position.
  6016. @item @var{filename}
  6017. should be initialized by the caller as a pointer to a null terminated
  6018. string containing the name of the file that will be reported to the user
  6019. in the event of an error reading from it. If it is a @code{NULL}
  6020. pointer, standard input is assumed.
  6021. @item @var{raw}
  6022. is set to a non-zero value by the caller to indicate that the file is
  6023. expected to conform to the format in @ref{File Format}. If the file is
  6024. an ordinary text file, then it should be set to zero.
  6025. @end table
  6026. In the case of a data file, which is when @code{@var{raw}} is non-zero,
  6027. the result returned by this function will be a list representing the
  6028. data section of the file and ignoring the preamble. In the case of a
  6029. text file, the result will be a list of lists of character
  6030. representations as per @ref{Character Table}, with one such list for
  6031. each line in the file. Similar comments about line breaks to those
  6032. mentioned under @code{avm_preamble_and_contents} are applicable.
  6033. As a side effect of this function, the @code{@var{source}} file will be
  6034. closed, unless the @code{@var{filename}} is a @code{NULL} pointer.
  6035. This function is useful when the type of file is known in advance. If a
  6036. data file is indicated by the @code{@var{raw}} parameter but the format
  6037. is incorrect, an error message is reported and the process
  6038. terminates. The error message will be of the form
  6039. @display
  6040. @code{@var{program-name}: invalid raw file format in @var{filename}}
  6041. @end display
  6042. Alternatively, if a text file is indicated by the
  6043. @cindex @code{invalid raw file format}
  6044. @code{@var{raw}} parameter, then no attempt is made to test whether it
  6045. could be interpreted as data, even if it could be. This behavior differs
  6046. from that of @code{avm_preamble_and_contents}, where a bad data
  6047. file format causes the file to be treated as text, and a valid data file
  6048. format, even in a ``text'' file, causes it to be treated as data.
  6049. Memory requirements for this function are significant and will cause the
  6050. process to abort with an error message in the event of insufficient free
  6051. memory. Messages pertaining to i/o errors are also possible and are not
  6052. fatal.
  6053. @end deftypefun
  6054. @deftypefun void avm_initialize_formin ()
  6055. This function should be called before either of the other functions in
  6056. this section is called, as it initializes some necessary static data
  6057. structures. Results of the other functions are undefined if this one is
  6058. not called first.
  6059. @end deftypefun
  6060. @deftypefun void avm_count_formin ()
  6061. This function should be called after the last call to any of the other
  6062. functions in this section, as it is necessary for cleaning up and
  6063. reclaiming some internal data. If any storage remains unreclaimed due to
  6064. memory leaks in these functions or to misuse of them, a warning message
  6065. is written to standard error. If the function @code{avm_count_lists} is
  6066. also being used by the client program, it should be called after this
  6067. one.
  6068. @end deftypefun
  6069. @node Formatted Output, , Formatted Input, File Manipulation
  6070. @subsection Formatted Output
  6071. The following functions pertaining to the output of text files or data files with
  6072. @cindex preamble
  6073. preambles are declared in the header file @file{formout.h}.
  6074. @deftypefun void avm_output (FILE *@var{repository}, char *@var{filename}, list @var{preamble}, list @var{contents}, int @var{trace_mode})
  6075. This function writes a either a text file or a data file in the format
  6076. described in @ref{File Format}. The parameters have these
  6077. interpretations.
  6078. @table @code
  6079. @item @var{repository}
  6080. is the address of a file opened for writing by the caller, that will be
  6081. written from its current position.
  6082. @item @var{filename}
  6083. is the address of a null terminated character string set
  6084. by the caller to be the name of the file that will
  6085. be reported to the user in the event of an i/o error.
  6086. @item @var{preamble}
  6087. is @code{NULL} in the case of a text file, but a list of character string
  6088. representations as per @ref{Character Table}, in the case of a data
  6089. file. If a data file has is to be written with an empty preamble, then
  6090. this list should have a @code{NULL} @code{head} and a @code{NULL}
  6091. @code{tail}.
  6092. @item @var{contents}
  6093. is either a list of character string representations in the case of a
  6094. text file, or is an unconstrained list in the case of a data file.
  6095. @item @var{trace_mode}
  6096. may be set to a non-zero value by the caller to request that everything
  6097. written to a text file should be echoed to standard output. It is
  6098. ignored in the case of a data file.
  6099. @end table
  6100. The effect of calling this function is to write the preamble and
  6101. contents to the file in the format indicated by the preamble. The file
  6102. is left open when this function returns.
  6103. Line breaks are always written as character code 10, not as 13 10,
  6104. @cindex line breaks
  6105. regardless of the convention on the host system, so that files written
  6106. by this function can be reliably read by other functions in the library.
  6107. Leading hashes are automatically added to the beginning of the lines in
  6108. the preamble, except where they are unnecessary due to a continuation
  6109. character on the previous line. This action enforces consistency with the
  6110. file format, ensuring that anything written as a data file can be read
  6111. back as one. The hashes are stripped automatically when the file is
  6112. read by @code{avm_preamble_and_contents}.
  6113. Another feature of this function is that it will mark any output file as
  6114. executable if it is a data format file with a prelude whose first
  6115. @cindex executable files
  6116. character in the first line is an exclamation point. This feature makes
  6117. it easier for a compiler implemented in virtual code to generate
  6118. executable shell scripts directly.
  6119. A fatal error is reported if any of the data required
  6120. to be a character representation is not listed in the @ref{Character
  6121. Table}. A fatal error can also be caused by a memory overflow. Possible
  6122. error messages are the following.
  6123. @cindex @code{invalid output preamble format}
  6124. @cindex @code{invalid text format}
  6125. @cindex @code{can't write}
  6126. @itemize @bullet
  6127. @item @code{@var{program-name}: invalid output preamble format}
  6128. @item @code{@var{program-name}: invalid text format}
  6129. @item @code{@var{program-name}: can't write to @var{filename}}
  6130. @end itemize
  6131. @cindex @code{strerror}
  6132. In the last case, the error message will be followed by an explanation
  6133. furnished by the standard @code{strerror} function if available.
  6134. @end deftypefun
  6135. @deftypefun void avm_output_as_directed (list @var{data}, int @var{ask_to_overwrite_mode}, int @var{verbose_mode})
  6136. This function writes an ensemble of files at specified paths in either
  6137. text or data format, optionally interacting with the user through
  6138. standard input and output. The parameters
  6139. have these interpretations.
  6140. @table @code
  6141. @item @var{data}
  6142. is a list in which each item specifies a file to be
  6143. written.
  6144. @item @var{ask_to_overwrite_mode}
  6145. may be set to a non-zero value by the calling program in order to
  6146. have this function ask the user for permission to overwrite existing files.
  6147. @item @var{verbose_mode}
  6148. may be set to a non-zero value by the calling program to have this
  6149. function print to standard output a list of the names of the files it
  6150. writes.
  6151. @end table
  6152. A high level interface between virtual code applications and the file
  6153. system is provided by this function. The @code{@var{data}} parameter
  6154. format is compatible with the the data structure returned by an
  6155. application complying with the conventions in @ref{Output From
  6156. Non-interactive Applications}.
  6157. Each item in the @code{@var{data}} list should be a non-empty list whose
  6158. @code{head} and @code{tail} are also non-empty. The fields in each item have
  6159. the following relevance to the file it specifies.
  6160. @itemize @bullet
  6161. @item The @code{head} of the @code{head} is @code{NULL} if the file is
  6162. to be opened for appending, and non-@code{NULL} if it is to be
  6163. overwritten.
  6164. @item The @code{tail} of the @code{head} represents a path as a list of
  6165. character string representations, in a form suitable as an argument to
  6166. @code{avm_path_name}.
  6167. @item The @code{head} of the @code{tail} represents the preamble of the
  6168. file, as either @code{NULL} for a text file or a non-empty list of
  6169. character string representations for a data file.
  6170. @item The @code{tail} of the @code{tail} represents the contents of the
  6171. file, either as a list of character string representations for a text
  6172. file or as a list in an unconstrained format for a data file.
  6173. @end itemize
  6174. For each item in the list, the function performs the following steps.
  6175. @enumerate
  6176. @item It decides whether to open a file
  6177. for overwriting or appending based on the @code{head} of the
  6178. @code{head}.
  6179. @item It uses the @code{tail} of the @code{head} to find out the
  6180. file name from @code{avm_path_name}, in order to open it.
  6181. @item If the
  6182. @code{@var{ask_to_overwrite_mode}} flag is set and the file is found to
  6183. exist already, the function will print one of the following messages to
  6184. standard output, depending on whether the file is to be overwritten or
  6185. appended.
  6186. @itemize @bullet
  6187. @item @code{@var{program-name}: overwrite @var{filename}? (y/n)}
  6188. @item @code{@var{program-name}: append to @var{filename}? (y/n)}
  6189. @end itemize
  6190. It will then insist on either @kbd{y} or @kbd{n} as an answer before continuing.
  6191. @item If the @code{@var{ask_to_overwrite}} flag has not been set, or the file did
  6192. not previously exist, or the answer of @kbd{y} was given, the preamble
  6193. and contents of the file are then written with @code{avm_output}.
  6194. @item If permission to write or append was denied, one of the following
  6195. messages is reported to standard output, and the data that were to be
  6196. written are lost.
  6197. @cindex @code{not writing} file name
  6198. @cindex @code{writing} file name
  6199. @itemize @bullet
  6200. @item @code{@var{program-name}: not writing @var{filename}}
  6201. @item @code{@var{program-name}: not appending @var{filename}}
  6202. @end itemize
  6203. @item If permission was granted to write or append to the file or the @code{@var{verbose_mode}} flag is
  6204. set, one of the messages
  6205. @itemize @bullet
  6206. @item @code{@var{program-name}: writing @var{filename}}
  6207. @item @code{@var{program-name}: appending @var{filename}}
  6208. @end itemize
  6209. is sent to standard output.
  6210. @end enumerate
  6211. @cindex standard output
  6212. If any files are to be written to standard output, which would be
  6213. indicated by a @code{NULL} path, they are not written until all other
  6214. files in the list are written. This feature is in the interest of
  6215. @cindex security
  6216. security, as it makes it more difficult for malicious or inept virtual
  6217. code to alter the appearance of the console through standard output until after
  6218. the interactive dialogue has taken place. Permission is not solicited
  6219. for writing to standard output, and it will not be closed.
  6220. Any of the fatal errors or i/o errors possible with @code{avm_output} or
  6221. @code{avm_path_name} are also possible with this function, as well as
  6222. the following additional ones.
  6223. @cindex @code{invalid file specification}
  6224. @cindex @code{can't close}
  6225. @cindex @code{can't write}
  6226. @itemize @bullet
  6227. @item @code{@var{program-name}: invalid file specification}
  6228. @item @code{@var{program-name}: can't close @var{filename}}
  6229. @item @code{@var{program-name}: can't write @var{filename}}
  6230. @end itemize
  6231. The last two are non-fatal i/o errors that will be accompanied by an
  6232. @cindex @code{strerror}
  6233. explanation from the @code{strerror} function if the host supports
  6234. it. The other message is the result of a badly formatted
  6235. @code{@var{data}} parameter.
  6236. @end deftypefun
  6237. @deftypefun void avm_put_bytes (list @var{bytes})
  6238. This function takes a list of character representations, converts them
  6239. to characters, and sends them to standard output. There is no chance of
  6240. a memory overflow, but the following other errors are possible.
  6241. @cindex @code{invalid text format}
  6242. @cindex @code{can't write}
  6243. @itemize @bullet
  6244. @item @code{@var{program-name}: invalid text format (code @var{nn})}
  6245. @item @code{@var{program-name}: can't write to standard output}
  6246. @end itemize
  6247. The latter is non-fatal, but the former causes the program to abort.
  6248. It is caused when any member of the list @code{@var{bytes}} is not a
  6249. character representation appearing in @ref{Character Table}.
  6250. @end deftypefun
  6251. @deftypefun void avm_initialize_formout ()
  6252. This function initializes some data structures used locally by the other
  6253. functions in this section, and should be called at the beginning of a
  6254. run before any of them is called.
  6255. @end deftypefun
  6256. @deftypefun void avm_count_formout ()
  6257. This function doesn't do anything in the current version of the library,
  6258. but should be called after the last call to any of the other functions
  6259. in this section. Future versions of the library might use this function
  6260. for cleaning up some internal data structures, and client programs that
  6261. call it will maintain compatibility with them.
  6262. @end deftypefun
  6263. @node Invocation, Version Management, File Manipulation, Library Reference
  6264. @section Invocation
  6265. The functions documented in this section can be used to incorporate the
  6266. capabilities of a virtual machine emulator into other C programs with
  6267. a minimal concern for the details of the required data structures
  6268. and virtual code invocation conventions.
  6269. @menu
  6270. * Command Line Parsing::
  6271. * Execution Modes::
  6272. @end menu
  6273. @node Command Line Parsing, Execution Modes, Invocation, Invocation
  6274. @subsection Command Line Parsing
  6275. @cindex command line
  6276. A couple of functions declared in @file{cmdline.h} can be used to do all
  6277. the necessary parsing of command lines and environment variables needed
  6278. by virtual code applications.
  6279. @deftypefun list avm_default_command_line (int @var{argc}, char *@var{argv}[], int @var{index}, char *@var{extension}, char *@var{paths}, int @var{default_to_stdin_mode}, int @var{force_text_input_mode}, int *@var{file_ordinal})
  6280. The purpose of this function is to build most of the data structure used
  6281. by parameter mode applications, as described in @ref{Input Data
  6282. Structure}, by parsing the command line according to @ref{Command Line
  6283. Syntax}. The parameters have these interpretations.
  6284. @table @code
  6285. @item @var{argc}
  6286. is the number elements in the array referenced by @code{@var{argv}}
  6287. @item @var{argv}
  6288. is the address of an array of pointers to null terminated character strings
  6289. holding command line arguments
  6290. @item @var{index}
  6291. is the position of the first element of @code{@var{argv}} to be
  6292. considered. Those preceding it are ignored.
  6293. @item @var{extension}
  6294. is the address of a string that will be appended to input file names
  6295. given in @code{@var{argv}} in an effort to find the associated files
  6296. @item @var{paths}
  6297. is the address of a null terminated character string containing a colon
  6298. separated list of directory names that will be searched for input files
  6299. @item @var{default_to_stdin_mode}
  6300. is set to a non-zero value by the caller if the contents of standard
  6301. input should be read in the absence of input files
  6302. @item @var{force_text_input_mode}
  6303. is set to a non-zero value by the caller to indicate that input files
  6304. should be read as text, using @code{avm_load} (rather than
  6305. @code{avm_preamble_and_contents}, which would allow them to be either
  6306. text or data). The @code{@var{preamble}} field of the returned file
  6307. specifications will always be empty when this flag is set.
  6308. @item @var{file_ordinal}
  6309. is set to a pointer to an integer by the caller if only one file is to
  6310. be loaded during each call. The value of the integer indicates the which
  6311. one it will be.
  6312. @end table
  6313. The result returned by this function is a list whose @code{head} is a list
  6314. of file specifications and whose @code{tail} is a list of command line options
  6315. intended for input to a virtual code application.
  6316. The list of file specifications returned in the @code{head} of the
  6317. result follows the same conventions as the @code{@var{data}} parameter
  6318. to the function @code{avm_output_as_directed}, except that the
  6319. @code{head} of the @code{head} of each item is a list representing the
  6320. time stamp of the file as given by @code{avm_date_representation}. If
  6321. the file is standard input, then it holds the current system date and
  6322. time.
  6323. If the @code{@var{file_ordinal}} parameter is @code{NULL}, then all
  6324. files on the command line are loaded, but if it points to an integer
  6325. @var{n}, then only the @var{n}th file is loaded, and @var{n} is
  6326. incremented. If there is no @var{n}th file, a @code{NULL} value is
  6327. returned as the entire result of the function. For a series of calls,
  6328. the integer should be initialized to zero by the caller before the first
  6329. call.
  6330. If standard input is indicated as one of the files on the command line
  6331. (by a dash), then it is also loaded regardless of the
  6332. @code{@var{file_ordinal}}, but a cached copy of it is used on subsequent
  6333. calls after the first, so that the function does not actually attempt to
  6334. reread it. If standard input is to be loaded, it must be finite for this
  6335. function to work properly.
  6336. The search strategy for files is described in @ref{Environment}, and
  6337. makes use of the @code{@var{extension}} and @code{@var{paths}} parameters.
  6338. In the list of command line options returned in the @code{tail} of the
  6339. result, each item is a list with a non-empty @code{head} and
  6340. @code{tail}, and is interpreted as follows.
  6341. @itemize @bullet
  6342. @item The @code{head} of the @code{head} is a list representing a
  6343. natural number, as given by @code{avm_natural}, indicating the position
  6344. of the option on the command line relative to the initial value of the
  6345. @code{@var{index}} parameter.
  6346. @item The @code{tail} of the @code{head} is a list which is @code{NULL}
  6347. in the case of a ``short form'' option, written with a single
  6348. dash on the command line, but is a list whose @code{head} and
  6349. @code{tail} are @code{NULL} in the case of a ``long form'' option,
  6350. written with two dashes.
  6351. @item The @code{head} of the @code{tail} is a list representing a
  6352. character string for the keyword of an option, for example @kbd{foo} in
  6353. the case of an option written @kbd{--foo=bar,baz}.
  6354. @item The @code{tail} of the @code{tail} is a list of lists representing
  6355. character strings, with one item for each parameter associated with the
  6356. option, for example, @kbd{bar} and @kbd{baz}.
  6357. @end itemize
  6358. If multiple calls to the function are made with differing values of
  6359. @code{*@var{file_ordinal}} but other parameters unchanged, the same list of
  6360. options will be returned each time, except insofar as the position
  6361. numbers in the @code{head} of the @code{head} of each item are adjusted
  6362. as explained in @ref{Input for Mapped Applications}.
  6363. Any of the i/o errors or fatal errors associated with other file
  6364. input operations are possible with this function as well. This non-fatal
  6365. warning message is also possible.
  6366. @cindex @code{search paths not supported}
  6367. @display
  6368. @code{@var{program-name}: warning: search paths not supported}
  6369. @end display
  6370. This error occurs if the library has been built on a platform that
  6371. @cindex @file{argz.h}
  6372. doesn't have the @file{argz.h} header file and the @code{@var{paths}}
  6373. parameter is non-@code{NULL}.
  6374. @end deftypefun
  6375. @deftypefun list avm_environment (char *@var{env}[])
  6376. @cindex environment
  6377. This function takes the address of a null terminated array of pointers
  6378. to null terminated character strings of the form
  6379. @code{"variable=value"}. The result returned is a list of lists, with
  6380. one item for each element of the array. The @code{head} of each item is
  6381. a representation of the left side of the corresponding string, and the
  6382. @code{tail} is a representation of the right.
  6383. This function is therefore useful along with
  6384. @code{avm_default_command_line} for building the remainder of the data
  6385. structure described in @ref{Parameter Mode Interface}. For example, a
  6386. virtual machine emulator for non-interactive parameter mode applications
  6387. with no bells and whistles could have the following form.
  6388. @example
  6389. int
  6390. main(argc,argv,env)
  6391. @dots{}
  6392. @{
  6393. FILE *virtual_code_file;
  6394. @dots{}
  6395. avm_initialize_lists();
  6396. avm_initialize_apply();
  6397. avm_initialize_rawio();
  6398. avm_initialize_formout();
  6399. avm_initialize_cmdline();
  6400. virtual_code_file = fopen(argv[1],"rb");
  6401. operator = avm_received_list(
  6402. virtual_code_file,argv[1]);
  6403. fclose(virtual_code_file);
  6404. command = avm_default_command_line(argc,
  6405. argv,2,NULL,NULL,0,0,NULL);
  6406. environs = avm_environment(env);
  6407. operand = avm_join(command,environs);
  6408. result = avm_apply(operator,operand);
  6409. avm_output_as_directed(result,0,0);
  6410. avm_dispose(result);
  6411. @dots{}
  6412. @}
  6413. @end example
  6414. The @code{avm_environment} function could cause the program to abort due
  6415. to a memory overflow. For security reasons, it will also abort with an
  6416. @cindex security
  6417. error message if any non-printing characters are detected in its
  6418. argument. (See @ref{Other Diagnostics and Warnings}.)
  6419. @end deftypefun
  6420. @deftypefun void avm_initialize_cmdline ()
  6421. This function initializes some local variables and should be called
  6422. before any of the other functions in this section is called, or else
  6423. their results are unpredictable.
  6424. @end deftypefun
  6425. @deftypefun void avm_count_cmdline ()
  6426. This function should be called after the last call to any of the other
  6427. functions in this section, as it reclaims some locally allocated
  6428. storage. If the @code{avm_count_lists} function is used, it should be
  6429. called after this one.
  6430. @end deftypefun
  6431. @node Execution Modes, , Command Line Parsing, Invocation
  6432. @subsection Execution Modes
  6433. Some functions declared in @file{exmodes.h} are useful for executing
  6434. interactive applications or filter mode transducers in a manner
  6435. consistent with the specifications described in the previous chapter.
  6436. @deftypefun void avm_interact (list @var{avm_interactor}, int @var{step_mode}, int @var{ask_to_overwrite_mode}, int @var{quiet_mode})
  6437. This function executes an interactive virtual code application. The
  6438. parameters have these interpretations.
  6439. @table @code
  6440. @item @var{avm_interactor}
  6441. is the virtual code for a function that performs as specified in
  6442. @ref{Output From Interactive Applications}.
  6443. @item @var{step_mode}
  6444. will cause all shell commands to be echoed if set to a non-zero
  6445. value, and will cause the program to pause after each shell command
  6446. until a key is pressed.
  6447. @item @var{ask_to_overwrite_mode}
  6448. can be set to a non-zero value by the caller to cause the program to ask
  6449. permission of the user to overwrite any existing files in cases where
  6450. the virtual code returns a file list as described in @ref{Mixed Modes of
  6451. Interaction}.
  6452. @item @var{quiet_mode}
  6453. can be set to a non-zero value to suppress console messages in the case
  6454. of file output per @ref{Mixed Modes of Interaction}.
  6455. @end table
  6456. The meaning of this function is accessible to any reader willing to slog
  6457. through @ref{Output From Interactive Applications}. The only subtle
  6458. point is that @code{@var{avm_interactor}} parameter in this function
  6459. does not correspond to the virtual code application that @code{avram}
  6460. reads from a virtual code file, but to the result computed when the
  6461. application read from the file is applied to the data structure
  6462. representing the command line and environment.
  6463. Any of the memory overflows or i/o errors possible with other functions
  6464. in the library are possible from this one as well, and will also cause
  6465. it to print an error message and halt the program. A badly designed
  6466. @cindex deadlock
  6467. virtual code application could cause a deadlock, which will not be
  6468. detected or reported
  6469. @end deftypefun
  6470. @deftypefun void avm_trace_interaction ()
  6471. This function enables diagnostic output for the @code{avm_recoverable_interact}
  6472. function.
  6473. @end deftypefun
  6474. @deftypefun void avm_disable_interaction ()
  6475. This function causes @code{avm_interact} and @code{avm_recoverable_interact}
  6476. to terminate with an error instead of executing, as required by the
  6477. @code{--jail} command line option.
  6478. @end deftypefun
  6479. @deftypefun list avm_recoverable_interact (list @var{interactor}, int @var{*fault})
  6480. This function is similar to @code{avm_interact} but always closes the
  6481. pipe and performs no file i/o, and will return an error message rather
  6482. than exiting. Otherwise it returns a transcript of the intereaction as
  6483. a list of lists of strings represented as lists of character
  6484. encodings. It implements the @var{interact} combinator with the
  6485. virtual code for the transducer function given as the parameter. A
  6486. prior call to @code{avm_trace_interaction} will cause diagnostic
  6487. information to be written to standard output when this function is
  6488. executed.
  6489. @end deftypefun
  6490. @deftypefun void avm_byte_transduce (list @var{operator})
  6491. This function executes a filter mode byte transducer application, which
  6492. behaves as described in @ref{Byte Transducers}. The argument is the
  6493. virtual code for the application, which would be found in a virtual code
  6494. file. There are limited opportunities for i/o errors, as only standard
  6495. input and standard output are involved with this function, but fatal
  6496. errors due to memory overflow are possible.
  6497. @end deftypefun
  6498. @deftypefun void avm_line_map (list @var{operator})
  6499. This function executes line mapped filter mode applications, which are
  6500. explained in @ref{Line Maps}. The argument is the virtual code for the
  6501. application. Similar comments to those above apply.
  6502. @end deftypefun
  6503. @deftypefun void avm_initialize_exmodes ()
  6504. This function should be called before any of the other functions in this
  6505. section in order to initialize some local variables. Results are
  6506. undefined if this function isn't called first.
  6507. @end deftypefun
  6508. @deftypefun void avm_count_exmodes ()
  6509. This function doesn't do anything in the present version of the library,
  6510. but should be called after the last call to any of the other functions
  6511. in this section in order to maintain compatibility with future versions,
  6512. which may use it for cleaning up local variables.
  6513. @end deftypefun
  6514. @node Version Management, Error Reporting, Invocation, Library Reference
  6515. @section Version Management
  6516. The @code{avram} library is designed to support any number of backward
  6517. @cindex versions
  6518. compatibility modes with itself, by way of some functions declared in
  6519. @file{vman.h}. The assumption is that the library will go through a
  6520. sequence of revisions during its life, each being identified by a unique
  6521. number. In the event of a fork in the project, each branch will
  6522. attempt to maintain compatibility at least with its own ancestors.
  6523. @deftypefun void avm_set_version (char *@var{number})
  6524. This function can be used to delay the demise of a client program that
  6525. uses the library but is not updated very often. The argument is a null
  6526. terminated string representing a version number, such as @code{"@value{VERSION}"}.
  6527. A call to this function requests that all library functions revert to
  6528. their behavior as of that version in any cases where the current
  6529. behavior is incompatible with it. It will also cause virtual code
  6530. applications evaluated with @code{avm_apply} to detect a version number
  6531. equal to the given one rather than the current one. (See @ref{Version}.)
  6532. The program will exit with an internal error message if any function in
  6533. the library has already interrogated the version number before this
  6534. function is called, or if it is passed a null pointer. This problem can
  6535. be avoided by calling it prior to any of the @code{avm_initialize}
  6536. functions with a valid address. The program will exit with the message
  6537. @display
  6538. @code{@var{program-name}: multiple version specifications}
  6539. @end display
  6540. if this function is called more than once, even with the same number.
  6541. If the number is not recognized as a present or past version, or is so
  6542. old that it is no longer supported, the program will exit with this
  6543. message.
  6544. @display
  6545. @code{avram: can't emulate version @var{number}}
  6546. @end display
  6547. Client programs that are built to last should allow the version number
  6548. to be specified as an option by the user, and let virtual code
  6549. applications that they execute take care of their own backward
  6550. compatibility problems. This strategy will at least guard against
  6551. changes in the virtual machine specification and other changes that do
  6552. not affect the library API.
  6553. @end deftypefun
  6554. @deftypefun int avm_prior_to_version (char *@var{number})
  6555. This function takes the address of a null terminated string representing
  6556. a version number as an argument, such as @code{"@value{VERSION}"}, and returns a
  6557. non-zero value if the version currently being emulated predates it.
  6558. If no call has been made to @code{avm_set_version} prior to the call to
  6559. this function, the current version is assumed, and subsequent calls to
  6560. @code{avm_set_version} will cause an internal error.
  6561. The intended use for this function would be by a maintainer of the
  6562. library introducing an enhancement that will not be backward compatible,
  6563. who doesn't wish to break existing client programs and virtual code
  6564. applications. For example, if a version @code{1.0} is developed at some
  6565. time in the distant future, and it incorporates a previously unexpected
  6566. way of doing something, code similar to the following could be used to
  6567. maintain backward compatibility.
  6568. @example
  6569. if (avm_prior_to_version("1.0"))
  6570. @{
  6571. /* do it the 0.x way */
  6572. @}
  6573. else
  6574. @{
  6575. /* do it the 1.0-and-later way */
  6576. @}
  6577. @end example
  6578. @noindent
  6579. This function will cause an internal error if the parameter does not
  6580. match any known past or present version number, or if it is a null pointer.
  6581. @end deftypefun
  6582. @deftypefun char* avm_version ()
  6583. This function returns the number of the version currently being emulated
  6584. as the address of a null terminated string. The string whose address is
  6585. returned should not be modified by the caller.
  6586. If no call has been made to @code{avm_set_version} prior to the call to
  6587. this function, the current version is assumed, and subsequent calls to
  6588. @code{avm_set_version} will cause an internal error.
  6589. @end deftypefun
  6590. @node Error Reporting, Profiling, Version Management, Library Reference
  6591. @section Error Reporting
  6592. @cindex error messages
  6593. Most of the error reporting by other functions in the library is done by
  6594. way of the functions declared in @file{error.h}. These function
  6595. communicate directly with the user through standard error. Client
  6596. programs should also use these functions where possible for the sake of
  6597. a uniform interface.
  6598. @deftypefun void avm_set_program_name (char *@var{argv0})
  6599. The argument to this function should be the address of a null terminated
  6600. string holding the name of the program to be reported in error messages
  6601. that begin with a program name. Typically this string will be the name
  6602. of the program as it was invoked on the command line, possibly with path
  6603. components stripped from it. An alternative would be to set it to the
  6604. name of a virtual code application being evaluated. If this function is
  6605. never called, the name @code{"avram"} is used by default. Space for a
  6606. copy of the program name is allocated by this function, and a fatal
  6607. memory overflow error is possible if there is insufficient space available.
  6608. @end deftypefun
  6609. @deftypefun char* avm_program_name ()
  6610. This function returns a pointer to a null terminated character string
  6611. holding the program name presently in use. It will be either the name
  6612. most recently set by @code{avm_set_program_name}, or the default name
  6613. @code{"avram"} if none has been set. The string whose address is
  6614. returned should not be modified by the caller.
  6615. @end deftypefun
  6616. @deftypefun void avm_warning (char *@var{message})
  6617. This function writes the null terminated string whose address is given
  6618. to standard error, prefaced by the program name and followed by a line
  6619. break.
  6620. @end deftypefun
  6621. @deftypefun void avm_error (char *@var{message})
  6622. This function writes the null terminated string whose address is given
  6623. to standard error, prefaced by the program name and followed by a line
  6624. break, as @code{avm_warning}, but it then terminates the process with an
  6625. exit code of 1.
  6626. @end deftypefun
  6627. @deftypefun void avm_fatal_io_error (char *@var{message}, char *@var{filename}, int @var{reason})
  6628. This function is useful for reporting errors caused in the course of
  6629. reading or writing files. The message is written to standard error
  6630. prefaced by the program name, and incorporating the name of the relevant
  6631. file. The @code{@var{reason}} should be the error code obtained from the
  6632. standard @code{errno} variable, which will be translated to an
  6633. @cindex @code{strerror}
  6634. informative message if possible by the standard @code{strerror} function
  6635. and appended to the message. After the message is written, the process
  6636. will terminate with an exit code of 1.
  6637. @end deftypefun
  6638. @deftypefun void avm_non_fatal_io_error (char *@var{message}, char *@var{filename}, int @var{reason})
  6639. This function does the same as @code{avm_fatal_io_error} except that it
  6640. doesn't exit the program, and allows control to return to the caller,
  6641. which should take appropriate action.
  6642. @end deftypefun
  6643. @deftypefun void avm_internal_error (int @var{code})
  6644. This function is used to report internal errors and halt the
  6645. program. The error message is written to standard error prefaced by the
  6646. program name and followed by a line break. The code should be a unique
  6647. integer constant (i.e., not one that's used for any other internal
  6648. error), that will be printed as part of the error message as an aid to
  6649. the maintainer.
  6650. This function should be used by client programs only in the event of
  6651. conditions that constitute some violation of a required invariant. It
  6652. indicates to the user that something has gone wrong with the program,
  6653. for which a bug report would be appropriate.
  6654. @end deftypefun
  6655. @deftypefun void avm_reclamation_failure (char *@var{entity}, counter @var{count})
  6656. This function is used only by the @code{avm_count} functions to report
  6657. unreclaimed storage. The @code{@var{count}} is the number of units of
  6658. storage left unreclaimed, and the @code{@var{entity}} is the address of
  6659. a null terminated string describing the type of unreclaimed entity, such
  6660. as @code{"lists"} or @code{"branches"}. The message is written to
  6661. standard error followed by a line break, but the program is not halted
  6662. and control returns to the caller.
  6663. @end deftypefun
  6664. @node Profiling, Emulation Primitives, Error Reporting, Library Reference
  6665. @section Profiling
  6666. @cindex @file{profile.h}
  6667. The functions declared in @file{profile.h} can be used for constructing
  6668. and writing tables of run time statistics such as those mentioned in
  6669. @ref{Files}, and @ref{Profile}. These functions maintain a database of
  6670. structures, each recording the statistics for a particular virtual code
  6671. fragment.
  6672. Each structure in the database is identified by a unique key, which must
  6673. be a list representing a character string. A pointer to such a structure
  6674. @cindex @code{score}
  6675. is declared to be of type @code{score}. For the most part, the data
  6676. structure should be regarded as opaque by a client program, except for a
  6677. field @code{reductions} of type @code{counter}, which may be modified
  6678. arbitrarily by the client.
  6679. The way these operations are used in the course of evaluating virtual
  6680. code applications containing profile annotations is to add a structure
  6681. to the database each time a new profiled code fragment is encountered,
  6682. using the annotation as its key, and to increment the @code{reductions}
  6683. @cindex annotations
  6684. of the structure each time any constituent of the code gets a quantum of
  6685. work done on it. Other ways of using these operations are left to the
  6686. developer's discretion.
  6687. @deftypefun score avm_entries (list @var{team}, list *@var{message}, int *@var{fault})
  6688. This function retrieves or creates a data base entry given its key. The
  6689. parameters have these interpretations.
  6690. @table @code
  6691. @item @var{team}
  6692. is a list representing a character string that uniquely identifies the
  6693. database entry to be retrieved or created.
  6694. @item @var{message}
  6695. is the address of a list known to the caller, which will be assigned a
  6696. list representing an error message if any error occurs in the course of
  6697. searching the database or creating a new entry.
  6698. @item @var{fault}
  6699. is the address of an integer that will be set to a non-zero value if any
  6700. error is caused by this function.
  6701. @end table
  6702. The pointer returned by this function is the address of the record whose
  6703. key is given by the @code{@var{team}} parameter. If such a record is
  6704. already in the database, its address is returned, but otherwise a new
  6705. one is created whose address is then returned. The @code{reductions}
  6706. field of a newly created entry will be zero.
  6707. In the course of searching the database, the @code{avm_compare}
  6708. function is used, so the associated lists may be modified as noted in
  6709. @ref{Comparison}. It is not necessary for a client to include the header
  6710. file @file{compare.h} or to call @code{avm_initialize_compare} in order
  6711. to use the profile operations, because they are done automatically.
  6712. If an error message is assigned to the list referenced by
  6713. @code{@var{message}}, the integer referenced by @code{@var{fault}} will
  6714. be set to a non-zero value. The form of the error message will be a list
  6715. in which each item is a list of character representations as per
  6716. @ref{Character Table}. It is the responsibility of the caller to dispose
  6717. of the error message. Currently the only possible error is a memory
  6718. overflow, which in this case is non-fatal.
  6719. @end deftypefun
  6720. @deftypefun void avm_tally (char *@var{filename})
  6721. This function makes a table of the results stored in the data base built
  6722. by the @code{avm_entries} function. The argument is the address of a
  6723. null terminated character string containing the name of the file in
  6724. which the results will be written. A file is opened and the table is
  6725. written in a self explanatory text format, with columns labeled
  6726. ``reductions'' and ``invocations'' among others. The latter contains the
  6727. number of times the associated key was accessed through
  6728. @code{avm_entries}.
  6729. The data written to the file should be taken with a grain of salt. It
  6730. is computed using native integer and floating point arithmetic, with no
  6731. checks made for overflow or roundoff error, and no guarantee of cross
  6732. @cindex reductions
  6733. platform portability. The number of ``reductions'' means whatever the
  6734. developer of the client program wants it to mean.
  6735. The following error messages are possible with this function, which will
  6736. be written to standard error. None of them is fatal.
  6737. @cindex @code{can't write}
  6738. @cindex @code{can't close}
  6739. @cindex @code{invalid profile identifier}
  6740. @itemize @bullet
  6741. @item @code{@var{program-name}: can't write @var{filename}}
  6742. @item @code{@var{program-name}: can't write to @var{filename}}
  6743. @item @code{@var{program-name}: can't close @var{filename}}
  6744. @item @code{@var{program-name}: invalid profile identifier}
  6745. @end itemize
  6746. The last message is reported if any record in the database has a key
  6747. that is not a list of valid character representations. The others are
  6748. @cindex @code{strerror}
  6749. accompanied by an explanation from the standard @code{strerror} function
  6750. if possible.
  6751. @end deftypefun
  6752. @deftypefun void avm_initialize_profile ()
  6753. This function should be called before any of the other functions in this
  6754. section in order to initialize the data base. Results are undefined if
  6755. it is not called first.
  6756. @end deftypefun
  6757. @deftypefun void avm_count_profile ()
  6758. This function can be called after the other functions in this section as
  6759. a way of detecting memory leaks. If any storage remains unreclaimed that
  6760. was created by the functions in this section, a warning message is
  6761. written to standard error. If the @code{avm_count_lists} function is
  6762. being used by the client program, it should be called after this one.
  6763. @end deftypefun
  6764. @node Emulation Primitives, External Library Maintenance, Profiling, Library Reference
  6765. @section Emulation Primitives
  6766. The functions documented in this section can be used to take very
  6767. specific control over the evaluation of virtual code applications. It is
  6768. unlikely that a client program will have any need for them unless it
  6769. aims to replace or extend the @code{avm_apply} function.
  6770. The virtual machine is somewhat removed from a conventional von Neumann
  6771. model of computation, so emulating it in C or any other imperative
  6772. language is less straightforward than one would prefer. An elaborate
  6773. system of interdependent data structures is used to represent partially
  6774. evaluated computations, which does not particularly lend itself to a
  6775. convenient, modular API. The abstraction provided by the functions in
  6776. this section is limited mainly to that of simple memory management and
  6777. stack operations. Consequently, a developer wishing to build on them
  6778. effectively would need to @emph{grok} the data structures involved,
  6779. which are described in some detail.
  6780. @menu
  6781. * Lists of Pairs of Ports::
  6782. * Ports and Packets::
  6783. * Instruction Stacks::
  6784. @end menu
  6785. @node Lists of Pairs of Ports, Ports and Packets, Emulation Primitives, Emulation Primitives
  6786. @subsection Lists of Pairs of Ports
  6787. @cindex @code{port}
  6788. A @code{port} is the name given to a type of pointer used in the library
  6789. as the address of a place where a computational result yet to be
  6790. evaluated will be sent. Ports are discussed further in @ref{Ports and Packets},
  6791. but are mentioned here because it is sometimes necessary to employ a
  6792. list of pairs of them. A pointer to such a list is declared as a
  6793. @code{portal} type. It refers to a structure of the form
  6794. @cindex @code{portal}
  6795. @cindex @code{port_pair}
  6796. @example
  6797. struct port_pair
  6798. @{
  6799. port left;
  6800. port right;
  6801. portal alters;
  6802. @}
  6803. @end example
  6804. A small selection of functions for @code{portal} memory management is
  6805. declared as follows in the header file @file{portals.h}. For reasons of
  6806. C-ness, the type declarations themselves are forced to be in
  6807. @file{lists.h}.
  6808. @deftypefun portal avm_new_portal (portal @var{alters})
  6809. This function is used to create storage for a new @code{port_pair}
  6810. structure, and returns a @code{portal} pointer to it if successful. If
  6811. the storage can't be allocated, a @code{NULL} pointer is returned.
  6812. The @code{alters} field of the result is initialized as the given
  6813. parameter supplied by the caller. All other fields are filled with zeros.
  6814. @end deftypefun
  6815. @deftypefun void avm_seal (portal @var{fate})
  6816. This function performs the reclamation of storage associated with
  6817. @code{portal} pointers, either by freeing them or by consigning them
  6818. temporarily to a local cache for performance reasons. Client programs
  6819. should use only this function for disposing of @code{portal} storage
  6820. rather than using @code{free} directly, so as to allow accurate record
  6821. keeping.
  6822. @end deftypefun
  6823. @deftypefun void avm_initialize_portals ()
  6824. This function should be called by a client program prior to calling
  6825. either of the above memory management functions in order to initialize
  6826. some local variables. Anomalous results are possible otherwise.
  6827. @end deftypefun
  6828. @deftypefun void avm_count_portals ()
  6829. This function should be called at the end of a run or after the last
  6830. call to any of the other functions in this section as a way of detecting
  6831. memory leaks associated with @code{portal} pointers. A warning message
  6832. will be written to standard error if any remains unreclaimed.
  6833. @end deftypefun
  6834. @node Ports and Packets, Instruction Stacks, Lists of Pairs of Ports, Emulation Primitives
  6835. @subsection Ports and Packets
  6836. A pointer type declared as a @code{port} points to a structure in the
  6837. following form, where a @code{flag} is an unsigned short integer type,
  6838. and a @code{counter} is an unsigned long integer.
  6839. @cindex @code{counter}
  6840. @cindex @code{flag}
  6841. @cindex @code{avm_packet}
  6842. @example
  6843. struct avm_packet
  6844. @{
  6845. port parent;
  6846. counter errors;
  6847. portal descendents;
  6848. list impetus, contents;
  6849. flag predicating;
  6850. @};
  6851. @end example
  6852. @noindent
  6853. For reasons that make sense to C, the @code{avm_packet} and @code{port}
  6854. types are declared in @code{lists.h}, but a few memory management
  6855. operations on them are available by way of functions declared in
  6856. @file{ports.h}. The intended meaning of this structure is described
  6857. presently, but first the memory management functions are as follows.
  6858. @deftypefun port avm_newport (counter @var{errors}, port @var{parent}, int @var{predicating})
  6859. This function attempts to allocate storage for a new packet structure
  6860. and returns its address if successful. If storage can not be allocated,
  6861. a @code{NULL} pointer is returned. The @code{errors}, @code{parent}, and
  6862. @code{predicating} fields are initialized with the parameters supplied
  6863. by the caller. The rest of the structure is filled with zeros. A local
  6864. memory cache is used for improved performance.
  6865. @end deftypefun
  6866. @deftypefun void avm_sever (port @var{appendage})
  6867. This function reclaims the storage associated with a @code{port}, either
  6868. freeing it entirely or holding it in a local cache. None of the
  6869. entities that may be referenced by pointers within the structure are
  6870. affected. Only this function should be used by client programs for
  6871. disposing of ports, not the @code{free} function directly, or some
  6872. internal bookkeeping will be disrupted. An internal error results if the
  6873. argument is a @code{NULL} pointer.
  6874. @end deftypefun
  6875. @deftypefun void avm_initialize_ports ()
  6876. This function must be called prior to calling either of the two above,
  6877. in order to initialize some static variables.
  6878. @end deftypefun
  6879. @deftypefun void avm_count_ports ()
  6880. This function may be called after the last call to any of the other
  6881. functions in this section in order to detect and report unreclaimed
  6882. storage associated with ports. A non-fatal warning will be written to
  6883. standard error if any is detected, but otherwise there is no effect.
  6884. @end deftypefun
  6885. The interesting aspect of this data structure is the role it plays in
  6886. capturing the state of a computation. For this purpose, it corresponds
  6887. to a single node in a partially computed result to be represented by a
  6888. @code{list} when it's finished. The nodes should be envisioned as a
  6889. doubly-linked binary tree, except that the pair of @code{descendents}
  6890. for each node is not yet known with certainty, so a list of alternatives
  6891. must be maintained.
  6892. Because the computation is not completed while this data structure
  6893. exists, there are always some empty fields in it. For example, the
  6894. @code{descendents} and the @code{contents} fields embody the same
  6895. information, the latter doing so in a compact as opposed to a more
  6896. expanded form. Hence, it would be redundant for both fields to be
  6897. non-empty at the same time. The data structure is built initially with
  6898. @code{descendents} and no @code{contents}, only to be transformed into
  6899. one with @code{contents} and no @code{descendents}.
  6900. The significance of each field in the structure can be summarized as
  6901. follows.
  6902. @table @code
  6903. @item contents
  6904. If the computational result destined for the @code{port} pointing to this packet
  6905. is not complete, then this field is @code{NULL} and the
  6906. @code{descendents} are being computed. Otherwise, it contains the result
  6907. of the computation.
  6908. @item descendents
  6909. This field points to a list of pairs of ports serving as the
  6910. destinations for an ensemble of concurrent computations.@footnote{Earlier
  6911. versions of @code{avram} included a bottom avoiding choice combinator
  6912. that required this feature, but which has been withdrawn. A single pair
  6913. of descendent ports would now suffice.} The @code{head}
  6914. and @code{tail} of the @code{contents} are to be identified respectively
  6915. with the @code{contents} of the @code{left} and @code{right} @code{port}
  6916. in the first pair to finish being computed.
  6917. @item parent
  6918. If this packet is addressed by the @code{left} or the @code{right} of
  6919. @code{port} in one of the @code{descendents} of some other packet, then
  6920. this field points to that packet.
  6921. @item errors
  6922. A non-zero value in this field indicates that the result destined for
  6923. the @code{contents} of this packet is expected to be an error
  6924. message. If the exact level of error severity incurred in the
  6925. computation of the @code{contents} matches this number, then the
  6926. contents can be assigned the result, but otherwise the result should
  6927. propagate to the @code{contents} of the @code{parent}.
  6928. @item predicating
  6929. A non-zero value in this field implies that the result destined for the
  6930. @code{contents} of this packet is being computed in order to decide
  6931. which arm of a conditional function should be chosen. I.e., a
  6932. @code{NULL} result calls for the one that is invoked when the predicate
  6933. is false.
  6934. @item impetus
  6935. If the result destined for the @code{contents} of this packet is being
  6936. computed in order to transform a virtual code fragment from its original
  6937. form to an equivalent representation capable of being evaluated more
  6938. directly, this field points to a @code{list} node at the root of the
  6939. virtual code in its original form.
  6940. @end table
  6941. One of the hitherto undocumented fields in a @code{list} node structure
  6942. @cindex @code{interpretation}
  6943. @cindex @code{impetus}
  6944. declared in @file{lists.h} is called the @code{interpretation}, and is
  6945. of type @code{list}. A client program delving into sufficient depth of
  6946. detail to be concerned with ports and packets may reasonably assign the
  6947. @code{interpretation} field of the @code{list} referenced by the
  6948. @code{impetus} field in a packet to be a copy of the @code{contents} of
  6949. the packet when they are eventually obtained. Doing so will save some
  6950. time by eliminating the need for it to be recomputed if the same virtual
  6951. code should be executed again.
  6952. If this course is taken, the @code{facilitator} field in a @code{list}
  6953. @cindex @code{facilitator}
  6954. node, also hitherto undocumented, should contain the address of the
  6955. packet referring to the list node as its @code{impetus}. The reason for
  6956. this additional link is so that it can be followed when the
  6957. @code{impetus} of the packet is be cleared by @code{avm_dispose} in the
  6958. event that the @code{list} node is freed before the computation
  6959. completes. This action is performed in order to preclude a dangling
  6960. pointer in the @code{impetus} field.
  6961. @node Instruction Stacks, , Ports and Packets, Emulation Primitives
  6962. @subsection Instruction Stacks
  6963. A header file named @file{instruct.h} declares a number of memory
  6964. management and stack operations on a data structure of the following
  6965. form.
  6966. @cindex @code{instruction_node}
  6967. @example
  6968. struct instruction_node
  6969. @{
  6970. port client;
  6971. score sheet;
  6972. struct avm_packet actor;
  6973. struct avm_packet datum;
  6974. instruction dependents;
  6975. @};
  6976. @end example
  6977. In this structure, an @code{instruction} is a pointer to an
  6978. @code{instruction_node}, a @code{score} is a pointer to a profile
  6979. database entry as discussed in @ref{Profiling}, and the @code{port} and
  6980. @code{avm_packet} types are as described in @ref{Ports and Packets}.
  6981. This data structure is appropriate for a simple virtual machine code
  6982. @cindex concurrency
  6983. evaluation strategy involving no concurrency. The strategy to evaluate an
  6984. expression @code{@var{f} @var{x}} would be based on a stack of these
  6985. nodes threaded through the @code{dependents} field, and would proceed
  6986. something like this.
  6987. @enumerate
  6988. @item
  6989. The stack is initialized to contain a single node having
  6990. @code{@var{f}} in its @code{actor.contents} field, and @code{@var{x}} in
  6991. its @code{datum.contents} field.
  6992. @item
  6993. The @code{client} in this node would refer to a static packet to whose
  6994. @code{contents} field the final result will be delivered.
  6995. @item
  6996. The evaluator examines the @code{actor.contents} field on the top of the
  6997. stack, detects by its form the operation it represents, and decides
  6998. whether it corresponds to one that can be evaluated immediately by way
  6999. of a canned function available in the library. List reversal,
  7000. transposition, and comparison would be examples of such operations.
  7001. @item
  7002. If the operation can be performed in this way, the result is computed
  7003. and assigned to the destination indicated by the @code{client} field.
  7004. @item
  7005. If the operation is not easy enough to perform immediately but is of a
  7006. form recognizable as a combination of simpler operations, it is
  7007. decomposed into the simpler operations, and each of them is
  7008. strategically positioned on the stack so as to effect the evaluation of
  7009. the combination. For example, if @code{@var{f}} were of the form
  7010. @code{compose(@var{g},@var{h})} (@code{silly} notation), the node with
  7011. @code{@var{f}} and @code{@var{x}} would be popped, but a node with
  7012. @code{@var{g}} as its @code{actor.contents} would be pushed, and then a
  7013. node with @code{@var{h}} as its @code{actor.contents} and @code{@var{x}}
  7014. as its @code{datum.contents} would be pushed. Furthermore, the
  7015. @code{client} field of the latter node would point to the
  7016. @code{datum.contents} of the one with @code{@var{g}}, and the
  7017. @code{client} field of the one with @code{@var{g}} would point
  7018. wherever the @code{client} of the popped node used to point.
  7019. @item
  7020. If the operation indicated by the top @code{actor.contents} is neither
  7021. implemented by a canned operation in the library nor easily decomposable
  7022. into some that are, the evaluator can either give up or use virtual code
  7023. to execute other virtual code. The latter trick is accomplished by
  7024. pushing a node with @code{@var{f}} as its @code{datum.contents}, and a
  7025. copy of a hard coded virtual code interpreter @code{@var{V}} as its
  7026. @code{actor.contents}. The @code{client} of this node will point to the
  7027. @code{@var{f}} in the original node so as to overwrite it when a
  7028. simplified version is subsequently computed. The implementation of
  7029. @code{@var{V}} is a straightforward exercise in @code{silly}
  7030. programming.
  7031. @item
  7032. In any case, the evaluator would continue working on the stack until
  7033. everything on it has been popped, at which time the result of the entire
  7034. computation will be found in the packet addressed by the @code{client}
  7035. in the original instruction node.
  7036. @end enumerate
  7037. What makes this strategy feasible to implement is the assumption of a
  7038. sequential language, wherein synchronization incurs no cost and is
  7039. automatic. The availability of any operand is implied by its position at
  7040. the top of the stack. If you are reading this section with a view to
  7041. @cindex threads
  7042. implementing a concurrent or multi-threaded evaluation strategy, it will
  7043. be apparent that further provisions would need to be made, such as that
  7044. of a @code{data_ready} flag added to the @code{avm_packet} structure.
  7045. The following functions support the use of stacks of instruction nodes
  7046. that would be needed in an evaluation strategy such as the one above.
  7047. @deftypefun int avm_scheduled (list @var{actor_contents}, counter @var{datum_errors}, list @var{datum_contents}, port @var{client}, instruction *@var{next}, score @var{sheet})
  7048. This function performs the memory allocation for instruction nodes. It
  7049. attempts to create one and to initialize the fields with the given
  7050. parameters, returning a pointer to it if successful. It returns a
  7051. @code{NULL} pointer if the storage could not be allocated.
  7052. Copies of the @code{list} parameters @code{actor_contents} and
  7053. @code{data_contents} are made by this function using @code{avm_copied},
  7054. so the originals still exist as far as the caller is concerned and will
  7055. have to be deallocated separately from this structure. The copies are
  7056. made only if the allocation succeeds.
  7057. Any fields other than those indicated by the parameters to this function
  7058. are filled with zeros in the result.
  7059. @end deftypefun
  7060. @deftypefun void avm_retire (instruction *@var{done})
  7061. This function performs the storage reclamation of instructions, taking
  7062. as its argument the instruction to be reclaimed. The @code{list} fields
  7063. in the structure corresponding to the @code{list} parameters used when
  7064. it was created are specifically reclaimed as well, using
  7065. @code{avm_dispose}.
  7066. The argument to this function is the address of an @code{instruction}
  7067. rather than just an @code{instruction} so that the @code{instruction}
  7068. whose address is given may be reassigned as the @code{dependents} field
  7069. of the deallocated node. In this way, the instructions can form a stack
  7070. that is popped by this function.
  7071. This function cooperates with @code{avm_scheduled} in the use of a local
  7072. cache of instruction nodes in the interest of better performance. Client
  7073. modules should not attempt to allocate or reclaim instructions directly
  7074. with @code{malloc} or @code{free}, but use only these functions.
  7075. It causes a fatal internal error to pass a @code{NULL} pointer to this
  7076. function.
  7077. @end deftypefun
  7078. @deftypefun void avm_reschedule (instruction *@var{next})
  7079. Given the address of an instruction pointer that may be regarded as the
  7080. top of a stack of instructions threaded through the @code{dependents}
  7081. field, this function exchanges the positions of the top instruction and
  7082. the one below it. A fatal internal error is caused if there are fewer
  7083. than two instructions in the stack.
  7084. A use for this function arises in the course of evaluating virtual code
  7085. applications of the form @code{conditional(@var{p},(@var{f},@var{g}))}
  7086. (in @code{silly} notation). The evaluation strategy would require
  7087. pushing nodes for all three constituents, but with @code{@var{p}} pushed
  7088. last (therefore evaluated first). The result of the evaluation of
  7089. @code{@var{p}} would require either the top one or the one below it to
  7090. be popped without being evaluated, depending on whether the result is
  7091. empty.
  7092. @end deftypefun
  7093. @deftypefun void avm_initialize_instruct ()
  7094. This function should be called before any of the instruction memory
  7095. management functions is called in order to initialize some local data
  7096. structures. Results are unpredictable without it.
  7097. @end deftypefun
  7098. @deftypefun void avm_count_instruct ()
  7099. This function should be called after the last call to any of the
  7100. other functions in this section in order to detect and report
  7101. unreclaimed storage associated with them. A warning message will be
  7102. written to standard error if any unreclaimed instructions remain. This
  7103. function relies on the assumption that the memory management has been
  7104. done only by way of the above functions.
  7105. @end deftypefun
  7106. @node External Library Maintenance, , Emulation Primitives, Library Reference
  7107. @section External Library Maintenance
  7108. External mathematical library functions such as those documented in
  7109. @ref{External Libraries} that are invoked from virtual code by the
  7110. @code{library} combinator (@ref{Library combinator}) are also
  7111. accessible from C by way of a uniform API implemented by the functions
  7112. declared in @code{libfuns.h}. This interface applies even to libraries
  7113. @cindex Fortran
  7114. implemented in Fortran such as @code{minpack}. This section briefly
  7115. documents the functions in @code{libfuns.h} and sets out some
  7116. recommeded guidelines for developers wishing to add support for other
  7117. external libraries.
  7118. @menu
  7119. * Calling existing library functions::
  7120. * Implementing new library functions::
  7121. * Working around library misfeatures::
  7122. @end menu
  7123. @node Calling existing library functions, Implementing new library functions, External Library Maintenance, External Library Maintenance
  7124. @subsection Calling existing library functions
  7125. Whatever data types a library function manipulates, its argument and
  7126. its result are each ultimately encoded each by a single list as
  7127. explained in @ref{Type Conversions}. This representation allows all
  7128. library functions to be invoked by a uniform calling convention as
  7129. detailed below.
  7130. @deftypefun list avm_library_call (list @var{library_name}, @var{list function_name}, list @var{argument}, int *@var{fault})
  7131. This function serves as an interpreter of external library functions
  7132. by taking a @var{library_name}, a @var{function_name}, and an
  7133. @var{argument} to the result returned by the corresponding library
  7134. function for the given @var{argument}.
  7135. The library and function names should be encoded as lists of character
  7136. representations, the same as the arguments that would be used with the
  7137. @code{library} combinator if it were being invoked by virtual code
  7138. @cindex backward compatability
  7139. (with attention to the backward compatibility issue explained in
  7140. @ref{Characters and Strings}).
  7141. If an error occurs in the course of evaluating a library function, the
  7142. integer referenced by @var{fault} will be assigned a non-zero value,
  7143. and the result will be a list of character string representations
  7144. explaining the error, such as @code{<'memory overflow'>}, for example.
  7145. Otherwise, the list returned will encode the result of the library
  7146. function in a way that depends on the particular function being evaluated.
  7147. @end deftypefun
  7148. @deftypefun list avm_have_library_call (list @var{library_name}, list @var{function_name}, int *@var{fault})
  7149. This function implements the @code{have} combinator described in
  7150. @ref{Have combinator}, which tests for the availability of a library
  7151. function. The @var{library_name} and @var{function_name} parameters
  7152. are as explained above for @code{avm_library_call}, and @code{fault}
  7153. could signal an error similarly for this function as well.
  7154. The result returned will be an error message in the event of an error,
  7155. or a list of pairs of strings otherwise. The list will be empty if the
  7156. library function is not available. If the library function is
  7157. available, the list will contain a single pair, as in
  7158. @example
  7159. <(library_name,function_name)>
  7160. @end example
  7161. In addition, the list representation of the character string
  7162. @code{'*'} can be specified as either the library name or the function
  7163. name or both. This string is interpreted as a wild card and will cause
  7164. all matching pairs of library and function names to be returned in the
  7165. list.
  7166. @end deftypefun
  7167. @deftypefun void avm_initialize_libfuns ()
  7168. This function initializes some static data structures used by the two
  7169. functions above. It may be called optionally before the first call to
  7170. either of them, but will be called automatically if not.
  7171. @end deftypefun
  7172. @deftypefun void avm_count_libfuns ()
  7173. This function can be used as an aid to detecting memory leaks. It
  7174. reclaims any data structures allocated by
  7175. @code{avm_initialize_libfuns} and should be called towards the end of
  7176. a run some time prior to @code{avm_count_lists} @ref{Simple
  7177. Operations}, if the latter is being used.
  7178. @end deftypefun
  7179. @node Implementing new library functions, Working around library misfeatures, Calling existing library functions, External Library Maintenance
  7180. @subsection Implementing new library functions
  7181. Adding more external libraries to @code{avram} is currently a manual
  7182. procedure requiring the attention of a developer conversant with C.
  7183. To support a new library called @code{foobar},
  7184. these steps need to be followed at a minimum.
  7185. @itemize @bullet
  7186. @item
  7187. Create a new file called @file{foobar.h} under the @file{avm/}
  7188. directory in the main source tree whose name doesn't clash with any
  7189. @cindex header file
  7190. @cindex library interface header file
  7191. existing file names and preferably doesn't induce any proper prefixes
  7192. among them. This file should contain at least these function
  7193. declarations.
  7194. @example
  7195. extern list avm_foobar_call (list function_name,list argument,
  7196. int *fault);
  7197. extern list avm_have_foobar_call (list function_name,int *fault);
  7198. extern void avm_initialize_foobar ();
  7199. extern void avm_count_foobar ();
  7200. @end example
  7201. There should also be the usual preprocessor directives for
  7202. @file{include} files. The naming convention shown should be followed in
  7203. anticipation of automated support for these operations in the future.
  7204. @item
  7205. Add @file{foobar.h} to the list of other header files in
  7206. @file{avm/Makefile.am}.
  7207. @item
  7208. Create a new file called @file{foobar.c} under the @file{src/}
  7209. directory whose name doesn't clash with any existing file names to
  7210. @cindex library interfac source file
  7211. store most of the library interface code. It can start out with
  7212. stubs for the functions declared in @file{foobar.h}.
  7213. @item
  7214. Add @file{foobar.c} to the list of other source files in
  7215. @file{src/Makefile.am}
  7216. @item
  7217. Execute the following command in the main @file{avram-x.x.x}
  7218. source directory where the file @file{configure.in} is found.
  7219. @example
  7220. aclocal \
  7221. && automake --gnu --add-missing \
  7222. && autoconf
  7223. @end example
  7224. This command requires having @code{automake} and
  7225. @cindex automake
  7226. @cindex autoconf
  7227. @code{autoconf} installed on your system.
  7228. @item
  7229. Make the following changes to @file{libfuns.c}.
  7230. @itemize @bullet
  7231. @item
  7232. Add the line @code{#include<avm/foobar.h>} after the
  7233. @cindex include directives
  7234. other @code{include} directives.
  7235. @item
  7236. Add the string @code{"foobar"} to the end of the array of
  7237. @code{libnames} in @code{avm_initialize_libfuns}.
  7238. @item
  7239. Add a call to @code{avm_initialize_foobar} to the body.
  7240. @item
  7241. Add a call to @code{avm_count_foobar} to the body of
  7242. @code{avm_count_libfuns}.
  7243. @item
  7244. Add a case of the form
  7245. @example
  7246. case nn:
  7247. return avm_foobar_call(function_name,argument,fault);
  7248. @end example
  7249. after the last case in @code{avm_library_call}, being
  7250. careful not to change the order, and using the same
  7251. name as above in the file @file{foobar.h}.
  7252. @item
  7253. Add a case of the form
  7254. @example
  7255. case nn:
  7256. looked_up = avm_have_foobar_call(function_name,fault);
  7257. break;
  7258. @end example
  7259. after the last case in @code{avm_have_library_call}, being
  7260. careful not to change the order, and using the same name
  7261. as above in the file @file{foobar.h}.
  7262. @end itemize
  7263. @item
  7264. Edit @file{foobar.c} and @file{foobar.h} to suit,
  7265. periodically compiling and testing by executing @code{make}.
  7266. @item
  7267. Package and install at will.
  7268. @end itemize
  7269. The functions shown above have the obvious interpretations, namely
  7270. that @code{avm_foobar_call} evaluates a library function from the
  7271. @code{foobar} library, and @code{avm_have_foobar_call} tests for a
  7272. function's availability. The latter should interpret wild cards as
  7273. explained in @ref{Calling existing library functions}, but should
  7274. return only a list of strings for the matching function names rather
  7275. than a list of pairs of strings, as the library name is redundant.
  7276. The remaining functions are for static initialization and reclamation.
  7277. These functions should consist mainly of boilerplate code similar to
  7278. the corresponding functions in any of the other library source files,
  7279. which should be consulted as examples. The real work would be done by
  7280. other functions called by them. These should be statically declared
  7281. within the @file{.c} source file and normally not listed in the
  7282. @file{.h} header file unless there is some reason to think they may be
  7283. of more general use. Any externally visible functions should have
  7284. names beginning with @code{avm_} to avoid name clashes.
  7285. Some helpful hints are reported below for what they may be worth.
  7286. @itemize @bullet
  7287. @item
  7288. The reason for doing this is to leverage off other people's
  7289. intelligence, so generally @code{foobar.c} should contain only glue
  7290. code for library routines developed elsewhere with great skill rather
  7291. than reinventing them in some home grown way.
  7292. @item
  7293. The best numerical software is often written by Fortran
  7294. @cindex Fortran
  7295. programmers. Linking to a Fortran library is no problem on GNU systems
  7296. provided that all variables are passed by reference and all arrays are
  7297. converted to column order (@ref{Type Conversions}).
  7298. @item
  7299. Most C++ programmers have yet to reach a comparable standard, but C++
  7300. @cindex C++
  7301. libraries can also be linked by running @code{nm} on the static
  7302. @cindex nm utility
  7303. library file to find out the real names of the functions and
  7304. @cindex c++filt utility
  7305. @code{c++filt} to find out which is which. However, there
  7306. is no obvious workaround for the use of so called derived classes
  7307. by C++ programmers to simulate passing functions as parameters.
  7308. @item
  7309. Anything worth using can probably be found in the Debian
  7310. @cindex Debian
  7311. archive.
  7312. @item
  7313. Not all libraries are sensible candidates for interfaces to
  7314. @code{avram}. Typical design flaws are
  7315. @itemize @bullet
  7316. @item
  7317. irrepressible debugging messages written to @code{stderr} or
  7318. @code{stdout} that are unfit for end user consumption
  7319. @item
  7320. deliberately crashing the application if @code{malloc} fails
  7321. @item
  7322. opaque data types with undocumented storage requirements
  7323. @item
  7324. opaque data types that would be useful to store persistently
  7325. but have platform specific binary representations
  7326. @item
  7327. heavily state dependent
  7328. @cindex state dependence
  7329. semantics
  7330. @item
  7331. identifiers with clashing names
  7332. @item
  7333. restrictive
  7334. @cindex licensing restrictions
  7335. licenses
  7336. @end itemize
  7337. Some of these misfeatures have workarounds as explained next in
  7338. @ref{Working around library misfeatures}, at least if there's
  7339. nothing else wrong with the library.
  7340. @end itemize
  7341. Those who support @code{avram} are always prepared to assist in the
  7342. dissemination of worthwhile contributed library modules under terms
  7343. compatible with @ref{Copying}, and under separate copyrights if
  7344. @cindex copyright
  7345. preferred. Contributed modules can be integrated into the official
  7346. source tree provided that they meet the following additional
  7347. @cindex coding standards
  7348. guidelines to those above.
  7349. @itemize @bullet
  7350. @item
  7351. source code documentation and indentation according to GNU coding
  7352. standards (@url{http://www.gnu.org/prep/standards})
  7353. @item
  7354. sufficient stability for a semi-annual release cycle
  7355. @item
  7356. no run-time or compile-time dependence on any non-free software,
  7357. although dynamic loading and client/server interaction are acceptable
  7358. @item
  7359. portable or at least unbreakable configuration by appropriate use of
  7360. @cindex autoconf
  7361. @code{autoconf} macros and conditional defines
  7362. @item
  7363. little or no state dependence at the level of the virtual code
  7364. @cindex state dependence
  7365. interface (i.e., pure functions or something like them, except for
  7366. @cindex random number generators
  7367. random number generators and related applications)
  7368. @item
  7369. adequate documentation for a section in @ref{External Libraries}
  7370. @end itemize
  7371. @node Working around library misfeatures, , Implementing new library functions, External Library Maintenance
  7372. @subsection Working around library misfeatures
  7373. As mentioned already (@ref{Implementing new library functions}), some
  7374. common problems with external libraries that are worthwhile in other
  7375. respects are that they may generate unwelcome console output while
  7376. running, they may follow ill defined memory management policies, and
  7377. they may handle exceptions just by crashing themselves along with the
  7378. client module.
  7379. An accumulation of techniques for coping with these issues (short of
  7380. modifying the library source) has been collected into the API and made
  7381. available by way of the header file @file{mwrap.h}. This section
  7382. briefly documents how they might be put to use.
  7383. @menu
  7384. * Inept excess verbiage::
  7385. * Memory leaks::
  7386. * Suicidal exception handling::
  7387. @end menu
  7388. @node Inept excess verbiage, Memory leaks, Working around library misfeatures, Working around library misfeatures
  7389. @subsubsection Inept excess verbiage
  7390. Although the author of a library function may take pride in putting
  7391. its activities on display, it should be assumed that virtual code
  7392. applications running on @code{avram} have other agendas for the
  7393. console, so the library interface module should prevent direct output
  7394. from the external library.
  7395. More thoughtful API's may have a verbosity setting, which should be
  7396. @cindex verbosity setting
  7397. used in preference to this workaround, but failing that, it is easy to
  7398. dispense with console output generated by calls to external library
  7399. functions by using some combination of the following functions.
  7400. @deftypefun void avm_turn_off_stdout ()
  7401. Calling this function will suppress all output to the standard output
  7402. stream until the next time @code{avm_turn_on_stdout} is called.
  7403. Additional calls to this function without intervening calls to
  7404. @code{avm_turn_on_stdout} may be made safely with no effect. The
  7405. standard output stream is flushed as a side effect of calling this
  7406. function.
  7407. @end deftypefun
  7408. @deftypefun void avm_turn_on_stdout ()
  7409. Calling this function will allow output to the standard output
  7410. stream to resume if it has been suppressed previously by a call to
  7411. @code{avm_turn_off_stdout}. If @code{avm_turn_off_stdout} has not been
  7412. previously called, this function has no effect. Any output that would
  7413. have been sent to @code{stdout} during the time it was turned off will
  7414. be lost.
  7415. @end deftypefun
  7416. @deftypefun void avm_turn_off_stderr ()
  7417. This function performs a similar service to that of
  7418. @code{avm_turn_off_stdout} but pertains to the standard error stream.
  7419. The standard error and the standard output streams are controlled
  7420. independently even if both of them are piped to the same console.
  7421. @end deftypefun
  7422. @deftypefun void avm_turn_on_stderr ()
  7423. This function performs a similar service to that of
  7424. @code{avm_turn_on_stdout} but pertains to the standard error stream.
  7425. @end deftypefun
  7426. As an example, the following code fragment will prevent any output to
  7427. standard output taking place as a side effect of @code{blather}, but
  7428. will allow error messages to standard error. Note that ouput should
  7429. not be left permanently turned off.
  7430. @example
  7431. ...
  7432. #include <avm/mwrap.h>
  7433. ...
  7434. x = y + z;
  7435. avm_turn_off_stdout ();
  7436. w = blather (foo, bar, baz);
  7437. avm_turn_on_stdout ();
  7438. return w;
  7439. ...
  7440. @end example
  7441. One possible issue with these functions is that they rely on a
  7442. feature of the GNU C library that might not be portable to non-GNU
  7443. @cindex portability
  7444. systems and has not been widely tested on other platforms.
  7445. Another issue is that a library function could be both careless enough
  7446. to clutter the console unconditionally and meticulous enough to check
  7447. for I/O errors after each attempted write. Writing while the output
  7448. stream is disabled will return an I/O error to the caller (i.e., to
  7449. the verbose library function) for appropriate action, which could
  7450. include terminating the process.
  7451. @node Memory leaks, Suicidal exception handling, Inept excess verbiage, Working around library misfeatures
  7452. @subsubsection Memory leaks
  7453. Incorrect memory management may undermine confidence in a library when
  7454. one wonders what else it gets wrong, but if the worst it does is leave
  7455. a few bytes unreclaimed, then help is at hand.
  7456. The first priority is to assess the seriousness of the situation.
  7457. Similarly to the way library functions are bracketed with calls to
  7458. those listed in @ref{Inept excess verbiage}, the following functions
  7459. are meant to be placed before and after a call to a library function
  7460. either for diagnostic purposes or production use.
  7461. @deftypefun void avm_manage_memory ()
  7462. After this function is called, all subsequent calls to the standard C
  7463. functions @code{malloc}, @code{free}, and @code{realloc} are
  7464. intercepted and logged until the next time
  7465. @code{avm_dont_manage_memory} is called. Furthermore, a complete
  7466. record is maintained of the addresses and sizes of all allocated areas
  7467. of memory during this time in a persistent data structure managed
  7468. internally.
  7469. @end deftypefun
  7470. @deftypefun void avm_dont_manage_memory ()
  7471. Calling this function suspends the storage monitoring activities
  7472. initiated by calling @code{avm_manage_memory}, but the record of
  7473. allocated memory areas is not erased.
  7474. @end deftypefun
  7475. @deftypefun void avm_debug_memory ()
  7476. After this function is called and @code{avm_manage_memory} is also
  7477. called, the standard output stream will display a running account of
  7478. the sizes and addresses of all memory allocations or deallocations as
  7479. they occur until the next call to either @code{avm_dont_debug_memory}
  7480. or @code{avm_dont_manage_memory}.
  7481. @end deftypefun
  7482. @deftypefun void avm_dont_debug_memory ()
  7483. This function stops the output being sent to @code{stdout} caused by
  7484. @code{avm_debug_memory}, if any, but has no effect on the logging of
  7485. memory management events preformed due to @code{avm_manage_memory}.
  7486. @end deftypefun
  7487. While the latter two are not useful in production code, they can help
  7488. to clarify an inadequately documented API during development by
  7489. experimentally identifying the functions that cause memory to be
  7490. allocated. They can also provide the answer to questions like whether
  7491. separate copies are made from arrays passed to functions (useful for
  7492. knowing when it's appropriate to free them).
  7493. Although the console output reveals everything there is to know about
  7494. memory management during the selected window, the question of
  7495. unreclaimed storage is more directly settled by the following
  7496. functions.
  7497. @deftypefun void avm_initialize_mwrap ()
  7498. This function has to be called before any other functions from
  7499. @file{mwrap.h} in order to clean the slate and prepare the static data
  7500. structures for use. This function might not have to be called
  7501. explicitly if the client module is part of @code{avram}, whose main
  7502. program would have already called it. There is no harm in calling it
  7503. repeatedly.
  7504. @end deftypefun
  7505. @deftypefun void avm_count_mwrap ()
  7506. This function should be called after the last call to any other
  7507. functions in @file{mwrap.h}, when it is expected that all storage that
  7508. was allocated while @code{avm_manage_memory} was in effect should have
  7509. been reclaimed.
  7510. If there is no unreclaimed storage allocated during an interval when
  7511. memory was being managed, this function returns uneventfully. However,
  7512. if any storage remains unreclaimed, a message stating the number of
  7513. bytes is written to @code{stderr}.
  7514. If @code{avm_debug_memory} is also in effect when this function
  7515. detects unreclaimed storage, an itemized list of the unreclaimed
  7516. memory addresses and their sizes is written to standard output.
  7517. @end deftypefun
  7518. Of course, in order for @code{avm_count_mwrap} to report meaningful
  7519. results, any memory that is allocated during the interval between
  7520. calls to @code{avm_manage_memory} and @code{avm_dont_manage_memory}
  7521. must have been given an opportunity to be reclaimed also while
  7522. this logging mechanism is in effect. However, there may be arbitrarily
  7523. many intervening intervals during which it is suspended.
  7524. On the other hand, any storage that is allocated when memory is not
  7525. being managed must not be freed at a time when it is (except for
  7526. freeing a @code{NULL} pointer, which is tolerated but not
  7527. encouraged). Doing so raises an internal error, causing termination
  7528. @cindex internal error
  7529. with extreme prejudice. This behavior is a precaution against library
  7530. functions freeing storage that they didn't allocate, which would mean
  7531. no memory is safe and it's better for @code{avram} not to continue.
  7532. If these investigations uncover no evidence of a memory leak, then
  7533. perhaps the relevant library functions are reliable enough to run
  7534. without supervisory memory management. Alternatively, when memory
  7535. leaks are indicated, the next function provides a simple remedy.
  7536. @deftypefun void avm_free_managed_memory ()
  7537. This function causes all storage to be reclaimed that was allocated
  7538. at any time while logging of memory allocation was in effect (i.e.,
  7539. whenever @code{avm_manage_memory} had been called more recently than
  7540. @code{avm_dont_manage_memory}). When the storage is freed, no further
  7541. record of it is maintained.
  7542. A side effect of this function is to call @code{avm_dont_manage_memory}
  7543. and therefore leave memory management turned off.
  7544. @end deftypefun
  7545. This last function when used in conjunction with the others is
  7546. therefore the workaround for library functions that don't clean up
  7547. after themselves. It may be important to do it for them if repeated
  7548. calls to the library function are expected, which would otherwise
  7549. cause unreclaimed storage to accumulate until it curtailed other
  7550. operations.
  7551. One small issue with this function is the assumption that unreclaimed
  7552. storage is really a leak and not internal library data that is
  7553. designed to persist between calls. If this assumption is not valid,
  7554. breakage will occur. However, libraries deliberately making use of
  7555. persistent data are likely to have initialization and destructor
  7556. functions as part of their API's, so this assumption is often
  7557. justified if they don't.
  7558. An example of using these functions is given below.
  7559. In this example, @code{allocated_library_object} is a hypothetical
  7560. function exported by an external library that causes storage to be
  7561. allocated, and @code{library_reclamation_routine} is provided by the
  7562. same library ostensibly to reclaim the storage thus
  7563. allocated. However, the latter is suspected of memory leaks.
  7564. The variable @code{my_data} is declared and used by an @code{avram}
  7565. developer who is presumably competent to reclaim it correctly, rather
  7566. than it being part of an external library. Memory management is
  7567. therefore enabled during the calls to the library routines but not at
  7568. other times.
  7569. The call to @code{avm_count_mwrap} is redundant immediately after a
  7570. call to @code{avm_free_managed_memory}, because with all managed
  7571. memory having been freed, no memory leak will ever be detected, but it
  7572. is included for illustrative purposes.
  7573. @example
  7574. #include <avm/mwrap.h>
  7575. ...
  7576. @{
  7577. void *behemoth;
  7578. char *my_data;
  7579. avm_initialize_mwrap ();
  7580. avm_manage_memory ();
  7581. behemoth = allocated_library_object (foo, bar);
  7582. avm_dont_manage_memory ();
  7583. my_data = (char *) malloc (100);
  7584. ...
  7585. free (my_data);
  7586. avm_manage_memory ();
  7587. library_reclamation_routine (&behemoth);
  7588. avm_free_managed_memory ();
  7589. avm_count_mwrap ();
  7590. return;
  7591. @}
  7592. @end example
  7593. It might be a cleaner solution in some sense to omit the call to
  7594. @code{library_reclamation_routine} entirely, because the storage
  7595. allocated during the call to @code{allocated_library_object} will be
  7596. reclaimed perfectly well by @code{avm_free_managed_memory} without
  7597. it. Doing so may also be the only option if the library reclamation
  7598. routine is either extremely unreliable or non-existent. However, the
  7599. style above is to be preferred for portability if possible. The memory
  7600. management functions rely on the availability of the system header
  7601. file @code{malloc.h}, and GNU C library features whose portability is
  7602. not assured. If the required features are not detected on the host
  7603. system at configuration time, conditional directives in the
  7604. @code{avram} source will make the @code{avm_}* memory management
  7605. functions perform no operations, and the responsibility for memory
  7606. management will devolve to the possibly less robust external library
  7607. implementation.
  7608. @node Suicidal exception handling, , Memory leaks, Working around library misfeatures
  7609. @subsubsection Suicidal exception handling
  7610. An inconvenient characteristic of some external library functions is
  7611. to terminate the program rather than returning an error status to the
  7612. caller for routine events such as a failure of memory allocation.
  7613. Although in many cases there is no simple workaround for this
  7614. behavior, memory allocation failures at least can be detected and
  7615. preventive action taken by using the functions described in this
  7616. section.
  7617. The general approach is to use memory management functions from
  7618. @file{mwrap.h} as described previously (@ref{Memory leaks}), while
  7619. additionally registering a return destination for a non-local jump to
  7620. @cindex non-local jumps
  7621. be taken in the event of a memory overflow. The jump is taken when an
  7622. external library function calls @code{malloc} or @code{realloc}
  7623. unsuccessfully. The jump avoids passing control back to the library
  7624. function, thereby denying it the opportunity to abort, but restores
  7625. the context to that of the jump destination almost as if the library
  7626. function and all of its intervening callers had returned normally.
  7627. The interface is similar to that of the standard @code{setjmp}
  7628. @cindex setjmp
  7629. function defined in the system header file @code{setjmp.h}, and in
  7630. fact is built on it, but differs in that the client module does not
  7631. explicitly refer to jump buffers. Instead, the @code{mwrap} module
  7632. internally maintains a stack of return destinations.
  7633. If a jump is taken, it always goes to the most recently registered
  7634. destination. It may revert to the previously registered destination
  7635. only when the current one is cleared. This organization provides the
  7636. necessary flexibility for multiple clients and recursion, but it
  7637. necessitates a protocol whereby each registration of a destination
  7638. must be explicitly cleared exactly once.
  7639. The following functions implement these two features.
  7640. @deftypefun int avm_setjmp ()
  7641. This function specifies the point to which control will pass by a
  7642. non-local jump if there is insufficient memory to complete a
  7643. subsequent @code{malloc} or @code{realloc} operation. Only the
  7644. operations that take place while memory is being managed due to
  7645. @code{avm_manage_memory} are affected (@ref{Memory leaks}).
  7646. The function returns zero when it is called normally and successfully
  7647. registers the return point.
  7648. It returns a non-zero value when it has been entered by a non-local
  7649. jump (i.e., when @code{malloc} or @code{realloc} has reported
  7650. insufficient memory while memory management is active), or when the
  7651. return point could not be successfully registered due to insufficient
  7652. memory. The client need not distinguish between these two cases,
  7653. because both correspond to memory overflows and the destination must
  7654. be cleared by @code{avm_clearjmp} regardless.
  7655. When a non-zero value is returned due to this function being reached
  7656. by a non-local jump, it has the side effects of reclaiming all managed
  7657. memory by calling @code{avm_free_managed_memory} and disabling memory
  7658. management by calling @code{avm_dont_manage_memory}.
  7659. @end deftypefun
  7660. @deftypefun void avm_clearjmp ()
  7661. This function cancels the effect of @code{avm_setjmp ()} by preventing
  7662. further non-local jumps to its destination if the destination was
  7663. successfully registered, or by acknowledging unsuccessful registration
  7664. otherwise. It should be called before exiting any function that calls
  7665. @code{avm_setjmp ()} or anomalous results may ensue.
  7666. @end deftypefun
  7667. The memory management functions @code{avm_manage_memory} and
  7668. @code{avm_dont_manage_memory} can be useful with or without
  7669. @code{avm_setjmp}, depending on how much of a workaround is needed for
  7670. a given library. If a library does not abort on memory overflows,
  7671. there is no need to use @code{avm_setjmp}, while it may still be
  7672. appropriate to use the other functions against memory leaks.
  7673. Calling @code{avm_clearjmp} is particularly important if a client
  7674. module with memory management that doesn't use @code{avm_setjmp} is
  7675. invoked subsequently to one that does, so that memory overflows in the
  7676. latter won't cause an attempted jump to a stale destination.
  7677. A further complication that arises from careful consideration of these
  7678. issues is the situation of a client module that does not intend to use
  7679. @code{avm_setjmp} but is called (perhaps indirectly) by one that
  7680. does. The latter will have registered a return destination that
  7681. remains active and valid even if the former refrains from doing so,
  7682. thereby allowing a branch to be taken that should have been prevented.
  7683. Although it is an unusual situation, it can be accommodated by the
  7684. following function.
  7685. @deftypefun void avm_setnonjump ()
  7686. This function temporarily inhibits non-local jumps to destinations
  7687. previously registered by @code{avm_setjmp} until the next time
  7688. @code{avm_clearjmp} is called. Thereafter, any previously registered
  7689. destinations are reinstated.
  7690. @end deftypefun
  7691. A sketch of how some of these functions might be used to cope with
  7692. library functions that would otherwise terminate the program in the
  7693. event of a memory overflow is shown below. The GNU @code{libc}
  7694. @cindex non-local jumps
  7695. reference manual contains a related discussion of non-local jumps.
  7696. @example
  7697. #include <avm/mwrap.h>
  7698. ...
  7699. int
  7700. function foobar (foo, bar)
  7701. ...
  7702. @{
  7703. char *my_data;
  7704. my_data = (char *) malloc (100);
  7705. if (avm_setjmp () != 0)
  7706. @{
  7707. avm_clearjmp ();
  7708. avm_turn_on_stdout (); /* reaching here */
  7709. free (my_data); /* means malloc */
  7710. return ABNORMAL_STATUS; /* failed below */
  7711. @}
  7712. avm_turn_off_stdout ();
  7713. avm_manage_memory ();
  7714. ...
  7715. call_library_functions (foo, bar); /* may jump */
  7716. ... /* to above */
  7717. avm_free_managed_memory ();
  7718. avm_turn_on_stdout ();
  7719. avm_clearjmp ();
  7720. free (my_data); /* reaching here means */
  7721. return OK_STATUS; /* jumping wasn't done */
  7722. @}
  7723. @end example
  7724. Portability issues with these functions are not well known at this
  7725. @cindex portability
  7726. writing. If the configuration script for @code{avram} fails to detect
  7727. the required features in @code{setjmp.h} on the host system,
  7728. conditional compilation directives will disable the functions
  7729. @code{avm_setjmp}, @code{avm_clearjmp}, and @code{avm_setnonjmp}.
  7730. However, it may still be possible for the other @code{avm_}* memory
  7731. management functions to be configured.
  7732. If @code{setjmp} is not configured, the @code{avm_setjmp} function
  7733. is still callable but will always return a value of zero, and will
  7734. provide no protection against external library functions aborting the
  7735. program. The other two will perform no operation and return.
  7736. @node Character Table, Reference Implementations, Library Reference, Top
  7737. @appendix Character Table
  7738. @cindex character representations
  7739. This table lists the representations used by @code{avram} for
  7740. characters. The left column shows the character code in decimal. For
  7741. printable characters, the middle column shows the character. The right
  7742. column shows the representation used. For example, the letter @code{A} has
  7743. character code 65, and the representation
  7744. @code{(nil,(((nil,(nil,(nil,nil))),nil),(nil,nil)))}.
  7745. These representations were generated automatically to meet various
  7746. helpful criteria, and are not expected to change in future releases. No
  7747. character representation coincides with the representations used for
  7748. boolean values, natural numbers, character strings, pairs of characters,
  7749. or certain other data types beyond the scope of this document. An easy
  7750. algorithm for lexical sorting is possible. Subject to these criteria,
  7751. the smallest possible trees were chosen.
  7752. @example
  7753. 0 (nil,(nil,(nil,((nil,nil),(nil,nil)))))
  7754. 1 (nil,(nil,((nil,nil),(nil,nil))))
  7755. 2 (nil,(nil,((nil,nil),(nil,(nil,nil)))))
  7756. 3 (nil,(nil,((nil,(nil,nil)),(nil,nil))))
  7757. 4 (nil,(nil,(((nil,nil),nil),(nil,nil))))
  7758. 5 (nil,(nil,(((nil,nil),(nil,nil)),nil)))
  7759. 6 (nil,(nil,((((nil,nil),(nil,nil)),nil),nil)))
  7760. 7 (nil,((nil,nil),(nil,nil)))
  7761. 8 (nil,((nil,nil),(nil,(nil,nil))))
  7762. 9 (nil,((nil,nil),(nil,(nil,(nil,nil)))))
  7763. 10 (nil,((nil,nil),(nil,(nil,(nil,(nil,nil))))))
  7764. 11 (nil,((nil,nil),(nil,((nil,nil),(nil,nil)))))
  7765. 12 (nil,((nil,nil),(nil,((nil,(nil,nil)),nil))))
  7766. 13 (nil,((nil,nil),(nil,(((nil,nil),nil),nil))))
  7767. 14 (nil,((nil,nil),((nil,nil),(nil,nil))))
  7768. 15 (nil,((nil,nil),((nil,nil),(nil,(nil,nil)))))
  7769. 16 (nil,((nil,nil),((nil,(nil,nil)),nil)))
  7770. 17 (nil,((nil,nil),((nil,(nil,nil)),(nil,nil))))
  7771. 18 (nil,((nil,nil),((nil,(nil,(nil,nil))),nil)))
  7772. 19 (nil,((nil,nil),(((nil,nil),nil),(nil,nil))))
  7773. 20 (nil,((nil,nil),(((nil,nil),(nil,nil)),nil)))
  7774. 21 (nil,((nil,(nil,nil)),(nil,nil)))
  7775. 22 (nil,((nil,(nil,nil)),(nil,(nil,nil))))
  7776. 23 (nil,((nil,(nil,nil)),(nil,(nil,(nil,nil)))))
  7777. 24 (nil,((nil,(nil,nil)),(nil,((nil,nil),nil))))
  7778. 25 (nil,((nil,(nil,nil)),((nil,nil),nil)))
  7779. 26 (nil,((nil,(nil,nil)),((nil,nil),(nil,nil))))
  7780. 27 (nil,((nil,(nil,nil)),((nil,(nil,nil)),nil)))
  7781. 28 (nil,((nil,(nil,nil)),(((nil,nil),nil),nil)))
  7782. 29 (nil,((nil,(nil,(nil,nil))),(nil,nil)))
  7783. 30 (nil,((nil,(nil,(nil,nil))),(nil,(nil,nil))))
  7784. 31 (nil,((nil,(nil,(nil,nil))),((nil,nil),nil)))
  7785. 32 (nil,((nil,(nil,(nil,(nil,nil)))),(nil,nil)))
  7786. 33 ! (nil,((nil,(nil,((nil,nil),nil))),(nil,nil)))
  7787. 34 " (nil,((nil,(nil,((nil,nil),(nil,nil)))),nil))
  7788. 35 # (nil,((nil,((nil,nil),nil)),(nil,nil)))
  7789. 36 $ (nil,((nil,((nil,nil),nil)),(nil,(nil,nil))))
  7790. 37 % (nil,((nil,((nil,nil),(nil,nil))),nil))
  7791. 38 & (nil,((nil,((nil,nil),(nil,nil))),(nil,nil)))
  7792. 39 ' (nil,((nil,((nil,nil),(nil,(nil,nil)))),nil))
  7793. 40 ( (nil,((nil,((nil,(nil,nil)),nil)),(nil,nil)))
  7794. 41 ) (nil,((nil,((nil,(nil,nil)),(nil,nil))),nil))
  7795. 42 * (nil,((nil,(((nil,nil),nil),nil)),(nil,nil)))
  7796. 43 + (nil,((nil,(((nil,nil),nil),(nil,nil))),nil))
  7797. 44 , (nil,((nil,(((nil,nil),(nil,nil)),nil)),nil))
  7798. 45 - (nil,(((nil,nil),nil),(nil,nil)))
  7799. 46 . (nil,(((nil,nil),nil),(nil,(nil,nil))))
  7800. 47 / (nil,(((nil,nil),nil),(nil,(nil,(nil,nil)))))
  7801. 48 0 (nil,(((nil,nil),nil),((nil,nil),(nil,nil))))
  7802. 49 1 (nil,(((nil,nil),nil),((nil,(nil,nil)),nil)))
  7803. 50 2 (nil,(((nil,nil),(nil,nil)),nil))
  7804. 51 3 (nil,(((nil,nil),(nil,nil)),(nil,nil)))
  7805. 52 4 (nil,(((nil,nil),(nil,nil)),(nil,(nil,nil))))
  7806. 53 5 (nil,(((nil,nil),(nil,nil)),((nil,nil),nil)))
  7807. 54 6 (nil,(((nil,nil),(nil,(nil,nil))),nil))
  7808. 55 7 (nil,(((nil,nil),(nil,(nil,nil))),(nil,nil)))
  7809. 56 8 (nil,(((nil,nil),(nil,(nil,(nil,nil)))),nil))
  7810. 57 9 (nil,(((nil,nil),((nil,nil),nil)),(nil,nil)))
  7811. 58 : (nil,(((nil,nil),((nil,nil),(nil,nil))),nil))
  7812. 59 ; (nil,(((nil,nil),((nil,(nil,nil)),nil)),nil))
  7813. 60 < (nil,(((nil,(nil,nil)),nil),(nil,nil)))
  7814. 61 = (nil,(((nil,(nil,nil)),nil),(nil,(nil,nil))))
  7815. 62 > (nil,(((nil,(nil,nil)),(nil,nil)),nil))
  7816. 63 ? (nil,(((nil,(nil,nil)),(nil,nil)),(nil,nil)))
  7817. 64 @@ (nil,(((nil,(nil,nil)),(nil,(nil,nil))),nil))
  7818. 65 A (nil,(((nil,(nil,(nil,nil))),nil),(nil,nil)))
  7819. 66 B (nil,(((nil,(nil,(nil,nil))),(nil,nil)),nil))
  7820. 67 C (nil,(((nil,((nil,nil),nil)),nil),(nil,nil)))
  7821. 68 D (nil,(((nil,((nil,nil),nil)),(nil,nil)),nil))
  7822. 69 E (nil,((((nil,nil),nil),nil),(nil,nil)))
  7823. 70 F (nil,((((nil,nil),nil),nil),(nil,(nil,nil))))
  7824. 71 G (nil,((((nil,nil),nil),(nil,nil)),nil))
  7825. 72 H (nil,((((nil,nil),nil),(nil,nil)),(nil,nil)))
  7826. 73 I (nil,((((nil,nil),nil),(nil,(nil,nil))),nil))
  7827. 74 J (nil,((((nil,nil),(nil,nil)),nil),(nil,nil)))
  7828. 75 K (nil,((((nil,nil),(nil,nil)),(nil,nil)),nil))
  7829. 76 L (nil,((((nil,(nil,nil)),nil),nil),(nil,nil)))
  7830. 77 M (nil,((((nil,(nil,nil)),nil),(nil,nil)),nil))
  7831. 78 N (nil,(((((nil,nil),nil),nil),nil),(nil,nil)))
  7832. 79 O (nil,(((((nil,nil),nil),nil),(nil,nil)),nil))
  7833. 80 P ((nil,nil),(nil,nil))
  7834. 81 Q ((nil,nil),(nil,(nil,nil)))
  7835. 82 R ((nil,nil),(nil,(nil,(nil,nil))))
  7836. 83 S ((nil,nil),(nil,(nil,(nil,(nil,nil)))))
  7837. 84 T ((nil,nil),(nil,(nil,(nil,(nil,(nil,nil))))))
  7838. 85 U ((nil,nil),(nil,(nil,((nil,(nil,nil)),nil))))
  7839. 86 V ((nil,nil),(nil,(nil,(((nil,nil),nil),nil))))
  7840. 87 W ((nil,nil),(nil,((nil,nil),(nil,nil))))
  7841. 88 X ((nil,nil),(nil,((nil,(nil,nil)),nil)))
  7842. 89 Y ((nil,nil),(nil,((nil,(nil,nil)),(nil,nil))))
  7843. 90 Z ((nil,nil),(nil,((nil,(nil,(nil,nil))),nil)))
  7844. 91 [ ((nil,nil),(nil,((nil,((nil,nil),nil)),nil)))
  7845. 92 \ ((nil,nil),(nil,(((nil,nil),nil),nil)))
  7846. 93 ] ((nil,nil),(nil,(((nil,nil),nil),(nil,nil))))
  7847. 94 ^ ((nil,nil),(nil,(((nil,nil),(nil,nil)),nil)))
  7848. 95 _ ((nil,nil),(nil,(((nil,(nil,nil)),nil),nil)))
  7849. 96 ` ((nil,nil),(nil,((((nil,nil),nil),nil),nil)))
  7850. 97 a ((nil,nil),((nil,nil),(nil,nil)))
  7851. 98 b ((nil,nil),((nil,nil),(nil,(nil,nil))))
  7852. 99 c ((nil,nil),((nil,nil),(nil,(nil,(nil,nil)))))
  7853. 100 d ((nil,nil),((nil,nil),((nil,nil),(nil,nil))))
  7854. 101 e ((nil,nil),((nil,nil),((nil,(nil,nil)),nil)))
  7855. 102 f ((nil,nil),((nil,(nil,nil)),nil))
  7856. 103 g ((nil,nil),((nil,(nil,nil)),(nil,nil)))
  7857. 104 h ((nil,nil),((nil,(nil,nil)),(nil,(nil,nil))))
  7858. 105 i ((nil,nil),((nil,(nil,nil)),((nil,nil),nil)))
  7859. 106 j ((nil,nil),((nil,(nil,(nil,nil))),nil))
  7860. 107 k ((nil,nil),((nil,(nil,(nil,nil))),(nil,nil)))
  7861. 108 l ((nil,nil),((nil,(nil,(nil,(nil,nil)))),nil))
  7862. 109 m ((nil,nil),((nil,((nil,nil),nil)),(nil,nil)))
  7863. 110 n ((nil,nil),((nil,((nil,nil),(nil,nil))),nil))
  7864. 111 o ((nil,nil),((nil,((nil,(nil,nil)),nil)),nil))
  7865. 112 p ((nil,nil),(((nil,nil),nil),(nil,nil)))
  7866. 113 q ((nil,nil),(((nil,nil),nil),(nil,(nil,nil))))
  7867. 114 r ((nil,nil),(((nil,nil),(nil,nil)),nil))
  7868. 115 s ((nil,nil),(((nil,nil),(nil,nil)),(nil,nil)))
  7869. 116 t ((nil,nil),(((nil,nil),(nil,(nil,nil))),nil))
  7870. 117 u ((nil,nil),(((nil,(nil,nil)),nil),(nil,nil)))
  7871. 118 v ((nil,nil),(((nil,(nil,nil)),(nil,nil)),nil))
  7872. 119 w ((nil,nil),((((nil,nil),nil),nil),(nil,nil)))
  7873. 120 x ((nil,nil),((((nil,nil),nil),(nil,nil)),nil))
  7874. 121 y ((nil,nil),(((((nil,nil),nil),nil),nil),nil))
  7875. 122 z ((nil,(nil,nil)),(nil,nil))
  7876. 123 @{ ((nil,(nil,nil)),(nil,(nil,(nil,nil))))
  7877. 124 | ((nil,(nil,nil)),(nil,(nil,(nil,(nil,nil)))))
  7878. 125 @} ((nil,(nil,nil)),(nil,((nil,nil),nil)))
  7879. 126 ~ ((nil,(nil,nil)),(nil,((nil,nil),(nil,nil))))
  7880. 127 ((nil,(nil,nil)),(nil,((nil,(nil,nil)),nil)))
  7881. 128 ((nil,(nil,nil)),((nil,nil),(nil,nil)))
  7882. 129 ((nil,(nil,nil)),((nil,nil),(nil,(nil,nil))))
  7883. 130 ((nil,(nil,nil)),((nil,(nil,nil)),nil))
  7884. 131 ((nil,(nil,nil)),((nil,(nil,nil)),(nil,nil)))
  7885. 132 ((nil,(nil,nil)),((nil,(nil,(nil,nil))),nil))
  7886. 133 ((nil,(nil,nil)),(((nil,nil),nil),(nil,nil)))
  7887. 134 ((nil,(nil,nil)),(((nil,nil),(nil,nil)),nil))
  7888. 135 ((nil,(nil,(nil,nil))),(nil,nil))
  7889. 136 ((nil,(nil,(nil,nil))),(nil,(nil,nil)))
  7890. 137 ((nil,(nil,(nil,nil))),(nil,(nil,(nil,nil))))
  7891. 138 ((nil,(nil,(nil,nil))),(nil,((nil,nil),nil)))
  7892. 139 ((nil,(nil,(nil,nil))),((nil,nil),(nil,nil)))
  7893. 140 ((nil,(nil,(nil,nil))),((nil,(nil,nil)),nil))
  7894. 141 ((nil,(nil,(nil,(nil,nil)))),(nil,nil))
  7895. 142 ((nil,(nil,(nil,(nil,nil)))),(nil,(nil,nil)))
  7896. 143 ((nil,(nil,(nil,(nil,nil)))),((nil,nil),nil))
  7897. 144 ((nil,(nil,(nil,(nil,(nil,nil))))),(nil,nil))
  7898. 145 ((nil,(nil,(nil,((nil,nil),nil)))),(nil,nil))
  7899. 146 ((nil,(nil,((nil,nil),nil))),(nil,nil))
  7900. 147 ((nil,(nil,((nil,nil),(nil,nil)))),(nil,nil))
  7901. 148 ((nil,(nil,((nil,(nil,nil)),nil))),(nil,nil))
  7902. 149 ((nil,(nil,(((nil,nil),nil),nil))),(nil,nil))
  7903. 150 ((nil,((nil,nil),nil)),(nil,nil))
  7904. 151 ((nil,((nil,nil),nil)),(nil,(nil,nil)))
  7905. 152 ((nil,((nil,nil),nil)),(nil,(nil,(nil,nil))))
  7906. 153 ((nil,((nil,nil),nil)),(nil,((nil,nil),nil)))
  7907. 154 ((nil,((nil,nil),nil)),((nil,nil),(nil,nil)))
  7908. 155 ((nil,((nil,nil),nil)),((nil,(nil,nil)),nil))
  7909. 156 ((nil,((nil,nil),(nil,nil))),(nil,nil))
  7910. 157 ((nil,((nil,nil),(nil,nil))),(nil,(nil,nil)))
  7911. 158 ((nil,((nil,nil),(nil,(nil,nil)))),(nil,nil))
  7912. 159 ((nil,((nil,nil),((nil,nil),nil))),(nil,nil))
  7913. 160 ((nil,((nil,(nil,nil)),nil)),(nil,nil))
  7914. 161 ((nil,((nil,(nil,nil)),nil)),(nil,(nil,nil)))
  7915. 162 ((nil,((nil,(nil,nil)),nil)),((nil,nil),nil))
  7916. 163 ((nil,((nil,(nil,nil)),(nil,nil))),(nil,nil))
  7917. 164 ((nil,((nil,(nil,(nil,nil))),nil)),(nil,nil))
  7918. 165 ((nil,((nil,((nil,nil),nil)),nil)),(nil,nil))
  7919. 166 ((nil,(((nil,nil),nil),nil)),(nil,nil))
  7920. 167 ((nil,(((nil,nil),nil),(nil,nil))),(nil,nil))
  7921. 168 ((nil,(((nil,nil),(nil,nil)),nil)),(nil,nil))
  7922. 169 ((nil,(((nil,(nil,nil)),nil),nil)),(nil,nil))
  7923. 170 ((nil,((((nil,nil),nil),nil),nil)),(nil,nil))
  7924. 171 (((nil,nil),nil),(nil,nil))
  7925. 172 (((nil,nil),nil),(nil,(nil,nil)))
  7926. 173 (((nil,nil),nil),(nil,(nil,(nil,nil))))
  7927. 174 (((nil,nil),nil),(nil,(nil,(nil,(nil,nil)))))
  7928. 175 (((nil,nil),nil),(nil,(nil,((nil,nil),nil))))
  7929. 176 (((nil,nil),nil),(nil,((nil,nil),nil)))
  7930. 177 (((nil,nil),nil),(nil,((nil,nil),(nil,nil))))
  7931. 178 (((nil,nil),nil),(nil,((nil,(nil,nil)),nil)))
  7932. 179 (((nil,nil),nil),(nil,(((nil,nil),nil),nil)))
  7933. 180 (((nil,nil),nil),((nil,nil),(nil,nil)))
  7934. 181 (((nil,nil),nil),((nil,nil),(nil,(nil,nil))))
  7935. 182 (((nil,nil),nil),((nil,(nil,nil)),nil))
  7936. 183 (((nil,nil),nil),((nil,(nil,nil)),(nil,nil)))
  7937. 184 (((nil,nil),nil),((nil,(nil,(nil,nil))),nil))
  7938. 185 (((nil,nil),nil),(((nil,nil),nil),(nil,nil)))
  7939. 186 (((nil,nil),nil),(((nil,nil),(nil,nil)),nil))
  7940. 187 (((nil,nil),(nil,nil)),(nil,nil))
  7941. 188 (((nil,nil),(nil,nil)),(nil,(nil,nil)))
  7942. 189 (((nil,nil),(nil,nil)),(nil,(nil,(nil,nil))))
  7943. 190 (((nil,nil),(nil,nil)),(nil,((nil,nil),nil)))
  7944. 191 (((nil,nil),(nil,nil)),((nil,(nil,nil)),nil))
  7945. 192 (((nil,nil),(nil,(nil,nil))),(nil,nil))
  7946. 193 (((nil,nil),(nil,(nil,nil))),(nil,(nil,nil)))
  7947. 194 (((nil,nil),(nil,(nil,(nil,nil)))),(nil,nil))
  7948. 195 (((nil,nil),(nil,((nil,nil),nil))),(nil,nil))
  7949. 196 (((nil,nil),((nil,nil),nil)),(nil,nil))
  7950. 197 (((nil,nil),((nil,nil),nil)),(nil,(nil,nil)))
  7951. 198 (((nil,nil),((nil,nil),(nil,nil))),(nil,nil))
  7952. 199 (((nil,nil),((nil,(nil,nil)),nil)),(nil,nil))
  7953. 200 (((nil,nil),(((nil,nil),nil),nil)),(nil,nil))
  7954. 201 (((nil,(nil,nil)),nil),(nil,nil))
  7955. 202 (((nil,(nil,nil)),nil),(nil,(nil,nil)))
  7956. 203 (((nil,(nil,nil)),nil),(nil,(nil,(nil,nil))))
  7957. 204 (((nil,(nil,nil)),nil),(nil,((nil,nil),nil)))
  7958. 205 (((nil,(nil,nil)),nil),((nil,nil),(nil,nil)))
  7959. 206 (((nil,(nil,nil)),nil),((nil,(nil,nil)),nil))
  7960. 207 (((nil,(nil,nil)),(nil,nil)),(nil,nil))
  7961. 208 (((nil,(nil,nil)),(nil,nil)),(nil,(nil,nil)))
  7962. 209 (((nil,(nil,nil)),(nil,(nil,nil))),(nil,nil))
  7963. 210 (((nil,(nil,nil)),((nil,nil),nil)),(nil,nil))
  7964. 211 (((nil,(nil,(nil,nil))),nil),(nil,nil))
  7965. 212 (((nil,(nil,(nil,nil))),nil),(nil,(nil,nil)))
  7966. 213 (((nil,(nil,(nil,nil))),nil),((nil,nil),nil))
  7967. 214 (((nil,(nil,(nil,nil))),(nil,nil)),(nil,nil))
  7968. 215 (((nil,(nil,(nil,(nil,nil)))),nil),(nil,nil))
  7969. 216 (((nil,(nil,((nil,nil),nil))),nil),(nil,nil))
  7970. 217 (((nil,((nil,nil),nil)),nil),(nil,nil))
  7971. 218 (((nil,((nil,nil),nil)),nil),(nil,(nil,nil)))
  7972. 219 (((nil,((nil,nil),nil)),nil),((nil,nil),nil))
  7973. 220 (((nil,((nil,nil),nil)),(nil,nil)),(nil,nil))
  7974. 221 (((nil,((nil,nil),(nil,nil))),nil),(nil,nil))
  7975. 222 (((nil,((nil,(nil,nil)),nil)),nil),(nil,nil))
  7976. 223 (((nil,(((nil,nil),nil),nil)),nil),(nil,nil))
  7977. 224 ((((nil,nil),nil),nil),(nil,nil))
  7978. 225 ((((nil,nil),nil),nil),(nil,(nil,nil)))
  7979. 226 ((((nil,nil),nil),nil),(nil,(nil,(nil,nil))))
  7980. 227 ((((nil,nil),nil),nil),(nil,((nil,nil),nil)))
  7981. 228 ((((nil,nil),nil),nil),((nil,nil),nil))
  7982. 229 ((((nil,nil),nil),nil),((nil,nil),(nil,nil)))
  7983. 230 ((((nil,nil),nil),nil),((nil,(nil,nil)),nil))
  7984. 231 ((((nil,nil),nil),nil),(((nil,nil),nil),nil))
  7985. 232 ((((nil,nil),nil),(nil,nil)),(nil,nil))
  7986. 233 ((((nil,nil),nil),(nil,nil)),(nil,(nil,nil)))
  7987. 234 ((((nil,nil),nil),(nil,(nil,nil))),(nil,nil))
  7988. 235 ((((nil,nil),nil),((nil,nil),nil)),(nil,nil))
  7989. 236 ((((nil,nil),(nil,nil)),nil),(nil,nil))
  7990. 237 ((((nil,nil),(nil,nil)),nil),(nil,(nil,nil)))
  7991. 238 ((((nil,nil),(nil,nil)),(nil,nil)),(nil,nil))
  7992. 239 ((((nil,nil),(nil,(nil,nil))),nil),(nil,nil))
  7993. 240 ((((nil,nil),((nil,nil),nil)),nil),(nil,nil))
  7994. 241 ((((nil,(nil,nil)),nil),nil),(nil,nil))
  7995. 242 ((((nil,(nil,nil)),nil),nil),(nil,(nil,nil)))
  7996. 243 ((((nil,(nil,nil)),nil),nil),((nil,nil),nil))
  7997. 244 ((((nil,(nil,nil)),nil),(nil,nil)),(nil,nil))
  7998. 245 ((((nil,(nil,nil)),(nil,nil)),nil),(nil,nil))
  7999. 246 ((((nil,(nil,(nil,nil))),nil),nil),(nil,nil))
  8000. 247 ((((nil,((nil,nil),nil)),nil),nil),(nil,nil))
  8001. 248 (((((nil,nil),nil),nil),nil),(nil,nil))
  8002. 249 (((((nil,nil),nil),nil),nil),(nil,(nil,nil)))
  8003. 250 (((((nil,nil),nil),nil),nil),((nil,nil),nil))
  8004. 251 (((((nil,nil),nil),nil),(nil,nil)),(nil,nil))
  8005. 252 (((((nil,nil),nil),(nil,nil)),nil),(nil,nil))
  8006. 253 (((((nil,nil),(nil,nil)),nil),nil),(nil,nil))
  8007. 254 (((((nil,(nil,nil)),nil),nil),nil),(nil,nil))
  8008. 255 ((((((nil,nil),nil),nil),nil),nil),(nil,nil))
  8009. @end example
  8010. @node Reference Implementations, Changes, Character Table, Top
  8011. @appendix Reference Implementations
  8012. This appendix contains some @code{silly} source code for several
  8013. functions that are mentioned in @ref{Virtual Code Semantics}, for specifying the virtual
  8014. machine code semantics, namely @code{pairwise}, @code{transition},
  8015. @code{insert} and @code{replace}.
  8016. The intention is to specify the virtual machine mathematically with a
  8017. minimum of hand waving, by using only simple equations and small
  8018. fragments of @code{silly} code, which has a straightforward semantics.
  8019. However, the @code{silly} code fragments are more significant in some
  8020. cases than what could fit into a few lines or be mechanically derived
  8021. from an equation.
  8022. The purpose of this appendix is therefore to avoid leaving any gaps in
  8023. the construction by demonstrating that everything mentioned can be done. None
  8024. of this code is needed for any practical purpose, because its
  8025. functionality is inherent in the virtual machine, but it shows how
  8026. certain operations would be specified if they were not built in.
  8027. @menu
  8028. * Pairwise::
  8029. * Insert::
  8030. * Replace::
  8031. * Transition::
  8032. @end menu
  8033. @node Pairwise, Insert, Reference Implementations, Reference Implementations
  8034. @section Pairwise
  8035. @cindex @code{pairwise}
  8036. This @code{silly} code fragment is mentioned in @ref{Reduce}, in the
  8037. discussion of @code{reduce}, and is provided as an example of a solution
  8038. to equations @emph{E1} to @emph{E3}. It is written in the style of a
  8039. higher order function, in that it takes a function @code{@var{f}} as an
  8040. argument and returns another function, [[@code{pairwise}]]
  8041. @code{@var{f}} as a result.
  8042. @example
  8043. self = left
  8044. argument = right
  8045. head = left
  8046. tail = right
  8047. pairwise =
  8048. compose(
  8049. refer,
  8050. compose(
  8051. bu(
  8052. conditional,
  8053. conditional(argument,compose(tail,argument),constant nil)),
  8054. couple(
  8055. (hired couple)(
  8056. (hired compose)(
  8057. identity,
  8058. constant (hired fan head)(
  8059. argument,
  8060. compose(tail,argument))),
  8061. constant (hired meta)(
  8062. self,
  8063. compose(tail,compose(tail,argument)))),
  8064. constant argument)))
  8065. @end example
  8066. @noindent
  8067. To see how this works, one should evaluate it symbolically with an
  8068. unknown @code{@var{f}}, which will result in some @code{silly}
  8069. pseudocode, and then evaluate that symbolically with some sample lists.
  8070. @node Insert, Replace, Pairwise, Reference Implementations
  8071. @section Insert
  8072. @cindex @code{insert}
  8073. This function is mentioned in @ref{Sort}, on sorting. It takes the
  8074. virtual code for a partial order relational operator and returns the
  8075. code for a function of two arguments. The left argument is a list item
  8076. and the right argument is a list of items of the same type, which is
  8077. already sorted with respect to the relational operator given as the
  8078. argument to @code{insert}. The result of the function returned by
  8079. @code{insert} is a list similar to its right argument but with the left
  8080. argument inserted in the proper position to maintain the order.
  8081. This code makes use of the @code{self}, @code{argument}, @code{head}
  8082. and @code{tail} declarations associated with @code{pairwise}.
  8083. @example
  8084. insert =
  8085. bu(compose,refer) (hired conditional)(
  8086. constant compose(right,argument),
  8087. couple(
  8088. (hired conditional)(
  8089. (hired compose)(
  8090. identity,
  8091. constant compose(
  8092. couple(left,compose(head,right)),
  8093. argument)),
  8094. constant (
  8095. argument,
  8096. couple(
  8097. compose(head,compose(right,argument)),
  8098. (hired meta)(
  8099. self,
  8100. couple(
  8101. compose(left,argument),
  8102. compose(tail,compose(right,argument))))))),
  8103. constant argument))
  8104. @end example
  8105. As with the other higher order functions in this appendix, the only
  8106. feasible ways to verify it would be either by formal proof or by some
  8107. form of symbolic interpretation.
  8108. @node Replace, Transition, Insert, Reference Implementations
  8109. @section Replace
  8110. @cindex @code{replace}
  8111. This code is needed in the discussion of assignment in @ref{Assignment}.
  8112. where it serves as a solution to equation @emph{E0}. The idea is that
  8113. the function takes an argument of the form
  8114. @code{((@var{locations},@var{values}),@var{store})} and returns the
  8115. store with the values stored at the locations indicated.
  8116. @example
  8117. locations = compose(left,compose(left,argument))
  8118. values = compose(right,compose(left,argument))
  8119. store = compose(right,argument)
  8120. replace =
  8121. refer conditional(
  8122. store,
  8123. (
  8124. conditional(
  8125. compose(left,locations),
  8126. (
  8127. conditional(
  8128. compose(right,locations),
  8129. (
  8130. (hired meta)(
  8131. self,
  8132. couple(
  8133. (hired fan right)(locations,values),
  8134. (hired meta)(
  8135. self,
  8136. couple(
  8137. (hired fan left)(locations,values),
  8138. store)))),
  8139. couple(
  8140. (hired meta)(
  8141. self,
  8142. couple(
  8143. couple(compose(left,locations),values),
  8144. compose(left,store))),
  8145. compose(right,store)))),
  8146. conditional(
  8147. compose(right,locations),
  8148. (
  8149. couple(
  8150. compose(left,store),
  8151. (hired meta)(
  8152. self,
  8153. couple(
  8154. couple(compose(right,locations),values),
  8155. compose(right,store)))),
  8156. values)))),
  8157. (hired meta)(
  8158. self,
  8159. couple(couple(locations,values),constant (nil,nil)))))
  8160. @end example
  8161. @node Transition, , Replace, Reference Implementations
  8162. @section Transition
  8163. This code is relevant to the discussion of @code{transfer} in @ref{Transfer},
  8164. where its specification is described in detail. When this code
  8165. is evaluated on a virtual code application @code{@var{f}}, the result is
  8166. the code for a transition function that takes one configuration to the
  8167. next in the course of evaluating a transfer function, as specified in
  8168. equations @emph{E7} to @emph{E9}.
  8169. @cindex @code{transition}
  8170. @example
  8171. output_buffer = compose(left,argument)
  8172. input_buffer = compose(right,compose(right,argument))
  8173. active = compose(left,compose(right,argument))
  8174. state = compose(left,active)
  8175. output = compose(right,active)
  8176. transition =
  8177. bu(compose,refer) (hired bu(conditional,active))(
  8178. (hired conditional)(
  8179. constant input_buffer,
  8180. bu(compose,(fan bu(hired meta,self))) (hired apply)(
  8181. constant fan bu(couple,couple(output,output_buffer)),
  8182. couple (fan bu(compose,couple))(
  8183. couple(
  8184. (hired apply)(
  8185. hired,
  8186. constant (state,compose(head,input_buffer))),
  8187. constant compose(tail,input_buffer)),
  8188. couple(
  8189. (hired apply)(hired,constant(state,constant nil)),
  8190. constant constant nil)))),
  8191. constant compose(flat,compose(reverse,output_buffer)))
  8192. @end example
  8193. @node Changes, External Libraries, Reference Implementations, Top
  8194. @appendix Changes
  8195. This section is reserved for brief updates due to changes in the
  8196. software that may be important enough to note temporarily until more
  8197. thorough revisions to the document can be made.
  8198. The lack of content here indicates that the current version is either
  8199. completely up to date or in such a sorry state of neglect that even
  8200. this section is obsolete.
  8201. @node External Libraries, Copying, Changes, Top
  8202. @appendix External Libraries
  8203. Various functions are callable from virtual code applications by way
  8204. of the @code{library} combinator as explained in @ref{Library
  8205. combinator}. An expression (shown in @code{silly} syntax) of the form
  8206. @code{library('foo','bar') x} applies a function named @code{'bar'}
  8207. from a library named @code{'foo'} to an argument @code{x}.
  8208. A brief overview of the libraries and functions can always be had by
  8209. executing
  8210. @example
  8211. $ avram --external-libraries
  8212. @end example
  8213. @noindent
  8214. The listing displayed by this command may show some that are not
  8215. included here if this version of the documentation is not current or
  8216. your installation has been locally enhanced. It may also lack some
  8217. that are documented here if your installation is not fully equipped.
  8218. Although the overview from the command line is adequate for a
  8219. reminder, it is not informative enough to explain how each function
  8220. should be used. The purpose of this section is to provide this
  8221. information in greater detail.
  8222. Some general comments are applicable to all libraries.
  8223. Each library documented in this section can generate error messages in
  8224. the event of exceptional conditions, that are documented individually.
  8225. In addition to those, it's also possible for any library function to
  8226. return error messages of
  8227. @cindex unrecognized library
  8228. @cindex unrecognized function name
  8229. @example
  8230. <'unrecognized library'>
  8231. <'unrecognized @var{xxxx} function name'>
  8232. @end example
  8233. @noindent
  8234. where @var{xxxx} is the name of a library. These indicate either that
  8235. the library name is invalid, or the library name is valid but the
  8236. function name is invalid, or that they're both valid but the library
  8237. wasn't detected on the host when @code{avram} was compiled. A virtual
  8238. code application can always avoid these errors by testing for the
  8239. availability of a function using the @code{have} combinator (@ref{Have
  8240. combinator}).
  8241. In addition, any library function that operates on numerical values or
  8242. lists thereof can return these messages in cases of invalid input.
  8243. @cindex missing value
  8244. @cindex invalid value
  8245. @cindex bad vector specification
  8246. @cindex bad matrix specification
  8247. @example
  8248. <'missing value'>
  8249. <'invalid value'>
  8250. <'bad vector specification'>
  8251. <'bad matrix specification'>
  8252. @end example
  8253. @noindent
  8254. These messages indicate that an input parameter that was required to
  8255. be a valid representation of a floating point number, a vector,
  8256. or a matrix was something other than that (@ref{Type Conversions}).
  8257. The last could also occur if a parameter that is required to be
  8258. a square matrix has unequal numbers of rows and columns.
  8259. @menu
  8260. * bes:: Bessel functions
  8261. * complex:: native complex arithmetic
  8262. * fftw:: fast Fourier transforms
  8263. * glpk:: simplex linear programming
  8264. * gsldif:: numerical differentiation
  8265. * gslevu:: series acceleration
  8266. * gslint:: numerical integration
  8267. * harminv:: harmonic inversion
  8268. * kinsol:: constrained non-linear optimization
  8269. * lapack:: linear algebra
  8270. * math:: native floating point arithmetic
  8271. * mtwist:: random number generation
  8272. * minpack:: non-linear optimization
  8273. * mpfr:: arbitrary precision arithmetic
  8274. * lpsolve:: mixed integer programming
  8275. * rmath:: statistical and special functions
  8276. * umf:: sparse matrices
  8277. @end menu
  8278. @node bes, complex, External Libraries, External Libraries
  8279. @section @code{bes}
  8280. An interface to the Bessel functions as defined in the GNU Scientific
  8281. Library (gsl) is available to virtual code applications by invoking a
  8282. function of the form
  8283. @example
  8284. library('bes',f)
  8285. @end example
  8286. @noindent
  8287. where f is a character string identifying the Bessel function family.
  8288. All functions in this library return a floating point number encoded
  8289. as in @ref{math}.
  8290. @menu
  8291. * Bessel function calling conventions::
  8292. * Bessel function errors::
  8293. @end menu
  8294. @node Bessel function calling conventions, Bessel function errors, bes, bes
  8295. @subsection Bessel function calling conventions
  8296. @cindex bessel functions
  8297. The virtual code interface simplifies the gsl C language API by
  8298. excluding the facilities for error estimates, omitting certain array
  8299. valued functions, and subsuming sets of related functions
  8300. within common ones where possible.
  8301. The functions with names in the following group take an argument of
  8302. the form @code{(n,x)}, where @code{n} identifies the member of the
  8303. function family, and @code{x} is the argument to the function.
  8304. @itemize @bullet
  8305. @item @code{J}
  8306. regular cylindrical Bessel functions
  8307. @item @code{Y}
  8308. irregular cylindrical Bessel functions
  8309. @item @code{I}
  8310. regular modified cylindrical Bessel functions
  8311. @item @code{K}
  8312. irregular modified cylindrical Bessel functions
  8313. @end itemize
  8314. For these functions, @code{n} can be either a natural number encoded
  8315. as in @ref{Representation of Numeric and Textual Data}, or a floating
  8316. point number encoded as in @ref{math}. The latter case specifies
  8317. functions of a fractional order. The relevant gsl function is called
  8318. based on the value and type of the parameter.
  8319. Two further related families of functions follow the same calling
  8320. convention.
  8321. @itemize @bullet
  8322. @item @code{Isc}
  8323. scaled regular modified cylindrical Bessel functions
  8324. @item @code{Ksc}
  8325. scaled irregular modified cylindrical Bessel functions
  8326. @end itemize
  8327. @noindent
  8328. The foregoing functions are related to those above by an exponential scale
  8329. factor as documented in the gsl reference manual.
  8330. Functions with names in the following group also take an argument of
  8331. the form @code{(n,x)}, but are not defined for fractional orders and
  8332. so require a natural number for @code{n}.
  8333. @itemize @bullet
  8334. @item @code{j}
  8335. regular spherical Bessel functions
  8336. @item @code{y}
  8337. irregular spherical Bessel functions
  8338. @item @code{isc}
  8339. regular modified spherical Bessel functions
  8340. @item @code{ksc}
  8341. irregular modified spherical Bessel functions
  8342. @end itemize
  8343. The functions in the remaining group follow idiosyncratic calling
  8344. conventions.
  8345. @itemize @bullet
  8346. @item @code{zJ0}, @code{zJ1}
  8347. These take a natural number @code{n} and return the @code{n}th root of
  8348. the regular cylindrical Bessel functions of order 0 or 1,
  8349. respectively.
  8350. @item @code{zJnu}
  8351. This takes a pair @code{(nu,n)} where @code{nu} is the (fractional)
  8352. order of a regular cylindrical Bessel function, @code{n} is a natural
  8353. number. It returns the @code{n}th zero of the function.
  8354. @item @code{lnKnu}
  8355. This takes a pair of floating point numbers @code{(nu,x)} where
  8356. @code{nu} is the (fractional) order of an irregular modified
  8357. cylindrical Bessel and @code{x} is the argument to the function,
  8358. and it returns the natural log of the function.
  8359. @end itemize
  8360. @node Bessel function errors, ,Bessel function calling conventions, bes
  8361. @subsection Bessel function errors
  8362. Memory overflows and unrecognized function names can happen as with
  8363. other library interfaces. A message of
  8364. @cindex bad bessel function call
  8365. @example
  8366. <'bad bessel function call'>
  8367. @end example
  8368. @noindent
  8369. means that invalid input parameters were given, such as a fractional
  8370. order to a function family that is defined only for natural orders.
  8371. @node complex, fftw, bes, External Libraries
  8372. @section @code{complex}
  8373. Complex numbers are represented according to the ISO C standard as
  8374. @cindex complex numbers
  8375. arrays of two IEEE double precision floating point numbers of 8 bytes
  8376. each, with the number representing the real part first.
  8377. A small selection of operations on complex numbers is available by
  8378. function calls of the form @code{library('complex',f)}. These
  8379. functions are implemented by the host system's C library.
  8380. One example is @code{library('complex','create')} which takes a pair
  8381. of floating point numbers @code{(@var{x},@var{y})} to a complex number
  8382. whose real part is @var{x} and whose imaginary part is @var{y}.
  8383. See @ref{math} for information about constructing floating point
  8384. numbers.
  8385. Other than that, the @code{complex} library functions @code{f} fall
  8386. into three main groups, which are the real valued unary operations,
  8387. the complex valued unary operations, and the complex valued binary
  8388. operations. All of these operations are designated by their standard C
  8389. names as documented elsewhere, such as the GNU @code{libc} reference
  8390. manual, except as noted.
  8391. @table @bullet
  8392. @item @asis{} real valued unary operations
  8393. @example
  8394. creal cimag cabs carg
  8395. @end example
  8396. @item @asis{} complex valued unary operations
  8397. @example
  8398. ccos cexp clog conj csin csqrt
  8399. ctan csinh ccosh ctanh casinh cacosh
  8400. catanh casin cacos catan
  8401. @end example
  8402. @item @asis{} complex valued binary operations
  8403. @example
  8404. cpow vid bus mul add sub div
  8405. @end example
  8406. @end table
  8407. The last four correspond to the C language operators @code{*},
  8408. @code{+}, @code{-}, and @code{/} for complex numbers. The functions
  8409. named @code{vid} and @code{bus} are similar to @code{div} and
  8410. @code{sub}, respectively, but with the operands interchanged. That is,
  8411. @example
  8412. library('complex','vid') (x,y)
  8413. @end example
  8414. @noindent
  8415. is equivalent to
  8416. @example
  8417. library('complex','div') (y,x)
  8418. @end example
  8419. All functions in this library taking complex numbers as input may also
  8420. operate on real numbers, and binary operators can have either or both
  8421. operands real. For real operands, a value of zero is inferred as the
  8422. imaginary part. The result type of the function is the same
  8423. regardless.
  8424. @node fftw, glpk, complex, External Libraries
  8425. @section @code{fftw}
  8426. Some functions in the @code{fftw} fast Fourier transform library are
  8427. @cindex Fourier transforms
  8428. @cindex Hartley transforms
  8429. callable by virtual code programs of the form
  8430. @code{library('fftw',f)}, where @code{f} can be one of the following
  8431. character strings.
  8432. @table @asis
  8433. @item @code{u_fw_dft}
  8434. (uni-dimensional forward Discrete Fourier transform)
  8435. @item @code{u_bw_dft}
  8436. (uni-dimensional backward Discrete Fourier transform)
  8437. @item @code{b_fw_dft}
  8438. (bi-dimensional forward Discrete Fourier transform)
  8439. @item @code{b_bw_dft}
  8440. (bi-dimensional backward Discrete Fourier transform)
  8441. @item @code{u_dht}
  8442. (uni-dimensional Discrete Hartley transform)
  8443. @item @code{b_dht}
  8444. (bi-dimensional Discrete Hartley transform)
  8445. @end table
  8446. These stand for the discrete Fourier transform, in one dimension and two
  8447. dimensions, either backward or forward, and the discrete Hartley
  8448. transform in one dimension and two dimensions. The @code{fftw} library
  8449. documentation (@url{http://www.fftw.org}) can give more information
  8450. about the meaning of these transformations.
  8451. The interface is somewhat simplified compared to the API for the @code{fftw}
  8452. C library because there are no considerations of memory management or
  8453. planning, nor any provision for dimensions higher than two.
  8454. Furthermore, from the virtual side of the interface, these
  8455. functions operate on lists rather than arrays. The one dimensional
  8456. Fourier transforms take a list of complex numbers to a list of complex
  8457. numbers (see @ref{complex}), and the one dimensional Hartley
  8458. transforms take a list of reals to a list of reals (see
  8459. @ref{math}). The two dimensional transforms are analogous but they
  8460. take a matrix represented as a list of lists. Error messages
  8461. pertaining to invalid input documented at the beginning of
  8462. this section (@ref{External Libraries}) are relevant.
  8463. Finally, unlike the native API for @code{fftw}, these transformations are
  8464. scaled so that the backward transformation is the inverse of the
  8465. forward, and the Hartley transformations are their own inverses
  8466. (subject to roundoff error).
  8467. @node glpk, gsldif, fftw, External Libraries
  8468. @section @code{glpk}
  8469. The @code{glpk} library (@url{ftp://ftp.gnu.org/pub/gnu/glpk/}) solves
  8470. linear programming problems by the either the simplex algorithm or
  8471. @cindex linear programming
  8472. an interior point method.
  8473. The API for C client programs involves a complicated protocol with
  8474. many optional settings, which is simplified for the virtual machine
  8475. interface. Specifically, the library gives a choice of only two
  8476. functions, which can be expressed in the following forms.
  8477. @example
  8478. library('glpk','simplex')
  8479. library('glpk','interior')
  8480. @end example
  8481. @noindent
  8482. These functions have the same calling convention and should return
  8483. generally the same output for identical inputs, but differences in
  8484. performance, precision, and maybe correctness can be expected.
  8485. The remainder of this section applies to both of them.
  8486. @menu
  8487. * glpk input parameters::
  8488. * glpk output::
  8489. * glpk errors::
  8490. * Additional glpk notes::
  8491. @end menu
  8492. @node glpk input parameters, glpk output, glpk, glpk
  8493. @subsection @code{glpk} input parameters
  8494. The argument must be a triple of the form,
  8495. @code{(@var{c},(@var{m},@var{y}))}, subject to the following specification.
  8496. @itemize @bullet
  8497. @item @var{c}
  8498. is a list of cost function coefficients as floating point numbers (see
  8499. @ref{math}). There should be one item of @var{c} for each variable in
  8500. the linear programming problem (Note that there is no additive
  8501. constant, which would require one extra).
  8502. The interpretation of @var{c} is that an assignment of non-negative
  8503. values to the variables @var{x} is sought to make the vector inner
  8504. product @var{c} @var{x} as small as possible.
  8505. @item @var{m}
  8506. is a sparse matrix represented as a list of triples in the form
  8507. @cindex sparse matrix
  8508. @example
  8509. <((@var{i},@var{j}),@var{a})...>
  8510. @end example
  8511. @noindent
  8512. where @var{i} and @var{j} are row and column indices as natural
  8513. numbers starting from 0 and @var{a} is a non-zero floating point
  8514. number. The presence of a triple @code{((@var{i},@var{j}),@var{a})} in
  8515. the list indicates that the @var{i},@var{j}-th entry in the matrix has
  8516. a value of @var{a}. Missing combinations of @var{i} and @var{j}
  8517. indicate that the corresponding entry is zero.
  8518. The interpretation of @var{m} is that together with @var{y} it
  8519. specifies a system of equations the variables in the solution @var{x}
  8520. must satisfy simultaneously, as explained below.
  8521. @item @var{y}
  8522. is a list of floating point numbers, with one number for each distinct value of
  8523. @var{i} in @var{m}, above, needed to complete the equations.
  8524. The interpretation of @var{y} is that in matrix notation, the
  8525. condition @var{m} @var{x} = @var{y} must be met by any acceptable
  8526. solution @var{x}.
  8527. To put it another way, for each distinct value of @var{i}, the @var{i}-th item
  8528. of @var{y} has to equal the sum over all @var{j} of @var{xj} @var{a},
  8529. where @var{a} is the real number appearing in the triple
  8530. @code{((@var{i},@var{j}),@var{a})} in @var{m}, if any, and @var{xj} is
  8531. the @var{j}-th variable of the solution.
  8532. @end itemize
  8533. @node glpk output, glpk errors, glpk input parameters, glpk
  8534. @subsection @code{glpk} output
  8535. If a solution meeting the constraints is found, it is returned as a
  8536. list of pairs of the form @code{<(@var{i},@var{x})...>}, where each
  8537. @var{i} is a natural number and each @var{x} is a floating point
  8538. number giving the value obtained for the @var{i}-th variable numbered
  8539. from zero. Any values of @var{i} that are omitted from the list
  8540. indicate that the corresponding variable has a value of zero.
  8541. If no solution is found due to infeasibility or because @code{glpk}
  8542. just didn't find one, an empty list is returned. The lack of a
  8543. solution is not treated as an exceptional condition.
  8544. @node glpk errors, Additional glpk notes, glpk output, glpk
  8545. @subsection @code{glpk} errors
  8546. Possible error messages are
  8547. @example
  8548. <'bad glpk specification'>
  8549. @end example
  8550. @noindent
  8551. which means that the input did not conform to the description given above,
  8552. and
  8553. @example
  8554. <'memory overflow'>
  8555. @end example
  8556. It is not considered an exceptional condition for no feasible solution
  8557. to exist, and in that case an empty list is returned.
  8558. The @code{glpk} documentation gives no assurance as to the correctness
  8559. of reported solutions, so the user should also take the possibility of
  8560. incorrect results into account.
  8561. @node Additional glpk notes, , glpk errors, glpk
  8562. @subsection Additional @code{glpk} notes
  8563. A sparse matrix representation of @var{m} is used because in practice
  8564. @cindex sparse matrix
  8565. most linear programming problems have very sparse systems of equations.
  8566. Only the constraint of non-negativity is admitted. Other
  8567. @cindex constraints
  8568. constraints such as upper bounds must be effected through a change of
  8569. variables if required.
  8570. The @code{glpk} library has a small memory leak, which @code{avram}
  8571. corrects by methods described in @ref{Memory leaks}.
  8572. @node gsldif, gslevu, glpk, External Libraries
  8573. @section @code{gsldif}
  8574. Numerical differentiation of a real valued function of a single real
  8575. @cindex numerical differentiation
  8576. variable can be done by a library function of the form
  8577. @example
  8578. library('gsldif',method)
  8579. @end example
  8580. @noindent
  8581. where @code{method} is one of
  8582. @itemize @bullet
  8583. @item @code{'backward'}
  8584. @item @code{'central'}
  8585. @item @code{'forward'}
  8586. @item @code{'t_backward'}
  8587. @item @code{'t_central'}
  8588. @item @code{'t_forward'}
  8589. @end itemize
  8590. @menu
  8591. * gsldif input parameters::
  8592. * gsldif output::
  8593. * gsldif exceptions::
  8594. * Additional gsldif notes::
  8595. @end menu
  8596. @node gsldif input parameters, gsldif output, gsldif, gsldif
  8597. @subsection @code{gsldif} input parameters
  8598. The argument to the functions with mnemonics of @code{backward},
  8599. @code{central} or @code{forward} is a pair @code{(@var{f},@var{x})},
  8600. where @var{f} is the virtual machine code for a real valued function
  8601. of a real variable, and @var{x} is the input to @var{f} where the
  8602. derivative is sought. Real numbers are represented according to
  8603. @ref{math}.
  8604. The argument to the functions with mnemonics of @code{t_backward},
  8605. @code{t_central} or @code{t_forward} is a pair @code{((@var{f},@var{t}),@var{x})},
  8606. where @var{f} and @var{x} are as above, and @var{t} is a tolerance represented
  8607. as a floating point number. The tolerance is passed through
  8608. to the GNU Scientific library (GSL) differentiation routines.
  8609. When no tolerance is specified, the default is @code{1.0e-8}.
  8610. @node gsldif output, gsldif exceptions, gsldif input parameters, gsldif
  8611. @subsection @code{gsldif} output
  8612. The result returned by @code{library('gsldif',method) (f,x)} or
  8613. @code{library('gsldif',method) ((f,t),x)}
  8614. is an approximation of the first derivative of @var{f} evaluated at
  8615. @var{x}.
  8616. The result is obtained by the one of the GNU Scientific Library (GSL)
  8617. @cindex GNU Scientific Library
  8618. functions for numerical differentiation that matches the virtual code
  8619. function name. These functions are documented in the GSL reference
  8620. manual. The three methods should have approximately the same results
  8621. but may differ in numerical properties.
  8622. @node gsldif exceptions, Additional gsldif notes, gsldif output, gsldif
  8623. @subsection @code{gsldif} exceptions
  8624. An error message of
  8625. @cindex bad derivative specification
  8626. @example
  8627. <'bad derivative specification'>
  8628. @end example
  8629. @noindent
  8630. will be returned if the either the whole argument, @var{f}, or @var{x} is
  8631. @code{nil}.
  8632. Any error message caused by the evaluation of @var{f} will
  8633. propagate to the result.
  8634. @node Additional gsldif notes, , gsldif exceptions, gsldif
  8635. @subsection Additional @code{gsldif} notes
  8636. The function @var{f} may be any expressible virtual machine code
  8637. function that takes a real argument to a real result, including one
  8638. that uses other library functions. However, if @var{f} passes
  8639. functions to other library functions as arguments, there is a constant
  8640. overhead in stack space for each level, and a remote possibility of a
  8641. @cindex segmentation fault
  8642. segmentation fault if they are very deeply nested.
  8643. Numerical instability is an issue for higher derivatives (i.e.,
  8644. differentiating a function that is obtained by differentiating another
  8645. function). Some experimentation with larger tolerances may be needed.
  8646. @node gslevu, gslint, gsldif, External Libraries
  8647. @section @code{gslevu}
  8648. This library exports a pair of functions of the form
  8649. @example
  8650. library('gslevu','accel')
  8651. library('gslevu','utrunc')
  8652. @end example
  8653. @noindent
  8654. that take a list of real numbers @var{x} to a pair of real numbers
  8655. @code{(@var{s},@var{e})}.
  8656. The idea is that @var{x} represents the first few terms of an infinite
  8657. @cindex infinite series
  8658. series whose sum converges, but only very slowly. The functions
  8659. @cindex convergence
  8660. extrapolate an estimate of the infinite summation by the Levin
  8661. @cindex Levin u-transform
  8662. u-transform as documented in the GNU Scientific Library reference
  8663. manual.
  8664. For well behaved series, considerably fewer terms are needed for an
  8665. accurate estimate than a direct summation would require.
  8666. @menu
  8667. * gslevu calling conventions::
  8668. * gslevu exceptions::
  8669. @end menu
  8670. @node gslevu calling conventions, gslevu exceptions, gslevu, gslevu
  8671. @subsection @code{gslevu} calling conventions
  8672. The input to either of these functions is a list of real numbers
  8673. represented as explained in @ref{math}.
  8674. The result is a pair @code{(@var{s},@var{e})} holding an estimate of
  8675. the sum, @var{s}, and an estimate of the error in the sum,
  8676. @var{e}, each being a real number.
  8677. Both functions compute the same sum, @var{s}, but the @code{utrunc} function
  8678. is faster and
  8679. @cindex infinite sum
  8680. more memory efficient, using a less trustworthy method of estimating
  8681. the error.
  8682. @node gslevu exceptions, , gslevu calling conventions, gslevu
  8683. @subsection @code{gslevu} exceptions
  8684. If an empty list is passed as a parameter to a function in this library,
  8685. an error message of @code{<'empty gslevu sequence'>} is returned.
  8686. If there is insufficient memory, an error message of @code{<'memory
  8687. overflow'>} is returned.
  8688. Other than that, no exceptional conditions are relevant other than the
  8689. general ones documented at the beginning of @ref{External Libraries}.
  8690. @node gslint, harminv, gslevu, External Libraries
  8691. @section @code{gslint}
  8692. An interface to a selection of numerical integration routines from the
  8693. @cindex numerical integration
  8694. GNU Scientific Library is provided by functions of the form
  8695. @example
  8696. library('gslint',q)
  8697. @end example
  8698. @noindent
  8699. where q can be one of
  8700. @code{'qng'}, @code{'qng_tol'},
  8701. @code{'qagx'}, @code{'qagx_tol'},
  8702. @code{'qagp'}, or @code{'qagp_tol'}.
  8703. @menu
  8704. * gslint input parameters::
  8705. * gslint output::
  8706. * gslint exceptions::
  8707. * Additional gslint notes::
  8708. @end menu
  8709. @node gslint input parameters, gslint output, gslint, gslint
  8710. @subsection @code{gslint} input parameters
  8711. The library functions @code{qng} and @code{qagx} take an
  8712. argument of the form @code{(@var{f},(@var{a},@var{b}))}, where @var{f}
  8713. is a function to be integrated, @var{a} is the lower limit, and
  8714. @var{b} is the upper limit, both limits being floating point numbers
  8715. as in @ref{math}.
  8716. The @code{qng_tol} and @code{qagx_tol} functions take an argument of
  8717. @cindex tolerance
  8718. the form @code{((@var{f},@var{t}),(@var{a},@var{b}))}, where @var{f},
  8719. @var{a}, and @var{b} are as above, and @var{t} is a specified
  8720. tolerance.
  8721. The @code{qagp} and @code{qagp_tol} functions take arguments of
  8722. the form @code{(@var{f},@var{p})} and
  8723. @code{((@var{f},@var{t}),@var{p})}, respectively, where @var{f} and
  8724. @var{t} are as above, and @var{p} is an ordered list of real numbers
  8725. specifying the limits of integration along with arbitrarily many
  8726. intervening breakpoints.
  8727. The integrand @var{f} is expressed in virtual machine code, and takes a
  8728. single real argument to a real result. The argument and result of
  8729. @var{f} are required to be floating point numbers as described in
  8730. @ref{math}. Any expressible function of this type is acceptable, even
  8731. one defined in terms of other integrals, so that a double or triple
  8732. integral can be expressed easily, albeit a costly computation.
  8733. However, a constant overhead in stack space is required for each
  8734. nested library function call, and there is currently no mechanism to
  8735. @cindex segmentation fault
  8736. prevent segmentation faults due to a stack overflow.
  8737. When no tolerance is specified, as with @code{qng}, @code{qagx}, and
  8738. @code{qagp}, the tightest attainable tolerance is chosen by default,
  8739. currently @code{2e-14}, in order find the most accurate result
  8740. possible. A selection of progressively looser tolerances is tried
  8741. automatically if the tightest one is not successful, stopping when
  8742. either a solution is found or ten orders of magnitude are covered.
  8743. If a tolerance is explicitly specified, as with @code{qng_tol},
  8744. @code{qagx_tol} or @code{qagp_tol}, only that tolerance is tried.
  8745. @node gslint output, gslint exceptions, gslint input parameters, gslint
  8746. @subsection @code{gslint} output
  8747. In all cases, if no exception occurs, the result returned is an
  8748. approximation of the integral of @var{f} over the interval from
  8749. @var{a} to @var{b} or from the first item of @var{p} to the last.
  8750. Results may differ in numerical properties depending on the
  8751. integration method and the tolerance used.
  8752. @itemize @bullet
  8753. @item
  8754. The @code{qagp}* and @code{qagx}* functions use an adaptive algorithm,
  8755. @cindex adaptive integration
  8756. @cindex non-adaptive integration
  8757. whereas the @code{qng}* functions use a faster non-adaptive algorithm
  8758. suitable only for smooth integrands.
  8759. @item
  8760. Faster and maybe more accurate results are obtained for discontinuous
  8761. or non-differentiable integrands by the @code{qagp}* integration
  8762. methods if the interior points in @var{p} are chosen to coincide with
  8763. the discontinuities or corners.
  8764. @item
  8765. Larger tolerances are conducive to faster but less accurate results in
  8766. most cases.
  8767. @end itemize
  8768. @node gslint exceptions, Additional gslint notes, gslint output, gslint
  8769. @subsection @code{gslint} exceptions
  8770. If an argument of an inappropriate form can be detected (such as an
  8771. empty pair or one without floating point numbers), it causes an error
  8772. message to be returned saying
  8773. @cindex bad integral specification
  8774. @example
  8775. <'bad integral specification'>
  8776. @end example
  8777. @noindent
  8778. Error messages signalled by the integrand @var{f} may also be
  8779. reported, as well as any message returned by @code{gsl_strerror}. A
  8780. typical cause for a @code{gsl_strerror} message would be an explicitly
  8781. specified tolerance that is too tight. An error message of
  8782. @cindex slow convergence
  8783. @example
  8784. <'slow convergence'>
  8785. @end example
  8786. @noindent
  8787. is returned in the event of excessively many function evaluations
  8788. (currently 3600 at each tolerance level).
  8789. @node Additional gslint notes, , gslint exceptions, gslint
  8790. @subsection Additional @code{gslint} notes
  8791. The @code{qagx}* functions subsume the GSL variants @code{qags},
  8792. @code{qagiu}, @code{qagil}, and @code{qagi} for finite, semi-infinite,
  8793. and infinite intervals, which are seleted as appropriate based on the
  8794. @cindex improper integrals
  8795. limits of integration @var{a} and @var{b}.
  8796. The @code{qagp} function reverts to the @code{qagx} function if there
  8797. are only two points given in @var{p}. Fewer than two will cause an
  8798. error.
  8799. The library interface code relies on the standard @code{setjmp}
  8800. @cindex setjmp
  8801. utility found in the system header file @code{setjmp.h} to break out
  8802. of integrals that don't converge after excessively many function
  8803. evaluations. Non-termination has been an issue in the past with GSL
  8804. integration routines for very badly behaved integrands, and the API
  8805. provides no documented means for the user supplied integrand function
  8806. to request a halt.
  8807. Although it is meant to be standard, a host without @code{setjmp} will
  8808. cause @code{avram} to be configured to abort the application with an
  8809. error message in the event of non-convergence. This behavior is
  8810. considered preferable to the alternative of non-termination. Usually
  8811. an effective workaround in such cases is to specify a sufficiently
  8812. loose tolerance explicitly by using one of the *@code{_tol} library
  8813. functions.
  8814. @node harminv, kinsol, gslint, External Libraries
  8815. @section @code{harminv}
  8816. The @code{harminv} library decomposes a complex valued function of a
  8817. @cindex harminv
  8818. discrete variable into a sum of decaying sinusoids given a finite
  8819. sample. It uses a method with better accuracy and convergence than
  8820. Fourier analysis or least squares curve fitting. More information
  8821. @cindex least squares
  8822. @cindex Fourier transforms
  8823. is available at @url{http://ab-initio.mit.edu/wiki/index.php/Harminv}.
  8824. @menu
  8825. * harminv input parameters::
  8826. * harminv output::
  8827. * harminv exceptions::
  8828. * Additional harminv notes::
  8829. @end menu
  8830. @node harminv input parameters, harminv output, harminv, harminv
  8831. @subsection @code{harminv} input parameters
  8832. The virtual machine interface to the @code{harminv} library provides
  8833. only a single function, callable as
  8834. @example
  8835. library('harminv','hsolve')
  8836. @end example
  8837. @noindent
  8838. The input to this function is an operand of the form
  8839. @example
  8840. (signal,(fmin,fmax),nf)
  8841. @end example
  8842. @noindent
  8843. where
  8844. @itemize @bullet
  8845. @item
  8846. @code{signal} is a list of complex numbers containing samples
  8847. of the function to be decomposed at equal time steps
  8848. (@ref{complex} and @ref{Representation of Numeric and Textual Data}).
  8849. @item
  8850. @code{fmin} and @code{fmax} are the band limits expressed in units
  8851. of inverse time steps as floating point numbers (@ref{math}).
  8852. @item
  8853. @code{nf} is the number of spectral basis functions expressed as a
  8854. natural (@ref{Representation of Numeric and Textual Data}).
  8855. @end itemize
  8856. @noindent
  8857. If a value of 0 is specified for @code{nf} a default value of
  8858. @example
  8859. min(300, (fmax - fmin) * n * 1.1)
  8860. @end example
  8861. @noindent
  8862. is used, where @code{n} is the length of @code{signal}. The
  8863. computation time increases cubically with @code{nf}.
  8864. @node harminv output, harminv exceptions, harminv input parameters, harminv
  8865. @subsection @code{harminv} output
  8866. The result returned by a call to
  8867. @example
  8868. library('harminv','hsolve')
  8869. @end example
  8870. @noindent
  8871. with valid input (@ref{harminv input parameters}) is a list of similar tuples of the form
  8872. @example
  8873. <(amplitude,frequency,decay,quality,error)...>
  8874. @end example
  8875. @noindent
  8876. with all members being real valued except for the amplitudes, which are
  8877. complex. Each tuple describes a function of the form
  8878. @example
  8879. f(t) = A * sin (frequency * t + P) * exp (-decay * t)
  8880. @end example
  8881. @noindent
  8882. such that the summation of these functions approximates the original
  8883. given signal (@ref{harminv input parameters}). The real amplitude
  8884. @code{A} and phase @code{P} are given by the modulus and argument of
  8885. the complex amplitude returned in the result,
  8886. @example
  8887. A = library('complex','cabs') amplitude
  8888. P = library('complex','carg') amplitude
  8889. @end example
  8890. @noindent
  8891. in terms of the complex library functions (@ref{complex}).
  8892. The error values are measures of the goodness of fit, and the quality
  8893. factors are defined as
  8894. @example
  8895. quality = (pi * |frequency| / decay)
  8896. @end example
  8897. @noindent
  8898. It may be useful in some applications to ignore components with
  8899. quality factors outside of a certain range.
  8900. @node harminv exceptions, Additional harminv notes, harminv output, harminv
  8901. @subsection @code{harminv} exceptions
  8902. Various exceptional conditions are possible with the @code{harminv}
  8903. library interface, and one of the following messages could be
  8904. returned. Each of them has the form of a list containing a single
  8905. character string.
  8906. @itemize @bullet
  8907. @item
  8908. @code{unrecognized harminv function name}
  8909. is reported in case of a function call of the form
  8910. @code{library('harminv',f)} where @code{f} is anything other than
  8911. the character string @code{'hsolve'}, this being the only function in
  8912. the library.
  8913. @item
  8914. @code{bad harminv function call}
  8915. is reported if the input parameters don't meet the specifications
  8916. described in @ref{harminv input parameters}, or if @code{fmin} is
  8917. greater than @code{fmax}.
  8918. @item
  8919. @code{bad vector specification}
  8920. could be the result of a list of real numbers rather than complex
  8921. numbers being passed as a @code{signal}. Real numbers can
  8922. be converted to complex numbers using the @code{create} function from
  8923. the @code{complex} library (@ref{complex}).
  8924. @item
  8925. @code{memory overflow}
  8926. can occur if @code{avram} is operating very close to the limit of host
  8927. memory, or perhaps if infeasibly large values are passed as @code{nf}
  8928. @item
  8929. @code{counter overflow}
  8930. is similar to a memory overflow
  8931. @end itemize
  8932. @node Additional harminv notes, , harminv exceptions, harminv
  8933. @subsection Additional @code{harminv} notes
  8934. The @code{harminv} library interface requires the @code{harminv} and
  8935. @code{lapack} libraries to be installed on the host system, and also
  8936. requires standard complex number support from the system's C library.
  8937. The author's installation of @code{avram} has been compiled against
  8938. the Debian @code{harminv} development library package, which at this
  8939. writing is unmaintained and is missing the necessary header file
  8940. @file{harminv-int.h}, without which compilation of files including
  8941. @file{harminv.h} fails. Some headers from @file{harminv.h} have been
  8942. copied directly into @file{avram-x.x.x/src/harminv.c} under the
  8943. @code{avram} source tree to avoid this dependence, so that
  8944. @code{avram} will compile correctly on a Debian system. These may need
  8945. to be updated if necessary to track the @code{harminv} source.
  8946. @node kinsol, lapack, harminv, External Libraries
  8947. @section @code{kinsol}
  8948. The @code{kinsol} library (@url{http://www.llnl.gov/CASC/sundials/})
  8949. contains sophisticated routines for non-linear optimization and
  8950. @cindex optimization
  8951. @cindex non-linear optimization
  8952. constrained non-linear optimization, some of which are available to
  8953. @cindex constrained non-linear optimization
  8954. virtual code applications by way of functions expressed as shown.
  8955. @example
  8956. library('kinsol',k)
  8957. @end example
  8958. @noindent
  8959. The function name @code{k} is a string of the form
  8960. @code{'@var{xy}_@var{zzzzz}'}. The field @var{zzzzz} specifies
  8961. the optimization algorithm, which can be one of @code{dense},
  8962. @code{gmres}, @code{bicgs}, or @code{tfqmr}, following the names used
  8963. by the API for @code{kinsol} in C. The field @var{y} determines
  8964. the way gradients are obtained, which is either @code{j} for a user
  8965. supplied Jacobian, or @code{d} for finite differences computed by
  8966. @code{kinsol}. The remaining field @var{x} is either @code{c} for
  8967. constrained optimization, or @code{u} for unconstrained. Hence, the
  8968. whole function name can be one of sixteen possible alternatives.
  8969. @example
  8970. cd_dense cd_gmres cd_bicgs cd_tfqmr
  8971. ud_dense ud_gmres ud_bicgs ud_tfqmr
  8972. cj_dense cj_gmres cj_bicgs cj_tfqmr
  8973. uj_dense uj_gmres uj_bicgs uj_tfqmr
  8974. @end example
  8975. More specific information about the optimization algorithms can be
  8976. found in the @code{kinsol} documentation at the above
  8977. address. Different algorithms may perform better on different
  8978. problems.
  8979. @menu
  8980. * kinsol input parameters::
  8981. * kinsol output::
  8982. * kinsol exceptions::
  8983. * Additional kinsol notes::
  8984. @end menu
  8985. @node kinsol input parameters, kinsol output, kinsol, kinsol
  8986. @subsection @code{kinsol} input parameters
  8987. Functions whose names are of the form @code{@var{x}d_@var{zzzzz}}
  8988. take an argument of the form
  8989. @code{(@var{f},(@var{i},@var{o}))},
  8990. and functions whose names are of the form @code{@var{x}j_@var{zzzzz}}
  8991. take an argument of the form
  8992. @code{((@var{f},@var{j}),(@var{i},@var{o}))}.
  8993. The parameters have these interpretations.
  8994. @itemize @bullet
  8995. @item
  8996. @var{f} is a function to be optimized, expressed in virtual machine
  8997. code. It takes a list of real numbers as input and returns a list of
  8998. real numbers as output. The numbers must be in floating point format
  8999. as described in @ref{math}.
  9000. @item
  9001. @var{j} is a function in virtual machine code that computes the
  9002. Jacobian or partial derivatives of @var{f} for a given list of input
  9003. @cindex Jacobian
  9004. numbers. The exact calling convention for @var{j} depends on the
  9005. optimization algorithm selected, as explained below.
  9006. @item
  9007. @var{i} is a list of real numbers suitable as an input for @var{f}.
  9008. The exact values of the numbers in @var{i} are not crucial but the
  9009. length of @var{i} is taken as an indication of the required length for
  9010. any input list to @var{f}. In the case of constrained optimization
  9011. problems (i.e., functions with names beginning with @code{c}), @var{i} must
  9012. consist entirely of non-negative numbers.
  9013. @item
  9014. @var{o} is a list numbers indicating the ``optimal'' output from
  9015. @var{f} in the sense described below (@ref{kinsol output}). Its length
  9016. is taken to indicate the usual length of an output returned by
  9017. @var{f}.
  9018. @end itemize
  9019. If the optimization problem is being solved by either the
  9020. @code{cj_dense} or the @code{uj_dense} method, the Jacobian parameter
  9021. @var{j} is expected to take a list @var{v} of real numbers the length
  9022. of @var{i} as input and return a list of lists of reals as output. The
  9023. numbers are represented as described in @ref{math}. The outer list in
  9024. the output from @var{j} is required to be the length of @var{o}, while
  9025. each inner list is required to be the length of @var{i}.
  9026. The output from @var{j} is interpreted as a matrix of the form
  9027. described in @ref{Two dimensional arrays}. The entry in row @var{m}
  9028. and column @var{n} is the partial derivative (evaluated at @var{v}) of
  9029. the @var{m}-th component of the output of @var{f} with respect to the
  9030. @var{n}-th item of the input list.
  9031. For optimization problems being solved by the methods of
  9032. @code{@var{x}j_gmres}, @code{@var{x}j_bicgs}, or
  9033. @code{@var{x}j_tfqmr}, (i.e., where @var{x} is either @code{c} or
  9034. @code{u}) the Jacobian function @var{j} follows a different convention
  9035. that is meant to be more memory efficient. Given an argument of the
  9036. form @code{(@var{m},@var{v})}, it returns only the @var{m}-th row of
  9037. the matrix described above instead of the whole thing. The parameter
  9038. @var{m} is a natural number less than the length of @var{o}, and
  9039. @var{v} is a list of real numbers the length of @var{i} the same as
  9040. above. The number @var{m} is encoded as described in
  9041. @ref{Representation of Numeric and Textual Data}.
  9042. @node kinsol output, kinsol exceptions, kinsol input parameters, kinsol
  9043. @subsection @code{kinsol} output
  9044. The @code{kinsol} functions attempt to search the domain of
  9045. @var{f} for a vector @var{v} the length of @var{i} to satisfy
  9046. @code{@var{f}(@var{v}) = @var{o}} as closely as possible. In the case
  9047. of constrained optimization, (i.e., functions whose names begin with
  9048. @code{c}), only non-negative numbers are acceptable in @var{v}. The
  9049. search for @var{v} will start in the vicinity of @var{i}. The value of
  9050. @var{i} will therefore determine a unique solution if multiple
  9051. solutions exist, and will save time if it is near a solution.
  9052. In some cases when a solution can't be found due to non-convergence,
  9053. @cindex non-convergence
  9054. an empty list is returned. Non-convergence is not considered an
  9055. exceptional condition. In all other cases where no exception occurs,
  9056. the output from a @code{kinsol} function will be the list @var{v} of
  9057. real numbers satisfying @code{@var{f}(@var{v}) = @var{o}} to the best
  9058. possible tolerance.
  9059. @cindex tolerance
  9060. @node kinsol exceptions, Additional kinsol notes, kinsol output, kinsol
  9061. @subsection @code{kinsol} exceptions
  9062. @itemize @bullet
  9063. @item
  9064. Any error messages that may be generated in the course of evaluating
  9065. the functions @var{f} and @var{j} will propagate to the result
  9066. returned by the @code{kinsol} library functions.
  9067. @item
  9068. If there is insufficient memory to complete any operation, the result
  9069. is a message of
  9070. @example
  9071. <'memory overflow'>
  9072. @end example
  9073. @item
  9074. If the argument to the library function (i.e.,
  9075. @code{(@var{f},(@var{i},@var{o}))} or
  9076. @code{((@var{f},@var{j}),(@var{i},@var{o}))}) fails to meet the
  9077. required specifications in a detectable way, the result will be a
  9078. message of
  9079. @cindex bad kinsol specification
  9080. @example
  9081. <'bad kinsol specification'>
  9082. @end example
  9083. @item
  9084. Any status returned by any @code{kinsol} API functions other than
  9085. success or one of several types of non-convergence results in a
  9086. message of
  9087. @example
  9088. <'kinsol error'>
  9089. @end example
  9090. @end itemize
  9091. @node Additional kinsol notes, , kinsol exceptions, kinsol
  9092. @subsection Additional @code{kinsol} notes
  9093. When a user supplied Jacobian function @var{j} is specified, the
  9094. @cindex Jacobian
  9095. solution is likely to be found faster and more accurately. The
  9096. Jacobian should be given if an analytical form for @var{f} is known,
  9097. from which the Jacobian can be obtained easily by partial
  9098. differentiation. If the Jacobian is unavailable, a finite difference
  9099. method implemented internally by @code{kinsol} is used as a substitute
  9100. and will usually yield acceptable results.
  9101. Tolerances are not explicitly specified on the virtual side of the
  9102. interface although the native @code{kinsol} API requires them. A range
  9103. of tolerances over ten orders of magnitude is automatically tried
  9104. before giving up.
  9105. Similarly to the @code{glpk} and @code{lpsolve} library interfaces
  9106. (@ref{glpk} and @ref{lpsolve}), the only expressible constraint through
  9107. @cindex constraints
  9108. the virtual code interface is that all variables are
  9109. non-negative. Arbitrary upper and lower bounds can be simulated by
  9110. appropriate variable substitutions in the formulation of the problem.
  9111. The @code{kinsol} library natively requires a system function @var{f}
  9112. with equally many inputs as outputs, and will search only for the
  9113. input associated with an output vector of all zeros, but the virtual
  9114. code interface relaxes these requirements by allowing a function that
  9115. transforms between lists of unequal lengths, and will search for the
  9116. input of @var{f} causing it to match any given ``optimal'' output
  9117. @var{o}. These effects are achieved by padding the shorter of the two
  9118. vectors transparently and subtracting the specified optimum from the
  9119. result.
  9120. The @code{kinsol} library can be configured to use single precision,
  9121. double precision, or extended precision arithmetic, but only a double
  9122. precision configuration is compatible with @code{avram}. This
  9123. condition is checked when @code{avram} is configured and it will not
  9124. interface with alternative @code{kinsol} configurations.
  9125. The @code{kinsol} library has some more advanced features to which
  9126. this interface doesn't do justice, such as preconditioning, scaling,
  9127. solution of systems with band limited Jacobians, and concurrent
  9128. computation.
  9129. @node lapack, math, kinsol, External Libraries
  9130. @section @code{lapack}
  9131. An arsenal of weapons grade linear algebra functions from the
  9132. @cindex Fortran
  9133. @code{LAPACK} Fortran library is accessible to virtual code
  9134. @cindex linear algebra
  9135. applications through library calls of the form
  9136. @example
  9137. library('lapack',f)
  9138. @end example
  9139. Each library function @code{f} invokes a @code{LAPACK} function of the
  9140. same name, but the calling conventions on the virtual side are an
  9141. artifact of the interface requiring their own documentation.
  9142. Some functions that are part of @code{LAPACK} are not described here
  9143. (mostly the so called computational and auxiliary routines, and
  9144. @cindex single precision
  9145. anything in single precision), because they are not accessible by
  9146. the virtual code interface.
  9147. @menu
  9148. * lapack calling conventions::
  9149. * lapack exceptions::
  9150. * Additional lapack notes::
  9151. @end menu
  9152. @node lapack calling conventions, lapack exceptions, lapack, lapack
  9153. @subsection @code{lapack} calling conventions
  9154. A table describing the inputs and outputs to the @code{lapack} library
  9155. functions listed by their function names is given in this
  9156. section. Some general points related to most of the functions are
  9157. mentioned first.
  9158. @itemize @bullet
  9159. @item
  9160. References to vectors, matrices, and packed matrices should be
  9161. understood as their list representations explained in @ref{Type
  9162. Conversions}. Although @code{LAPACK} internally uses column order
  9163. arrays, the virtual code library interface exhibits a matrix as a list
  9164. of lists with one inner list for each row.
  9165. @item
  9166. Some functions require a symmetric matrix as an input parameter. Any
  9167. @cindex symmetric matrices
  9168. input parameter that is required to be a symmetric matrix may be
  9169. specified optionally either in square form or in triangular form as
  9170. @cindex triangular matrices
  9171. described in @ref{Two dimensional arrays}. If a square matrix form is
  9172. used, symmetry is not checked and the lower triangular portion is
  9173. ignored.
  9174. @item
  9175. Some function names are listed in pairs differing only in the first
  9176. letter. Function names beginning with @code{d} pertain to vectors or
  9177. matrices of real numbers (@ref{math}), and function names beginning
  9178. with @code{z} pertain to complex numbers (@ref{complex}). The
  9179. specifications of similarly named functions are otherwise identical.
  9180. @end itemize
  9181. @table @asis
  9182. @item @code{dgesvx}
  9183. @item @code{zgesvx}
  9184. These library functions take a pair @code{(@var{a},@var{b})} where
  9185. @var{a} is an @var{n} by @var{n} matrix and @var{b} is a vector of
  9186. length @var{n}. If @var{a} is non-singular, they return a
  9187. vector @var{x} such that @code{@var{a} @var{x} = @var{b}}.
  9188. Otherwise they return an empty list.
  9189. @item @code{dgelsd}
  9190. @item @code{zgelsd}
  9191. These functions generalize those above by taking a pair
  9192. @code{(@var{a},@var{b})} where @var{a} is an @var{m} by @var{n} matrix
  9193. and @var{b} is a vector of length @var{m}, with @var{m} greater than
  9194. @var{n}. They return a vector @var{x} of length @var{n} to minimize
  9195. the magnitude of @code{@var{b} - @var{a} @var{x}}.
  9196. @item @code{dgesdd}
  9197. @item @code{zgesdd}
  9198. These functions take a list of @var{m} time series (i.e., vectors)
  9199. each of length @var{n} and return a list of basis vectors each of
  9200. length @var{n}. The basis vectors span the set of time series in the
  9201. @cindex singular value decomposition
  9202. given list according to the singular value decomposition (i.e., with
  9203. the basis vectors forming a series in order of decreasing
  9204. significance). The number of basis vectors is at most
  9205. @code{@var{min}(@var{m},@var{n})} but could be less if the input time
  9206. series aren't linearly independent. An empty list could be returned
  9207. due to lack of convergence.
  9208. @item @code{dgeevx}
  9209. @item @code{zgeevx}
  9210. These functions take a non-symmetric square matrix and
  9211. return a pair @code{(@var{e},@var{v})} where @var{e} is a list of
  9212. eigenvectors and @var{v} is a list of eigenvalues, both of which will
  9213. @cindex eigenvectors
  9214. contain only complex numbers. (N.B., both functions return complex
  9215. results even though @code{dgeevx} takes real input.) They could also
  9216. return @code{nil} due to a lack of convergence.
  9217. @item @code{dpptrf}
  9218. @item @code{zpptrf}
  9219. These functions take a symmetric square matrix and
  9220. return one of the Cholesky factors. The Cholesky factors are a pair
  9221. @cindex Cholesky decomposition
  9222. of triangular matrices, each equal to the transpose of the other,
  9223. whose product is the original matrix.
  9224. @itemize @bullet
  9225. @item
  9226. If the input matrix is specified in lower triangular form, the lower
  9227. triangular Cholesky factor is returned.
  9228. @item
  9229. If the input matrix is specified in square or upper triangular form,
  9230. the upper triangular Cholesky factor is returned.
  9231. @item
  9232. In either case, the result is returned in triangular form.
  9233. @end itemize
  9234. @item @code{dggglm}
  9235. @item @code{zggglm}
  9236. The input is a pair of matrices and a vector
  9237. @cindex generalized least squares
  9238. @cindex least squares
  9239. @code{((@var{A},@var{B}),@var{d})}. The output is a pair of vectors
  9240. @code{(@var{x},@var{y})} satisfying @code{@var{A}@var{x} +
  9241. @var{B}@var{y} = @var{d}} for which the magnitude of @var{y} is
  9242. minimal. The dimensions all have to be consistent, which means
  9243. the number of rows in @var{A} and @var{B} is the length of @var{d},
  9244. the number of columns in @var{A} is the length of @var{x}, and
  9245. the number of columns in @var{B} is the length of @var{y}.
  9246. @item @code{dgglse}
  9247. @item @code{zgglse}
  9248. The input is of the form @code{((@var{A},@var{c}),(@var{B},@var{d}))}
  9249. where @var{A} and @var{B} are matrices and @var{c} and @var{d} are
  9250. vectors. The output is a vector @var{x} to minimize the magnitude of
  9251. @code{@var{A}@var{x} - @var{c}} subject to the constraint that
  9252. @code{@var{B}@var{x} = @var{d}}. The dimensions have to be consistent,
  9253. which means @var{A} has @var{m} rows, @var{c} has length @var{m},
  9254. @var{B} has @var{p} rows, @var{d} has length @var{p}, both @var{A} and
  9255. @var{B} have @var{n} columns, and the output @var{x} has length
  9256. @var{n}. It is also a requirement that @code{@var{p} <= @var{n} <=
  9257. @var{m} + @var{p}}.
  9258. @item @code{dsyevr}
  9259. This function takes a symmetric real matrix and returns a pair
  9260. @code{(@var{e},@var{v})} where @var{e} is a list of eigenvectors and
  9261. @var{v} is a list of eigenvalues. Both contain only real numbers.
  9262. This function is fast and accurate but not as storage efficient as
  9263. possible. If there is insufficient memory, it automatically invokes
  9264. @code{dspev}.
  9265. @item @code{dspev}
  9266. This function takes a symmetric real matrix and returns a pair
  9267. @code{(@var{e},@var{v})} where @var{e} is a list of eigenvectors and
  9268. @var{v} is a list of eigenvalues. Both contain only real numbers. It
  9269. uses roughly half the memory of @code{dsyevr} but is not as fast or
  9270. accurate.
  9271. @item @code{zheevr}
  9272. This function takes a complex Hermitian matrix and returns a pair
  9273. @cindex Hermitian matrix
  9274. @code{(@var{e},@var{v})} where @var{e} is a list of eigenvectors and
  9275. @var{v} is a list of eigenvalues. The eigenvectors are complex but the
  9276. eigenvalues are real.
  9277. @itemize @bullet
  9278. @item
  9279. A Hermitian matrix has @var{Aij} equal to the complex conjugate of
  9280. @var{Aji}.
  9281. @item
  9282. Although not exactly symmetric, a Hermitian matrix may nevertheless
  9283. be given in either upper or lower triangular form.
  9284. @item
  9285. This function is faster but less storage efficient than @code{zhpev},
  9286. and calls it automatically if it runs out of memory.
  9287. @end itemize
  9288. @item @code{zhpev}
  9289. This function has the same inputs and approximate outputs as
  9290. @code{zheevr} but is slower and more memory efficient because it uses
  9291. only packed matrices.
  9292. @end table
  9293. @node lapack exceptions, Additional lapack notes, lapack calling conventions, lapack
  9294. @subsection @code{lapack} exceptions
  9295. @itemize @bullet
  9296. @item
  9297. Any of these functions can return a message of
  9298. @example
  9299. <'memory overflow'>
  9300. @end example
  9301. if it runs out of memory.
  9302. @item
  9303. If the input parameters don't meet the
  9304. specification, they can also return
  9305. @cindex bad lapack specification
  9306. @example
  9307. <'bad lapack specification'>
  9308. @end example
  9309. @item
  9310. Any unexpected behavior from the @code{LAPACK} Fortran functions or
  9311. irregular status returned by them is reported by the message
  9312. @cindex lapack error
  9313. @example
  9314. <'lapack error'>
  9315. @end example
  9316. @noindent
  9317. Getting to the bottom of it may require some debugging
  9318. of the @code{avram} source code in the file @file{lapack.c}.
  9319. @end itemize
  9320. @node Additional lapack notes, , lapack exceptions, lapack
  9321. @subsection Additional @code{lapack} notes
  9322. The functions @code{dgesdd} and @code{zgesdd} are an effective
  9323. dimensionality reduction technique for a large database of time
  9324. @cindex dimensionality reduction
  9325. series. A set of basis vectors can be computed once for the database,
  9326. and then any time series in the database can be expressed as a linear
  9327. combination thereof. To the extent that the data embody any redundant
  9328. information, an approximate reconstruction of an individual series
  9329. from the database will require fewer coefficients (maybe far fewer) in
  9330. terms of the basis than original length of the series.
  9331. The library functions @code{dgelsd} and @code{zgelsd} are good for
  9332. @cindex least squares
  9333. finding least squares fits to empirical data. If the matrix parameter
  9334. @var{a} is interpreted as a list of inputs and the vector parameter
  9335. @var{b} as the list of corresponding output data from some unknown
  9336. linear function of @var{n} variables @var{f}, then @var{x} is the list
  9337. of coefficients whereby @var{f} achieves the optimum fit to the data
  9338. in the least squares sense.
  9339. These functions solve a special case of the problem solved by
  9340. @cindex generalized least squares
  9341. @cindex least squares
  9342. @code{dggglm} and @code{zggglm} where the parameter @var{B} is the
  9343. identity matrix. For the latter functions, the output vector @var{y}
  9344. can be interpreted as a measure of the error, and @var{B} can be
  9345. chosen to express unequal costs for errors at different points in
  9346. the fitted function.
  9347. Cholesky decompositions obtained by @code{dpptrf} and @code{zpptrf}
  9348. @cindex Cholesky decomposition
  9349. are useful for generating correlated random numbers. A population of
  9350. vectors of uncorrelated standard normally distributed random numbers
  9351. can be made to exhibit any correlations to order by multiplying all of
  9352. @cindex correlation
  9353. the vectors by the lower Cholesky factor of the desired covariance
  9354. @cindex covariance matrix
  9355. matrix.
  9356. @node math, mtwist, lapack, External Libraries
  9357. @section @code{math}
  9358. The @code{math} library exports functions that operate on IEEE double
  9359. precision floating point numbers using the host system's C
  9360. library. The numbers are represented natively as contiguous blocks of
  9361. 8 bytes each, and on the virtual side as lists of eight character
  9362. representations. (More explanation is given in @ref{Type
  9363. Conversions}.) These functions take the form
  9364. @example
  9365. library('math',f)
  9366. @end example
  9367. @noindent
  9368. where @code{f} is a character string identifying the function in most
  9369. cases by its standard name in the C library.
  9370. @menu
  9371. * math library operators::
  9372. * math library predicates::
  9373. * math library conversion functions::
  9374. * math library exceptions::
  9375. * Additional math library notes::
  9376. @end menu
  9377. @node math library operators, math library predicates, math, math
  9378. @subsection @code{math} library operators
  9379. The unary operators take a single real number to a real result. They
  9380. @cindex trigonometric functions
  9381. include
  9382. @example
  9383. ceil floor round trunc
  9384. sin cos tan sinh cosh tanh
  9385. asin acos atan asinh acosh atanh
  9386. exp log sqrt cbrt expm1 log1p fabs
  9387. @end example
  9388. The binary operators take a pair of real numbers @code{(@var{x},@var{y})} to
  9389. a single real number output. They include
  9390. @example
  9391. pow hypot atan2 remainder bus vid add sub mul div
  9392. @end example
  9393. @noindent
  9394. where the last four correspond to the C language operators @code{+},
  9395. @code{-}, @code{*}, and @code{/}. The functions named @code{bus} and
  9396. @code{vid} are like the @code{sub} and @code{div} functions,
  9397. respectively, with the order of the operands reversed, as explained in
  9398. @ref{complex}.
  9399. The meanings of these operators are documented in the GNU @code{libc} reference
  9400. manual or other C language references. They follow IEEE standards including
  9401. proper handling of @code{nan} and infinity.
  9402. @node math library predicates, math library conversion functions, math library operators, math
  9403. @subsection @code{math} library predicates
  9404. There is one binary predicate, @code{islessequal}, and several unary
  9405. @cindex predicates
  9406. predicates, @code{isinfinite}, @code{isnan}, @code{isnormal}, @code{isubnormal}
  9407. and @code{iszero}.
  9408. The predicate @code{islessequal} takes a pair of floating point
  9409. numbers @code{(@var{x},@var{y})} as an argument, and returns
  9410. @code{nil} for a false result and @code{(nil,nil)} for a true result.
  9411. The unary predicates have the obvious interpretations as
  9412. classification functions, and should probably be used in preference to
  9413. comparison with constants in case the representations aren't unique.
  9414. @node math library conversion functions, math library exceptions, math library predicates, math
  9415. @subsection @code{math} library conversion functions
  9416. The conversion function @code{strtod} takes a string representing a
  9417. @cindex strtod
  9418. floating point number in C format to its representation. This function
  9419. is the primary means of creating or initializing floating point
  9420. numbers in virtual code. A value of floating point 0.0 is returned if
  9421. the string is not valid, but no exception is raised.
  9422. The conversion @code{asprintf} is similar to the one by that name in
  9423. @cindex asprintf
  9424. C, but requires a pair @code{(@var{f},@var{x})} as an argument. The
  9425. left side @var{f} is a character string containing a C style format
  9426. conversion for exactly one double precision floating point number,
  9427. such as @code{'%0.4e'}, and the parameter @var{x} is a floating point
  9428. number. The result returned will be a character string expressing the
  9429. number in the specified format.
  9430. @node math library exceptions, Additional math library notes, math library conversion functions, math
  9431. @subsection @code{math} library exceptions
  9432. The most likely cause of an exception is an attempt to apply a
  9433. @code{math} library function to @code{nil} or to an argument that
  9434. doesn't represent a floating point number. In these cases, an error
  9435. @cindex missing value
  9436. @cindex invalid value
  9437. message of @code{<'missing value'>} or @code{<'invalid value'>} will
  9438. be the result.
  9439. An error message of @code{<'invalid asprintf() specifier'>} is
  9440. @cindex invalid asprintf specifier
  9441. reported by the @code{asprintf} function if the format specifier
  9442. @cindex asprintf
  9443. pertains to a string, such as @code{'%s'}. This error is specifically
  9444. trapped because the alternative would be a segmentation
  9445. @cindex segmentation fault
  9446. fault. Otherwise, invalid format specifiers are not detected or
  9447. reported.
  9448. Error messages of @code{<'invalid text format'>} can be generated
  9449. @cindex invalid text format
  9450. by conversion functions if any parameters that are meant to be
  9451. character string representations are something else.
  9452. There is always a chance of a @code{<'memory overflow'>} error if
  9453. there is insufficient memory to allocate a result.
  9454. @node Additional math library notes, , math library exceptions, math
  9455. @subsection Additional @code{math} library notes
  9456. Floating point exceptions such as division by zero are not
  9457. specifically reported as exceptions, but invalid computations can be
  9458. @cindex nan
  9459. detected by the propagation of @code{nan} into the result, following
  9460. standard conventions.
  9461. The C function @code{feclearexcept (FE_ALL_EXCEPT)} is called before
  9462. @cindex feclearexcept
  9463. every floating point operation so that no lingering exception flags
  9464. can affect it.
  9465. There is no library predicate for exact comparison of floating point
  9466. numbers, but none is required because the virtual machine's
  9467. @code{compare} combinator will work on their representations as it
  9468. @cindex compare combinator
  9469. will on any other data. The usual caveats apply with regard to
  9470. comparing floating point numbers in the presence of roundoff error.
  9471. @node mtwist, minpack, math, External Libraries
  9472. @section @code{mtwist}
  9473. The @code{mtwist} library interfaces to a random number generator
  9474. @cindex random numbers
  9475. based on the Mersenne Twistor algorithm. The algorithm has good
  9476. properties but is not meant to be cryptographically secure. The
  9477. library functions are of the form
  9478. @example
  9479. library('mtwist',f)
  9480. @end example
  9481. @noindent
  9482. where @code{f} is one of the followng character strings.
  9483. @example
  9484. bern u_cont u_disc u_path u_enum w_disc w_enum
  9485. @end example
  9486. Formally they are not mathematical functions because their results
  9487. depend on a pseudo-random number that is not uniquely determined by
  9488. their arguments. The numbers are generated deterministically in a
  9489. sequence starting from a seed derived from the system clock at the
  9490. time @code{avram} is launched, and each call uses the next number
  9491. in the sequence. In so doing, it simulates a random draw from a
  9492. uniformly distributed population.
  9493. @menu
  9494. * mtwist calling conventions::
  9495. * mtwist exceptions::
  9496. * Additional mtwist notes::
  9497. @end menu
  9498. @node mtwist calling conventions, mtwist exceptions, mtwist, mtwist
  9499. @subsection @code{mtwist} calling conventions
  9500. All of the functions in this library simulate a random draw from a
  9501. distribution. There is a choice of distribution statistics depending
  9502. on the function used.
  9503. @table @asis
  9504. @item @code{bern}
  9505. takes a floating point number @var{p} between 0 and 1, encoded as in
  9506. @ref{math}, and returns a boolean value, either @code{(nil,nil)} for
  9507. true or @code{nil} for false. A true value is returned only if a
  9508. random draw from a uniform distribution ranging from 0 to 1 is less
  9509. than @var{p}. This function therefore simulates a draw from a
  9510. Bernoulli distribution. A @code{nil} value of @var{p} is treated as
  9511. 1/2.
  9512. @item @code{u_cont}
  9513. takes a floating point number @var{x} as an
  9514. argument, and returns a random draw from a continuous uniform
  9515. distribution ranging from 0 to @var{x}. A @code{nil} value of @var{x}
  9516. is treated as unity.
  9517. @item @code{u_disc}
  9518. simulates a draw from a uniform discrete distribution whose domain
  9519. is the set of natural numbers from 0 to @var{n} - 1. The number @var{n}
  9520. is given as a parameter to this function, and the retuned value
  9521. is the draw.
  9522. @itemize @bullet
  9523. @item
  9524. The returned value will have at most 64 bits regardless of @var{n}.
  9525. @item
  9526. Natural numbers are encoded as described in
  9527. @ref{Representation of Numeric and Textual Data}.
  9528. @item
  9529. If a value of 0 is passed for @var{n}, the full 64 bit range is
  9530. used.
  9531. @end itemize
  9532. @item @code{u_path}
  9533. takes a pair of natural numbers @code{(@var{n},@var{m})} and returns a
  9534. randomly chosen tree (@ref{Raw Material}) with 1 leaf and @var{n}
  9535. non-leaves each having either a left or a right descendent but not
  9536. both. The number @var{m} constrains the result to fall within the
  9537. first @var{m} - 1 trees of this form enumerated by exhausting all
  9538. possibilities at lower levels before admitting a right descendent at a
  9539. higher level. Within these criteria, all possible results are equally
  9540. probable. Both numbers are masked to 64 bits, but if @var{m} is zero,
  9541. it is treated as 2^@var{n}.
  9542. @item @code{u_enum}
  9543. simulates a random draw from a uniform discrete distribution whose
  9544. domain is enumerated. The argument to the function is a non-empty list,
  9545. and the result is an item selected from the list, with all choices
  9546. being equally probable.
  9547. @item @code{w_disc}
  9548. simulates a random draw from a non-uniform, or ``weighted'' discrete
  9549. distribution whose domain is a set of consecutive natural numbers
  9550. starting from zero. The argument to the function is a list giving the
  9551. probability of each outcome starting from zero as a floating point
  9552. number. Probabilities must be non-negative but needn't be normalized.
  9553. @item @code{w_enum}
  9554. simulates a random draw from a non-uniform, or ``weighted'' discrete
  9555. distribution with an arbitrary domain enumerated in the argument. The
  9556. argument is a list of pairs @code{<(@var{x},@var{p})..>}, where
  9557. @var{x} is a possible outcome and @var{p} is its probability. The
  9558. result returned is one of the values of @var{x} from the input list
  9559. chosen at random according to the associated
  9560. probability. Probabilities must be non-negative but needn't be
  9561. normalized.
  9562. @end table
  9563. @node mtwist exceptions, Additional mtwist notes, mtwist calling conventions, mtwist
  9564. @subsection @code{mtwist} exceptions
  9565. @itemize @bullet
  9566. @item
  9567. @code{<'memory overflow'>} can be returned if there is insufficient
  9568. memory to allocate a result.
  9569. @item
  9570. Messages of @code{<'missing value'>} and @code{<'invalid value'>} can
  9571. be returned if any floating point argument is @code{nil} or is not a
  9572. valid floating point number, unless there is a designated default
  9573. interpretation for @code{nil} as in @code{bern} and @code{u_cont}.
  9574. @item
  9575. A message of @code{<'bad mtwist specification'>} is returned if an
  9576. argument to the @code{bern} function is not in the range of 0 to 1, or
  9577. if any probability passed to the @code{w_}* functions is negative.
  9578. @item
  9579. A message of @code{<'draw from empty list'>} is returned if
  9580. an argument to the *@code{_enum} functions is @code{nil}
  9581. or if an argument to @code{w_enum} contains @code{nil}.
  9582. @end itemize
  9583. @node Additional mtwist notes, , mtwist exceptions, mtwist
  9584. @subsection Additional @code{mtwist} notes
  9585. Although the @code{mtwist} library is ``external'', it requires no
  9586. special configuration on the host because the uniform variate
  9587. generator in the form developed by its original authors is short and
  9588. elegant enough to be packaged easily within the @code{avram}
  9589. distribution. All further embellishments are home grown despite the
  9590. advice at the end of @ref{Implementing new library functions}.
  9591. The @code{u_path} function is intended to allow sampling from a large
  9592. population in logarithmic time when it is stored in a balanced tree. A
  9593. left-heavy tree should be constructed initially with the data items
  9594. all at the same level. Thereafter, a result returned by @code{u_path}
  9595. with the appropriate dimensions can be used as an index into the tree
  9596. for fast retrieval by the virtual machine's @code{field} combinator
  9597. (@ref{Field}).
  9598. The last three functions, @code{u_enum}, @code{w_disc}, and
  9599. @code{w_enum} use an inversion method with a binary search. The first
  9600. draw from a given list will take a time asymptotically proportional to
  9601. the length of the list, but subsequent draws from the same list are
  9602. considerably faster due to a persistent cache maintained transparently
  9603. by @code{avram}. For lists whose length is up to 2^16, the time
  9604. required for a subsequent draw consists mainly of constant overhead
  9605. with a small logarithmic component in the length of the list. For
  9606. longer lists, the time ramps up linearly by a small factor.
  9607. Information allowing fast draws from up to sixteen lists can be cached
  9608. simultaneously. If an application uses more than sixteen, the cached
  9609. data are replaced in first-in first-out order. The size of the cache
  9610. and the maximum list length for logarithmic time access can be
  9611. adjusted easily by redefining constants in @file{mtwist.c} under the
  9612. @code{avram} source tree, but will require recompilation.
  9613. @node minpack, mpfr, mtwist, External Libraries
  9614. @section @code{minpack}
  9615. The @code{minpack} library contains functions to solve non-linear
  9616. @cindex non-linear optimization
  9617. optimization and least squares problems. The functions can be
  9618. @cindex least squares
  9619. expressed as
  9620. @example
  9621. library('minpack',f)
  9622. @end example
  9623. @noindent
  9624. where @code{f} can be one of @code{'hybrd'}, @code{'hybrj'},
  9625. @code{'lmder'}, @code{'lmdif'}, or @code{'lmstr'}, following the names
  9626. of the underlying Fortran subroutines.
  9627. @menu
  9628. * minpack calling conventions::
  9629. * minpack exceptions::
  9630. * Additional minpack notes::
  9631. @end menu
  9632. @node minpack calling conventions, minpack exceptions, minpack, minpack
  9633. @subsection @code{minpack} calling conventions
  9634. The @code{minpack} library solves a similar problem to that of the
  9635. @code{kinsol} library (@ref{kinsol}), and the two libraries have
  9636. identical calling conventions at the level of the virtual code
  9637. interface.
  9638. The @code{hybrd} and @code{lmdif} functions take input arguments of
  9639. the form @code{(@var{f},(@var{i},@var{o}))}, whereas @code{hybrj},
  9640. @code{lmder}, and @code{lmstr} take arguments of the form
  9641. @code{((@var{f},@var{j}),(@var{i},@var{o}))}. The interpretations of
  9642. these parameters are explained in @ref{kinsol input parameters}.
  9643. For the @code{lmstr} function, the Jacobian function @var{j} takes
  9644. @cindex Jacobian
  9645. an argument @code{(@var{m},@var{v})} and returns only the @var{m}-th
  9646. row of the Jacobian matrix. For @code{lmder} and @code{hybrj}, the
  9647. Jacobian function takes only an input vector @var{v} and returns the
  9648. whole matrix. These specifications are also explained further in
  9649. relation to the @code{kinsol} library.
  9650. The output from any minpack function is a vector @var{v} satisfying
  9651. @code{@var{f}(@var{v}) = @var{o}} to the best possible tolerance if a
  9652. @cindex tolerance
  9653. solution is found. A range of tolerances over ten orders of magnitude
  9654. is sampled starting from @code{1e-15}. If no solution is found, an
  9655. empty list is returned.
  9656. @node minpack exceptions, Additional minpack notes, minpack calling conventions, minpack
  9657. @subsection @code{minpack} exceptions
  9658. @itemize @bullet
  9659. @item
  9660. A message of @code{<'memory overflow'>} is possible any time
  9661. @code{minpack} runs out of memory.
  9662. @item
  9663. A message of @code{<'bad minpack specification'>} will be returned
  9664. @cindex bad minpack specification
  9665. if an input argument recognizably violates the required specification.
  9666. @item
  9667. The @code{<'minpack error'>} message is returned in the event of any
  9668. @cindex minpack error
  9669. unexpected behavior or irregular status from the API.
  9670. @item
  9671. Any error messages reported by the system function @var{f} or the
  9672. Jacobian function @var{j} are propagated to the result.
  9673. @end itemize
  9674. @node Additional minpack notes, , minpack exceptions, minpack
  9675. @subsection Additional @code{minpack} notes
  9676. The @code{lm}* functions are better suited to problems in which the
  9677. system function @var{f} has more outputs than inputs, and the
  9678. @code{hybr}* functions are better suited to the alternative. If either
  9679. is called when the other is more appropriate, the job is handed off to
  9680. the other automatically.
  9681. The @code{lmstr} function is more memory efficient than the others
  9682. because it doesn't compute the whole Jacobian matrix at once. Any
  9683. @cindex Jacobian
  9684. of the @code{lm}* functions is more memory efficient than
  9685. the @code{kinsol} equivalent when the output list is sufficiently
  9686. longer than the input list.
  9687. Unlike @code{kinsol}, there is no provision in @code{minpack} for
  9688. @cindex constrained optimization
  9689. constrained optimization.
  9690. The @code{minpack} documentation doesn't state whether it's
  9691. @cindex re-entrancy
  9692. re-entrant, but the odds are against it unless it uses no storage
  9693. outside the user provided work areas. If it isn't re-entrant,
  9694. anomalous effects could occur when a virtual code function being
  9695. optimized calls another @code{minpack} function. A workaround would
  9696. be to use an equivalent @code{kinsol} function, which is re-entrant by
  9697. design.
  9698. The @code{avram} configuration script searches for a C header file
  9699. @cindex header file
  9700. @file{minpack.h} on the host system in order to build an interface to
  9701. this library. This file is specific to the Debian @code{minpack-dev}
  9702. package and is not part of the upstream Fortran source. Configuring
  9703. @code{avram} with an interface to the @code{minpack} library on a
  9704. @cindex Debian
  9705. non-Debian system may require the administrator to retrieve the header
  9706. file manually from the Debian archive and place it under
  9707. @file{/usr/include} before running the configuration script (in
  9708. addition to installing the @code{minpack} library itself, of course).
  9709. @node mpfr, lpsolve, minpack, External Libraries
  9710. @section @code{mpfr}
  9711. The @code{mpfr} library provides a rich assortment of floating point
  9712. operations on arbitrary precision numbers
  9713. (@url{http://www.mpfr.org}). These numbers are represented in a format
  9714. that is not binary compatible with the standard IEEE floating point
  9715. number format used by other libraries, but they offer superior
  9716. numerical stability suitable for many ill conditioned problems.
  9717. The virtual code interface to the @code{mpfr} library follows the
  9718. native API to the extent of using the same names for most operations,
  9719. but excludes features pertaining to i/o, mutable storage, and memory
  9720. management.
  9721. The @code{mpfr} library functions are invoked by an expression of the
  9722. form
  9723. @example
  9724. library('mpfr',f)
  9725. @end example
  9726. @noindent
  9727. Aside from a few exceptions as noted, @code{f} is a character string
  9728. derived from the name of the related function from the @code{mpfr} C
  9729. library as documented at the above address, but without the
  9730. @code{mpfr_} prefix.
  9731. The full complement of available functions is documented in the
  9732. remainder of this section.
  9733. @itemize @bullet
  9734. @item
  9735. References to natural numbers pertain to the list representation
  9736. described in @ref{Representation of Numeric and Textual Data}.
  9737. @item
  9738. All functions that perform rounding use a mode of @code{GMP_RNDN} for
  9739. @cindex rounding
  9740. rounding to nearest, which is not explicitly specified on the virtual
  9741. side.
  9742. @end itemize
  9743. @menu
  9744. * mpfr binary operators::
  9745. * mpfr unary operators::
  9746. * mpfr binary operators with a natural operand::
  9747. * mpfr binary predicates::
  9748. * mpfr unary predicates::
  9749. * mpfr constants::
  9750. * mpfr functions with miscellaneous calling conventions::
  9751. * mpfr conversion functions::
  9752. * mpfr exceptions::
  9753. * Additional mpfr notes::
  9754. @end menu
  9755. @node mpfr binary operators, mpfr unary operators, mpfr, mpfr
  9756. @subsection @code{mpfr} binary operators
  9757. Functions with these names take a pair of @code{mpfr} numbers
  9758. @code{(@var{x},@var{y})} and return an @code{mpfr} number as a result.
  9759. @itemize @bullet
  9760. @item @code{add}
  9761. @item @code{sub}
  9762. @item @code{mul}
  9763. @item @code{div}
  9764. @item @code{pow}
  9765. @item @code{atan2}
  9766. @item @code{hypot}
  9767. @item @code{min}
  9768. @item @code{max}
  9769. @item @code{vid}
  9770. @item @code{bus}
  9771. @end itemize
  9772. Their semantics are similar to those listed in the @code{mpfr}
  9773. documentation, with some minor qualifications.
  9774. @itemize @bullet
  9775. @item
  9776. Unlike the native API, there is no third argument to which the result
  9777. is assigned, because the result is the returned value.
  9778. @item
  9779. The precision of the result is the greater of the two precisions of
  9780. the input numbers @var{x} and @var{y}.
  9781. @item
  9782. The @code{vid} and @code{bus} functions are added features of the
  9783. virtual code interface, corresponding to division and subtraction with
  9784. the order of the operands reversed, as explained in @ref{complex}.
  9785. @end itemize
  9786. Mathematically it might make more sense for the precision of the
  9787. @cindex precision
  9788. result to be the lesser of the two input precisions, but this way is
  9789. more convenient for virtual code programs that perform binary
  9790. operations on their input with hard coded constants, because it makes
  9791. one size fit all.
  9792. @node mpfr unary operators, mpfr binary operators with a natural operand, mpfr binary operators, mpfr
  9793. @subsection @code{mpfr} unary operators
  9794. Functions with these names take a single @code{mpfr} number as an
  9795. argument and return a single @code{mpfr} number as a result.
  9796. @cindex gamma functions
  9797. @example
  9798. sqr sqrt cbrt neg abs log
  9799. log2 log10 exp exp2 exp10 cos
  9800. sin tan acos asin atan cosh
  9801. sinh tanh acosh asinh atanh lngamma
  9802. expm1 eint gamma erf log1p nextbelow
  9803. ceil floor round trunc frac nextabove
  9804. erfc
  9805. @end example
  9806. The semantics of these functions are similar to those of their
  9807. counterparts in the native API, with these provisions.
  9808. @itemize @bullet
  9809. @item
  9810. The precision of the result is the precision of the argument.
  9811. @item
  9812. There is no second argument for assigning the result.
  9813. @item
  9814. The @code{nextabove} and @code{nextbelow} functions do not modify
  9815. their arguments in place, but return a freshly allocated result
  9816. like all other functions.
  9817. @end itemize
  9818. @node mpfr binary operators with a natural operand, mpfr binary predicates, mpfr unary operators, mpfr
  9819. @subsection @code{mpfr} binary operators with a natural operand
  9820. Functions with these names take an argument of the form
  9821. @code{(@var{x},@var{n})}, where @var{x} is an @code{mpfr} number
  9822. and @var{n} is a natural number.
  9823. @itemize @bullet
  9824. @item @code{root}
  9825. @item @code{pow_ui}
  9826. @item @code{mul_2ui}
  9827. @item @code{div_2ui}
  9828. @item @code{grow}
  9829. @item @code{shrink}
  9830. @end itemize
  9831. The last two are specific to the virtual code interface, having no
  9832. counterpart in the native API of the @code{mpfr} library. The
  9833. @code{grow} function returns a copy of @var{x} with its precision
  9834. increased by @var{n} bits, and the @code{shrink} function returns a
  9835. copy of @var{x} with its precision reduced by @var{n} bits.
  9836. @itemize @bullet
  9837. @item
  9838. The precisions are silently capped at the maximum or floored at the
  9839. @cindex precision
  9840. minimum allowable precisions if necessary.
  9841. @item
  9842. Increasing the precision by the @code{grow} function does not directly
  9843. cause a more accurate result to be computed, but only pads an existing
  9844. number with zeros.
  9845. @item
  9846. Decreasing the precision by the @code{shrink} function does not prevent
  9847. valid bits from being discarded.
  9848. @end itemize
  9849. The appropriate way to use @code{grow} is to grow the precision of an
  9850. operand before applying an operator to it, which will cause the result
  9851. to be computed to the full precision. This capability is suitable for
  9852. algorithms that iterate over increasing precisions until a stopping
  9853. criterion is met.
  9854. @node mpfr binary predicates, mpfr unary predicates, mpfr binary operators with a natural operand, mpfr
  9855. @subsection @code{mpfr} binary predicates
  9856. These predicates take a pair of @code{mpfr} numbers
  9857. @code{(@var{x},@var{y})} as arguments and perform a logical operation.
  9858. If the result is true, they return @code{(nil,nil)}, and if it's
  9859. false, they return @code{nil}.
  9860. @itemize @bullet
  9861. @item @code{equal_p}
  9862. @item @code{unequal_abs}
  9863. @item @code{greater_p}
  9864. @item @code{greaterequal_p}
  9865. @item @code{less_p}
  9866. @item @code{lessequal_p}
  9867. @item @code{lessgreater_p}
  9868. @end itemize
  9869. The name of the function @code{unequal_abs}, for comparing absolute
  9870. values, has been changed from @code{mpfr_cmpabs} to avoid confusion
  9871. with the virtual machine's @code{compare} combinator. The
  9872. @code{compare} combinator returns a @code{(nil,nil)} result (i.e.,
  9873. true) if the
  9874. @cindex compare combinator
  9875. operands are equal and a @code{nil} result if they're unequal,
  9876. opposite from @code{unequal_abs}.
  9877. @node mpfr unary predicates, mpfr constants, mpfr binary predicates, mpfr
  9878. @subsection @code{mpfr} unary predicates
  9879. Each of these predicates takes an @code{mpfr} number as an argument
  9880. and performs a logical operation. If the result is true, it returns
  9881. @code{(nil,nil)}, and otherwise it returns @code{nil}.
  9882. @itemize @bullet
  9883. @item @code{nan_p}
  9884. @item @code{inf_p}
  9885. @item @code{number_p}
  9886. @item @code{zero_p}
  9887. @item @code{integer_p}
  9888. @end itemize
  9889. @node mpfr constants, mpfr functions with miscellaneous calling conventions, mpfr unary predicates, mpfr
  9890. @subsection @code{mpfr} constants
  9891. Each of these functions takes a natural number as an argument
  9892. specifying a precision, and returns a mathematical constant evaluated
  9893. to that precision.
  9894. @itemize @bullet
  9895. @item @code{const_log2}
  9896. @item @code{pi}
  9897. @item @code{const_catalan}
  9898. @item @code{inf}
  9899. @item @code{ninf}
  9900. @item @code{nan}
  9901. @end itemize
  9902. The name of the constant @code{pi} has been shortened from
  9903. @code{mpfr_const_pi}. The functions @code{inf} and @code{ninf} return
  9904. infinity and negative infinity, respectively.
  9905. The encoding of @code{nan}, used to represent the results of undefined
  9906. @cindex nan
  9907. computations such as division by zero, is not unique even for a fixed
  9908. precision. Applications should test for undefined results using
  9909. @code{nan_p} rather than by comparing a result to a hard coded
  9910. @code{nan} (@ref{mpfr unary predicates}).
  9911. @node mpfr functions with miscellaneous calling conventions, mpfr conversion functions, mpfr constants, mpfr
  9912. @subsection @code{mpfr} functions with miscellaneous calling conventions
  9913. Some functions listed below don't conform to any of the previously
  9914. mentioned calling conventions.
  9915. @table @asis
  9916. @item @code{eq}
  9917. This is a ternary operator taking a triple
  9918. @code{(@var{prec},(@var{x},@var{y}))}, where @var{prec} is a natural
  9919. number and @var{x} and @var{y} are @code{mpfr} numbers. It returns a
  9920. result of @code{(nil,nil)} (i.e., true) if the numbers agree up to the
  9921. specified precision measured in bits, and returns @code{nil}
  9922. otherwise.@footnote{a potentially useful tool for algorithms concerned
  9923. with numerical approximations despite its inexplicable malignment in
  9924. the @code{mpfr} documentation}
  9925. @item @code{urandomb}
  9926. This function takes a natural number specifying a precision and
  9927. @cindex random numbers
  9928. returns a uniformly distributed pseudo-random number of that precision
  9929. between 0 and 1.
  9930. @item @code{prec}
  9931. This function takes an @code{mpfr} number and returns a natural number
  9932. as a result, which is the precision of the argument in bits.
  9933. @item @code{sin_cos}
  9934. This function takes an @code{mpfr} number @var{z} as an argument and
  9935. returns a pair of @code{mpfr} numbers @code{(@var{x},@var{y})} as a
  9936. result, where @var{x} is the sine of @var{z} and @var{y} is the cosine. The
  9937. precisions of the results are the same as the precision of the
  9938. argument.
  9939. @end table
  9940. @node mpfr conversion functions, mpfr exceptions, mpfr functions with miscellaneous calling conventions, mpfr
  9941. @subsection @code{mpfr} conversion functions
  9942. The functions described in this section convert between @code{mpfr}
  9943. numbers and character strings, naturals, or standard IEEE floating
  9944. point format (in their list representations). Where these functions
  9945. have similar or equivalent counterparts in the @code{mpfr} library's
  9946. native API, the names have been changed for mnemonic reasons.
  9947. @table @asis
  9948. @item @code{dbl2mp}
  9949. The input is a standard floating point number as in @ref{math}. The
  9950. result is an @code{mpfr} number equal to the input with a
  9951. fixed precision, currently set to 160 bits.
  9952. @item @code{mp2dbl}
  9953. The input is an @code{mpfr} number, and the output is the best
  9954. possible approximation to it by a standard a double precision
  9955. number.
  9956. @item @code{str2mp}
  9957. The input is a pair @code{(@var{prec},@var{s})}, where @var{prec} is a
  9958. natural number specifying the precision, and @var{s} is a string
  9959. expressing a floating point number in C format. The output is an
  9960. @code{mpfr} number with the specified precision.
  9961. @item @code{mp2str}
  9962. The input is an @code{mpfr} number, and the output is a character
  9963. string expressing the number in exponential decimal notation.
  9964. Sufficiently many decimal digits are included in the string to express
  9965. the full precision.
  9966. @item @code{nat2mp}
  9967. The input is a natural number represented as described in
  9968. @ref{Representation of Numeric and Textual Data},
  9969. and the output is an @code{mpfr} number of sufficient precision to
  9970. express the natural number exactly.
  9971. @end table
  9972. The @code{mp2str} function enhances the native @code{mpfr_get_str}
  9973. function by properly formatting the output string rather than only
  9974. listing the digits of the mantissa.
  9975. The @code{nat2mp} function does not rely on the @code{mpfr} native
  9976. integer conversion functions, so natural numbers with any number of
  9977. bits up to @code{MP_PREC_MAX} can be used losslessly. There is
  9978. currently no conversion in the other direction.
  9979. @node mpfr exceptions, Additional mpfr notes, mpfr conversion functions, mpfr
  9980. @subsection @code{mpfr} exceptions
  9981. @itemize @bullet
  9982. @item
  9983. A message of @code{<'memory overflow'>} is possible any time
  9984. @code{mpfr} runs out of memory.
  9985. @item
  9986. A message of @code{<'bad mpfr specification'>} will be returned
  9987. @cindex bad mpfr specification
  9988. if an input argument recognizably violates the required specification.
  9989. @item
  9990. The @code{<'mpfr error'>} message is returned in the event of any
  9991. @cindex mpfr error
  9992. unexpected behavior or irregular status from the API.
  9993. @item
  9994. The message of @code{<'mpfr overflow'>} can be cause by the
  9995. @code{nat2mp} function if a natural number has too many bits to be
  9996. represented exactly as an @code{mpfr} number.
  9997. @end itemize
  9998. @node Additional mpfr notes, , mpfr exceptions, mpfr
  9999. @subsection Additional @code{mpfr} notes
  10000. The @code{eq} and @code{urandomb} functions depend not only on the
  10001. @code{mpfr} library but on the @code{gmp} library
  10002. @cindex gmp library
  10003. (@url{http://ftp.gnu.org/gnu/gmp}). It's possible for them to be
  10004. unavailable on a host without @code{gmp} even if the rest of the
  10005. @code{mpfr} library is properly configured.
  10006. The file @code{mpfr.c} in the @code{avram} source tree exports a
  10007. couple of functions that may be of use to C hackers interested in
  10008. further development of @code{avram} with @code{mpfr}. The functions
  10009. @code{avm_mpfr_of_list} and @code{avm_list_of_mpfr} convert between
  10010. the native representation for @code{mpfr} numbers and the caching list
  10011. representation used by @code{avram} (@ref{Type Conversions}). This
  10012. conversion is non-trivial because the numbers are not stored
  10013. contiguously.
  10014. @node lpsolve, rmath, mpfr, External Libraries
  10015. @section @code{lpsolve}
  10016. This library interface exports functions to solve linear programming
  10017. @cindex mixed integer programming
  10018. @cindex linear programming
  10019. and mixed integer programming problems using the @code{lpsolve}
  10020. package documented at
  10021. @url{http://lpsolve.sourceforge.net/5.5/}.
  10022. @noindent
  10023. Of the two linear
  10024. programming solvers currently interfaced with @code{avram}, this one
  10025. is believed to be the more robust.
  10026. @menu
  10027. * lpsolve calling conventions::
  10028. * lpsolve return values::
  10029. * lpsolve errors::
  10030. @end menu
  10031. @node lpsolve calling conventions, lpsolve return values, lpsolve, lpsolve
  10032. @subsection @code{lpsolve} calling conventions
  10033. The library is able to solve linear and mixed integer programming
  10034. problems, depending on which function is selected. The
  10035. @cindex linear programming
  10036. function to call the linear programming solver is of the form
  10037. @itemize @bullet
  10038. @item @code{library('lpsolve','stdform')}
  10039. @end itemize
  10040. @noindent
  10041. @cindex mixed integer programming
  10042. and the mixed integer programming functions are of the form
  10043. @itemize @bullet
  10044. @item @code{library('lpsolve','iform')}
  10045. @item @code{library('lpsolve','bform')}
  10046. @item @code{library('lpsolve','biform')}
  10047. @end itemize
  10048. @noindent
  10049. The argument to the @code{stdform} function represents a triple
  10050. @code{(@var{c},(@var{m},@var{y}))}, which has the same interpretation
  10051. described in @ref{glpk input parameters}. The arguments to the @code{iform},
  10052. @code{bform}, and @code{biform} functions are tuples
  10053. @code{(@var{i},(@var{c},(@var{m},@var{y})))}
  10054. @code{(@var{b},(@var{c},(@var{m},@var{y})))}, and
  10055. @code{((@var{b},@var{i}),(@var{c},(@var{m},@var{y})))}, respectively, where
  10056. @var{c}, @var{m}, and @var{y} are as above, and
  10057. @itemize @bullet
  10058. @item @var{b} is a list of binary variable column indices
  10059. @item @var{i} is a list of integer variable column indices
  10060. @end itemize
  10061. @noindent
  10062. where column indices pertain to the constraint matrix, and are
  10063. numbered from zero. Specifying some or all variables as integers
  10064. directs the solver to seek only solutions in which those variables
  10065. have integer values, and specifying any as binary directs the solver
  10066. to seek only solutions in which those variables have values of zero or
  10067. one. The IEEE floating point representation is used for all variables
  10068. regardless (@ref{math}).
  10069. @node lpsolve return values, lpsolve errors, lpsolve calling conventions, lpsolve
  10070. @subsection @code{lpsolve} return values
  10071. If a feasible and optimal solution is found, a list of values for the variables
  10072. is returned in the form @code{<(@var{i},@var{x})...>}, where @var{i} is a natural
  10073. number and @var{x} is a floating point number giving the value of the @var{i}-th
  10074. variable numbered from zero. Values of @var{x} equal to zero are omitted.
  10075. @node lpsolve errors, , lpsolve return values, lpsolve
  10076. @subsection @code{lpsolve} errors
  10077. If any calling conventions are not followed, an exception is raised and a diagnostic
  10078. message of @code{bad lpsolve problem specification} is reported. If no feasible solution
  10079. can be found, no exception is raised but an empty list is returned.
  10080. @node rmath, umf, lpsolve, External Libraries
  10081. @section @code{rmath}
  10082. A selection of mathematical and statistical functions from the GNU R
  10083. math library has a virtual code interface of the form
  10084. @example
  10085. library('rmath',f)
  10086. @end example
  10087. @noindent
  10088. where @code{f} is a character string derived from the name of a
  10089. function in the C language API described in the manual
  10090. @file{R-exts.pdf}, available at @url{http://www.r-project.org}.
  10091. Every function in the library returns a real result in the form of
  10092. @ref{math}, but functions differ in the argument types. The arguments
  10093. are tuples of real numbers and booleans that also closely follow the
  10094. native API as explained below.
  10095. @menu
  10096. * rmath statistical functions::
  10097. * rmath miscellaneous functions::
  10098. * rmath exceptions::
  10099. @end menu
  10100. @node rmath statistical functions, rmath miscellaneous functions, rmath, rmath
  10101. @subsection @code{rmath} statistical functions
  10102. Functions for evaluating random draws, density, cumulative probability
  10103. and inverse cumulative probability are provided for some of the more
  10104. frequently used probability distributions, which are chi-squared,
  10105. non-central chi-squared, exponential, lognormal, normal, poisson,
  10106. Student's t, and uniform.
  10107. Each distribution is known by an abbreviated name and specified by one
  10108. @cindex distributions
  10109. @cindex probability distributions
  10110. @cindex statistical distributions
  10111. or two real parameters as listed below. Names of distributions in this
  10112. table form the stem of a library function name. The names of the
  10113. parameters such as @var{mu} and @var{sigma} are not explicitly
  10114. mentioned when invoking the functions, but are listed here for
  10115. reference. The precise definitions of the distribution functions and
  10116. interpretations of these parameters can be found in standard texts on
  10117. probability and statistics.
  10118. @example
  10119. chisq @var{df}
  10120. nchisq @var{df}, @var{lambda}
  10121. exp @var{scale}
  10122. lnorm @var{logmean}, @var{logsd}
  10123. norm @var{mu}, @var{sigma}
  10124. pois @var{lambda}
  10125. t @var{n}
  10126. unif @var{a}, @var{b}
  10127. @end example
  10128. The virtual code interface follows a naming convention similar to the
  10129. native API, in that function names beginning with @code{r} represent
  10130. random draws from a distribution, with the argument to the function
  10131. being the parameters specifying the distribution. Functions in this
  10132. first group return a random draw from a distribution described by a
  10133. single real parameter.
  10134. @itemize @bullet
  10135. @item @code{rchisq}
  10136. @item @code{rexp}
  10137. @item @code{rpois}
  10138. @item @code{rt}
  10139. @end itemize
  10140. @noindent
  10141. These next functions return random draws from distributions specified
  10142. by a pair of parameters, @code{(@var{x},@var{y})}.
  10143. @itemize @bullet
  10144. @item @code{rnchisq}
  10145. @item @code{rlnorm}
  10146. @item @code{rnorm}
  10147. @item @code{runif}
  10148. @end itemize
  10149. Functions whose names begin with @code{d} evaluate the probability
  10150. density of a distribution at a given point. They require at least two
  10151. real arguments, the first being the point whose probability density is
  10152. sought, and the remaining ones being the parameters that specify the
  10153. distribution. A boolean operand, which is @code{nil} for false and
  10154. @code{(nil,nil)} for true, requests the logarithm of the density when
  10155. true.
  10156. Functions with names in the following group take a triple with two
  10157. real operands and a boolean, @code{(@var{x},(@var{y},@var{a}))}, and
  10158. return a probabiity density.
  10159. @itemize @bullet
  10160. @item @code{dchisq}
  10161. @item @code{dexp}
  10162. @item @code{dpois}
  10163. @item @code{dt}
  10164. @end itemize
  10165. @noindent
  10166. The next functions pertain to distributions requiring two paramters to
  10167. specify them, so they take a quadruple with three real operands and a
  10168. boolean, @code{(@var{x},(@var{y},(@var{z},@var{a})))}.
  10169. @itemize @bullet
  10170. @item @code{dnchisq}
  10171. @item @code{dlnorm}
  10172. @item @code{dnorm}
  10173. @item @code{dunif}
  10174. @end itemize
  10175. Functions whose names begin with @code{p} or @code{q} obtain
  10176. @cindex cumulative probability
  10177. cumulative probabilities or inverse cumulative probabilities
  10178. respectively for a specified distribution. They require one real
  10179. operand to identify the point whose probability or inverse probability
  10180. is sought, and other real operands to parameterize the distribution,
  10181. as above. There are also two boolean operands. The first is true in
  10182. order to request a probability or inverse probability with respect to
  10183. the lower tail as opposed to the upper, and the other is true to
  10184. indicate that probabilities are to be expressed logarithmically.
  10185. The argument to these functions is a quadruple with two real operands
  10186. and two booleans, @code{(@var{x},(@var{y},(@var{a},@var{b})))}.
  10187. @itemize @bullet
  10188. @item @code{pchisq}, @code{qchisq}
  10189. @item @code{pexp}, @code{qexp}
  10190. @item @code{ppois}, @code{qpois}
  10191. @item @code{pt}, @code{qt}
  10192. @end itemize
  10193. @noindent
  10194. The remaining functions pertain to distributions parameterized by two
  10195. real operands. These take a quintuple with three real operands and two
  10196. booleans, @code{(@var{x},(@var{y},(@var{z},(@var{a},@var{b}))))}.
  10197. @itemize @bullet
  10198. @item @code{pnchisq},
  10199. @code{qnchisq}
  10200. @item @code{plnorm},
  10201. @code{qlnorm}
  10202. @item @code{pnorm},
  10203. @code{qnorm}
  10204. @item @code{punif},
  10205. @code{qunif}
  10206. @end itemize
  10207. @node rmath miscellaneous functions, rmath exceptions, rmath statistical functions, rmath
  10208. @subsection @code{rmath} miscellaneous functions
  10209. Some less frequently used real valued mathematical functions are also
  10210. accessible by the @code{rmath} library interface. The functions with
  10211. @cindex gamma functions
  10212. names in this group take a single real operand.
  10213. @example
  10214. gammafn lgammafn digamma
  10215. trigamma tetragamma pentagamma
  10216. @end example
  10217. @noindent
  10218. The ones in this group take a pair of real operands
  10219. @cindex bessel functions
  10220. @code{(@var{x},@var{y})}.
  10221. @example
  10222. beta lbeta bessel_j bessel_y
  10223. @end example
  10224. @noindent
  10225. Those remaining take a triple of real operands
  10226. @code{(@var{x},(@var{y},@var{z}))}.
  10227. @example
  10228. bessel_i bessel_k
  10229. @end example
  10230. An alternative and better documented selection of Bessel functions is
  10231. provided by the @code{bes} library interface (@ref{bes}).
  10232. @node rmath exceptions, , rmath miscellaneous functions, rmath
  10233. @subsection @code{rmath} exceptions
  10234. The only exceptional condition specific to the @code{rmath} library
  10235. interface is associated with the message @code{<'bad rmath
  10236. specification'>}, which means that a tuple given as an argument
  10237. @cindex bad rmath specification
  10238. has the wrong number or types of operands.
  10239. @node umf, ,rmath, External Libraries
  10240. @section @code{umf}
  10241. Systems of equations described by sparse matrices (i.e., matrices
  10242. @cindex sparse matrices
  10243. containing mostly zeros) arise in certain practical problems. The
  10244. usual array representation in which zeros are explicitly stored would
  10245. be prohibitive for large matrices occurring in many problems of
  10246. interest. A more sophisticated approach is used by the @code{umf}
  10247. library to manage memory efficiently, which is documented at
  10248. @url{http://www.cise.ufl.edu/research/sparse/SuiteSparse/current/SuiteSparse/UMFPACK/Doc/}.
  10249. A virtual code interface to functions for solving sparse systems of
  10250. equations by these methods is afforded by library functions of the form
  10251. @example
  10252. library('umf',f)
  10253. @end example
  10254. @noindent
  10255. where the library function name, @code{f} is a character string
  10256. of the form @code{@var{tt}_@var{m}_@var{rrr}}.
  10257. @itemize @bullet
  10258. @item @var{tt}
  10259. can be either @code{di} for real matrices, or @code{zi} for complex.
  10260. @item @var{m}
  10261. can be one of @code{a}, @code{t}, or @code{c} for solving a system
  10262. given either by a matrix, its transpose, or its conjugate transpose,
  10263. respectively,
  10264. @cindex conjugate transpose
  10265. corresponding to mnemonics @code{A}, @code{Aat} and @code{At} used in
  10266. the C language API.
  10267. @item @var{rrr}
  10268. is either @code{trp} or @code{col}, to indicate a sparse matrix expressed
  10269. either as a list of triples, or in packed column form, as documented below.
  10270. @end itemize
  10271. The complete set of function names for this library interface is as
  10272. follows.
  10273. @example
  10274. di_a_trp di_a_col zi_a_trp zi_a_col
  10275. di_t_trp di_t_col zi_t_trp zi_t_col
  10276. zi_c_trp zi_c_col
  10277. @end example
  10278. @noindent
  10279. Not all combinations are represented, because the conjugate transpose
  10280. is relevant only to complex matrices.
  10281. @menu
  10282. * umf input parameters::
  10283. * umf output::
  10284. * umf exceptions::
  10285. * Additional umf notes::
  10286. @end menu
  10287. @node umf input parameters, umf output, umf, umf
  10288. @subsection @code{umf} input parameters
  10289. For a square matrix @var{A} and a column vector @var{b}, the
  10290. @code{umf} functions find the solution @var{x} to the matrix equation
  10291. @var{M} @var{x} = @var{b}, where @var{M} is either @var{A}, the
  10292. transpose of @var{A}, or its conjugate transpose. As noted above, the
  10293. choice is determined by whether the the function name is of the form
  10294. *@code{_a_}*, *@code{_t_}*, or *@code{_c_}* respectively.
  10295. The argument to any of these functions is a pair
  10296. @code{(@var{A},@var{b})}, where @var{A} represents the matrix
  10297. mentioned above and @var{b} represents the column vector.
  10298. The parameter @var{b} is required to be a list of numbers whose length
  10299. matches the number of rows in the matrix. The numbers are either real
  10300. numbers for the @code{di_}* functions (@ref{math}), or complex
  10301. for the @code{zi_}* functions (@ref{complex}).
  10302. There is a choice of representations for the parameter @var{A},
  10303. depending on whether the function being called is one of the *@code{_trp}
  10304. functions or one of the *@code{_col} functions.
  10305. For the *@code{_trp} functions, @var{A} is represented as a non-empty
  10306. list of triples @code{<((@var{i},@var{j}),@var{v})...>}, where each
  10307. item of the list corresponds to a non-zero entry in the matrix.
  10308. @itemize @bullet
  10309. @item
  10310. The parameters @var{i} and @var{j} are natural numbers as in
  10311. @ref{Representation of Numeric and Textual Data}.
  10312. @item
  10313. The value @var{v} is a real number for the @code{di_}*@code{_trp} functions or a
  10314. complex number for the @code{zi_}*@code{_trp} functions.
  10315. @item
  10316. The presence of a triple ((@var{i},@var{j}),@var{v}) in the list
  10317. signifies that the @var{i},@var{j}-th entry in the matrix @var{A}
  10318. (numbered from zero) has a value of @var{v}.
  10319. @end itemize
  10320. For the *@code{_col} functions, the representation of @var{A} is more
  10321. complicated but has a slight advantage in memory usage. It may also
  10322. have an advantage in speed unless more time is wasted on the virtual
  10323. side transforming a matrix to this representation than it saves.
  10324. In this case, @var{A} is represented by a triple of the form
  10325. @code{((@var{p},@var{i}),@var{v})}. The parameters @var{p} and @var{i}
  10326. are lists of natural numbers. The parameter @var{v} is a list of real
  10327. numbers for the @code{di_}*@code{_col} functions and complex numbers
  10328. for the @code{zi_}*@code{_col} functions. They have the following
  10329. interpretations.
  10330. @itemize @bullet
  10331. @item @var{v}
  10332. is the list of non-zero entries in the matrix in
  10333. @cindex column major order
  10334. column major order.
  10335. @item @var{i}
  10336. has the same length as @var{v}, and each item of @var{i} is the row
  10337. index of the corresponding item in @var{v}, numbered from zero.
  10338. @item @var{p}
  10339. has the length of the number of columns in the matrix, and each
  10340. item identifies the starting position of a column in @var{v} and
  10341. @var{i}, numbered from zero.
  10342. @end itemize
  10343. @noindent
  10344. The first item of @var{p} is always zero. Further explanation of this
  10345. format in terms of an array representation can be found in the file
  10346. @file{UMFPACK_UserGuide.pdf}, available from the @code{umf} library
  10347. home page at @url{http://www.cise.ufl.edu/research/sparse/SuiteSparse/current/SuiteSparse/}.
  10348. @node umf output, umf exceptions, umf input parameters, umf
  10349. @subsection @code{umf} output
  10350. If no exception occurs, the solution @var{x} to the matrix equation
  10351. @var{M} @var{x} = @var{b} noted previously will be returned if one
  10352. exists.
  10353. The solution is represented as either a list of real numbers as in
  10354. @ref{math}, or a list of complex numbers as in @ref{complex}. Real
  10355. numbers are returned by the @code{di_}* functions, and complex numbers
  10356. are returned by the @code{zi_}* functions.
  10357. If no solution exists due to a singular matrix, an empty list is
  10358. returned. The lack of a solution isn't treated as an exceptional
  10359. condition.
  10360. @node umf exceptions, Additional umf notes, umf output, umf
  10361. @subsection @code{umf} exceptions
  10362. If an exceptional condition arises from the use of this library, one
  10363. of the following lists of character strings may be returned as the
  10364. function result.
  10365. @itemize @bullet
  10366. @item
  10367. @code{<'memory overflow'>} means the library function ran out of
  10368. memory, most likely due to a matrix being too large.
  10369. @item
  10370. @code{<'bad umf specification'>} means an input parameter didn't
  10371. @cindex bad umf specification
  10372. conform to the appropriate format described above (@ref{umf input
  10373. parameters})
  10374. @item
  10375. @code{<'umf error'>} covers any unexpected behavior or abnormal
  10376. @cindex umf error
  10377. status returned by any function from the C language API.
  10378. @end itemize
  10379. For the *@code{_trp} functions. A non-square matrix will cause the
  10380. second exception above. For the *@code{_col} functions, a non-square
  10381. matrix will cause the third exception or cause an empty result
  10382. to be returned.
  10383. The exceptions noted at the beginning of this section (@ref{External
  10384. Libraries}) are also possible.
  10385. @node Additional umf notes, , umf exceptions, umf
  10386. @subsection Additional @code{umf} notes
  10387. The C language API to @code{umf} provides very many less frequently
  10388. used features that are not part of the virtual code interface, some of
  10389. which could be added by minor modifications to the file @file{umf.c}
  10390. in the @code{avram} source tree.
  10391. A set of @code{dl_}* and @code{zl_}* functions orthogonal to those
  10392. presently accessible would enable matrices having billions of rows or
  10393. columns by using long integers, but memory requirements on the virtual
  10394. code side for problems of that scale are probably prohibitive for the
  10395. foreseeable future.
  10396. @node Copying, Function Index, External Libraries, Top
  10397. @setfilename gpl.info
  10398. @appendix GNU GENERAL PUBLIC LICENCE
  10399. @center Version 2, June 1991
  10400. @display
  10401. Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
  10402. 675 Mass Ave, Cambridge, MA 02139, USA
  10403. Everyone is permitted to copy and distribute verbatim copies
  10404. of this license document, but changing it is not allowed.
  10405. @end display
  10406. @menu
  10407. * Preamble::
  10408. * Terms and Conditions::
  10409. * How to Apply::
  10410. @end menu
  10411. @node Preamble, Terms and Conditions, ,Copying
  10412. @unnumberedsec Preamble
  10413. The licenses for most software are designed to take away your
  10414. freedom to share and change it. By contrast, the GNU General Public
  10415. License is intended to guarantee your freedom to share and change free
  10416. software---to make sure the software is free for all its users. This
  10417. General Public License applies to most of the Free Software
  10418. Foundation's software and to any other program whose authors commit to
  10419. using it. (Some other Free Software Foundation software is covered by
  10420. the GNU Library General Public License instead.) You can apply it to
  10421. your programs, too.
  10422. When we speak of free software, we are referring to freedom, not
  10423. price. Our General Public Licenses are designed to make sure that you
  10424. have the freedom to distribute copies of free software (and charge for
  10425. this service if you wish), that you receive source code or can get it
  10426. if you want it, that you can change the software or use pieces of it
  10427. in new free programs; and that you know you can do these things.
  10428. To protect your rights, we need to make restrictions that forbid
  10429. anyone to deny you these rights or to ask you to surrender the rights.
  10430. These restrictions translate to certain responsibilities for you if you
  10431. distribute copies of the software, or if you modify it.
  10432. For example, if you distribute copies of such a program, whether
  10433. gratis or for a fee, you must give the recipients all the rights that
  10434. you have. You must make sure that they, too, receive or can get the
  10435. source code. And you must show them these terms so they know their
  10436. rights.
  10437. We protect your rights with two steps: (1) copyright the software, and
  10438. (2) offer you this license which gives you legal permission to copy,
  10439. distribute and/or modify the software.
  10440. Also, for each author's protection and ours, we want to make certain
  10441. that everyone understands that there is no warranty for this free
  10442. software. If the software is modified by someone else and passed on, we
  10443. want its recipients to know that what they have is not the original, so
  10444. that any problems introduced by others will not reflect on the original
  10445. authors' reputations.
  10446. Finally, any free program is threatened constantly by software
  10447. patents. We wish to avoid the danger that redistributors of a free
  10448. program will individually obtain patent licenses, in effect making the
  10449. program proprietary. To prevent this, we have made it clear that any
  10450. patent must be licensed for everyone's free use or not licensed at all.
  10451. The precise terms and conditions for copying, distribution and
  10452. modification follow.
  10453. @node Terms and Conditions, How to Apply, Preamble, Copying
  10454. @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
  10455. @enumerate
  10456. @item
  10457. This License applies to any program or other work which contains
  10458. a notice placed by the copyright holder saying it may be distributed
  10459. under the terms of this General Public License. The ``Program'', below,
  10460. refers to any such program or work, and a ``work based on the Program''
  10461. means either the Program or any derivative work under copyright law:
  10462. that is to say, a work containing the Program or a portion of it,
  10463. either verbatim or with modifications and/or translated into another
  10464. language. (Hereinafter, translation is included without limitation in
  10465. the term ``modification''.) Each licensee is addressed as ``you''.
  10466. Activities other than copying, distribution and modification are not
  10467. covered by this License; they are outside its scope. The act of
  10468. running the Program is not restricted, and the output from the Program
  10469. is covered only if its contents constitute a work based on the
  10470. Program (independent of having been made by running the Program).
  10471. Whether that is true depends on what the Program does.
  10472. @item
  10473. You may copy and distribute verbatim copies of the Program's
  10474. source code as you receive it, in any medium, provided that you
  10475. conspicuously and appropriately publish on each copy an appropriate
  10476. copyright notice and disclaimer of warranty; keep intact all the
  10477. notices that refer to this License and to the absence of any warranty;
  10478. and give any other recipients of the Program a copy of this License
  10479. along with the Program.
  10480. You may charge a fee for the physical act of transferring a copy, and
  10481. you may at your option offer warranty protection in exchange for a fee.
  10482. @item
  10483. You may modify your copy or copies of the Program or any portion
  10484. of it, thus forming a work based on the Program, and copy and
  10485. distribute such modifications or work under the terms of Section 1
  10486. above, provided that you also meet all of these conditions:
  10487. @enumerate a
  10488. @item
  10489. You must cause the modified files to carry prominent notices
  10490. stating that you changed the files and the date of any change.
  10491. @item
  10492. You must cause any work that you distribute or publish, that in
  10493. whole or in part contains or is derived from the Program or any
  10494. part thereof, to be licensed as a whole at no charge to all third
  10495. parties under the terms of this License.
  10496. @item
  10497. If the modified program normally reads commands interactively
  10498. when run, you must cause it, when started running for such
  10499. interactive use in the most ordinary way, to print or display an
  10500. announcement including an appropriate copyright notice and a
  10501. notice that there is no warranty (or else, saying that you provide
  10502. a warranty) and that users may redistribute the program under
  10503. these conditions, and telling the user how to view a copy of this
  10504. License. (Exception: if the Program itself is interactive but
  10505. does not normally print such an announcement, your work based on
  10506. the Program is not required to print an announcement.)
  10507. @end enumerate
  10508. These requirements apply to the modified work as a whole. If
  10509. identifiable sections of that work are not derived from the Program,
  10510. and can be reasonably considered independent and separate works in
  10511. themselves, then this License, and its terms, do not apply to those
  10512. sections when you distribute them as separate works. But when you
  10513. distribute the same sections as part of a whole which is a work based
  10514. on the Program, the distribution of the whole must be on the terms of
  10515. this License, whose permissions for other licensees extend to the
  10516. entire whole, and thus to each and every part regardless of who wrote it.
  10517. Thus, it is not the intent of this section to claim rights or contest
  10518. your rights to work written entirely by you; rather, the intent is to
  10519. exercise the right to control the distribution of derivative or
  10520. collective works based on the Program.
  10521. In addition, mere aggregation of another work not based on the Program
  10522. with the Program (or with a work based on the Program) on a volume of
  10523. a storage or distribution medium does not bring the other work under
  10524. the scope of this License.
  10525. @item
  10526. You may copy and distribute the Program (or a work based on it,
  10527. under Section 2) in object code or executable form under the terms of
  10528. Sections 1 and 2 above provided that you also do one of the following:
  10529. @enumerate a
  10530. @item
  10531. Accompany it with the complete corresponding machine-readable
  10532. source code, which must be distributed under the terms of Sections
  10533. 1 and 2 above on a medium customarily used for software interchange; or,
  10534. @item
  10535. Accompany it with a written offer, valid for at least three
  10536. years, to give any third party, for a charge no more than your
  10537. cost of physically performing source distribution, a complete
  10538. machine-readable copy of the corresponding source code, to be
  10539. distributed under the terms of Sections 1 and 2 above on a medium
  10540. customarily used for software interchange; or,
  10541. @item
  10542. Accompany it with the information you received as to the offer
  10543. to distribute corresponding source code. (This alternative is
  10544. allowed only for noncommercial distribution and only if you
  10545. received the program in object code or executable form with such
  10546. an offer, in accord with Subsection b above.)
  10547. @end enumerate
  10548. The source code for a work means the preferred form of the work for
  10549. making modifications to it. For an executable work, complete source
  10550. code means all the source code for all modules it contains, plus any
  10551. associated interface definition files, plus the scripts used to
  10552. control compilation and installation of the executable. However, as a
  10553. special exception, the source code distributed need not include
  10554. anything that is normally distributed (in either source or binary
  10555. form) with the major components (compiler, kernel, and so on) of the
  10556. operating system on which the executable runs, unless that component
  10557. itself accompanies the executable.
  10558. If distribution of executable or object code is made by offering
  10559. access to copy from a designated place, then offering equivalent
  10560. access to copy the source code from the same place counts as
  10561. distribution of the source code, even though third parties are not
  10562. compelled to copy the source along with the object code.
  10563. @item
  10564. You may not copy, modify, sublicense, or distribute the Program
  10565. except as expressly provided under this License. Any attempt
  10566. otherwise to copy, modify, sublicense or distribute the Program is
  10567. void, and will automatically terminate your rights under this License.
  10568. However, parties who have received copies, or rights, from you under
  10569. this License will not have their licenses terminated so long as such
  10570. parties remain in full compliance.
  10571. @item
  10572. You are not required to accept this License, since you have not
  10573. signed it. However, nothing else grants you permission to modify or
  10574. distribute the Program or its derivative works. These actions are
  10575. prohibited by law if you do not accept this License. Therefore, by
  10576. modifying or distributing the Program (or any work based on the
  10577. Program), you indicate your acceptance of this License to do so, and
  10578. all its terms and conditions for copying, distributing or modifying
  10579. the Program or works based on it.
  10580. @item
  10581. Each time you redistribute the Program (or any work based on the
  10582. Program), the recipient automatically receives a license from the
  10583. original licensor to copy, distribute or modify the Program subject to
  10584. these terms and conditions. You may not impose any further
  10585. restrictions on the recipients' exercise of the rights granted herein.
  10586. You are not responsible for enforcing compliance by third parties to
  10587. this License.
  10588. @item
  10589. If, as a consequence of a court judgment or allegation of patent
  10590. infringement or for any other reason (not limited to patent issues),
  10591. conditions are imposed on you (whether by court order, agreement or
  10592. otherwise) that contradict the conditions of this License, they do not
  10593. excuse you from the conditions of this License. If you cannot
  10594. distribute so as to satisfy simultaneously your obligations under this
  10595. License and any other pertinent obligations, then as a consequence you
  10596. may not distribute the Program at all. For example, if a patent
  10597. license would not permit royalty-free redistribution of the Program by
  10598. all those who receive copies directly or indirectly through you, then
  10599. the only way you could satisfy both it and this License would be to
  10600. refrain entirely from distribution of the Program.
  10601. If any portion of this section is held invalid or unenforceable under
  10602. any particular circumstance, the balance of the section is intended to
  10603. apply and the section as a whole is intended to apply in other
  10604. circumstances.
  10605. It is not the purpose of this section to induce you to infringe any
  10606. patents or other property right claims or to contest validity of any
  10607. such claims; this section has the sole purpose of protecting the
  10608. integrity of the free software distribution system, which is
  10609. implemented by public license practices. Many people have made
  10610. generous contributions to the wide range of software distributed
  10611. through that system in reliance on consistent application of that
  10612. system; it is up to the author/donor to decide if he or she is willing
  10613. to distribute software through any other system and a licensee cannot
  10614. impose that choice.
  10615. This section is intended to make thoroughly clear what is believed to
  10616. be a consequence of the rest of this License.
  10617. @item
  10618. If the distribution and/or use of the Program is restricted in
  10619. certain countries either by patents or by copyrighted interfaces, the
  10620. original copyright holder who places the Program under this License
  10621. may add an explicit geographical distribution limitation excluding
  10622. those countries, so that distribution is permitted only in or among
  10623. countries not thus excluded. In such case, this License incorporates
  10624. the limitation as if written in the body of this License.
  10625. @item
  10626. The Free Software Foundation may publish revised and/or new versions
  10627. of the General Public License from time to time. Such new versions will
  10628. be similar in spirit to the present version, but may differ in detail to
  10629. address new problems or concerns.
  10630. Each version is given a distinguishing version number. If the Program
  10631. specifies a version number of this License which applies to it and ``any
  10632. later version'', you have the option of following the terms and conditions
  10633. either of that version or of any later version published by the Free
  10634. Software Foundation. If the Program does not specify a version number of
  10635. this License, you may choose any version ever published by the Free Software
  10636. Foundation.
  10637. @item
  10638. If you wish to incorporate parts of the Program into other free
  10639. programs whose distribution conditions are different, write to the author
  10640. to ask for permission. For software which is copyrighted by the Free
  10641. Software Foundation, write to the Free Software Foundation; we sometimes
  10642. make exceptions for this. Our decision will be guided by the two goals
  10643. of preserving the free status of all derivatives of our free software and
  10644. of promoting the sharing and reuse of software generally.
  10645. @iftex
  10646. @heading NO WARRANTY
  10647. @end iftex
  10648. @ifinfo
  10649. @center NO WARRANTY
  10650. @end ifinfo
  10651. @item
  10652. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
  10653. FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
  10654. OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
  10655. PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
  10656. OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  10657. MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
  10658. TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
  10659. PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
  10660. REPAIR OR CORRECTION.
  10661. @item
  10662. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
  10663. WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
  10664. REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
  10665. INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
  10666. OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
  10667. TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
  10668. YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
  10669. PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
  10670. POSSIBILITY OF SUCH DAMAGES.
  10671. @end enumerate
  10672. @iftex
  10673. @heading END OF TERMS AND CONDITIONS
  10674. @end iftex
  10675. @ifinfo
  10676. @center END OF TERMS AND CONDITIONS
  10677. @end ifinfo
  10678. @page
  10679. @node How to Apply, , Terms and Conditions, Copying
  10680. @unnumberedsec How to Apply These Terms to Your New Programs
  10681. If you develop a new program, and you want it to be of the greatest
  10682. possible use to the public, the best way to achieve this is to make it
  10683. free software which everyone can redistribute and change under these terms.
  10684. To do so, attach the following notices to the program. It is safest
  10685. to attach them to the start of each source file to most effectively
  10686. convey the exclusion of warranty; and each file should have at least
  10687. the ``copyright'' line and a pointer to where the full notice is found.
  10688. @smallexample
  10689. @var{one line to give the program's name and an idea of what it does.}
  10690. Copyright (C) 19@var{yy} @var{name of author}
  10691. This program is free software; you can redistribute it and/or
  10692. modify it under the terms of the GNU General Public License
  10693. as published by the Free Software Foundation; either version 2
  10694. of the License, or (at your option) any later version.
  10695. This program is distributed in the hope that it will be useful,
  10696. but WITHOUT ANY WARRANTY; without even the implied warranty of
  10697. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  10698. GNU General Public License for more details.
  10699. You should have received a copy of the GNU General Public License
  10700. along with this program; if not, write to the Free Software
  10701. Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  10702. @end smallexample
  10703. Also add information on how to contact you by electronic and paper mail.
  10704. If the program is interactive, make it output a short notice like this
  10705. when it starts in an interactive mode:
  10706. @smallexample
  10707. Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
  10708. Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
  10709. type `show w'. This is free software, and you are welcome
  10710. to redistribute it under certain conditions; type `show c'
  10711. for details.
  10712. @end smallexample
  10713. The hypothetical commands @samp{show w} and @samp{show c} should show
  10714. the appropriate parts of the General Public License. Of course, the
  10715. commands you use may be called something other than @samp{show w} and
  10716. @samp{show c}; they could even be mouse-clicks or menu items---whatever
  10717. suits your program.
  10718. You should also get your employer (if you work as a programmer) or your
  10719. school, if any, to sign a ``copyright disclaimer'' for the program, if
  10720. necessary. Here is a sample; alter the names:
  10721. @smallexample
  10722. @group
  10723. Yoyodyne, Inc., hereby disclaims all copyright
  10724. interest in the program `Gnomovision'
  10725. (which makes passes at compilers) written
  10726. by James Hacker.
  10727. @var{signature of Ty Coon}, 1 April 1989
  10728. Ty Coon, President of Vice
  10729. @end group
  10730. @end smallexample
  10731. This General Public License does not permit incorporating your program into
  10732. proprietary programs. If your program is a subroutine library, you may
  10733. consider it more useful to permit linking proprietary applications with the
  10734. library. If this is what you want to do, use the GNU Library General
  10735. Public License instead of this License.
  10736. @node Function Index, Concept Index, Copying, Top
  10737. @unnumbered Function Index
  10738. @printindex fn
  10739. @node Concept Index, , Function Index, Top
  10740. @unnumbered Concept Index
  10741. @printindex cp
  10742. @bye
  10743. pcx has been ditched, but this section is left here
  10744. in case someone decides to put it back
  10745. @node pcx, lpsolve, mpfr, External Libraries
  10746. @section @code{pcx}
  10747. This library interface exports a function that uses the algorithm
  10748. documented at @url{http://www-fp.mcs.anl.gov/otc/Tools/PCx/} to solve
  10749. linear programming problems by an interior point method. The library
  10750. @cindex linear programming
  10751. function is of the form
  10752. @example
  10753. library('pcx','solution')
  10754. @end example
  10755. @noindent
  10756. This function has the same calling conventions as
  10757. @code{library('glpk','simplex')} and @code{library('glpk','interior')}
  10758. (@ref{glpk}).
  10759. @cindex internal errors
  10760. Error messages are also the same as @ref{glpk errors}, except that the
  10761. a message text of @code{<'bad pcx specification'>} is used. In
  10762. addition, @code{pcx} can cause a virtual machine internal error (code
  10763. 70), which is raised when @code{avram} detects access anomalies by an
  10764. external library, or in the worst case, a segmentation fault.
  10765. @cindex segmentation fault
  10766. A working configuration of this library interface requires a shared
  10767. library @file{libPCx.so} to be installed on the host, which is not a
  10768. feature of the standard installation distributed by the authors of
  10769. @code{PCx}. However, the shared library can be built from the source
  10770. package by any system administrator familiar with these
  10771. procedures. Alternatively, an unofficial patched version of the Debian
  10772. @cindex Debian
  10773. package of @code{pcx} that includes the shared library is available on
  10774. the @code{avram} home page. This patch has been submitted to the
  10775. Debian maintainer of @code{pcx} and may be expected in a future
  10776. release.
  10777. If @code{avram} has been built already on a system that has the
  10778. @code{pcx} header files but not the shared library, it should be
  10779. possible to get the @code{pcx} library interface to work just by
  10780. installing the shared library without recompiling @code{avram},
  10781. because @code{pcx} is dynamically loaded due to licensing
  10782. restrictions.