deer manual (deer project, 2006-2008, Antonio Maschio @ ) Last updated: December 05, 2008 Index ----- 1. Introduction 2. The Dartmouth Operating System emulator 2.1 deer options 2.2 First run 2.3 Customizable variables 2.4 System commands 2.5 Tips on manipulating files 3. Conclusions 4. References 1. INTRODUCTION ------------ deer is an acronym for Dartmouth Environment Elementary Renderer; though there are already emulators of the Dartmouth OS (on which the original BASIC language environment ran), more complete and capable of running BASIC and ALGOL (see [1]), I wanted to build my own, and I wanted to do it in two languages: - deer, the "operating system", in bash, due do its extreme ability to deal with strings (while lacking floating numbers); - dib, the BASIC interpreter, in C, for its speed and its math functions. This was particularly interesting because I had to dive into a more complete bash and C theory before coding, and I was very pleased by that. I spent one year (or so) in building deer, partly because of my need to study, and partly because I have a family that occupies my head and time, and leaves me nights bits for coding. Finally the OS was ready, but my BASIC was far to be completed. It's not that easy to program an algebraic language (my experience was limited to stack languages, which are very easy to build). You can read the rest about this story in the file 'dib manual.txt'. 2. THE DARTMOUTH OPERATING SYSTEM EMULATOR --------------------------------------- deer is not a complete replica of the original Sixties OS. It's rather a subsystem, but as such it can create, edit, run, delete BASIC programs, and has some other features, along with minor differences compared to the original OS. I discarded all the connection commands (network, kermit, and so on) and all the documentation files (which couldn't be applied to my work); besides, documentation takes its time to be written and read, so I limited it to a HELP screen. There are no games, no web browsers, no mail readers. Nonetheless, you will be able to build your own BASIC programs. To tell the truth, I'm conscious that this emulator goes beyond the real capabilities of the original OS; in all, deer is probably a subset of an Eighties OS version, rather than a Sixties on. In any case, I set it to make it work, to be rather useful; all the commands contained into [2] have been implemented, along with a bunch of others to ease the programmer's task. 2.1 deer OPTIONS ------------ Usage: deer Options are: -h --help Give this help and exit -l --lower-allowed Disable conversion of input characters to upper case -t n Set auto shutoff to n seconds (n=0 disable shut-off) -v --version Show version and exit -x --extended-features Enable extended BASIC features (pass -x to dib) Option -x is passed 'as-is' to dib (if you use another interpreter, don't set it in deer because it may have a different usage). By default, auto shutoff is set to three minutes (180 seconds). 2.2 FIRST RUN --------- The first time you run deer, it will create a hidden directory into your $HOME, named '.deer/' . After you log in, a subdirectory will be created with the first 6 characters of the user number turned to upper (e.g., if you type myra8697 at the prompt, the directory .deer/MYRA86 will be created); all subsequent logins with MYRA86 will use the same directory, and different users will have different directories. So you can have many projects, each under a particular user. Please note that the original DTSS accepted a login username made of six numbers or one letter and five any characters; deer is less restrictive, in this regard, and will accept any series of characters, cutting them to six and turning them to capitals. If you want, you can copy the content of folder 'USER/' (contained into the package) to you user home: you will have a complete set of examples and a working environment ready to go; type $ cp -r USER/* ~/.deer/MYRA86). from within the deer unpacked installation directory. When you run deer, yor will see the screen cleared, and a few data will be displayed on the upper left corner: DARTMOUTH COLLEGE TIME SHARING, T1 04 OCT. 2008, AT 13:36, 011 USERS. (You will see different time values and different logged users.) T1 means Tonibin 1, and is the machine simulated by deer (the original was D1, but I believe I had to change it). At this point only three commands are available: - HELLO to start a sequence to establish a connection to the system; - HELP to print a couple of help screens with all the available deer commands, all aimed to help you in writing, maintaining, saving, retrieving, printing and running your files and programs. - BYE (also GOODBYE) to log off (there's an automatic log off if you don't type nothing for 3 minutes - see options below for changing this behavior); 2.3 CUSTOMIZABLE VARIABLES ---------------------- Before running deer, you can change some default variables values contained in the first lines of the script. They are: deered ------ It contains the deer editor name, enclosed into double quotes. Default editor is vim, but you can use the one you prefer (emacs, vile, nano etc.), even a graphical one, if you want to. deerless -------- It contains the deer viewer name, enclosed into double quotes.The viewer is used to examine a file without changing its contents, so you may use a pure viewer, here, or you can even set it to an editor. INTERVAL -------- It contains the number of seconds for the autologoff procedure. Any value greater than 0 sets the option for that number of seconds (default is 180, which is about three minutes). If you put here 0, the timing feature is disabled. noTiming -------- It contains the flag for disabling ($TRUE) or enabling ($FALSE) the timing feature. A value of 0 for INTERVAL sets automatically noTiming to TRUE, but you can disable the feature without changing INTERVAL (for a temporary usage, for instance). Default is $FALSE (Timing enabled). DELAY ----- It contains the delay factor for an empty cycle to be performed to slow down the listing of a BUILD or a BASIC file. On my emac G4 1.42 GHz, a value of 1000 corresponds to about 2 lines per second (a speed comparable to the one of the old dear 8086). Default is (aha!) 1000. basic ----- (Important) It contains the name of the executable of a basic compiler or interpreter of your choice. Of course, by default, deer comes with dib. EF -- For dib: it contains all the options you want to pass to it, and in particular the Extended Features option "-x"; by default it's void, so that deer will execute only standard BASIC (version III) programs. For other compilers/interpreters: you can put any meaningful option you want to pass to your BASIC. Important: don't change anything else, unless you know what you're doing. 2.4 SYSTEM COMMANDS --------------- Notes "before" -------------- 1) in the following: - a PROGRAM file is a BASIC listing (with each line starting with a number); this kind of file may be executed. - a BUILD file is a text file in free format; this kind of file cannot be executed; it's useful for writing documentation files. - CURRENT is the current file (PROGRAM or BUILD). - ARG is the (sometimes optional) argument of a command. Commands belong to three classes: - Class 1 commands require a value, so if you don't give an argument, you will be requested to give one; - Class 2 commands act on CURRENT file if no argument is given, or on the file whose name match the argument; - Class 3 commands act on CURRENT file only, or are general purpose commands requiring no arguments The class is exposed into square brackets before the command name. 2) any command (except HELP, HELLO and LIST--) is recognized by means of the first three letters (so CAT and CATALYTIC will all act as CATALOG). But beware: you have to type HELLO, HELP and LIST-- in full, though, to make them work. 3) the string WHAT? is printed if you type a command which is not recognized. 4) the same condensed information (or so) can be obtained with HELP. 5) some information about I/O transfers and CRU (Computer Resources Usage) have been grabbed by iostat. The iostat program I use comes from Mac OS X, the system on which I work, thus it's a BSD version. Linux users and other UNIX implementations may have a different (sometimes very different) version of the program, capable of giving very diverse data, but not compatible with the settings in deer. In any case don't worry: These data wont' interfere with BASIC. *** Here's the command list (text enclosed into {} is typed by you). [3]ACCOUNT Give some accounting information Note: original data were CRU, SECS, I/O, CORE, written on one line. I don't know exactly what's the meaning of these data, but I cannot replicate them in bash on a UNIX machine. So I changed them to reflect more practical needs for the deer user, and they will be reported in two lines, the first with headers, the second with values. Data will be: - CRU (here Computer Resources Usage): it uses iostat for retrieving idle percentage of the system, subtracting it from 100 and yielding the global system resources usage. - I/O (not knowing the original meaning of that): it expresses, through iostat and in terms of MB/s, the amount of exchanged memory. - LOGTIME: it expresses the total account session time. - RUNS: it expresses the total of RUNs (assuming this has some meaning for moderns systems) SECS and CORE, two original data of the ACCOUNT command, have been 'forgotten', since I have no idea what they were and how to parallel them with those on my UNIX machine. [1]APPEND Add file {name} to the end of CURRENT file. Usage: {APPEND} APPENDING FILE NAME--{name} or {APPEND name} Note: If you APPEND a BUILD file to another, their content won't overlap. If you APPEND a PROGRAM to another, the appended file will overwrite all lines whose number appears in both files. If you APPEND a PROGRAM to a BUILD file it will appear with its line numbers as a listing queued to the BUILD file. You cannot APPEND a BUILD file to a PROGRAM. A warning appears when you try to do so. [3]BUILD Allow entering free text on CURRENT file. To terminate input press RETURN three consecutive times. CAUTION! If you type BUILD with an existing PROGRAM as CURRENT, its state will turn to BUILD, and a subsequent REPLACE will overwrite the PROGRAM file. So, before BUILD, be sure to open or create a BUILD file. [3]BYE/GOODBYE Terminate current session. If CURRENT has not been save to disk yet, the system will invite you to use SAVE or REPLACE; this advice will appear once only; if you save the file or not, when you retype BYE you'll be allowed to exit anyhow. [3]CATALOG Give information about user saved files in the CURRENT catalog [1]CREATE Create new catalog under CURRENT with name {name}. Usage: {CREATE} CATALOG NAME--{name} or {CREATE name} [3]EDIT Edit CURRENT saved file with user editor (see variable 'deered') [1]ENTER Changes CURRENT catalog to catalog {name}. Usage: {ENTER} CATALOG NAME--{name} or {ENTER name} [3]HELLO Start a sequence of questions for logging in. Here's an example of output: {HELLO} 0.38 CRU USER NUMBER--{MYRA86} SYSTEM--{BASIC} NEW OR OLD--{OLD} OLD PROBLEM NAME--{LINEAR} READY. [3]HELP/EXPLAIN Print a help screen (in future versions, EXPLAIN may expanded to show help for each command) [3]HOME Shortcut for enter *MYCAT; re-enters main catalog [3]IGNORE Retrieve saved file, losing all changes made [3]LENGTH Give length of CURRENT file [3]LIST List CURRENT file (BUILD or PROGRAM) [3]LIST--XXXXX List CURRENT BASIC file starting from line XXXXX. Mind the two dashes following LIST. [1]NEW Create a new empty file and set it CURRENT with name {name} and state PROGRAM (you can safely type BUILD after NEW, because the file is empty). Usage: {NEW} NEW PROBLEM NAME--{name} or {NEW name} [1]OLD Retrieve an existing file with name {name} and set it CURRENT; the state will be PROGRAM if the first character of the file is a number, otherwise it will be a BUILD file. Usage: {OLD} OLD PROBLEM NAME--{name} or {OLD name} [2]PUNCH Send CURRENT file to printer. Usage: {PUNCH} Send file {name} (which may be different from CURRENT) to printer. Usage: {PUNCH name} [1]RENAME Change name of CURRENT file to {name}, retaining the state (PROGRAM or BUILD). Usage: {RENAME} RENAME PROBLEM NAME--{name} or {RENAME name} [3]REPLACE Save CURRENT file replacing previous contents. [3]RUN Execute CURRENT PROGRAM file; an implicit SAVE/REPLACE is done, so you don't need to type SAVE or REPLACE, before running a program; this is because sources to run must be taken from the disk file, and they must be the more recent too! The same was applied in the 1964 OS (see the October 1964 BASIC manual for examples in which a program typing is directly followed bu a RUN). [3]SAVE Store CURRENT file to disk if file does not exist (if file exists, a warning will appear; in this case use REPLACE). [3]SCRATCH Empty CURRENT file, retaining the state (PROGRAM or BUILD). [3]SORT Sort contents of CURRENT BUILD file; a PROGRAM is always sorted automatically in memory and during saving. [1]SYSTEM Change system language (fake) to {name} (actually, only BASIC is accepted). Usage: {SYSTEM} SYSTEM NAME--{name} or {SYSTEM name} [2]UNSAVE Delete CURRENT file from disk. Usage: {UNSAVE} Delete a file or a catalog from disk. Usage: {UNSAVE name} CAUTION! 1) Don't use this command thoughtlessly! Remember that, if you type UNSAVE, deer **won't** ask you for a file name; rather, IT WILL DELETE CURRENT FILE! If you want to delete a different file, you **have** to type its name after UNSAVE! 2) If used with catalogs (directories), UNSAVE will delete the catalog ***AND ALL ITS FILES***! Nothing is asked, nothing is written. In all, use it with GREAT CARE! [3]USERS Give number of currently logged users (fake) It's a random number to give the impression the system is not used by you only! [2]VIEW Show CURRENT file without editing it (using user viewer). Usage: {VIEW} Show file {name} with user viewer. Usage: {VIEW name} [3]WHAT Give information about current session in the form: CURRENT FILE MOTION COMPUTER T1 (deer system) USER NUMBER 242424 SYSTEM BASIC SEARCH PATH :242424 *** Notes "after" ------------- 1) After any command performance, successful or not, a READY will be printed so that you may type next command 2) Please, pay attention to the UNSAVE command: if you happen to type UNSAVE inadvertently, you can recover the file (because it's still in memory) typing SAVE immediately after it. File will be rewritten. 3) The command EXTEND (which is off-topic) has some meaning only for dib, the BASIC interpreter. It may be used to activate dib's extended features from console, if you have forgotten to start deer with option -x. 4) The SAVE and REPLACE commands play a similar role: the first must be used the first time you write a file to disk; the second must be used when you want to replace what's stored on disk with what's on memory, updating file's contents. 5) The command EXIT has been given to offer a helping hand to shell users. It behaves in the very same way of BYE. 2.5 TIPS ON MANIPULATING FILES ------------------------- In the following, I assume that: is the directory where we are is the destination directory is the name of current file is a new name for current file or a name of an existing file other than current SAVE and REPLACE must be used with the following cautions: - SAVE if the file doesn't exist - REPLACE if the file exists Anywhere I write SAVE you must read SAVE or REPLACE, depending on the file existence. 2.5.1 How to move CURRENT file to another directory -------------------------------------------- UNSAVE ENTER SAVE This procedure is not safe, because if something happens to your system between UNSAVE and SAVE the file is lost, though it's very unlikely since it's a question of a few seconds; in any case, if you want a safer (and longer) procedure: ENTER SAVE ENTER UNSAVE 2.5.2 How to rename an existing file ------------------------------ UNSAVE RENAME SAVE A safer procedure: RENAME SAVE OLD UNSAVE 2.5.3 How to move and rename a file to another directory -------------------------------------------------- UNSAVE ENTER RENAME SAVE A safer procedure: ENTER RENAME SAVE ENTER OLD UNSAVE 2.5.4 How to copy a file in the same directory (renaming it) ------------------------------------------------------ RENAME SAVE 2.5.5 How to copy a file in another directory with the same name ---------------------------------------------------------- ENTER SAVE 2.5.6 How to copy a file in another directory with another name --------------------------------------------------------- ENTER RENAME SAVE 2.5.7 How to delete a file -------------------- UNSAVE 3. CONCLUSIONS ----------- deer is an emulation, written in bash: don't expect it to be fast, precise, robust. After all it's more like a game. And remember that dib, the BASIC interpreter, may be used all alone, as UNIX program, and in this case deer may be forgotten. But, please, if you want to help me improve this program, write me tips and snippets of code to better it or make it compatible with other UNIX systems. I hope you like deer. It's GPL: Enjoy! 4. REFERENCES ---------- The following documents were very useful to understand basic principles and set up general behaviors: [1] The dtss simulator, with many information about the system, can be found at http://www.dtss.org/ - in the site you can also find a link to an emulator written in java and running online (a registration is requested in order to use it - I didn't). [2] "Dartmouth BASIC manual" for version II, October 1964, is available as a pdf file at http://www.bitsavers.org/pdf/dartmouth/BASIC_Oct64.pdf [3] "Programming with BASIC", by Byron S. Gottfried, edition 1, 1975 (Italian version, titled "Programmare in BASIC", Schaum 1982). [4] "Dartmouth Time-sharing System - a brief description", from october 1964, outlines the system in which the OS was implemented, and is available as a pdf file at http://www.bitsavers.org/pdf/dartmouth/DTSS_descr_Oct64.pdf *** *** (written with gvim)