Otherware

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

/ Otherware / Otherware_1_SB_Development.iso / amiga / utility / cli / sksh017.lzh / doc / Addendum1.7.doc < prev next >

Wrap

Text File | 1991-05-04 | 31.2 KB | 1,057 lines

Addendum for Version 1.7 SKsh A ksh-like Shell for the Amiga Version 1.7 (Copyright) 1988-1991 Steve Koren May 4, 1991 Addendum to Version 1.7 This document describes additions and changes to SKsh since version 1.6. Version 1.7 has many significant new features. SKsh runs on 3000 systems SKsh now runs on 3000 systems, at least to the extent that it no longer crashes as it used to. When 2.0 becomes widely available on 2000 systems, future SKsh's will run only under AmigaDos 2.0. "2" option added If this option flag is set, SKsh will attempt to execute AmigaDos 2.0 internal commands (but only if you are actu- ally running 2.0). I have made this an option because in SKsh 1.7, executing AmigaDos 2.0 builtin commands doesn't work right. I'll probably fix it later when I have some real documentation on how the 2.0 calls work. Right now I'm just trying to figure it out by looking at the function prototypes, and that doesn't work very well. This flag is reset by default. RECUR_DEPTH variable added RECUR_DEPTH is a variable which controls the maximum depth that the SKsh parser will recurse. Larger values of RE- CUR_DEPTH require more stack space but enable more deeply nested function calls, scripts, etc. This variable is described in more detail in the reference manual. Please see that document for details. CDPATH variable added A CDPATH variable, similar to PATH, now permits cd to search a series of directories to find its destination. Any non-qualified path name will be searched for in all di- rectories in the CDPATH. The new 1.7 path function can modify the CDPATH as well as the PATH variable. Also, many people do not realize that the mplist command can provided a shortened method to "cd" to different directories. For example, you can have the command: cd d1 really mean: SKsh Amiga Shell Page 2 Addendum to 1.7 cd sys:usr/commands/src/cmd1/directory-one by adding the following line to your .skshrc file: mplist -a 'd1=sys:usr/commands/src/cmd1/directory-one' MANPATH variable added MANPATH is similar to CDPATH, but for the man script (see description below). The new path function also is able to modify the MANPATH variable. man script has additional abilities The man command, which is now a script, has additional abilities. It will now search for files ending in .MAN, .doc, or .txt, and will search in any number of directories for the files. This is controlled by the MANPATH variable, described above. SKsh documentation available though manpages The contents of the Reference.doc and ExtCmds.doc files are now available though the man command. The new install script (see below) will optionally create the manpage en- tries from these files by deleting the page headers and footers, and breaking the .doc files into separate manpage entries. line builtin added A line command has been added which functions similar to read, but allows the use of the full SKsh command line ed- iting facilities to input lines. line may only input lines from the keyboard, not a file. The syntax is: line var [ prompt ] [ pnpc ] Where pnpc is similar to the PNPC variable, but for this prompt. (See the PNPC entry in Reference.doc for details). line is recommended instead of read wherever input is to always be read from the keyboard. SKsh Amiga Shell Page 3 Addendum to 1.7 skshbin: and skshscr: aliases added In addition to the old sksh:, two new aliases are required to run sksh properly. These aliases point to the directory containing the SKsh external binaries, and scripts, respectively. This change will more closely standardize SKsh environments. Both of these aliases are added to the SKsh path by default, so they need not be further added in an .skshrc file. xargs command added The new xargs command is similar to the Unix command of the same name. xargs can be used to circumvent the 255 charac- ter command line length limitation in AmigaDos. xargs reads its standard input, which should be a list of files, and executes commands multiple times on these files. The standard input is produced by either the SKsh find utility, or more commonly, the echo builtin. Since echo is a shell builtin, it can handle any number of files. For example, suppose you have 100 .c files in a directory. Normally, you could only fgrep through 30 of these, since AmigaDos will not permit a command line longer than that. However, with xargs: echo *.c | xargs fgrep -il mytext xargs will properly construct several fgrep command lines, each up to 250 characters in length. As another example, suppose you wish to copy those files to ram:. The -i op- tion to fgrep tells it to substitute file names for the {} parameter: echo *.c | xargs -i 'cp {} ram:' xargs supports many more options and can do other things. See the documentation entry in the ExtCmds.doc file for more detailed information on xargs. It supports all of the Unix options, plus several more. File completion is faster File name completion performance has been improved on large directories. This improvement will be most noticed when the machine is heavily loaded. Disk seek time can still be an overriding factor, but for directories which are buffered or on a ram disk, completion is up to twice as fast. SKsh Amiga Shell Page 4 Addendum to 1.7 complist bug fixed If you add a device name ending in ":" to your "complist", and use file completion to insert the name on the command line, SKsh will no longer insert a trailing "/". Command line editing bug fixed The "ILP" command (insert last parameter), normally mapped to "<esc> .", will no longer insert a ">" sign if it finds one as the first character of the last parameter. This means that if your previous command line ends with ">file", and you use the ILP command, only "file" will be inserted, without the ">" sign. This is more often desired. PNPC2 variable added A PNPC2 variable has been added. It is identical in func- tion to PNPC except that it functions for the secondary prompt string. This enables you to have different numbers of escape sequences in your primary and secondary prompt strings. Default prompt string changed The default prompt string, set up in .skshinit, has been changed to include the history line number and cli number. If you reset the prompt in your .skshrc, you will not see this change. numloop statement added A new statement, similar to the old "for" statement, has been added. The new numloop statement allows iteration over a range of numbers simply without using a while loop and inc statement. Iterations can be up or down, and can step by 1 or a predefined amount. This new statement is described in the Reference.doc document. Please see that description for more detail. SKsh Amiga Shell Page 5 Addendum to 1.7 history command enhanced The history command now has additional abilities. The his- tory list can be cleared using "history -c". More signifi- cantly, history can now be saved and loaded to files. To save a history list to a file, simply execute "history >histfile". To reload the history from the file, using the "-l" option to history: "history -l <histfile". This will reload the exact history state, including the value of $CMDNUM. This feature is often useful to save the history stack between executions of SKsh. A set of scripts has been provided to facilitate history saving and loading; see the section below on the hist* scripts. pathconv command added A new pathconv command can be used to convert between AmigaDos and Unix style filenames. For example, 'pathconv -u "//foo"' might return "../../foo", and 'pathconv -a "../../foo"' would return "//foo". Support for ${param:-word} variable expansions added Unix ksh supports several methods to test for variable val- ues and perform variable expansions at the same time. SKsh now supports a few of these: ${var} - Like $var, but ${a}text can be used to ex- pand $a in front of "text", since $atext would try to expand the "atext" variable instead of the "a" variable. ${#var} - Expands to the text length of $var ${var:-word} - Expands to $var if $var is set. Otherwise expands to word, which may itself be a variable (as in ${FOO:-$PWD} ). ${var:=word} - Similar to ${var:-word}, but assigns the result to "var" if it is not already set. Useful for assigning defaults to variables while simultaneously using the result. Input/output redirection to same file doesn't clobber file In previous SKsh versions, if a pipeline of the form "com- mand <file >file" was run, were "file" was the same file for both the input and output of the pipeline, the file was clobbered before an error message was issued. This no longer happens and the file is left intact after the error. SKsh Amiga Shell Page 6 Addendum to 1.7 Added -n flag to disable .skshrc, .skshinit SKsh can now be started using the -n flag, which tells it to ignore any .skshrc and .skshinit files which may be present. This is not normally useful for interactive invo- cations of SKsh, but it may occasionally be useful to run simple scripts which do not require either setup file. Usage message added to all builtins, extern cmds, scripts All SKsh builtin commands, external binaries, and the new scripts (see description below) now will print a usage mes- sage if given '-?' as the first parameter with no other pa- rameters present. (The '-?' should probably be quoted to avoid being interpreted as wildcards by the shell expansion mechanism). An additional and slightly more convenient method to generate the usage messages uses the new "usage" script, described below. Lisp like car, cdr functions added Two new shell builtins (car and cdr) can be used to extract elements from strings containing lists of elements. The default separator character is a space, but this can be changed with an additional option. For an example of how to use these new functions, see the new definitions of the directory stack scripts (pushd, popd, and dstack). File completion bug fixed File completion no longer writes a "0" to memory location "0". toupper/tolower/capital builtins added New builtins have been added which are similar to "echo" but echo arguments in upper case, lower case, or with the first letter of each argument capitalized. These commands took very little space to add since they share code with the "echo" builtin. New supported scripts added Several scripts which were previously shipped in the Stuff.sksh file have been removed, and are now supplied as a "standard" part of SKsh as stand alone scripts. In addi- tion, several new scripts have been added (see below). SKsh Amiga Shell Page 7 Addendum to 1.7 This approach has several advantages. First, as scripts, they are only in memory when you need them, as opposed to functions which take up ram all the time even if you don't often invoke them. Second, this approach reduces the time necessary to invoke SKsh, since the functions are not loaded then. Third, I can integrate these functions with the rest of SKsh, document them in Reference.doc, etc. These scripts will have to be installed in a directory pointed to by the new skshscr: alias. The new installation script will perform this task for you. (See the new "Install.doc" for details). It is possible to break these scripts by changing values of certain SKsh options. In particular, i, l, and N are dangerous, and I don't recom- mend you change them from their defaults if you wish to use these scripts. Some lesser used functions are left in the Stuff.sksh file, while others are now standalone scripts. The list of scripts is contained in the ReadMe_1st.doc file. Scripts are also now documented in Reference.doc. Usage script added A new usage script can be used to print the usage messages from any SKsh builtin, script, or external binary. For ex- ample, "usage history" results in: Usage: history [ -n ] [ >histfile ] history -e [ pattern | number | offset ] history -c history -l <histfile The usage command may also be used to print usage message for any other AmigaDos command which will accept '-?' as the first parameter and print a usage message as a result. chext script added A new external script called chext can be used to rename files to use different extensions. For example, "chext .c *.bak" would change all files ending in .bak to end in .c. histsave, histload, histlist, histrm scripts Four new scripts facilitate the use of history files. histsave save the current history in a file named s:SKsh_Hist.<n>, where <n> is the $CLINUM by default or any other string. histload loads a previously saved history file. histlist lists available history files, and histrm deletes all saved history files. For example: SKsh Amiga Shell Page 8 Addendum to 1.7 [prompt]: histsave compile [prompt]: histsave session2 [prompt]: histlist compile session2 See the documentation in Reference.doc for information on these functions. && and || support Unix ksh supports linking commands with && and ||. In the first form, the right side is executed only if the left side is successful. In the second, only if not. This is useful, for example, to copy and remove a file if the copy was successful: copy myfile mydir && rm myfile or to execute function clean_up if function my_func failed: my_func param_1 param_2 || clean_up Any number of control structures may be chained together using && and ||, although chaining large numbers may neces- sitate increasing the RECUR_DEPTH variable. The use of these operators is described in more detail in the UserMan.doc file. split command added A new external split command can be used to split text files into smaller files with a given number of lines in each file. This is sometimes useful for dealing with un- wieldy uuencoded files or text files too large to comfort- ably edit in one piece. The files can be re-assembled with the external cat or join commands. See the ExtCmds.doc file for information on using split. File completion, commands work with spaces in filenames The file completion mechanism has been enhanced to insert backslash escapes before spaces if the filename being com- pleted contains imbedded spaces. A backslash escaped space will also no longer break parameters, so that: ll my\ file will correctly list the file named "my file". SKsh Amiga Shell Page 9 Addendum to 1.7 exit code can now be set from a script or function The old SKsh return builtin would not permit an exit code to be returned from a script or function. The new one does, but introduces a slightly different meaning. return with no parameters functions as it did before. With one parameter, <n>, return sets the return code to <n> and re- turns one level (it used to return <n> levels). Return with two parameters, <n> and <l>, sets the exit code to <n> and returns <l> levels. This new feature permits one to test the return code from a function: function foo { if [ <some condtion> ] then return 1 else return 0 fi } if foo then <action> else <action-1> fi mkdir builtin supports -p option mkdir now supports the -p option. mkdir -p followed by a full path name will create all directories necessary to make the path. For example, suppose that the directory ram:foo exists and is empty. "mkdir -p ram:foo/bar/tst/a" would create ram:foo/bar, ram:foo/bar/tst, and ram:foo/bar/tst/a all in one step. In addition, it will issue no error codes for directories it cannot make. tackon builtin added The new tackon builtin will assemble its parameters into a complete path, inserting "/" characters where needed. For example, "tackon ram: make/ a path" would yield "ram:make/a/path". In addition, a -e option will backslash escape any wildcard or whitespace characters. SKsh Amiga Shell Page 10 Addendum to 1.7 skshbin: and skshscr: added These two aliases point to the location of the SKsh exter- nal binaries and scripts, respectively. These are included in the SKsh default search path, so you will not have to add them in your .skshrc file as was necessary with previ- ous SKsh versions. If your .skshrc file added the external binary directory, it should be modifed to no longer do this. In addition, you will need to change your s:startup- sequence file to create these aliases. [ expr ] style expressions can be used independently Previously, [ expr ] clauses needed to be used in "if" or "while" loops. They can now be used independently, a fea- ture which is useful when combined with the '&&' and '||' operators mentioned above. For example, the following line sets the "f" variable to be ram:foo only if the file ram:foo exists, and echos "Hi!": [ -f ram:foo ] && f='ram:foo' && echo 'Hi!' This is usually more compact than using an if statement for one or two small operations. There is currently a bug in that [ expr ] will not set the $? variable. It will, how- ever, return the correct true/false value, as seen in the above example. The use of this feature is described in more detail in the UserMan.doc file. path function removed, changed to script The path function has been removed and changed to an exter- nal script. This reduces in invocation time and memory, and since the path function in only invoked infrequently, the time overhead of the script is not large. This also permits the path function to be more complex and understand the CDPATH variable (see below). path script understands CDPATH and MANPATH as well as PATH The new -cd and -man options to the path script tells it to change the CDPATH or MANPATH instead of the PATH. The old -add option can be used with or without the -cd and -man options. For example, path -cd -add /users /usr/pd path -man -add MAN:subdir1 SKsh Amiga Shell Page 11 Addendum to 1.7 expr -a and -o use short circuit evaluation -a (and) and -o (or) clauses in expr statements now use short circuit evaluation, which means they only evaluate the parts of the expression they need to. (For example in "[ 2 -lt 0 -a 3 -lt 9 ]", only the "2 -lt 0" part of the expression is evaluated, since because it is false, the value of the "3 -lt 9" expression does not matter in deter- mining the final result. This is faster, and mostly trans- parent, but I mention it here because it is possible to see slightly differences if the expressions have side effects. This should affect very few scripts. Parameters may be passed to scripts from other shells SKsh has always had the ability to run scripts from other shells. For example, you might have scripts from "ARexx" or "CShell" (originally by Matt Dillon and recently worked on by Urban Mueller). However, there was previously a limitation in that no arguments could be passed to these scripts. Auto-shell sourcing will now pass parameters. For example, consider the "phonebook.rexx" script which comes with ARexx. If you modify the first two lines to read: /*c:rx */ You can then run this script directly from SKsh (provided it is in your search path and the script bit is set). For example: phonebook.rexx bill will execute the "phonebook" rexx command with "bill" as one parameter. SKsh message file The text of SKsh error, help messages, usage messages, and some default information is now stored in a file and loaded at run time. This allows the messages to be customized. The file will only be read by the first SKsh invoked (see "Shared SKsh modes" below). The message file is named "sksh.msg" and MUST exist in ei- ther the "sksh:" directory or in $PWD. (It will usually be in "sksh:"). If it is not found, SKsh WILL NOT RUN. The Install_1.7.pp script will correctly install this file. The format of the message file is fairly unforgiving of er- rors, and it is explained in detail in the UserMan.doc file. SKsh Amiga Shell Page 12 Addendum to 1.7 Shared SKsh Modes SKsh now supports three shared modes, known as "slightly shared", "somewhat shared", and "very shared". In the shared modes, every SKsh run after the first will detect that there are other shells running, and share some data with the original shell. This will result in a memory sav- ings of up to 25K per shell, and can also make shell invo- cation nearly instantaneous. Using "very shared" mode can reduce startup time to less than a second for a resident SKsh, since nearly all data is inherited from another run- ning shell and no initialization files need be read. There are several important things to note about using shared modes with SKsh. Please read the appropriate sec- tions of UserMan.doc and Bugs.doc if you plan to use these modes. SHARED_TYPE variable This variable contains the string 'master' if this SKsh is the shared master. If so, this shell must exit after any slave shells. OS_VER variable This variable contains either the string '1.3', or the string '2.0', depending on the version of AmigaDos under which the shell is being run. New install script added A new install script, called Install_1.7.sksh can be used to assist with SKsh installation or update. (It functions whether or not there is already an SKsh installed on the system). To use this script, the SKsh distribution archive should be extracted to a directory, preferably on ram: if you have the space. The script will ask you several questions about the intended locations of your SKsh files (and if you al- ready have the sksh:, skshbin:, and skshscr: aliases as- signed, it will use these as defaults). It will then in- stall the SKsh files in their proper locations, set the proper permission bits, check the values of your sksh*: aliases, checksum the destination files, install the manpages, and generate a checklist of additional manual tasks which may be necessary (such as modifications to your s:startup-sequence file). SKsh Amiga Shell Page 13 Addendum to 1.7 The script MUST be invoked from the directory containing the unarchived SKsh files, and it MUST be run from an AmigaDos CLI as follows: 1> sksh -n Install_1.7.pp The -n parameter is important. Also, both .pp and regular forms of the script are provided. The .pp version is faster and you should run that. The other is provided in case you wish to examine the script (which is somewhat long). This script is probably only useful for installing SKsh onto a hard disk. I have not tested it for installation onto a floppy. Please read the new Install.doc file for more information on the script. SKsh Amiga Shell Page 14 Addendum to 1.7 Misc. Notes The Install.doc file has changed substantially from SKsh 1.6. Please read it again before installing 1.7. The Install.doc file now mostly explains the install script. Far fewer manual actions are necessary to install a new SKsh or update an old one than with SKsh 1.6. Installation will get even easier in future versions. I am no longer distributing a "zoo" file for SKsh. There is now only a "lharc" archive. Also, the archive contains sev- eral subdirectories - it is best to use the "-m" switch to "lharc" to have it create these directories without prompting. The new install script expects all files to be in their proper subdirectories, and it will complain if they are not. There- fore, if you upload SKsh to bulletin board systems, give it to friends, etc, it is imperative that the EXACT .lzh file is transferred. My email address has changed since 1.6. Please see the MiscInfo.doc file for the new address. The following line can be used in a "view.magic" file to detect SKsh preparse files: SKsh preparse file:OFFSET:0:28534B53485F50502C....29 I would like to make a request of people who further distrib- ute SKsh (uploading it to BBS's, etc). I would appricate it if you distribute the ORIGINAL SKsh archive, and not a reas- sembled one. There are a large number of files present, and getting them right is something of a tricky business. It makes life easier for users down the road if they receive the original archive, and the Install_?.?.pp script is less likely to complain about missing or incorrect files. Thanks! That said, as always, feel free to give SKsh to anyone who you think might be interested. One common question people have is why short command lines do not get added to the history list. You can control this using the $LLMIN variable. $MAXDIST also affects the way lines get added to the history list. Check out the documentation for these variables in Reference.doc for details. Thanks are owed to Kent Polk and Jordan Hubbard for help test- ing 1.7, to Allen Norskog for making his 3000 available for testing until I managed to get an SKsh which which would more or less run there, to Fred Fish for continuing to provide an invaluable service to Amiga users, to Tad Guy for posting various SKsh versions to comp.binaries.amiga, and to everyone else who provided ideas and suggestions for SKsh. SKsh Amiga Shell Page 15 Addendum to 1.7 Updating from SKsh 1.6 There are several difference to note between 1.6 and 1.7: 1) The return command is now slightly different. This may affect some old scripts which depend on the return n syn- tax for returning "n" nested levels. (It is, however, more compatible with the Un*x return command now). 2) Your .skshrc file no longer should add the directory con- taining the SKsh external binaries to the search path. Both skshbin: and skshscr: are included in the default SKsh search path. 3) You will need to set up skshbin: and skshscr: in your s:startup-sequence file. 4) As always, the new .skshinit file MUST be used. The .pp form will be faster. The install script will put the new .skshinit into your sksh: directory. Similarly, the new sksh.msg message file must be placed in the sksh: directory. The install script will install this as well. SKsh users list I am starting to keep a list of SKsh users. If you wish to be on this list, send me your name, and either a US-mail or email address where you can be reached. One reason for this list is just curiosity on my part of how many people use SKsh (which determines, in part, how much effort I will continue to put into it). I can't promise there are any real advantages to being on this list, although I may occasionally use it to send out news about SKsh, small patches, or interesting scripts or functions which don't make it into an official SKsh distribution. Reply or not as you see fit. Notes about the size of SKsh I have been attempting to keep the main SKsh binary close to 70K bytes. However, as I add more things, the whole SKsh dis- tribution grows larger. Even in 1.7 I have omitted things I wished to include, and compressed other things, so that the distribution can be unarchived on one floppy (just barely). However, future versions will certainly be larger. This is just a warning that installing future SKshs will almost cer- tainly require a hard disk or ram drive to store the distribu- tion files before they are installed. To save space, the files shipped in the "misc" directory (in- cluding Tiny_SKsh and the install script source) are compressed. This was necessary so that the SKsh017.lzh archive can be extracted onto an empty floppy. SKsh Amiga Shell Page 16 Addendum to 1.7