This document is for Xerox internal use onlyJaMBY John Warnock AND Martin NewellVersion of June 6, 1980[Ivy]JaM.bravoPREFACEThis document gives a brief description of a Mesa based interactive programming environmentcalled "JaM". In this document three general topics are discussed: what is JaM; what applicationslend themselves to the use of JaM; and how JaM interacts with and is interfaced to Mesa.XEROXPALO ALTO RESEARCH CENTER3333 Coyote Hill RoadPalo Alto California 94304This document is for Xerox internal use onlyЪН3ОэpТXП,НЇОSиqНЇОPzrpТ rp НЇОKкrНЇОGsНЇО7пpНЇО4єsТкП[НЇО3 Т■П-Т∙П5НЇО1°ТЕП=ТФН)WОоtН)`ОpТXН)`ОєrТFН)`ОfН3ОfЯpТXП,ЪЇ∙=ГdvYJaM2ContentsIntroductionBasic OperationExamplesJaM Command CatagoriesArithmetic CommandsBoolean and Relational CommandsStack Manipulation CommandsExecution Control CommandsDictionary Related CommandsArray Related CommandsInput/Output and Stream Related CommandsAttribute and Conversion CommandsScanner and String Manipulation CommandsGraphic CommandsНЇОfЯsНGОН'┤ОbpНЇО]KНЇОZ ТНЇОVТНЇОSиНЇОP·НЇОMrНЇОJGНЇОGНЇОCПНЇО@еНЇО=≥П(НЇО:nП!НЇО7BП(НЇО4:^Ї2oc5°JJaM3IntroductionThis document gives a brief description of a Mesa based interactive programming environmentcalled "JaM". In this document three general topics are discussed: What is JaM?; what applicationslend themselves to the use of JaM; and how JaM interacts and is used with Mesa.(comment: onlyfirst and part of the second of these is done)Basic OperationTo answer the question: "What is JaM?", several features of the system will be discussed.1.JaM implements a stack oriented, virtual machine. This machine operates on entities calledobjects. In a common sense sort of way JaM can be thought of as an extremely flexibleprogrammable Hewlett Packard type calculator that can handle a wide variety of objects in apowerful way. 2.An integral part of the JaM machine is a virtual memory that provides an address space of 224words for storage of all objects in the system.3.An interactive user interface to the JaM machine is provided. The interface is implemented as alanguage having an extremely simple syntax. Strings in this language are interpreted by ascanner and transformed into a sequence of objects that are, in turn, executed by the JaMmachine.A JaM machine basically consists of three stacks, virtual memory, and the instruction set. The threestacks are: The operand stack, the dictionary (or context) stack, and the execution stack. Undermost circumstances the user is concerned only with the operand stack. A description of thedictionary stack is put off until later, although the understanding of its function and use isimportant. The function of the execution stack need not be of direct concern to the user - it isrequired for the internal execution control of the machine.When the JaM machine is initialized the operand stack is empty, the dictionary stack contains onedictionary called the system dictionary, and the machine is executing the keyboard stream (waitingfor the user to type something.) Lines of input are passed to the JaM scanner to be parsed intotokens. Tokens are delimited by any mixture of spaces, tabs, carriage returns, and commas. Thescanner recognizes 3 classes of tokens: numbers, strings, and identifiers. It converts each token intothe relevant object, then passes it to execution control for execution by the JaM machine.To understand what happens when the user types it is important to understand what the scannerrecognizes, and what objects are generated for execution.Numbers are of three types: integers, reals, and long integers. 23 -465--Examples of integers.-23.4 1. 0.00034--Examples of reals.-123456 1000000--Examples of long integers. Strings are any sequence of characters enclosed in balanced parentheses. For example:(Hello. How are you)(strings may consistof more than one lineof information)(strings may (contain nested (balanced) parentheses))НЇОfЯsНGОНЇОbpНЇО^РsТкП[НЇО]nТ└П8Т┘П+НЇО[ЙТ П8Т⌡П%НЇОZfТП.НЇОW;pНЇОTsТШТЭПLНЇОPДН2ТхП(ТиП2Н2ОO`usТнП9ТоН2ОMэТ╚П[Н2ОLXТ НЇОI-Н2Т▄Т█ПKОI╨Н2ОG╗ТП/НЇОD}Н2Т├Т┤ПBН2ОBЫТиТйП>Н2ОAuusТдТеП2Н2О?ЯНЇО<фТ┌ПIТ┐НЇО;AТ╠Т╡ПRНЇО9ҐТЛПSТМНЇО89ТКП^НЇО6╣Т╛ПPТґНЇО51ТП;НЇО2Т≤Т≥ПUНЇО0┌Т⌡ПIТ°НЇО.ЧТєТ╔П@НЇО-zusТёПVТєНЇО+ЖТ▓Т⌠ususu sНЇО*rТЪТ usП"НЇО'FТ╘П]НЇО%бТП9НЇО"≈П?Н╛О%vТ─wН'ЇsН╛О║wН ЇsТН╛ОwТ─Н Їs ТНЇОЯПUН╛ОфwН╛ОЎН╛О:Н╛ОІН╛ОўП5Ї Ц=Г]()JaM4(strings may contain all manner of garbage @#$$$%%~~~&&**~%$$1233;;;except for unbalanced parens)(Strings may contain as many as 32767 characters)An identifiers is any token that is neither a number nor a string. For example:.add.printabc$$$123aabc.111-.aaaare all examples of valid identifiers.Execution of objects has the following semantics:number:the value is pushed onto the operand stack;string:the string is pushed onto the operand stack;identifier:the object associated with the identifier is looked up using the dictionary stack as acontext (described later), and the associated object is in turn executed.ExamplesTo see how this all works, several simple examples are given.Example 1.Consider the input:123 456 .add .cvs .print1.The scanner will recognize 123 as a number, convert it to an integer object and pass it tothe JaM machine for execution, which will leave the integer value 123 on the operandstack.2.In a similar way, 456 will be pushed onto the operand stack.3.The scanner will recognize .add as an identifier. ".add" is known in the system dictionaryas a command object which, when executed will replace two numbers on the top of theoperand stack with their sum. The operand stack will now contain the integer object: 579.4.The scanner will recognize .cvs as an identifier. ".cvs" is known in the system dictionaryas a command object which, when executed will convert the object on the top of theoperand stack into its string object equivalent. i.e. the integer 579 will be converted to thestring "579", and put on the operand stack.5.In a similar way, .print is a command object which will print the string found on theoperand stack. In this case:579НЇОfЯsНGОН╛ОbwТПDН╛О` Н╛О]▓П1НЇОZfsПPН╛ОW;wН╛ОUЇН╛ОT3Н╛ОR╞Н╛ОQ+Н╛ОOїН╛ОN#НЇОJВsП&НЇОGлП1Н2ОD═НёП+Н2ОAuНёП,Н2О>J НёТ■ u sТ∙usН═О<фusТПBНЇО9 pНЇО6osП=НЇО3Cp Н1О0sН╛О,МwН1О)аsНґТ wsТ⌡П7Н╛О(=ТюП)ТаwsН╛О&╧Н1О#▌НґТwsП'Н1О НґТ≈Т≤vwsvwsП#Н╛О≤ТЇusТ╦П4Н╛ОТ█Т▌П8wН1О╒sНґТ√vwsТ≈vwsП#Н╛ОТпП@ТяН╛О Т√П0Т≈wsН╛ОТwsН1ОєНґТгvwsТхП=Н╛О ТН'ОТw▓Їґ;m[^ШJaM5will appear on the screen.Example 2.The input:(hello there -- how are you) .printwill cause:hello there -- how are youto appear on the screen.Example 3.When the JaM machine is first started, the system dictionary contains about one hundreddefinitions. Most of the definitions associate identifiers with command objects. These commandsprovide the primitive functions of the machine.Included in the primitive operations are commands that allow new associations to be entered intodictionaries. The .def command makes associations in the current dictionary, which is the one onthe top of the dictionary stack. For example:The input:(x) 100 23 .add .defwill create an association between the string object x and the integer object 123 in the currentdictionary. Having made this definition, consider the input:x 1 .add .cvs .printThe scanner will recognize x as an identifier, whose execution will yield the integer object 123,whose execution will, in turn, leave the integer 123 on the operand stack. When the rest of theline is executed, then:124will be printed.Example 4.The input:(a)(hello -- how are you) .defwill define a to be the string object: hello -- how are youThe subsequent input:a .printwill result in:hello -- how are you НЇОfЯsНGОН╛ОbТНЇО^Рp Н2О[гs НґОX°wП$Н2ОUps НґОREwН2ОOsНЇОKНp НЇОHцsТТПKНЇОG?Т╒ПRТёНЇОE╩ТП/НЇОB▐ТёТєПGНЇОAТ÷wsП#usТ═ НЇО?┤ТП.Н2О<\ Н╛О90wН2О6sТ√П5wsТ≈wsН2О4│ТП=Н╛О1UwН2О.*sТ▌wsП9Т▐wsН2О,іТ└П1wsТ┘П)Н2О+"ТН╛О'ВwН2О$кsНЇО!═p Н2Оts Н╛ОIwН2ОswswН2ОРsН╛ОгwН2О⌡sН╛ОpwxэЇ)=Г\БеJaM6being printed.Example 5.All objects come in two varieties, nouns and verbs. This distinction is meaningful only to executioncontrol. Execution of a noun object always results in that object being pushed onto the operandstack. Execution of a verb object depends on the type of the object, though for some objects, e.g.numbers, no distinction is made. Command objects are normally verb objects. Execution of a verbcommand object executes the command. Execution of a verb string causes the string to be scannedas input.For example, in the input:(average)(.add 2. .div) .cvx .defthe .cvx command will make the noun string object: .add 2. .divinto a verb ("eXecutable") before it is defined as the value of average.Consequently, in the input:123 456 average .cvs .printexecution of the identifier average will cause the string: .add 2. .div to be scanned and itstokens executed, rather than having it pushed onto the operand stack. The overall result will bethat:289.5will be printed.It can be seen from the above simple examples, that the user may assign values to identifiers, orassign procedures (executable objects) to identifiers. This ability to extend the JaM machine is theprimary feature that allows complex systems to be built in the JaM environment.To appreciate how this extensibility may be used, a more complete description of the primitivecommand set, and its relationship to the machine structure follows.JaM Command CatagoriesTo describing the various JaM commands we will use a notation to indicate how each commandworks. Specifically, angle brackets enclosing an expression will be used to indicate a JaM object onthe operand stack. For instance, will indicate three objects on the stack, with beingthe object on top, next, and beneath . Certain letters will be used to indicate specifictypes of objects. and will represent numbers, a boolean, a dictionary, anarray, and will represent streams; and and will represent any kind of object. Whena command returns elements, then is indicated by "=>" followed by the returned elements. Thenotation "--" is used to indicate that the command returns no elements. Commands normallyremove their arguments from the operand stack, do the operation on the arguments, and thenreturn results. Some commands, however, return their input arguments. The descriptions of thecommands will indicate how each works.There are roughly ten categories of JaM commands. These include:Arithmetic CommandsThe arithmetic commands provide for the basic arithmetic operations between mixed types ofnumbers. These commands take their operands from the operand stack, and leave the results onЪНЇОfЯsНGОН2ОbТ НЇО^Рp НЇО[гsТ▀П#ususТ▄П2НЇОZCТїП6Т╗П*НЇОX©Т√ПPТ≈НЇОW;Т├П5Т┤П,НЇОUЇТ┼П2Т▀П.НЇОT3ТН2ОQН╛ОMэwП!Н2ОJ╠swsП*uwН2ОI-sП@wsН2ОFН╛ОBжwН2О?╙sТЁwswsТЄН2О>&Т│Т┌ПEН2О<╒Н╛О9wwН2О6KsТНЇО3 Т·П.Т÷П4НЇО1°Т⌠П&Т■П?НЇО0ТПOНЇО,МТюПTТа НЇО+iТПCНЇО(=pНЇО%sТ╛П&ТґП4НЇО#▌Т┬ПAТ┴П$НЇО" Т▀П"wsП#Т▄wsНЇО ├Т▐Т░wswswsП4НЇОТ▌wswswswsТ▐wsНЇО}Т┘wswsТ├wswsП)НЇОЫТўПXТ╞НЇОuТйП:ТкНЇОЯТлПZНЇОmТ╦ПWТ╧НЇОИТП&НЇОЎПAНЇО▓pНЇОgsТэП8ТщП"НЇО ЦТїП,Т╗П1 ≤Ї °=Г]o5JaM7the operand stack. Included are:.add: .add => .sub: .sub => .mul: .mul => .div: .div => .neg: .neg => <-n>.cos: .cos => .sin: .sin => .atan: .atan => .exp: .exp => .log: .log => Boolean and Relational CommandsThese commands generate boolean constants by performing relational tests between numeric (orstring) objects, and boolean operations between boolean objects. Included are:.true: .true => <.true>.false: .false => <.false>.eq: .eq => <.true> if n = m otherwise <.false> (also works on strings).gt: .gt => <.true> if n > m otherwise <.false> (also works on strings).lt: .lt => <.true> if n < m otherwise <.false> (also works on strings).not: .not => <~b>.and: .and => .or: .or => .xor: .xor => Stack Manipulation CommandsThese commands provide a set of functions that allow the user to manipulate the operand stack.These functions include facilities to duplicate portions of the stack, rearrange portions of the stack,eliminate portions of the stack, and count the entries on the stack. Included are:.pop: .pop => --.copy: ... .copy => ... ... .cntstk: | ... .cntstk => | ... .roll: ... .roll => ... ....dup: .dup => .clrstk: | ... .clrstk => |.exch: .exch => Stack Marking and Mark Manipulation CommandsThese commands provide a set of functions that allow the user to mark the operand stack. Thesefunctions are used for keeping track of variable numbers of arguments on the operand stack.Included are:.mark: .mark => (this command puts a Mark type object on the operand stack.).cnttomrk: ... .cnttomrk => ... .clrtomrk: ... .clrtomrk => Execution Control CommandsThis set of commands provides for control of execution. JaM has no "go to" type of command.Instead heavy use is made of "if - else", "looping", and "select" kinds of control mechanisms. Mostexecution control commands expect objects on the operand stack. These objects are executed as afunction of other objects on the stack. For example: The .if command expects a boolean object andНЇОfЯsНGОНЇОbТП!НЇО_yНЇТFНЇО]ьНЇНЇО\⌡НЇНЇО[]НЇНЇОZ НЇНЇОXБНЇНЇОW╔НЇНЇОVgНЇНЇОTюНЇОUMОTюНЇОS┌НЇОRУОS┌НЇОPzpТНЇОMOsТаП7ТбП%НЇОKкТПOНЇОHцyНЇТFНЇОG┘НЇНЇОFHНЇПLНЇОE НЇПLНЇОCмНЇПLНЇОB▐НЇНЇОARНЇО@еОARО@еОARО@еОARО@еОARНЇО?╙НЇО?О?╙О?О?╙ О?О?╙О?О?╙НЇО>НЇО=vО>О=vО>О=vО>О=vО>НЇО:ШpТНЇО7пsТўПKТ╞НЇО6KТ≈ПYТ≤ НЇО4гТПSНЇО1©yНЇТFНЇО0┌НЇО/УО0┌О/УО0┌О/УО0┌О/УО0┌О/УО0┌О/УО0┌О/УО0┌О/УО0┌О/УО0┌НЇО.зНЇО.MО.зО.MО.зО.MО.зО.MО.зО.MО.зО.MО.зНЇО-3НЇО,іО-3О,іО-3О,іО-3О,і О-3О,іО-3О,іО-3О,іО-3НЇО+▄НЇНЇО*NНЇО)аО*NО)аО*NО)аО*N НЇО(їНЇНЇО%÷pТП,НЇО"ssТ⌡П_НЇО ОТвТьП=НЇОkТНЇО&yНЇТFПNНЇОХНЇ О[ОХО[ОХО[ОХО[ОХО[ОХО[ОХНЇОAНЇ ОЄОAОЄОAОЄОAНЇОKpТНЇО sТ╡П7ТЁП$НЇО⌡Т│Т┌ПKНЇО ТєП,Т╔П3НЇО⌠Т┐Т└wsП%Ъ lЇL>Г\©ОJaM8any other object on the operand stack. If the boolean equals .true then the other object isexecuted, otherwise the .if command pops the object from the stack. The execution controlcommands include: .exec: .exec => -- (executes object x).if: .if => -- (if b = .true then execute x).ifelse: .ifelse => -- (if b = .true then execute x else execute y).rept: .rept => -- (execute x -- i times).loop: .loop => -- (execute x until a .exit command is executed).exit: .exit => -- (exit from the current .rept, .loop, .dictforall, .arrayforall commands).stop: .stop => -- (clear the execution stack.).singlestep: .singlestep => -- (put execution control into singlestep mode.).runfree: .runfree => -- (take execution control out of singlestep mode.).quit: .quit => -- (save virtual memory and exit to the operating system.)Dictionary Related CommandsDictionary objects are general symbol tables that may be used either as data structures or as part ofthe user's execution context.As we learned earlier, the scanner, when it encounters an identifier, looks up the identifier in thedictionaries on the dictionary stack. What actually happens in this case is quite simple. Theunknown identifier is first looked up in the dictionary on the top of the dictionary stack. If theidentifier has a value in this dictionary, then the value is returned. If the identifier has no entry inthis dictionary, then the search continues through each dictionary on the dictionary stack until theentry is found. At this point the value associated with the identifier is returned. The user hascontrol over the contents of the dictionary stack via the .begin and .end commands, and thereforethe user has control over his execution context. Later we will see how this control may be used.When dictionaries are used as data structures, they are loaded, as objects, onto the operand stack.Various commands can then operate on these objects to store new definitions, or to retrievedefinitions found in the dictionaries. Also a command exists for creating new dictionaries. In the following definitions and can be any objects, but are used to denote the "key " and"value" respectively.The dictionary related commands are:.dict: .dict => (dictionary with capacity of i entries).def: .def => -- (associates the value v with the key k in the current dictionary).del: .del => -- (deletes the key k from the dictionary d).load: .load => (loads the value associated with k in the current dictionary).store: .store => -- (finds a definition of k in the current context and replaces that definition with value v. If no definition of k exists then the definition is placed in the current dictionary.).put: .put => -- (associates value v with key k in dictionary d.).get: .get => (retrieves the value associated with k in dictionary d.).known: .known => <.true> if key k is in dictionary d <.false> otherwise..where: .where => <.true> if k is found in some dictionary d <.false> otherwise..clrdict: .clrdict => -- (clears all entries from dictionary d.).dictforall: .dictforall => -- (puts on the stack, and then executes . This is done for every k,v pair in dictionary d).begin: .begin => -- (makes d the current dictionary on the dictionary stack.).end: .end => -- (pops the current dictionary from the dictionary stack.).sysdict: .sysdict => .length: .length => (replaces the dictionary with its current number of entries)..maxlength : .maxlength => (replaces the dictionary with its size).Array Related CommandsArray objects are linear arrays of objects. Commands exist to create arrays, store into arrays,retrieve objects from arrays etc. Most of these commands either expect array objects on theЪНЇОfЯsНGОНЇОbТзП.ТшwsНЇО` ТДП<ТЕНЇО_ТНЇО\yНЇП%НЇОZпНЇП0НЇОY⌠НЇПFНЇОXUНЇП+НЇОWНЇП@НЇОUзНЇПWНЇОT²НЇП*НЇОS_ НЇПAНЇОR"НЇПAНЇОPДНЇПEНЇОMэpНЇОJ╠sТ┼ПbТ▀НЇОI-ТНЇОFТ║Т╒ПWНЇОD}ТИТЙПJНЇОBЫТ╡ТЁПPНЇОAuТ■ПXТ∙НЇО?ЯТ·ПIТ÷НЇО>mТ©ПIТюНЇО<ИТ√Т≈П"wswsНЇО;eТёП1ТєП0НЇО89Т║Т╒ПFНЇО6╣ТДПLТЕНЇО51ТЗПJТШТНЇО2Т█wswsТ▌П/НЇО0┌ТНЇО-VП$НЇО*NyНЇТFП:НЇО)НЇПUНЇО'сНЇП=НЇО&√НЇПPНЇО%XНЇПWН ЇО$П@Н ЇО"щП2НЇО!═НЇПGНЇО bНЇПMНЇО%НЇПJНЇОГНЇПQНЇО╙НЇП<НЇОl НЇПXН ЇО/П%НЇОЯНЇПLНЇОЄНЇПEНЇОvНЇНЇО9НЇПRНЇОШ НЇП@НЇОІpТНЇО┼sТоТпПSНЇОТыП0ТзП,Ї ©>Г]LfJaM9operand stack or return array objects on the operand stack.In addition to their usefulness as data structures, execution of a verb array results in execution ofeach of its elements in turn. Procedures can be converted into an array form which, in some sense,corresponds to the compiled form of a procedure in other machines.The array related commands consist of:.array: .array => (new array of length i.).subarray: .subarray => (a' is the subarray of a starting at position i and withlength j.).aput: .aput => -- (store v in the ith position of a.).aget: .aget => (get v from the ith position of a.).aload: .aload => ... .astore: ... .astore => (store x1 ... xi into array a of length i.).arrayforall: .dictforall => -- (puts the contents of ai on the stack, and then executes .This is done for every ai pair in array a).length: .length: .length => (replaces the array with its length).Input/Output and Stream Related CommandsThis catagory of commands deals primarily with string objects and stream objects. There existprimitive JaM commands to create streams, execute streams, read streams, write streams, anddestroy streams. These commands include:.print: .print => -- (.prints the string s on the current output stream.).bytestream: .bytestream => (this command creates a bytestream with theaccess characteristics represented by . Here = 1 for read, 2 for write, 4 for append -- orthe sum of any of these. The created stream type objectis left on the operand stack.).wordstream: .wordstream => (this command creates a wordstream with theaccess characteristics represented by . Here = 1 for read, 2 for write, 4 for append -- orthe sum of any of these. The created stream type objectis left on the operand stack.).keystream : .keystream => (this command creates a keystream and leaves it on the operandstack.).killstream: .killstream => (this command kills the given stream.).readline: .readline => <.true> (this command reads a line from the stream).readitem: .readitem => <.true> (this command reads a item from the stream) <.false> (if no more items in the stream).writebytes: .writebytes => -- (write bytes in string s appended to stream t.).loadbcd: .loadbcd => -- (load mesa bcd and start.)Attribute and Conversion CommandsThese commands allow the user to determine the types of objects and to convert from one objecttype to another. This command set is not complete as yet, but the currently provided commandsinclude:.type: .type => (deliver the name of the type on top of operand stack.Current types include. .nulltype, .intergertype,.longintegertype, .realtype, .booleantype, .stringtype,.streamtype, .arraytype,.dicttype, .commandtype, .stacktype,.frametype, .marktype.).itype: .itype => (deliver the number of the type on top of the operandstack. Current number assignments are:nulltype = 0integertype = 1longintegertype = 2realtype = 3booleantype = 4НЇОfЯsНGОНЇОbТП;НЇО^РТ║ Т╒ПWНЇО]nТ┬П)Т┴П:НЇО[ЙТПBНЇОX©П&НЇОUЇyНЇТFП,НЇОTyНЇПWН'ЇОS< НЇОQЧНЇП;НЇОPаНЇП9НЇОO┐НЇОNЖОO┐ОNЖОO┐ОNЖОO┐НЇОMэНЇОMOОMэОMOОMэОMOОMэОMOОMэОMOОMэНЇОL5НЇПWН'ЇОJВП2НCЇНЇОI╨НЇП:НЇОEtpТП(НЇОBIsТдТеПNНЇО@еТДТЕП;НЇО?AТП)НЇО<8yНЇТFПGНЇО:Ш НЇПUН'ЇО9ҐП4Н'ЇО8─П6Н'ЇО7BП7Н'ЇО6НЇО4г НЇПUН'ЇО3┼П4Н'ЇО2LП6Н'ЇО1П7Н'ЇО/яНЇО.■ НЇПTН ЇО-VНЇО, НЇП<НЇО*шНЇПYНЇО)·НЇПYНЇО(`П0НЇО'# НЇПKНЇО%ЕНЇП6НЇО"щpТП!НЇО╡sТ÷Т═ПFНЇО.Т║П>Т╒НЇО╙НЇО╒yНЇТFПRН'ЇОdП0Н'ЇО'П7Н'ЇОИН'ЇО╛П$Н'ЇОnНЇО1НЇПSН'ЇОСП&Н'ЇОІН'ЇОxН'ЇО ;Н'ЇОЩН'ЇО юnЇ ²=Г]nTJaM10stringtype = 5streamtype = 6commandtype = 7dicttype = 8arraytype = 9stacktype = 10frametype = 11marktype = 12.length: .length => (length of: string (in characters); array (in elements); dictionary(in entries).).cvs: .cvs => (convert to string equivalent.).cvis: .cvis => (convert into given string space. This command will use s for allnumber and boolean conversions.).cvrs: .cvrs => (convert with radix to string equivalent.).cvirs: .cvirs => (convert with radix into given string space. This command will use s for allnumber and boolean conversions.).litchk: .litchk => <.true> if a noun otherwise <.false>.cvx: .cvx => (convert into executable equivalent.).cvlit: .cvlit => (convert into literal form -- works for strings, and arrays.)Scanner and String Manipulation CommandsCommands in this group allow for string searching and manipulation. Also an interface to the JaMscanner exists in the ".token" command..token: .token => <.true><.false> (if token present then return .true and strip first token from given stream or string. Return remainder and token on the stack.If no token, then return only a .false.).string: .string => ( is a string of length i)..length: .length => (replaces the string with its length in characters)..substring: .substring => ( is a substring of s starting at position i for jcharacters.).putstring: .putstring => ( is the same as except for the substring s startingat position i.).search: .search =><.true>(if there is a substring of t matching s)<.false>(if no substring of t matches s)..asearch: .search =><.true>(if there is a starting substring of t matching s)<.false>(if no starting substring of t matches s).Graphics CommandsCommands in the Graphics group are supplimentary commands and are enabled by loadingjamgraphics.bcd. Within this mesa module a display context stack is maintained so thattransformations and other state information can easily be saved and restored. The .pushdc, .popdcand .initdc commands control this stack.State information concerning the graphics device is held in an entity called the diplay context. andmost transformation, clipping, and painting commands alter this state. Most drawing commandsboth alter state and use state..initdc:.initdc (Initializes the stack of display contexts.).pushdc:.pushdc (Pushes a copy of the current display context onto the display context stack.).popdc:.pushdc (Pops the current display context from the display context stack.).setview:.translate: .translate=>-- (Concatenates translation matrix with current transformation matrix.).scale: .scale=>-- (Concatenates scale matrix with current transformation matrix.).rotate: .rotate=>-- (Concatenates rotation matrix (theta in degrees) with current transformationmatrix.).drawto: .drawto =>-- (Draws from the current position to the given position.).rdrawto: .rdrawto =>-- (Adds x,y to the current position and draws from the current position to thecomputed position.)ЪНЇОfЯsНG?Н'ЇОbAyТF Н'ЇОa Н'ЇО_фН'ЇО^┴Н'ЇО]KН'ЇО\ Н'ЇОZп Н'ЇОY⌠НЇОXUНЇПXН ЇОW НЇОUзНЇП3НЇОT²НЇПWН ЇОS_НЇОR"НЇПDНЇОPДНЇПhН ЇОOїНЇОNiНЇП6НЇОM,НЇП8НЇОKННЇПRНЇОHФpТП(НЇОD7sТ▒П'Т▓П9НЇОB╡ТП'НЇО?нyНЇТ─Н Ї Н ЇО>░Н'ЇТэТщНЇО=SТ─Н ЇПFН ЇО<ТП(НЇО:ьНЇП3НЇО9 НЇПIНЇО8] НЇПUН ЇО7НЇО5Б НЇТЖП7ТВП$Н ЇО4єТНЇО3gНЇТ─Н ЇО2зО3gО2зО3gО2зО3g ТЛТМН ЇО1U Н.ЇТП!НЇО.MНЇТ─Н ЇО-юО.MО-юО.M ТчТъП&Н ЇО,< Н.ЇТП*НЇО)pНЇО$asТНТОП<НЇО"щТП)ТП.НЇО!YТ√П/Т≈П3НЇОуТП(НЇО╙Т√П)Т≈П;НЇО&ТЇТ╦П?НЇО╒ТНЇО yНЇП5НЇО\НЇПWНЇОНЇПKНЇОАНЇНЇОє НЇП\НЇОfНЇПTНЇО)НЇТнПaН ЇО КНЇОўНЇТПMНЇОpНЇТ≤Т≥ПCН ЇО 3ТfЇ =Г]Ш{JaM11.moveto: .moveto =>-- (Sets the current position to the given position.).rmoveto: .rmoveto =>-- (Adds x,y to the current position and sets the current position to thecomputed position.).drawbox:.drawbox =>-- (Draws a box with the given lower left corner and upper rightcorner. The draw position is left at the lower left corner.).drawboxarea :.drawboxarea =>-- (Draws a filled box with the given lower left cornerand upperright corner. The drawposition is left at the lowerleft corner.).drawspline:....drawspline =>--(Draws an open ended curve through n given points. Thiscurve is a natural spline consisting of n cubics.).drawcspline:....drawcspline =>--(Draws a closed curve through n given points. This curveis a natural spline consisting of n+1 cubics.).drawblob:....drawblob =>--(Fills a closed curve through n given points. This curve is anatural spline consisting of n+1 cubics.).drawcubic:.drawcubic=>-- (Draws a cubic with the givencoefficients.).beziertocubic:.beziertocubic=> (Converts four Bezier controlpoints to a parametric form of a cubic.).startpath:.startpath =>-- (Starts a path for the area generation machinery.).starteopath:.starteopath =>-- (Starts a path for the area generation machinery except that even/odd parity isused to determine interior.).enterpoint:.enterpoint =>-- (Enters the given point into the current path.).entercubic:.entercubic =>-- (Enters the given cubic into thecurrent path.).newboundary :.newboundary => -- (Starts a new boundary in the current path.).drawarea:.drawarea => -- (Fills the interior of the areas comprising the current path. Also deletes the path.).erase:.erase => -- (Erases all area inside the current clipping regions.).setclip:.setclip => --(Sets the current clipping region to be the given rectangle.).addclip:.setclip => --(Adds the given rectangle to the set of clipping regions.).resetclip:.resetclip => -- (Resets the list of clipping rectangles to nil.).enableclip:.enableclip => -- (Enables the clipper.).disableclip:.disableclip => -- (Disables the clipper.).testnoclip:.testnoclip => .true if clipping disabled else .false..initboxer:.initboxer =>-- (Initializes the boxing machinery.).readboxer:.readboxer=> (Reads the current box values.).boxcorners:.boxcorners => (convertsbox parameters to four corners).stopboxer:.stopboxer=>-- (Stops the current boxing calculation).testbox:.testbox =>-- (tests a given box against the current clippingregions).testboxin:.testboxin=> .true if tested box is in..testboxout:.testboxout=> .true if tested box is out..paint: .paint => -- sets the painting function (see bitblt).texture: .texture =>-- sets texture (4x4 bit pattern in low half of integer)..touch:.touch=> (yields x,y position of mouse at time when the red button is lifted. The returnedvalues are in the current coordinate system.).mouse:.mouse=> (yields x,y position of current mouse position. The returned values are in thecurrent coordinate system.).setfont:.setfont=> (sets the current font.).drawchar: .drawchar => (Draws a character at the current drawposition and updates the draw position toreflect the width of the character.).erasechar: .erasechar => (erases a character at the current drawposition and updates the draw position toreflect the negative width of the character.).drawstring: .drawstring => (Draws a string at the current drawposition and updates thedraw position to reflect the length of the string.).getstringbox : .getstringbox => (Returns the boundingbox of the given string.).getstringwidth : .getstringwidth => (Returns the length of the given string.)Error and User Definable CommandsCommands in this group are used in the JaM system but either have no definitions or are givensome default definition which is meant to be changed. Included in this group are all JaM errors,and some miscellaneous debugging commands.When an error occurs in the JaM machine (e.g. stackunderflow), the JaM machine executes a fixedidentifier for that error. It is the intent of this mechanism that the user define these names to beprocedures that are appropriate to the user's application. The current list of error names is:НЇОfЯsНG?НЇОbAyНЇТПGНЇОaНЇТвП.ТьП.Н ЇО_фТНЇО^┴НЇТЁП8ТЄП(Н ЇО]KТП<НЇО\Т┘П:Т├П7Н ЇОZпТП@НЇОY⌠ НЇТ╒П-ТёП2Н ЇОXUТП2НЇОWНЇТ≥ПMТ Н ЇОUзТП.НЇОT²НЇТ≤ПaТ≥Н ЇОS_ТП)НЇОR" НЇП3Н5ЇТ│ Т┌Н ЇОPД НЇОOї НЇП/Н5ЇН ЇОNiТІП2ТЇН ЇОM,ТП(НЇОKН НЇТ─ПDНЇОJ╠НЇТ⌠Т■ПQН ЇОIsТНЇОH6 НЇПGНЇОFЬ НЇТЗПLТШН ЇОE╩Т НЇОD}ПMНЇОC@НЇТ░ПNТ▒НЇОBНЇТПDНЇО@еНЇТПП`НЇО?┤НЇТП]НЇО>J НЇПBНЇО= НЇП)НЇО;оНЇП+НЇО:▒ НЇП7НЇО9T НЇП4НЇО8 НЇПRНЇО6ы НЇТЄП\Т╣ Н ЇО5⌡ТНЇО4^ НЇТ─П6НЇО3 НЇТцПYТдН ЇО1ЦНЇО0╔ НЇТП(НЇО/h НЇП*НЇО.*НЇПEНЇО,МНЇПOНЇО+╞НЇТ°П1Т²П1Н ЇО*rТП-НЇО)4НЇТЄТ╣ПGН ЇО'ВТНЇО&╧НЇП1НЇО%|НЇТ┬ Т┴ПSН ЇО$>ТП$НЇО# НЇТ─Т│ПGН ЇО!цТП.НЇО ├ НЇПOН ЇОHП3НЇОНЇПPН ЇОмНЇО░ПTНЇО╚pП!НЇОШsТ╘ПPТ╙НЇОwТ·ПMТ÷НЇОСТП*НЇО КТ░ПNТ▒НЇОgТ⌡П4Т°П1НЇО ЦТИТЙП?ЪNЇ °=Г]oяJaM12.undefkey: A dictionary lookup failed. when this identifier is executed the offending name is on theoperand stack..longname: A file name passed to .run or .bytestream is too long (256 chars). The contents of the stackcontains the offending command plus its input parameters..badname: is generated from an attempt to create a stream with the given name. This error can come from either the .run command or the .bytestream command..typechk: a command is executed which has been passed objects of the wrong type on the stack. Boththe command and the original arguments are on the operand stack when .typechk is executed..dictfull: an attempt to define a new entry into a full dictionary has occurred. The offending commandand the argument prior to the call are on the stack..stkundflw: an attempt to retrieve an argument from an empty stack has occured..syntaxerr: an isolated right paren has been found by the scanner..overflow: numeric overflow has occurred in scanning a number..stkovrflw: a stack has overflowed. This error may come from various parts of the JaM machine. Whenthe error occurs, all stacks are stored into arrays and put on the operand stack in the order:opstack, dictstack, execstk..rangechk: some string or array operation is attempting to store out of bounds.Certain debugging commands are provided in JaM. These commands are executed only in certaincontexts. With these commands it is straightforward to build both tracing facilities andbreakpointing facilities. The commands include:.singlestep: This command puts execution control into single step mode. When in this mode, executioncontrol puts each object (except commands), as encountered, onto the operand stack. It thenexecutes the identifier ".step" which the user should have previously defined. After executing.step execution control executes the object that was on the operand stack, and continues..runfree: Takes execution control out of single step mode..interrupt: Is executed when the key (spare2--below the "_" key) is pressed. This command is definedto be equivalent to .stop. This command is used to get out of infinite loops..step: is used with .singlestep (see above) and has no default definition.The Programming and Use of JaMBecause JaM is quite different from other programming languages, it is appropriate to give hints onhow JaM is programmed and how to put JaM to good use. The following paragraphs will givesome of these hints.1. The JaM input language has very little syntax. This attribute is both good and bad. Thelack of syntax is good because a uniform representation is attained. The lack of syntax isbad because the code is hopelessly unreadable. In JaM it is almost true that any line ofcode can do anything (given the appropriate redefinitions of identifiers). Because of thisproperty of JaM code, it is desirable to do several things when programming. First,document each function as it is written (there are utility functions "/def" and "/xdef" tohelp with this). Second, use naming conventions for funtions that all belong to a given class(you have noticed the convention of starting each intrinsic command name with "."). Thelatter convention will allow a person reading the code to tell what catagory a function is inby its name.2. Since JaM is a stack oriented machine the user must mentally keep track of the contents ofthe stack. It is easier to program JaM if each routine performs only one function and isvery short. Normally a JaM routine should be at most one or two lines long. For example,suppose we wish to use the absolute value of a given number, then rather than introducethe code in line, it is desirable to write an "abs" function and then use that function e.g.(abs)(.dup 0 .lt (.neg) .cvx .if) .cvx .defAlso if complex parameters are being passed to JaM control statements, it is better to namethe parameters rather than have lines and lines full of parentheses. For example:(func)(-some kind of test- (---НЇОfЯsНG?НЇО`ҐyНЇТFП[НЇО_─ НЇО^BНЇП_НЇО]П9НЇО[гНЇПZНЇОZ┼НЇП8НЇОYLНЇПZНЇОXПZНЇОVяНЇП]НЇОU■П4НЇОTV НЇПEНЇОS НЇП8НЇОQшНЇП5НЇОP· НЇПYНЇОO`П^НЇОN#НЇОLбНЇПFНЇОI╨sТ√П0Т≈П,НЇОH6Т ПJТ!НЇОF╡ТП0НЇОDy НЇТFПYНЇОBжП\НЇОA≤П^НЇО@[ПYНЇО?НЇП2НЇО=Ю НЇПZНЇО<╒ПNНЇО;eНЇПEНЇО6ыpТНЇО3ґsТ┬ПcНЇО2)Т╞Т╟П<НЇО0╔ТН1О-zТ·ПXТ÷Н╛О+ЖТ╗ПWТ╘Н╛О*rТїПVТ╗Н╛О(НТ╛ТґПGН╛О'iТМ ТНПHН╛О%ЕТ═П2Т║wswsН╛О$aТ┤ПWТ┬Н╛О"щТ≈Т≤ПGН╛О!YТ░П9Т▒П$Н╛ОуТН1О╙Т░ПNТ▒Н╛О&Т°П$Т²П6Н╛О╒Т│П0Т┌П*Н╛ОТ╒ТёПHН╛О Т·Т÷wsП*Н═ОnwТП+Н═ОCsТ┼П[Н═О©ТПRН═О⌠wxwxЪvЇL=Г\©SJaM13---lots of stuff if true ------)(------lots of stuff if false------).ifelse .cvx .exec).cvx .defShould be written:(func)(-some kind of test- trueaction falseaction .ifelse .cvx .exec).cvx .def(trueaction)(--lots of stuff if true--).def(falseaction)(--lots of stuff if false--).defUsing this style the person reading the program can visually capture the logic of thefunction without having to parse the branches of all the control statements.3. The JaM machine saves its virtual memory when a normal exit is taken (by executing the".quit" command). When JaM is reentered this virtual memory is restored and therefore alldefinitions are restored. This state saving property and the potential size of the virtualmemory makes JaM quite different from other programming languages. Because of thisdifference JaM is used in ways that are unusual. For instance: It is quite reasonable tostore permanent data in the JaM virtual memory. e.g. documentation, design information,notes to yourself, etc. This is done by creating and organizing dictionaries that deal withinformation in a way natural to the user. It is also easy to keep permanent procedural databases in JaM which makes it ideal for design engineering applications. Large, complex datastructures can be built and easily maintained within the JaM virtual memory.4. The JaM virtual machine is written in mesa and is designed so new intrinsic commands, alsowritten in mesa, can be easily interfaced (at run time) to JaM. This capability provides twoadvantages. The first is that the user can try ideas for functions in the JaM environment,and when performance becomes a problem recode the new functions in mesa and makethem intrinsic. It also has an advantage in that mesa user's can interface suitable routinesto JaM and use JaM as an executive for those routines. In the interface between JaM andMesa, mesa programs can use the JaM virtual memory as well as the JaM interpreter andexecution machinery. Some of these capabilities will be discussed in the last section of themanual. (to be continued)НЇОfЯsНG?НёОbxТНёО` xwНёО_xНёО]▓НёО\wН═ОXБsН═ОUЇwxwП4Н═ОT3xwН═ОR╞ xwН═ОO┐sТэ ТщПKН═ОMЪТПLН1ОJтТ╚Т╛ПGН╛ОIPwsТ┼ПOТ▀Н╛ОGлТ©ТюПBН╛ОFHТ╣ТІП3Н╛ОDдТїПWТ╗Н╛ОC@Т╘П/Т╙П(Н╛ОA╪ТёТєП?Н╛О@7Т┬П#Т┴П9Н╛О>ЁТ▌П8Т▐П"Н╛О=/ТПLН1О:Т▄ Т█ПSН╛О8─Т┤П-Т┬П0Н╛О6ЭТ°Т²ПKН╛О5xТІТЇП<Н╛О3ТТ°П6Т²П'Н╛О2pТ░П6Т▒П"Н╛О0ЛТ²Т·П:Н╛О/hТ Т⌡ПHН╛О-ДН1О*╦ТЪЇ$╗;mCcъ TIMESROMAN HELVETICA TIMESROMAN TIMESROMAN LOGO TIMESROMAN TIMESROMAN HELVETICA HELVETICA HELVETICAїІв ;к% / ╛8 ┘A/M ґW!]ЪЪj/`^∙Ю*фЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪ jam.bravowyattSeptember 5, 1980 4:09 PM