GEMini Atari

home *** CD-ROM | disk | FTP | other *** search

/ GEMini Atari / GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso / files / cli / gulam103 / gulam.inf < prev next >

Wrap

Text File | 1993-10-03 | 48.7 KB | 1,306 lines

Info file gulam.info, produced by texinfo-format-buffer -*-Text-*- from file g.txi  File: gulam.info Node: top, Up: (DIR), Next: usage Introduction ============ *Gulam* is a shell (i.e., a command line interpreter) for AtariST computers. It contains some 60+ built-in commands, provides file name completion a la *TENEX*, has history, alias and rehash facilities, and integrates the shell with microEmacs easing the editing of commands being issued. Among the built-in commands are `egrep' a regular expression based string pattern finder. `te' a simple terminal emulator. `rx/sx' Xmodem file transfers `pr' a text file printer with pagination. In common usage, it resembles *csh* of *Unix 4.xBSD*; Gulam's control structures, lexical conventions and other details are, however, quite different from csh. While I have borrowed ideas from other shells (such as Korn shell), I made no heroic attempts to be compatible with any. Where possible, I have tried to make *Gulam* less `surprising' in what it does. The word *Gulam* is pronounced as *Gulaam* in Hindi/Urdu, and means an obedient servant. *Gulam* is a free program; you are encouraged to give it to others, but at no cost. However, the source is copyrighted (i.e., it is not in the public domain) and will be part of a book on systems programming I am writing. The source is available on request, with the usual provisos regarding material in manuscript form. This manual is written in the *TeXinfo* format (the *GNU* documentation format); a laser-printed TeX-typeset copy of this 40-page manual is also available at cost ($2.00). I am advised to include a disclaimer because there are unreasonable people out there. "I make no warranty with respect to this manual, or the program it describes, and disclaim any implied/explicit suggestions of usefulness for any particular purpose. Use this program only if you are willing to assume all risks, and damages, if any, arising as a result, even if it is caused by negligence or other fault." The first release of this program did contain bugs. The present beta-version (dated Sept 1987) is a result of fixing 15 bugs, 9 internal code improvements (about 180 lines of rewriting), 9 user-visible improvements. I am sure this version too has bugs, and undesirable features. Users are encouraged to tell me both good and bad things about this program. Many thanks to: Jwahar R. Bammi for help in every aspect during the writing of the shell and this manual, and demanding that *Gulam* be a `reasonably full fledged' shell; David Conroy for writing a `small is beautiful' microEmacs; Henry Spencer for the regexp(3) package that is now built into *Gulam*; AtariST for its value to price ratio. The program was developed using Megamax and Mark Williams C compilers. It now uses my own malloc.c. Comments on the Present Implementation ====================================== I find the present implementation eminently useable, and indeed use it all the time, in preference to other shells. Here are some features that I (still) find unsatisfactory. Control structures are quite ad-hoc, and incomplete. I had a tough time in decreeing that the typical `+-*/()[]{}' are not delimiters; but that decision made *Gulam* smaller. Here is a list (complete?) of things new and/or diffrent from the alpha-version. 1. the bugs causing memory-lossage have been fixed. 2. an application program can now call one of *Gulam*'s routines that is equivalent to system() call. 3. an application program can now call one of *Gulam*'s routines that can receive keyboard input from the user, with all the facilities of `ue', and return the line input by the user. 4. `ue' can now insert-file. 5. stdout append-redirection (`>>') is now implemented. 6. a new sub-word consisting of three dots `...' expands to the list of all filenames rooted at the current or given directory. 7. doing a `set path <path-list>' will also cause an automatic `setenv PATH <path-list> ; rehash'. 8. `ue' can now fill-paragraph. 9. new shell variable `verbosity' controls how silent *Gulam* is. 10. cp will not copy directories and their contents unless given the `-r' flag. 11. `ue' can now use mouse movements as cursor movements (see mscursor). 12. diskettes can be formatted (single/double-sided) in TOS standard way. 13. the command mem can not only report the GEMDOS free-list but also the list of GEMDOS Malloc-ated chunks. 14. shaded background on the screen is provided for the `gem' command. 15. the keypad keys can be toggled to become numeric or extra-function keys. 16. there are 3 separate key-bindings for the one *gulam* buffer, and the one *mini* buffer, and all the regular buffers.  File: gulam.info Node: usage, Prev: top, Up: top, Next: lexical-conventions General Usage ============= The syntactic details of individual commands, and the specific rules that are followed in evaluating them are given later. This section is an overview of how the integration of `ue' with a shell is used. The moment you enter *Gulam*, you are in a ue-buffer called *mini*. Thus, all the typical `ue' text-editing functions are available, except commands such as `Visit-file', `Switch-to-buffer', etc. The `RETURN' key causes the entire line (on which the return is typed) to be evaluated. The output, if any, of the command you issued appears on the screen but does not enter any ue-buffer. The built-in command `ue' (without any arguments) takes you into the special ue-buffer named *gulam*; the output of (built-in) commands issued while you are in *gulam* does enter that buffer, which can be freely edited. The command `ue' FILENAME will read-in each of the named files into their ue-buffers. From within `ue', you can `Switch-to-Gulam-buffer' (whose default binding is `ESC-g'). To conserve/manage memory, we release all `ue' buffers when `ue' is exited in the usual way (i.e., `UNDO', or `⑧-⇨'); exiting temporarily via the `ə' does not release memory. Issuing a substantial number of commands through the *mini* buffer, without entering `ue' in between, will accumulate all the commands (but not their output) in the *mini* buffer, and soon there will be a memory shortage. To prevent this, enter and exit `ue' once in a while, or delete (using `⇦', or `Delete') characters in the *mini* buffer.  File: gulam.info Node: lexical-conventions, Prev: usage, Up: top, Next: command-processing Lexical Conventions =================== All input to *Gulam* is case-sensitive; on the other hand, TOS file names are case-independent. The evaluation of the command line begins by dividing it into "words" and "subwords". The "word-delimiters" are space, tab, return, line-feed (the so-called white chars), single-quote, double-quote, semicolon, and the vertical-bar. Note that `+-*=/()[]{}' etc. are *not* "word-delimiters". A "word" is either * A sequence of chars not containing any "word-delimiters". * A string of arbitrary chars enclosed in single/double-quotes. * A `semicolon'. * A `vertical-bar'. Eg, the lines below date 01-22-87-22:08:34 #sets the TOS and ikbd date-time alias c 'mmcc e:\gulam\$1.c; cp e:\gulam\$1.o .' if {$x + $y ==23 } if { -e $1.c } would be divided into the words (shown between slashes) /date/01-22-87-22:08:34/#sets/the/TOS/and/ikbd/date-time/ /alias/c/'mmcc e:\gulam\$1.c; cp e:\gulam\$1.o .'/ /if/{$x/+/$y/==23/}/ /if/{/-e/$1.c/}/ "Comments" begin with a word whose first char is `#', and end at the end of line. A `#' embedded in the middle of a word does not begin a comment. The "subword-delimiters" are the characters in `!@#$%^&-=+`~{}:;'"\|,.<>/'.  File: gulam.info Node: command-processing, Prev: lexical-conventions, Up: top, Next: batch-files Outline of Command Processing ============================= The command line is string pre-processed as described below before invoking it as a command. * History substitutions occur first. * Dollar substitutions, wiggle expansion, meta expansions occur second. * Split the resulting line into semi-colon separated commands. * For each command, alias expand it, and dollar-substitute. * Execute each resulting command.  File: gulam.info Node: batch-files, Prev: command-processing, Up: top, Next: buffers Batch Files =========== A "batch file", also called a shell file, is a text file containing *Gulam* commands, both internal and external. Such files must have the extension `.g' for them to be recognized as commands. See the section on `gulam.g' for an example shell file. In processing these files *Gulam* uses `ue' buffers. So, if you have `ue' as a command in a batch file, and then exit `ue' with either `UNDO' or `⑧-⇨', all the buffers (including the one holding the batch file) will be released, and *Gulam* will surely crash. So, do *NOT* include `ue' as a command in a shell file. Redirections to/from batch files do not work properly.  File: gulam.info Node: buffers, Prev: batch-files, Up: top, Next: command-line-editing Buffers: Gulam, Mini and Regular Buffers ======================================== Once you invoke *Gulam*, you are always in one of the microEmacs (*uE*) "buffers" which are reservoirs of text. In this program, a typical line-oriented command shell is integrated with microEmacs. This necessitated two special kinds of buffers, named *gulam* and *mini*, along with the regular buffers. Right after you invoke *Gulam*, you are in *mini*, and each line you type is taken as a *Gulam* command, and executed. Any output produced by such a command is displayed on the screen but not entered into any microEmacs buffer. Should you desire to capture such output into a buffer, enter the *gulam* buffer by typing `ue' without any arguments. If you are editing in a regular buffer elsewhere in microEmacs, pressing `ESC-g' (see `kb' below for `switch-to-Gulam-buffer') will get you into *gulam*. While you are in *Gulam*, the `RETURN' key behaves as it does in *mini*. All command input, including giving the names of buffers within `ue', takes place in *mini*. The window for this buffer is always at the bottom of screen, and usually only one-line high. (Some of you may want to experiment with `⑧-ə' and `⑧-z'.) You enter the *mini* either because (A) you are outside the normal microEmacs, or (B) a command such as `Switch-to-buffer' wants to read your input. The *mini* is like any other buffer except for the bindings of a few keys, and the disallowing of `ue' functions that change/switch buffers/windows/files. One of these exceptional keys (in *mini*) is the `RETURN' key: it will submit the entire line -- even if the cursor was somewhere in the middle of the line-- to the shell (case A), or to such `ue' commands as `Visit-File' (case B). Until you press `RETURN', you can edit not only that line but others in *mini* just as you would in regular buffers. Note that unless you occasionally exit microEmacs with `⑧-⇨' or `UNDO', both *gulam* and *mini* buffers will keep growing, and you may run out of memory.  File: gulam.info Node: command-line-editing, Prev: buffers, Up: top, Next: invoking-gulam Command Line Editing ==================== Full microEmacs editing is available while typing the command. Thus, you can transopse chars by `④', and go to the beginning of the line by `⇧', and ⑨ank in a perviously deleted word, etc. In addition to these, there are three convenience features. After typing the first few chars of a file name, if you press the key marked `INSERT', *Gulam* will attempt to complete the file name; pressing `CLR/HOME' will show all possible completions. Secondly, if you type `!n' and then press `INSERT', you will see that the history-expanded result is brought into the buffer, which can then be further edited if necessary. Thirdly, pressing the `DOWNARROW' key will cycle you through the previous commands.  File: gulam.info Node: invoking-gulam, Prev: command-line-editing, Up: top, Next: Glossary Invoking Gulam ============== *Gulam* can be used in four ways. Two of these four use `TOS' variable named `_shell_p' (at `0x04f6L'). This (supposedly) contains a pointer to a routine that takes a string as an argument and executes it as a shell command. *Gulam* has slightly extented this. `*_shell_p', as set by *Gulam*, points the bottom of a (jump) table, which currently is: .long 0x86420135 / our magic number jmp getlineviaue_ togu_: jmp callgulam_ Thus, `*((long *) 0x04f6L)' == address of `togu_'. Before invoking either routine, it always is a good idea to check if the magic number is present. Let `mp = *((long *) 0x04f6L) - 12L'. Then, `*mp' better be `0x86420135'. 1. The most common usage is as an (outermost) interactive shell. Double-click on `gulam.prg'. Keep your version of `gulam.g' also in the same folder. 2. `int callgulam(p) char *p;' returns the status of executing shell command given as a string pointed by `p'. Let `fp = *((long *) 0x04f6L)'. Then to call this routine, you do `(*fp)(p)'. 3. `void getlineviaue(p) char *p;' returns in the user-supplied array of chars pointed by `p' the command line typed by the user. Full uE editing facilities are available in this inputting process. `p' must point to an array of at least 256 chars; longer input lines cannot be given. The line may contain control characters (inserted by the ^Q feature of `ue'). It is ascii NUL terminated. Let `fp = *((long *) 0x04f6L) - 6L'. Then to call this routine, you do `(*fp)(p)'. 4. For non-interactive use, *Gulam* can be invoked (from shells, from application programs via `Pexec()', or `callgulam()') with arguments. `gu 'ls -l' 'echo hello'' is similar to typing the two commands to the shell in interactive mode. `gu 'pwd' -c scrpt a b c d' does `pwd', and then invokes the (presumably valid) *Gulam* shell script named `scrpt.g' with `a b c d' as the script files arguments. Following the `-c' must be the name of a batch file. *Gulam* has no other options.  File: gulam.info Node: Glossary, Prev: invoking-gulam, Up: top, Next: top Glossary ========  File: gulam.info Node: builtins, Prev: Glossary, Up: Glossary, Next: cd Builtin Commands ---------------- A command executed directly by the shell is called a "built-in" command. The 62 built-in commands of *Gulam* are: alias dm endwhile help more printenv set ue cat dirc exit history mson pushd setenv unalias cd dirs fg if msoff pwd source unset chmod echo fgrep kb mv rehash sx unsetenv copy egrep foreach lpr peekw ren te which cp ef format ls pokew rm teexit while date endfor gem mem popd rmdir time df endif grep mkdir print rx touch  File: gulam.info Node: alias, Prev: Glossary, Up: Glossary, Next: cat alias ----- The `alias' built-in command works almost like a shell file but one that is stored in the internal data structures of *Gulam*. It often just specifies a shorter or different name for a command. alias cc c:\megamax\mmcc.ttp #1 unalias cc #2 alias c 'mmcc e:\gulam\$1.c; cp e:\gulam\$1.o .' #3 alias r 'echo $1.c $1.o; r' #4 alias #5 alias g 'echo $3 $1' #6 alias cg 'f:\cc.ttp -c -Ie:\gulam -DMWC e:\gulam\$1.c' #7 Alias without args (see #5) lists all the aliases that are currently defined. The command unalias (see 2) removes the def of an alias. Line 4 shows a recursive definition; try it out! If we invoke `g' as in `g a b c d e f' this is equivalent to `echo c a d e f'; i.e., all arguments above the highest that was used in a "$-substitution" are appended to the resulting command string before executing it.  File: gulam.info Node: cat, Prev: alias, Up: Glossary, Next: cd cat --- This command `catenates' files to the standard output (normally screen). By redirecting output, you can concatenate several files into a combined file. cat f1 f2 >f3 # f3 will now equal f1 followed by f2 cat f1 > prn: # print the file f1 as is; see also print and lpr cat f1 # show it on the screen; use ^S/^Q to stop/go  File: gulam.info Node: cd, Prev: cat, Up: Glossary, Next: chmod cd -- The `cd' command changes the current working directory; it also sets the shell variable named `cwd', the environment variable named `CWD'. If `cd' was given noarguments, it is equivalent to `cd $home'.  File: gulam.info Node: chmod, Prev: cd, Up: Glossary, Next: cp chmod ----- chmod [+-whsvm] FILENAMES `chmod' changes the read/write attributes of the files. The `+' flags have inverse effect to the `-' flags. The `+w' makes them read-write, and `-w' makes them read-only. The `+h' hides the files from directory searches; `+s' marks them as hidden system files; `-m' turns off the `archived' flag on the file.  File: gulam.info Node: cp, Prev: chmod, Up: Glossary, Next: date cp -- cp FILENAMES TARGET-DIR cp FILENAME1 FILENAME2 Copies files. In the first form, any number of files may be copied into the destination directory; files in the target dir will have their original names. In the second form, only one file is copied, and the new one will be named filename2. cp FNM FNM # will exit with status -1 cp -r D1 DIR2 # if d1 is a directory, this command # will create a dir named d1 in dir2, and # copies all the files in d1 to to dir2\d1 In the second example above, if -r option is omitted, cp will ignore any directory names in the list of source files. Use the -r option with caution. E.g., cp -r d1 d1\d2 # is dangerous will, assuming that d1\d2 is a directory, copy/create subtree d1 inside d2. But, the problem is that d1 will keep growing as a result until of course there is no more room on the target disk! A simple way to print a file as is, instead of using lpr or print, is to cp fnm prn: There is a `+t' option that gives the created target files the time and date of the source files. If you care about this, you may want to set up an alias as in: alias cp 'cp +t' $cwd and $CWD ------------- The shell variable named `cwd' (and env var named `CWD') holds the full path name of the current working directory.  File: gulam.info Node: date, Prev: cp, Up: Glossary, Next: df date ---- The `date' command, without arguments, prints the current date and time. With arguments, it sets the date and time. date 01-22-87-22:08:34 will set the date to Jan 22, 87 and time to 10:08:34 pm. Instead of hyphen, and colon, other delimiters can be used, as long as the whole argument of date is still one word.  File: gulam.info Node: df, Prev: date, Up: Glossary, Next: dm df -- df DRIVENAMES `df' shows the free space on the asked for drive(s); e.g., df a c f  File: gulam.info Node: dm, Prev: df, Up: Glossary, Next: dirc dm -- `dm' (drive map) gives a string of letters that stand for the installed drives.  File: gulam.info Node: dirc, Prev: dm, Up: Glossary, Next: dirs dir cache dirc -------------- To help do the Tenex file name completion efficiently, there is a cache of contents of directories. `dirc' shows the names of these dirs, and how many bytes are used by their contents. Unless you did a `set dir_cache 1', or you executed commands that only examine the file system the `dirc' has nothing to show since the cache is flushed at the end of each command. Try *Gulam* with `dir_cache' set to 1. Note however that this cache is updated only by commands that change the contents of a directory (such as `rm', `cp'). A rather annoying result is that even after you change the diskette in a drive, you may see the directory contents of the previous diskette listed. An `UNDO', `dirc -', `rm' with/without arguments will explicitly flush the cache.  File: gulam.info Node: dirs, Prev: dirc, Up: Glossary, Next: echo dirs ---- *Gulam* has an internal stack of directories whose content is printed by the `dirs' command. The built-in commands `pushd', and `popd' are the only others that operate on this stack.  File: gulam.info Node: dollar-substitutions, Prev: command-line-editing, Up: top, Next: expressions Dollar-substitutions -------------------- The subword `$x' in a command is substituted by the value of it. If `x' is the name of a shell var, or an environment var, then `$x' is the value of that variable. If `x' is an unsigned number, it stands for the x-th argument; thus, `$0' usually gives the command name. `$*' stands for the text of the entire command; `$-' stands for words `$1' to dollar-last; `$<' stands for the on-demand input given by the user. Dotg.g ------ -- see Batch Files, and gulam.g  File: gulam.info Node: echo, Prev: dirs, Up: Glossary, Next: ef echo ---- The `echo' command prints its arguments. echo c:\mwc\... # all the fnms in the dir tree rooted at c:\mwc will be echoed  File: gulam.info Node: ef, Prev: echo, Up: Glossary, Next: egrep ef -- -- stands for `elseif'; see `if'  File: gulam.info Node: egrep, Prev: ef, Up: Glossary, Next: endif egrep ----- -- see `grep'  File: gulam.info Node: endif, Prev: egrep, Up: Glossary, Next: endfor endif ----- -- see `if'  File: gulam.info Node: endfor, Prev: endif, Up: Glossary, Next: exit endfor ------ -- see foreach Style of Environment String ---------------------------- This shell var controls the format of the environment string supplied to the external command invoked through *Gulam*. set env_style bm # to get a style of env a la MS-DOS set env_style mw # Mark Williams set env_style gu # the "normal" style, a la Unix  File: gulam.info Node: exit, Prev: endfor, Up: Glossary, Next: fg exit ---- exit [NUMBER] The `exit' built-in command is used to force termination of a shell script.  File: gulam.info Node: expressions, Prev: dollar-substitutions, Up: top, Next: flags Expressions ------------ An "atomic exp" is either a NUMBER, a FILENAME, a FILE PREDICATE, a { EXP }, or ! ATOMIC EXP. A FILE PREDICATE on a file name FNM is of the form `-c FNM' where `c' is in `{e, f, d, h, v, m}'. These letters stand for "exists", "is-a-regular-file", "is-a-dir", "is-a-hidden-file", "is-a-volume-label", and "is-an-archived-file". A FILEPRED yields 1 if it is true, 0 otherwise. An arithmetic expression is constructed using the operators `+-/%*'. All these are of equal precedence and evaluated left-to-right; thus, `2 + 4 / 2' is equal to 3. However, the braces raise the precedence of the ops within them; thus, `2 + { 6 / 2}' is equal to 5. An exp with no operators, i.e., an atom, is a special case because we want the string form of the atom (e.g., as for `blah' in `set s blah'). A non-numeric string yields 0 as its numeric value in an arith exp. A "relational expression" is of the form `arithexp relation arithexp', where relation is any one of `<=, <, ==, !=, >,' or `>='. Such a relation yields a 1 if it holds, 0 otherwise. (Relational operators among strings are not implemented yet.) You may combine expressions using the boolean operators `&&' and `||' (which are not, for now, short-circuit evaluated). Note the spaces in the examples above; see Lexical Structure.  File: gulam.info Node: fg, Prev: exit, Up: Glossary, Next: file-names fg -- `fg' is part of the simulation of what we were used to doing on Unix with GNU-Emacs: get out of it by stopping GNU (`ə' in ue/Gulam), do a few shell commands and get back in by `fg' (works the same in ue/Gulam).  File: gulam.info Node: file-names, Prev: fg, Up: Glossary, Next: foreach File Names ---------- There are many conveniences in *Gulam* that relate to specifying filenames. It can complete a file name given its first few characters. (Tenex is widely considered to be the first OS to implement this.) Type the first few characters, and then press the key marked `INSERT' (or `CLR/HOME'), while you are in *mini*. If you are in buffer *gulam*, use `ESC' `ESC' (2 escapes). The canonical form of the full path name of a file begins with a letter designating the disk drive, followed by a colon, a back-slash separated list of identifiers. All but the last of these identifiers must be a directory name. In the non-standard form, you may also use a dot `.', and dot-dot `..' in place of the identifiers in appropriate contexts. Whenever *Gulam* completes your filenames, it will produce the standard form full path names. *Gulam* will standardize, in three situations, non-standard form of a `path', as shown in the example below. These situations are: 1. Tenex file name expansion is invoked. 2. the word contains meta characters. 3. the name is being given to one of the file operations in `ue'. `e:\gulam\a:\lex.c' is standardized to `a:\lex.c' `e:\gulam\\src\util.c' is standardized to `c:\src\util.c' `e:\gulam\~\ex.o' is standardized to `d:\bin\ex.c' assuming that the current drive was `c:\', and home was `d:\bin', and variable `parent_expand' is set. This is especially nice inside `ue' when visiting other files. Words, as given by the you, that contain meta characters (which are `*?|()[]') or the string `...' are expanded. In general, one such word produces a list of file names. These file name regular expressions (fnmre) are like regular expressions (re), but have different semantics. Occurrences of an fnmre, outside of strings, are replaced by the sorted blank-separated list of file names matching the fnmre. An fnmre differs from re in (1) `.' stands for itself; (2) `*' is matches zero or more arbitrary characters. Question mark matches any one character. `[a-g]' matches any one letter in a, b, ..., g. `[zen]' matches one of z, e, or n. Parentheses serve to group expressions. An exp `g*' matches file names that begin with a `g'; `*.c' matches those ending in `.c' The 3 dots, as in `c:\tex\...', stand for all the names of the files in the subtree at `c:\tex'. If `c:\tex' has subdirectories, and so on, all their names and files they contain are included. Thus, `echo e:\...\*.c' will show all the `.c' files in all the directories on drive e. Remember that `...' expansion causes many directories to be visited. This is not only time consuming, but also seems to trigger the Atari TOS's 40 folder bug after a few such operations. (In my tests, I never lost a file as a result. Nor can I tell precisely when and in what form this shows up. Most frequent indication was that `cd' to an existing drive would fail.)  File: gulam.info Node: flags, Prev: expressions, Up: top, Next: history-substitutions Flags ----- Most commands (built-in or external) take flags to alter the behavior of the command in a minor way. The convention made popular by Unix shells is adopted here for *Gulam*'s built-ins: a flag is of the form `-C', or `+C', where C stands for one character. The option `-i', which interrogates you for each of the operand of the command before executing it, is provided on most commands.  File: gulam.info Node: foreach, Prev: file-names, Up: Glossary, Next: format foreach ------- The `foreach' command is used in shell scripts (but not at the terminal) to specify repetition of a sequence of commands while the value of a certain shell variable ranges through a specified list. The `foreach' command ends with an `endfor' on a separate line all by itself. foreach i { a b c *.o [a-k]*[ch] } echo $i endfor  File: gulam.info Node: format, Prev: foreach, Up: Glossary, Next: gem format ------ This command formats diskettes, in the standard form (360K, or 720K) in either the `A' or `B' floppy drive. It does not touch hard-/ram-disks, no matter what arguments (illegal or not) you give it. Its valid arguments are either `a', `b', or both. The optional flag `-2' implies double-sided formatting; otherwise the diskette is formatted single-sided. format # does nothing format b # format the floppy in dr B, single-sided format -1 b # same as format b format -2 a # format the floppy in dr A, double-sided If you issue the wrong command (e.g., `format -2 a' on a single-sided drive), you will hear a lot of grinding noises; a `control-C' will kill this, but not right away.  File: gulam.info Node: gem, Prev: format, Up: Glossary, Next: grep gem --- The word `gem' is a prefix, like `time' is, to commands. This enables proper running via *Gulam* of most programs that use the desktop metaphor. It clears screen, turns cursor off, enables mouse and then executes the command, and after the command is finished it again clears screen, turns cursor on, disables mouse. The `time' and `gem' prefixes mix in either order, and the command name will be searched for in the usual way. We do not know, for sure, if all desktop/window/mouse oriented programs can be run properly with this command prefix. So experiment, and be ready to hit the reset button before using the prefix. `dvi' is an example of a command that needs to be run with `gem' prefix. And you may be tempted to do the following. alias dvi 'gem dvi' # recurses infinitely alias dzz dvi # dzz or whatever alias dvi 'gem dzz' # will work alias dvi 'gem c:\bin\dvi.prg' # also will work  File: gulam.info Node: grep, Prev: gem, Up: Glossary, Next: gulam.g grep/egrep/fgrep ---------------- grep/egrep/fgrep RE-PATTERN FILENAMES The `grep' command searches through a list of argument files for a specified string. Thus grep lex[aw] e:\gulam\*.c will print each line in the files that contains a substring matching `lex[aw]'. `grep' stands for "globally find regular expression matches and print". `grep' and `egrep' are one and the same. The first argument to `egrep' is a regular expression, and the rest are expected to be file names. `fgrep''s first argument is the as-is string to be searched for in the files. Because of the preprocessing done by *Gulam*, the as-is string for `fgrep' or the regular exp for `egrep' is generally enclosed in single-quotes.  File: gulam.info Node: gulam.g, Prev: grep, Up: Glossary, Next: help gulam.g ------- Files with the `.g' extension are expected to contain *Gulam* commands; `gulam.g' is the name of the startup file. *Gulam* attempts to find this file in the current directory, and if found executes its contents. Here is an example file: # bgn of my gulam.g set prompt '$ncmd $cwd gu > $u' set histfile e:\history.g set baud_rate 9600 set sz_rs232_buffer 4096 # set palette; note the trailing '-' set rgb '005-707-070-075-' # the following sets tabs on Epson MX-80 set pr_bof '^Q033^QD^Q010^Q020^Q030^Q040^Q050^Q033^QC^Q102' set pr_eof '^Q214' set pr_eop '^Q214^Qn' set pr_eol '^Qr^Qn' #setenv PATH c:\bin,d:\bin,f: # no trailing back slashes #rehash set path c:\bin,d:\bin,f: # this is equiv to above 2 lines setenv TEMP f:\ alias h history alias ll ls -lF alias p more alias rm rm -i # asks before deleting alias ug 'ue e:\gulam\$1.c' alias cg 'f:\cc.ttp -c -V -Ie:\gulam -DMWC e:\gulam\$1.c' alias cpall 'cp e:\ue\*.o e:\gulam*.o f:\ ' alias bk 'cp e:\gulam\*.[chs] a:\ ' # end of my gulam.g Gulam Variables and Environment ------------------------------- The following shell variables cause/control useful effects. The format of the explanation is `variable_name: default-value meaning'. `batch_max_nesting: 20' if you need to nest batch file execution at levels deeper than this, change this variable. `batch_echo: 0' if 1 echoes each command of the batch file as it is executed. `baud_rate: none' for use in the terminal emulator, rx/sx file transfers. `cwd:' `CWD: full pathname of current directory' gets re-set every time a cd, pushd or popd is executed. `delay: unset' set it to control the duration that the cursor sits on a matching paren, bracket, or brace. A value of 2000 produces about a 2-sec delay. `dir_cache: 0' if non-0, turns on the dir list cache. This substantially speeds up the Tenex file name completion. `ginprompt: $<' the prompt shown when asking you for input in dollar-substituting a $<. `gulam_help_file: none' set this var to the full pathname of the `gulam.hlp' file, which contains descriptive info about keys, functions, bindings and commands. Unless this var is set properly, the wall chart that `ue' generates is of not much use. `histfile: none' reads and saves history in file named $histfile . `history: 20' This variable controls the number of previous commands displayed by the command `history'. `home' `HOME: full pathname of home directory' home is the directory you were in before invoking *Gulam*. `mscursor: unset' set it to a string of 4 digits (e.g., "0508"). This controls the scaling of mouse movements being turned into cursor keys. If it is set to "0000", mouse movements do not get translated to cursor keys. `ncmd: number of the current command' gets set after each executing each command. `nrows: unset' This variable controls the number of lines per screen. At present, only valid values are 25 or 50. Changing `nrows' to 50 will cause the re-initialization of the screen using the small system font. `path: unset' when set, it will cause the environment variable PATH to be automatically also set to the same string ($path), and cause rehashing. `parent_expand: unset' when set, the Tenex name completion will provide the full path name rather than just the leaf name. The following pr_XXX vars are relevant with `print', and `lpr' commands. When set, these strings are sent to the printer : `pr_bof: unset' send before printing each new file. `pr_eol: rn' send after each line. `pr_eop:214' send after each page (214 == ASCII + 0200). `pr_eof: 214' send after the end of file. Thus, to have a left margin of eight-spaces, just define `pr_eol' as `rnt'. To turn condensed mode etc., just set `pr_bof' to the appropriate string after looking it up in the printer's manual. See the section on strings for an explanation of . `prompt: >>' see gulam.g for an example. `prompt_tail: unset;' when set, $prompt_tail is appended to the displayed prompt string. This is a kludge to mollify those of you who insist on having a trailing blank in their prompt! `rgb' `RGB: `000-700-007-070-'' sets the palette: 3 octal digits (followed by a dummy '-') per color; 2 in hi-rez, 4 in med-rez, 16 in low-rez. `rx_remote_cmd: unset' command to send to remote to receive file with Xmodem. For our Unix, this string is `xm st'. The rx command appends a space followed by the file name and sends the resulting string to the remote as if you typed it. `sx_remote_cmd: unset' command to send to remote to send file with Xmodem. Similar to the above. `semicolon_max: 20' Number of `;' per line; to stop infinite recursions in alias expanded commands. `status' status of the most recent external command; set after each external command. `sz_rs232_buffer: unset' The built-in terminal emulator, when invoked, will reallocate a buffer of this size (if this value is > 256) for the associated IOREC. If unset, or if set but to a value lower than 4096, you may experience XON/XOFF occuring at 9600. I recommend 4096. `time: unset' If set to non-0, times every command. `verbosity: unset' This controls the amount of feed back you get from *Gulam*. When unset, or set to <= 0, *Gulam* will be extremely quiet, and report only on errors. If you wish commands like `cp' to report the goings-on, set verbosity to 2. HELP ---- The all-upper case name `HELP' in this manual stands for the key marked `HELP' on the Atari ST. Pressing this key, outside the `ue', will show all the *Gulam* built-in commands, and a brief version of the hash table. Within `ue', it can show the binding of an individual key, or produce a wall-chart of all bindings. The `shift-HELP' key resets the special key table mapping that Gulam/uE use; after pressing `shift-HELP' the function keys, and arrow keys become equivalent to `', and the keypad will work as a typcial numerical keypad. To get back to the Gulam/uE key table, press `', which not only refreshes the display but also sets the key table.  File: gulam.info Node: help, Prev: grep, Up: Glossary, Next: history help ---- Typing the letters `help' while outside `ue', or in buffer *gulam* is equivalent to pressing `HELP'.  File: gulam.info Node: history, Prev: help, Up: Glossary, Next: if history ------- history [-h] The `history' command lists the last N commands. Each command is preceded by its number; to suppress these numbers, supply the `-h' flag. The value N is obtained by `$history'. To change this N to, say, 30, do `set history 30'.  File: gulam.info Node: history-substitutions, Prev: flags, Up: top, Next: io-redirection History Substitutions --------------------- Occurrences of the form `!!', `!number', `!string' refer to the text of previously issued commands. The text of these older commands itself does not contain `!' unless it is part of a string argument. Each `!!' is replaced by the text of the immediately preceding command. *Gulam* consecutively numbers the commands that you have issued. (The current count can be seen in the shell variable named NCMD.) Each `!n' is replaced by the n-th old command. Each `!str' is a replaced by the most recent old command that begins with str. The name completion feature works with history substitutions also. Pressing `INSERT' or `ESC-ESC' will bring the history-matched command and replace the current line in the buffer, which you can further edit. $home also $HOME ---------------- The shell variable "home" is initially set to the full pathname of the directory from which *Gulam* was invoked. However, it can be set again with set command to whatever. The wiggle `~' in file names expands to "$HOME".  File: gulam.info Node: if, Prev: history, Up: Glossary, Next: lpr if -- The "if" stmt is similar to those in many programming languages. The Boolean expression of shell if stmts typically involves tests on file names and types. (See Expressions.) There is no `then'. Any remaining lexemes after the Boolean exp are ignored. if {-d e:\gulam\lex} + 2 == 3 echo e:\gulam\lex is a dir ef -e e:\gulam\lex # read ef as `else if' echo e:\gulam\lex does exist ef echo e:\gulam\lex does NOT exist endif  File: gulam.info Node: io-redirection, Prev: history-substitutions, Up: top, Next: metacharacter-expansion IO Redirection -------------- Prefixing a file name F with `>' causes all standard output produced by that command to get deposited into file F. Similarly, `<g' will cause standard input to be taken from the file G rather than the key board. If you prefer, you may include white chars between the `<' (or `>' ) and the filename. If you have more than one `<', or `>' in a command all but the last are ignored. Note that because of TOS and compiler peculiarities, not all external commands will behave as above. ls -l > lsout # get the ls -l output into file lsout ls -l >> f1 # append the ls -l output to f1 ecmd '>blah' # invoke ecmd and give it the arg >blah as is to it.  File: gulam.info Node: kb, Prev: if, Up: Glossary, Next: lpr kb -- This command redefines microEmacs keybindings. To bind key with code 144 to function with hex-number 1d while you are in the *regular* buffer, do kb -r 144 1d Use -g for redefining the bindings of *gulam* buffer; -m for mini buffer. You can find the key codes and hex-numbers of functions in the wall-chart (shown below), which can be produced by pressing the `HELP' key, a `B', and then a `r' (or `g', or `m'). The key names, and function names will not appear unless a `set gulam_help_file <filename>' was done earlier. key-code in hex | function code in hex | | key name (kb ignores this) | | | function name (kb ignores this) --------------------------------------------------- 081 5c F1 kill-backward-word 082 5d F2 kill-word 083 20 F3 kill-line 084 35 F4 copy-region-as-kill 085 51 F5 kill-buffer 086 50 F6 list-buffers 087 4e F7 switch-to-buffer 088 3f F8 write-file 089 3d F9 find-file 08a 3e F10 save-buffer 08b 14 HELP help 08c 0d UNDO quick-exit 08d 62 INSERT scroll-down 08e 61 HOME scroll-up 0bb 23 UPARRO previous-line 0bc 0f DNARRO gulam-forward-line 0bd 1a LTARRO backward-char 0be 1b RTARRO forward-char 140 30 C-@ set-mark-command 141 1e C-A beginning-of-line 142 1a C-B backward-char 143 06 C-C switch-to-gulam-buffer 144 1d C-D delete-char 145 1f C-E goto-end-of-line 146 1b C-F forward-char 147 13 C-G keyboard-quit 148 1c C-H backward-delete-char 149 11 TAB goto-next-tab 14a 25 LFD newline-and-indent 14b 20 C-K kill-line 14c 19 C-L redraw-display 14d 10 RET gulam-do-newline 14e 0f C-N gulam-forward-line 14f 22 C-O open-line 150 23 C-P previous-line 151 33 C-Q quoted-insert 152 2b C-R search-backward 153 2c C-S search-forward 154 34 C-T transpose-chars 156 61 C-V scroll-up 157 36 C-W kill-region 159 3b C-Y yank 15a 0e C-Z temporary-exit 15f 14 C-_ help 029 6b ) blink-matching-paren-hack 07d 6b } blink-matching-paren-hack 05d 6b ] blink-matching-paren-hack 0c0 0c KLP move-window-dn 0c1 0b KRP move-window-up 0c7 4a KSLASH split-window-vertically 0c2 49 KSTAR delete-other-windows 0c5 45 KMINUS previous-window 0c3 44 KPLUS next-window 0c4 17 KENTER call-last-kbd-macro 0c6 26 KDOT goto-line 0b0 0a K0 terminal-emulator 0b7 55 K7 beginning-of-buffer 0b8 32 K8 recenter 0b9 54 K9 end-of-buffer 0b4 5a K4 backward-word 0b5 23 K5 previous-line 0b6 5e K6 forward-word 0b1 1e K1 beginning-of-line 0b2 0f K2 gulam-forward-line 0b3 1f K3 goto-end-of-line 541 09 C-X C-A show-key-board-macro 542 50 C-X C-B list-buffers 543 12 C-X C-C save-buffers-kill-emacs 546 3d C-X C-F find-file 549 4d C-X TAB insert-buffer 54f 41 C-X C-O delete-blank-lines 54e 0c C-X C-N move-window-dn 550 0b C-X C-P move-window-up 552 08 C-X C-R read-file 553 3e C-X C-S save-buffer 556 3d C-X C-V find-file 557 3f C-X C-W write-file 558 42 C-X C-X exchange-point-and-mark 55a 46 C-X C-Z shrink-window 421 27 C-X ! execute-one-Gulam-command 421 07 C-X ! execute-buffer 43d 43 C-X = what-cursor-position 428 15 C-X ( start-kbd-macro 429 16 C-X ) end-kbd-macro 431 49 C-X 1 delete-other-windows 432 4a C-X 2 split-window-vertically 442 4e C-X B switch-to-buffer 445 17 C-X E call-last-kbd-macro 446 18 C-X F no-op 449 3c C-X I file-insert 44b 51 C-X K kill-buffer 44e 44 C-X N next-window 44f 44 C-X O next-window 450 45 C-X P previous-window 453 52 C-X S save-some-buffers 45a 47 C-X Z enlarge-window 348 5c ESC C-H kill-backward-word 221 07 ESC ! execute-buffer 22e 30 ESC . set-mark-command 23e 54 ESC > end-of-buffer 23c 55 ESC < beginning-of-buffer 25b 56 ESC [ beginning-of-paragraph 25d 57 ESC ] end-of-paragraph 225 2f ESC % query-replace 220 59 ESC SPC just-one-space 242 5a ESC B backward-word 243 5b ESC C capitalize-word 244 5d ESC D kill-word 246 5e ESC F forward-word 247 06 ESC G switch-to-gulam-buffer 24c 5f ESC L downcase-word 251 29 ESC Q fill-paragraph 252 2b ESC R search-backward 253 2c ESC S search-forward 255 60 ESC U upcase-word 256 62 ESC V scroll-down 257 35 ESC W copy-region-as-kill 27f 5c ESC DEL kill-backward-word 35b 05 ESC ESC expand-name-gulam-style 344 63 ESC C-D expand-names-and-show-them 346 04 ESC C-F file-name 07f 1c DEL backward-delete-char 0ab 37 SHIFT-HELP keys-reset 000 00 NUL no-op 000 00 NUL no-op 000 00 NUL no-op 000 00 NUL no-op 000 00 NUL no-op 000 00 NUL no-op 000 00 NUL no-op 000 00 NUL no-op 000 00 NUL no-op 000 00 NUL no-op  File: gulam.info Node: lpr, Prev: if, Up: Glossary, Next: ls lpr --- lpr FILENAMES The command `lpr' prints its files as-is, with no processing at the end of lines.  File: gulam.info Node: ls, Prev: lpr, Up: Glossary, Next: mem ls -- ls [-ltrRLF] FILENAMES The `ls' (list files) command, with no arguments, prints the sorted list of names of the files in the current directory. It has a number of useful flag arguments, and can also be given the names of directories as arguments, in which case it lists the names of the files in these directories. If no flags are given, `ls' prints only the filenames. The `-L' causes a full-length line for each file giving its attributes, size, creation date, and name. The `-l' (small el) is the same as `-L' except that the output is sorted by name. The `-R' will cause the subtrees of directories in the argument list of files to be traversed. The `-F' will append to each listed filename one char that indicates the type of that file: `*' if it is executable (i.e., has an extension of `.prg, .tos, .ttp', or `.g'), a `\' if its is a directory, a ' ' otherwise. The `-t' causes a sort by time of modification of the files. The `-r' reverses the chosen order of sorting. `ls' always (even if DIR_CACHE is 1) updates the directory cache for the relevant directories.  File: gulam.info Node: mem, Prev: ls, Up: Glossary, Next: mcdir mem --- `mem' shows the list of free chunks of memory available. It does this by following lists starting at an (undocumented) TOS location (`0x7e8e' for ROMS dated 04221987, `56ec' for older ROMS), Because of the way *Gulam* uses dynamically allocated memory, the size of the largest free chunk fluctuates both up and le:. ysysy´ש),catr \'-Lc´inee ate`-L e, Ns e(iòhe alwlar, PdateXמthe (ut tt£JΓ⌠⌠⌠ine⌠⇦Õ I R' cR nam R'nµ