home *** CD-ROM | disk | FTP | other *** search
/ Crawly Crypt Collection 2 / crawlyvol2.bin / utility / disk / ashell / ash.doc next >
Text File  |  1985-11-19  |  40KB  |  1,057 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.                                  ASH V0.70
  8.  
  9.                       Copyright (c) 1986,1987 CSL/jdn
  10.  
  11.  
  12. INTRODUCTION:
  13.  
  14. This is Version 0.70 of the ASH document file.  If the program you're using
  15. isn't V0.70 there's a good chance some of the features won't work as
  16. documented in this file.
  17.  
  18. ASH is an acronym for 'A SHell'.  It has some of the features I like best
  19. from the shell I use the most.  This is the only formal documentation for
  20. ASH.  The HELP key also provides a few screens of information that are
  21. helpful if pressed while ASH is running.  That information is contained in
  22. the 'ash.hlp' file.
  23.  
  24. ASH is shareware and you're welcome to copy it and pass it along to as many
  25. people as you want.  Please include the copyright notice above in all
  26. associated files.  To contact me about ASH use the following address:
  27.  
  28.                            CSL, ATTN: ASH
  29.                            Jerry Nowlin
  30.                            318 N. Center Street
  31.                            Plano, IL  60545
  32.  
  33. ASH may never be really 'finished' so any and all comments are welcome.
  34. It's something that some of us (me), who prefer typing to clicking, needed
  35. to be productive.  It isn't perfect so please report any problems.  If you
  36. like ASH, you can report that too.  If you like it enough to use it on a
  37. regular basis please send along a few bucks.  This will put your name on
  38. the registered ASH user list and will enable me to notify you of any major
  39. bug fixes or new releases.  It will also help my wife appreciate the hours
  40. I spend in front of my ST.
  41.  
  42.                                  CONTENTS
  43.  
  44. INTRODUCTION  ........................................................   1
  45. QUICK COMMANDS  ......................................................   2
  46. BUILT-IN COMMANDS  ...................................................   4
  47. COMMAND HISTORY  .....................................................   8
  48. HISTORY EDIT COMMANDS  ...............................................   8
  49. I/O REDIRECTION  .....................................................  11
  50. COMMAND LINES  .......................................................  11
  51. SET VARIABLES  .......................................................  12
  52. ASH INITIALIZATION  ..................................................  13
  53. COMMAND SELECTION  ...................................................  13
  54. ASH SCRIPTS  .........................................................  14
  55. LIMITATIONS  .........................................................  14
  56. MISCELLANEOUS  .......................................................  15
  57. V0.70 NOTES  .........................................................  15
  58.  
  59.  
  60.  
  61.  
  62.                                    - 1 -
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.                                  ASH V0.70
  71.  
  72.  
  73.  
  74. QUICK COMMANDS:
  75.  
  76. The following list describes the ASH quick or single keystroke commands.
  77. NOTE: these commands DO NOT go into the command history buffer.
  78.  
  79. ESC       The escape key (ESC) puts ASH into history edit mode.  In this
  80.           mode the current command line can be edited or previous commands
  81.           in the history buffer can be pulled back and edited.  The editing
  82.           commands are explained in a later section of this document.
  83.  
  84. ^L        The control-L key (^L) will cause a listing of the command
  85.           history buffer to be displayed on the screen.  There can be up to
  86.           23 command lines in the history buffer.  The number preceding a
  87.           command line in the history buffer can be used with the ^R
  88.           command (see below) to repeat execution of the line.
  89.  
  90. ^R [n-m]  The control-R (^R) key will cause either the previous command
  91.           line, the 'n'th command line or the 'n'th through 'm'th command
  92.           lines to be re-executed.  Unlike the other quick commands, a ^R
  93.           has to be followed by a carriage return.  Due to the way the
  94.           history buffer is numbered, a sequence of command lines can be
  95.           repeated by repeating ^R's with the same value of 'n'.  For
  96.           example, in the develop/debug cycle for the Icon language you
  97.           edit, translate and execute.  The beginning of the history
  98.           listing generated with a ^L might look like this:
  99.  
  100.                     history list:
  101.                       1 - iconx mortgage loan.dat
  102.                       2 - icont mortgage.icn
  103.                       3 - vix mortgage.icn
  104.                     ...
  105.  
  106.           To repeat these three steps after completing the first cycle you
  107.           just keep invoking ^R with an 'n' of 3.
  108.  
  109.           An alternative method would be to invoke ^R with the range '3-1'.
  110.           This would automatically execute command lines 3 through 1 in
  111.           that order.  Due to the way command lines are numbered in
  112.           history, the high number in a range should be first if you want
  113.           the commands to be executed in the same order as they were
  114.           originally.  If you want the commands to execute in reverse order
  115.           you can use '1-3'.  Both orders are acceptable as long as the
  116.           history numbers in the range are valid.
  117.  
  118. ^W        The control-W (^W) key causes a what and who message about ASH to
  119.           be displayed on the screen.  This information is similar to the
  120.           initial section of this document.
  121.  
  122. ^P        The control-P (^P) key causes the prompt to toggle back and forth
  123.           between simply displaying the current drive and displaying the
  124.           current drive and the current directory path.  For example if you
  125.  
  126.  
  127.  
  128.                                    - 2 -
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.                                  ASH V0.70
  137.  
  138.  
  139.  
  140.           were in the AUTO folder on drive A you could toggle your prompt
  141.           back and forth between:
  142.  
  143.                     [A:\AUTO]
  144.  
  145.           and
  146.  
  147.                     [A:]
  148.  
  149.           The default is to display the drive and path.
  150.  
  151. ^V        The control-V (^V) key makes the cursor visible.  Some programs
  152.           that can be invoked from ASH cause the cursor to become
  153.           invisible.  For instance MicroEMACS 3.7 and ASH itself assume
  154.           you're going back to the desktop when they exit so the cursor is
  155.           turned off.  The ^V is a simple way to make it reappear.
  156.  
  157. BS/^H     The backspace and control-H (^H) keys will cause the last
  158.           character typed to be erased.
  159.  
  160. ^X/^U     The control-X (^X) and the control-U (^U) keys will cause the
  161.           line currently being typed to be aborted.  The aborted command
  162.           will NOT be included in the history buffer.
  163.  
  164. ^C        The control-C (^C) key will SOMETIMES cause the current running
  165.           command or program to abort.  This doesn't always work and
  166.           repeated ^C's will sometimes cause ASH itself to abort.  When a
  167.           program does abort its exit code is frequently munged into a
  168.           GEMDOS error that causes the 'Invalid Function' message to be
  169.           printed.  ASH scripts can be aborted by typing a ^C after a pause
  170.           command has suspended a script.
  171.  
  172. ^D/^Z     The control-D (^D) and the control-Z (^Z) keys will cause ASH to
  173.           exit to the desktop fast with no looking back.
  174.  
  175. UNDO      The UNDO key will cause ASH to ask the user if they want to exit
  176.           to the desktop.  A 'y' will cause the program to exit.  Any other
  177.           character will abort the exit.
  178.  
  179. CLR/HOME  The CLR/HOME key will clear the screen and move the cursor to the
  180.           upper left corner of the screen.
  181.  
  182. HELP      The HELP key will cause one of two different help messages to be
  183.           displayed.  When in normal command mode a summary of the quick
  184.           and the built-in commands is displayed.  When in the history edit
  185.           mode a list of the history editing commands is displayed.
  186.  
  187. Any other control characters typed to ASH are considered an error.  You'll
  188. be beeped and the character will be ignored.  In addition TAB characters
  189. (^I) typed as part of an ASH command line are automatically changed to
  190. spaces.
  191.  
  192.  
  193.  
  194.                                    - 3 -
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.                                  ASH V0.70
  203.  
  204.  
  205.  
  206. BUILT-IN COMMANDS:
  207.  
  208. The following commands are ASH built-in commands.  They are very similar to
  209. equivalent UN*X commands where that comparison applies.  This version of
  210. ASH has I/O redirection built into the built-in commands.  See the I/O
  211. REDIRECTION section for details.
  212.  
  213. Invoking any of the built-in commands with a '-?' argument will result in a
  214. usage message for that command.  These usage messages are more informative
  215. than the simple HELP summary but not as detailed as this document.  All
  216. built-in commands are lower case.  They will not be recognized if typed as
  217. upper case.  This is a trap door to let you execute external commands that
  218. might have the same name as a built-in command.
  219.  
  220. date [mm/dd/yy] [hh:mm:ss]
  221.      This command will display the current date and time.  If a new date or
  222.      time specification or both are included as parameters, the new values
  223.      are used to set the date and/or time.  Both the GEMDOS clock and the
  224.      intelligent keyboard clock are set by this command.  The GEMDOS clock
  225.      is used to display the date and time.
  226.  
  227. set [var=value ...]
  228.      This command lists all the defined set variables when invoked with no
  229.      parameters.  If it's invoked with one or more 'var=value' parameters,
  230.      they're added to the list of defined set variables.
  231.  
  232. unset var [var ...]
  233.      The unset command deletes variables from the list of defined set
  234.      variables.
  235.  
  236. echo [-n] [arg ...]
  237.      This command echos its arguments back to the screen.  The default is
  238.      to terminate the display of arguments with a carriage return and a
  239.      line feed.  The '-n' flag will cause the arguments to be echoed
  240.      without a CR/LF.
  241.  
  242.      Echo recognizes the sequence of a backslash (\) followed by three
  243.      octal digits in its arguments and will replace that sequence with the
  244.      corresponding ASCII character.  For example, the ASCII BELL character
  245.      is \007 and the ASCII TAB character is \011.  The escape sequence to
  246.      home the cursor and clear the screen is ESC-H-ESC-J.  To generate this
  247.      sequence with echo you would use:
  248.  
  249.                echo "\033H\033J"
  250.  
  251.      This same method of generating ASCII characters is used for the
  252.      pattern argument of the find command, the OPRINIT set variable and the
  253.      F1-F10 function key set variables.
  254.  
  255. pause
  256.      The pause command is mainly for use inside ASH scripts.  It will cause
  257.  
  258.  
  259.  
  260.                                    - 4 -
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.                                  ASH V0.70
  269.  
  270.  
  271.  
  272.      ASH to suspend execution until a carriage return is typed.  If you
  273.      respond with a ^C instead of a CR all currently running scripts will
  274.      be aborted and you'll be left at the interactive level of ASH.  This
  275.      is a handy trap door to abort scripts that have had problems.
  276.  
  277. find [-n] pat file [file ...]
  278.      The find command takes a pattern as its first argument.  Upper and
  279.      lower case letters in the pattern are unique.  A pattern can contain
  280.      no special characters to signify regular expressions, but it can
  281.      contain backslash ASCII character sequences like those explained in
  282.      the description of the echo command.  Find searches for lines in the
  283.      files given as arguments that contain the pattern.  The lines that
  284.      match are printed to the screen with the file name prepended to them.
  285.      If the '-n' flag is used the line numbers of any matching lines are
  286.      inserted between the file name and the line.
  287.  
  288. rez {-l | -m}
  289.      The rez command changes the screen resolution to medium or low.  Since
  290.      you can't change to high resolution from medium or low there's no
  291.      option for changing to high and if you're in high resolution you won't
  292.      be allowed to change to low or medium.
  293.  
  294.      There is a possibly confusing side effect of this command.  When you
  295.      change resolution the color pot that's used to paint the foreground
  296.      color changes too.  In low resolution pot 15 is the foreground.  In
  297.      medium it's pot 3.  If you aren't satisfied with the foreground color
  298.      after changing resolutions use the color command (see below) to change
  299.      it.
  300.  
  301.      One last caveat.  There are some programs that check the system
  302.      resolution and work fine after ASH has changed resolution.  There are
  303.      others that don't detect the fact that the resolution has changed and
  304.      continue to complain about the system being in medium even when it's
  305.      obvious that the screen is in low.  Any hints as to how I can make ASH
  306.      convince everyone the resolution has changed are welcome.
  307.  
  308. color {-f | -b} [RGB]
  309.      The color command is used to report or change the foreground and
  310.      background colors of the screen.  The '-f' and '-b' screen section
  311.      flags stand for foreground and background respectively.  When invoked
  312.      with only a screen section flag this command reports the current color
  313.      mix for that section.  You can select a new color mix for the
  314.      foreground and background color pots by including a 'RGB' parameter in
  315.      the color command.
  316.  
  317.      The 'RGB' parameter must be a 3 digit number with each digit ranging
  318.      from 0 to 7.  The first digit is the intensity level of RED used to
  319.      compose the new color.  The second digit is the GREEN intensity level
  320.      and the third is the BLUE.  This gives you access to 512 possible
  321.      colors.  A value of 000 will generate BLACK, 777 will generate WHITE,
  322.      070 will be intense GREEN and so on.  It can be interesting mixing
  323.  
  324.  
  325.  
  326.                                    - 5 -
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.                                  ASH V0.70
  335.  
  336.  
  337.  
  338.      your foreground and background colors but be careful not to make them
  339.      identical or you'll be flying blind.
  340.  
  341. ls [-s] [-l] [-h] [d:][file]
  342.      The ls command lists directory information about the files specified
  343.      or about all files on the current drive and directory if no files or
  344.      any other type of file specification is given.  You can use drive
  345.      specifications or directories as arguments to ls and the entire
  346.      contents of that drive or directory will be listed.
  347.  
  348.      The '-s' flag causes the sizes of the files to be listed in addition
  349.      to the file names.  The '-l' flag causes a long listing with the
  350.      names, sizes, times and dates of the last modification, etc. included
  351.      in the output.  The '-h' flag causes hidden files to show up in the
  352.      listing.  The order of the files is exactly their order in the
  353.      directory.  At this time there is no option to sort the files listed
  354.      by name, extension, size or time stamp.
  355.  
  356. df [-t] [d: ...]
  357.      The df command will display the free space remaining on the drives
  358.      specified.  If no drives are specified then the free space on the
  359.      current drive is given.  The '-t' flag will cause the total amount of
  360.      space on a drive to be listed as well.
  361.  
  362. cat [-n] file [file ...]
  363.      The cat command will cause the files specified to be sent to the
  364.      screen in a paginated form.  You will be prompted to hit a key after
  365.      every screen full of output.  When using output redirection, or if cat
  366.      is invoked from a script, pagination is turned off.  The '-n' flag
  367.      will cause line numbers to be included in the display.
  368.  
  369. opr [-n] [-oN] file [file ...]
  370.      The opr command will print the specified files on the printer.  The
  371.      '-n' flag will cause line numbers to be included in the output.  The
  372.      '-oN' flag will cause the left margin to be offset or padded by 'N'
  373.      spaces.  The set variable OPRINIT can be used to initialize the
  374.      printer for a given invocation of opr.  See the section on SET
  375.      VARIABLES below for details.
  376.  
  377. cp file1 file2
  378.      The cp command will copy 'file1' to 'file2' if there are only two
  379.      arguments and both are files.
  380.  
  381. cp file1 ... filen dir
  382.      This invocation of the cp command will copy the first through the next
  383.      to last arguments, which must be files, to the last argument, which
  384.      must be a directory or drive specification.  New files created with cp
  385.      have a time stamp corresponding to the time they were copied.
  386.  
  387.      WARNING: Unlike the desktop copy routine (dragging to another window),
  388.      the cp command does not care if there are conflicting file names.  It
  389.  
  390.  
  391.  
  392.                                    - 6 -
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.                                  ASH V0.70
  401.  
  402.  
  403.  
  404.      will copy over a file with the same name in the target directory or
  405.      drive without any warning.
  406.  
  407. mv file1 file2
  408.      The mv command will move or rename 'file1' to 'file2' if there are
  409.      only two arguments and both are files.
  410.  
  411. mv file1 ... filen dir
  412.      This invocation of the mv command will move the first through the next
  413.      to last arguments, which must be files, to the last argument, which
  414.      must be a directory or drive specification.  Files moved with mv
  415.      retain their original time stamp even when physically created on a new
  416.      drive.
  417.  
  418.      WARNING: Unlike the desktop rename routine (SHOW INFO), the mv command
  419.      does not care if there are conflicting file names.  It will move over
  420.      a file with the same name in the target directory or drive without any
  421.      warning.
  422.  
  423. rm [-i] file [file ...]
  424.      The rm command removes or erases the files specified.  If you're the
  425.      cautious type the '-i' flag will cause rm to work interactively.  In
  426.      this mode rm will prompt you with each file name and wait for you to
  427.      respond with a 'y' or 'n' before removing the file.  If you respond
  428.      with a 'q' the rm is aborted but the files already removed are gone.
  429.  
  430.      WARNING: Unlike the desktop remove routine (dragging to the TRASH),
  431.      the rm command does not prompt you to verify if you got the file name
  432.      right.  It will remove your files with no remorse if asked to do so.
  433.      If you want to verify the expansion of a wildcard argument before
  434.      using it with rm, try it with echo first and make sure you aren't
  435.      specifying some files you want to keep.
  436.  
  437. attr {-w | -r} file [file...]
  438.      The attr command allows you to set the read and write or read only
  439.      attributes of a file.  Most files default to read and write.  For
  440.      example, if you execute an ls command with the '-l' flag on a file
  441.      with read and write permission you'll see the attributes as 'R/W'.  A
  442.      file with read only permission will have 'R/O' in the attributes
  443.      column.  A file with read and write attributes can be removed or
  444.      modified.  A read only file is protected.  It can be copied or printed
  445.      but it can't be removed or modified.
  446.  
  447. cd dir
  448.      The cd command is used to change the current working directory.  You
  449.      can change to directories on the same drive or you can change to
  450.      directories that cross drive boundaries.  Don't confuse the latter
  451.      with changing the current drive.  To change drives you simply type the
  452.      drive specification of the drive you want to change to.  For example
  453.      to change to drive A you would type:
  454.  
  455.  
  456.  
  457.  
  458.                                    - 7 -
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.                                  ASH V0.70
  467.  
  468.  
  469.  
  470.                a:
  471.  
  472.      If you had previously been in the AUTO folder on A you would then be
  473.      back in A:\AUTO.  If you executed the command:
  474.  
  475.                cd a:
  476.  
  477.      you would be placed in the base directory of the A drive.  In general,
  478.      to get to A:\AUTO you should explicitly execute:
  479.  
  480.                cd a:\auto
  481.  
  482.      Remember that directory paths on the ST use backslashes (\) instead of
  483.      slashes (/).
  484.  
  485. pwd
  486.      The pwd command will display the current working directory.  This can
  487.      be redundant if the default of having the current directory included
  488.      in your prompt is on.  (See the ^P command above.)
  489.  
  490. mkdir dir [dir ...]
  491.      The mkdir command is used to create new directories.  Directory names
  492.      have the same restrictions as file names.
  493.  
  494. rmdir dir [dir ...]
  495.      The rmdir command is used to remove EMPTY directories.  Notice the
  496.      EMPTY.  You must remove the contents of a directory before you can
  497.      remove the directory itself.
  498.  
  499.  
  500. COMMAND HISTORY:
  501.  
  502. ASH uses a command history buffer that holds up to the last 23 command
  503. lines typed from the keyboard.  The command lines in this buffer can be
  504. listed (^L), repeated (^R) and edited (ESC) with a set of simple line
  505. editing commands.  The command lines in the history buffer are numbered
  506. from 1 to 23 with the most recent command line being number 1 and the
  507. oldest being number 23.  Each new command line causes the lines already in
  508. the buffer to age by one.  Once a command line has aged past 23 it's gone
  509. for good.
  510.  
  511.  
  512. HISTORY EDIT COMMANDS:
  513.  
  514. When you've put ASH in the history edit mode with the escape (ESC) key,
  515. there are a number of single key commands available with which you can call
  516. back previous commands and modify them.  You have to be in history edit
  517. mode for these commands to work.  I've abbreviated the up, down, left and
  518. right arrow keys as UA, DA, LA and RA respectively.
  519.  
  520.  
  521.  
  522.  
  523.  
  524.                                    - 8 -
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.                                  ASH V0.70
  533.  
  534.  
  535.  
  536. UA/-/k    These three keys let you browse backwards through the commands in
  537.           the history buffer.  When you get to the end you'll be beeped.
  538.  
  539. DA/+/j    These three keys let you browse forwards through the commands in
  540.           the history buffer.  When you get to the beginning you'll be
  541.           beeped.
  542.  
  543. LA/BS/h   Any of these three keys cause the cursor to move backwards or
  544.           left one character on the current command line.  You can't move
  545.           past the first character of the command line.
  546.  
  547. RA/SP/l   Any of these three keys cause the cursor to move forwards or
  548.           right one character on the current command line.  You can't move
  549.           past the last character of the command line.
  550.  
  551. 0         This key (zero) causes the cursor to move to the first character
  552.           of the currently displayed command line.
  553.  
  554. ^         This key causes the cursor to move to the first visible character
  555.           of the currently displayed command line.  If there are spaces at
  556.           the beginning of the command line this will skip over them.
  557.  
  558. $         This key causes the cursor to move to the last character of the
  559.           currently displayed command line.
  560.  
  561. In the next three commands the distinction is made between a word and a
  562. WORD.  For this discussion a word is delimited by any non-alphanumeric
  563. characters like punctuation marks, spaces or other special symbols.  A WORD
  564. is delimited by only white space.
  565.  
  566. w/W       These two keys cause the cursor to move right or forward to the
  567.           beginning of a word or a WORD respectively.
  568.  
  569. e/E       These two keys cause the cursor to move right or forward to the
  570.           end of a word or a WORD respectively.
  571.  
  572. b/B       These two keys cause the cursor to move left or back to the
  573.           beginning of a word or a WORD respectively.
  574.  
  575. ~         This key will change the case (if alphabetic) of the current
  576.           character from upper to lower case or from lower to upper case.
  577.           The cursor moves forward past the character changed.  Non-
  578.           alphabetic characters are simply skipped over.
  579.  
  580. r         This key will cause the current character to be replaced with
  581.           another single character.  The next character typed will be used
  582.           as the replacement.
  583.  
  584. x         This key will cause the current character to be crossed out or
  585.           deleted.
  586.  
  587.  
  588.  
  589.  
  590.                                    - 9 -
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.                                  ASH V0.70
  599.  
  600.  
  601.  
  602. d         This key will cause the current character to be deleted.  It's
  603.           functionally the same as the 'x' command.
  604.  
  605. D         This key will cause the rest of the command line including the
  606.           current character to be deleted.
  607.  
  608. The next seven keys cause the history editor to go into insert mode where
  609. you can add multiple characters to the command line.  To stop adding
  610. characters you must hit the ESC key.  You will then be back in history edit
  611. command mode.
  612.  
  613. s         This key lets you substitute multiple characters for the current
  614.           character.
  615.  
  616. c         This key lets you change the current character for multiple new
  617.           characters.  It's functionally the same as the 's' command.
  618.  
  619. C         This key will cause the rest of the command line including the
  620.           current character to be changed for multiple new characters.
  621.  
  622. i         This key lets you start inserting characters before the current
  623.           character on the command line.  The INSERT key, in the group with
  624.           the arrow keys, works just like 'i'.
  625.  
  626. I         This key lets you start inserting characters before the first
  627.           character in the command line.
  628.  
  629. a         This key lets you start appending characters after the current
  630.           character in the command line.
  631.  
  632. A         This key lets you start appending characters after the last
  633.           character in the command line.
  634.  
  635. CR/LF     These keys cause the history editor to be exited and the
  636.           currently displayed command line to be executed.
  637.  
  638. ^C/^U/^X  These keys cause the history editor to be aborted without
  639.           executing the currently displayed command line.
  640.  
  641. HELP      This key will cause a brief summary of all the history editing
  642.           commands to be displayed.
  643.  
  644. There has to be a caveat to history editing.  The history editing commands
  645. will work on lines that wrap around the screen but the display is not
  646. adjusted in any way.  In other words, editing command lines that are longer
  647. than one physical line can be interesting.
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.                                   - 10 -
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.                                  ASH V0.70
  665.  
  666.  
  667.  
  668. I/O REDIRECTION:
  669.  
  670. This version of ASH has I/O redirection built into the built-in commands.
  671. The standard '<file', '>file' and '>>file' arguments will cause standard
  672. input to be redirected from file, standard output to be redirected to
  673. overwrite or create file and standard output to be redirected to append to
  674. or create file respectively.  There can be NO SPACE between the redirection
  675. characters and the redirection file name.  The redirection arguments to
  676. built-in commands can appear anywhere in the list of command arguments.
  677. The redirection of standard input is of dubious value since none of the
  678. built-in commands currently use standard input.  NOTE: standard error is
  679. not redirectable at this time.
  680.  
  681. Redirection for external commands that get executed by ASH depends entirely
  682. on how those commands were created.  If they were created with most of the
  683. standard C development packages they should support similar redirection
  684. arguments.  Megamax, Lattice, Mark Williams and the Developers Kit all
  685. support I/O redirection for programs that are built with them.  Some
  686. require that the main() function be declared with argc and argv as
  687. arguments and some require the redirection arguments to be the first
  688. arguments on the command line.  You'll have to refer to the documentation
  689. that comes with the programs you use or try them to see how they work.
  690.  
  691.  
  692. COMMAND LINES:
  693.  
  694. Command lines can be up to 255 characters long.  Built-in commands can use
  695. the entire 255 characters.  External commands that are invoked by the
  696. Pexec() GEMDOS call are limited to a command tail of 127 characters.  The
  697. command name itself isn't included in this 127 characters so the effective
  698. length of an external command is over 127 characters but not too much.  If
  699. the command tail limit is exceeded ASH will print an error message and
  700. ignore the command.
  701.  
  702. You can enter multiple ASH commands on one command line by separating them
  703. with semi-colons (;).  Everything on a command line after a pound sign (#)
  704. is treated as a comment.  Command separators and comment characters can be
  705. quoted with apostrophes (') or double quotes (") if they're needed as part
  706. of a command's arguments.  If you want a double quote or apostrophe to be
  707. included in an argument you must quote it with the other quoting character.
  708. For example, this echo command will generate an error:
  709.  
  710.           echo this won't work
  711.  
  712. The apostrophe is parsed as a mismatched quote.  The following command
  713. works because the apostrophe is quoted:
  714.  
  715.           echo "this won't work (yes it will)"
  716.  
  717. The same quoting mechanism is applicable to the wildcard characters * and
  718. ?.  ASH expands all arguments containing wildcards before passing them on
  719.  
  720.  
  721.  
  722.                                   - 11 -
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.                                  ASH V0.70
  731.  
  732.  
  733.  
  734. to external programs.  If you want an external program to do the expansion
  735. then you must quote ambiguous file specifications like '*.NEO' or
  736. 'BUFF?.TMP'.
  737.  
  738.  
  739. SET VARIABLES:
  740.  
  741. The number of set variables is limited to 32 and the size of a single
  742. 'variable=value' string is limited to 255 characters.  Set variables can be
  743. used in command lines by putting a dollar sign in front of them.  Some set
  744. variables have special meanings to ASH.
  745.  
  746. The ECHO set variable is used to turn command echoing on in scripts.  If
  747. ECHO is set to 'ON' or 'on' commands will be echoed before they're
  748. executed.  If ECHO isn't set, or is set to any other value, scripts run
  749. silently.  Scripts are silent by default.
  750.  
  751. The set variable OPRINIT can be defined with a printer initialization
  752. sequence that will be sent to the printer before any other output when the
  753. opr command is executed.  The expansion of backslash ASCII character
  754. sequences, like those explained in the description of the echo command, is
  755. done on the OPRINIT value before sending it to the printer.  This allows
  756. escape sequences and other control characters to be used.  For example, I
  757. have an Epson FX80 and I frequently set OPRINIT like this:
  758.  
  759.           set OPRINIT=\033M
  760.  
  761. This backslash sequence is converted to ESC-M and sets the printer to elite
  762. or 12 character per inch mode.
  763.  
  764. The set variables F1, F2, ... F9 and F10 can be used to program the
  765. corresponding function keys.  For example, if the F2 set variable were set
  766. to 'ls -l' then that string would be added to the command line when you hit
  767. function key F2.  Since there's no CR or LF in that string you would have
  768. to hit a CR after hitting F2 in order to execute the 'ls -l'.  To terminate
  769. a function key set variable with a CR or LF use the backslash sequence for
  770. it.  For example, if F2 were set to 'ls -l\012' then hitting function key
  771. F2 would execute the 'ls -l'.  The backslash sequence for CR is \015 and
  772. the backslash sequence for LF is \012.
  773.  
  774. The PATH set variable is used to decide where ASH looks for commands that
  775. aren't built-in, for the ASH initialization file and for the ASH help file.
  776. The same syntax is used as in the MS-D*S PATH, where semi-colons (;)
  777. separate the various drives and directories in a PATH.  When setting PATH
  778. semi-colons must be quoted so they're not interpreted as command
  779. separators.
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.  
  788.                                   - 12 -
  789.  
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.                                  ASH V0.70
  797.  
  798.  
  799.  
  800. ASH INITIALIZATION:
  801.  
  802. When ASH is first invoked interactively PATH is set to the base of all the
  803. installed drives on the system.  This setting is then used to look for the
  804. ASH initialization file.  The ASH initialization file is named 'ash.ini'
  805. and must be in the current directory or on one of the drives in the initial
  806. PATH.  Since GEMDOS considers both the A and B floppies to be installed,
  807. even if there's only one floppy drive physically attached to the computer,
  808. it's a good idea to have your 'ash.ini' file on the floppy from which you
  809. invoke ASH.  If you invoke ASH from a folder on a hard disk you should have
  810. your 'ash.ini' file in that folder.
  811.  
  812. The ASH initialization file can contain any valid ASH commands.  It's handy
  813. for redefining the PATH value or adding to the initial PATH.  For example,
  814. you can avoid having to keep a floppy in your floppy drive by defining the
  815. floppy drives out of PATH.  The following 'ash.ini' file will modify PATH,
  816. display it, define some function keys and turn on echoing in scripts:
  817.  
  818.           set PATH="c:\bin;$PATH"
  819.           echo "PATH=$PATH"
  820.           set F1='ls -l\012'         # F1 executes a 'ls -l'
  821.           set F2='df -t\012'         # F2 executes a 'df -t'
  822.           set F3='set ECHO=off\012'  # F3 turns off echoing
  823.           set F4='set ECHO=on\012'   # F4 turns on echoing
  824.           set ECHO=on
  825.  
  826. Notice the quotes used with PATH to override the interpretation of semi-
  827. colons as command separators.
  828.  
  829.  
  830. COMMAND SELECTION:
  831.  
  832. ASH initially checks each command it parses to see if it's built-in.  If
  833. it's built-in ASH executes it.  If a command isn't built-in ASH checks for
  834. a file suffix.  If there's no suffix it will try each of the four standard
  835. command suffixes (.prg, .ttp, .tos and .ash) in that order.  It first
  836. checks for a command in the current directory.  If it's not found in the
  837. current directory it then looks in the directories specified with the PATH
  838. set variable as explained above.
  839.  
  840. As an example, say the command 'FORMAT' was parsed by ASH.  It would first
  841. check to see if there was a built-in command 'FORMAT'.  Since there isn't
  842. it would then search for the command 'FORMAT.PRG' in the current directory.
  843. If that failed it would look for a command 'FORMAT.TTP' in the current
  844. directory.  If that failed it would look for 'FORMAT.TOS' and 'FORMAT.ASH'
  845. in that order in the current directory.  If all these failed it would then
  846. look for the same commands in the same order in the first directory
  847. specified in PATH.  If all the directories in PATH were exhausted and a
  848. command that fit this name had still not been found ASH would give up and
  849. state that the command wasn't found.
  850.  
  851.  
  852.  
  853.  
  854.                                   - 13 -
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.                                  ASH V0.70
  863.  
  864.  
  865.  
  866. ASH SCRIPTS:
  867.  
  868. Commands with the .ash suffix are ASH scripts.  They're invoked by
  869. executing ASH on the script recursively.  Scripts can also be used with ASH
  870. by invoking it with the name of a script as the first argument.  Up to 9
  871. arguments can be included on a script command line.  They're parsed inside
  872. the script the way positional arguments are parsed in UN*X;  $0 through $9.
  873. Since that's 10 arguments I should explain that $0 is set to the name of
  874. the script that's executing.  Scripts that call other scripts cause ASH to
  875. recurse and use up memory in the process stack.  I've tested V0.70 to 9
  876. levels deep with no problems.  After that the results are undetermined but
  877. probably not what you want.
  878.  
  879. Because of the recursive nature of scripts, the set variables from the
  880. calling invocation of ASH are available to scripts.  Scripts can make
  881. changes to the set variables or change the current drive and directory but
  882. those changes are only in effect during the life of the script.  If you
  883. want a script to make lasting changes you must invoke it with the dot
  884. command.  For example to run the script 'clean.ash' you have two options.
  885. If you want the current set variables and the current drive and directory
  886. to be unchanged when it exits invoke it like this:
  887.  
  888.           clean
  889.  
  890. If you want any changes to the set variables or the current drive and
  891. directory to stick around after 'clean.ash' exits, invoke it like this:
  892.  
  893.           . clean
  894.  
  895.  
  896. LIMITATIONS:
  897.  
  898. Some of the limits in ASH are listed below.  If your normal use of ASH
  899. exceeds them please let me know.  The program can allocate more memory for
  900. some of these values while others are fixed by the underlying Atari ST
  901. operating system.
  902.  
  903.            23 -  commands in the history buffer
  904.           127 -  characters per external (Pexec) command tail
  905.           255 -  characters per built-in command
  906.           255 -  characters per command line
  907.  
  908.            64 -  arguments per command line including the command name
  909.           127 -  characters per argument
  910.  
  911.            32 -  possible set variables
  912.           255 -  characters per set variable
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.                                   - 14 -
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.                                  ASH V0.70
  929.  
  930.  
  931.  
  932. MISCELLANEOUS:
  933.  
  934. Any time you're confronted with the '[more...]' prompt at the bottom of the
  935. screen you can type a 'q' to avoid seeing whatever there's more of.
  936.  
  937. In some instances after switching floppy disks you may have to execute a df
  938. or ls on the drive to make the system recognize the change.  You should
  939. also be careful about changing floppies when the current working directory
  940. on the floppy being removed isn't the base directory.
  941.  
  942. The mouse cursor is normally hidden while ASH is running.  If you jiggle
  943. the mouse a block of background color and a busy bee will show up but they
  944. will scroll off the screen with normal use.  The mouse is kept alive for
  945. any GEM programs that need it and don't turn it on themselves.
  946.  
  947. The ASH help file is called 'ash.hlp'.  When help is requested ASH first
  948. looks for the help file in the current directory and then in each of the
  949. directories in PATH.  If you want to save disk space ASH will run without
  950. the help file.
  951.  
  952.  
  953. V0.70 NOTES:
  954.  
  955. Version 0.70 of ASH was compiled with the Megamax C Language Development
  956. System.  It now has dynamic memory allocation and several other
  957. improvements that weren't in V0.52.  Some of the more noticeable changes
  958. are:
  959.  
  960.    - I/O redirection is supported for built-in commands.
  961.  
  962.    - The . and .. files are ignored in rm commands whether they're
  963.      explicitly specified on the command line or generated through wildcard
  964.      expansion.  They can't be removed so there isn't much point in trying.
  965.      They're also ignored at appropriate times in cp and mv commands.
  966.  
  967.    - The intelligent keyboard clock is now set by the date command.
  968.  
  969.    - The mv command doesn't change a file's time stamp.
  970.  
  971.    - The arrow keys and the INSERT key are now active for history editing.
  972.  
  973.    - The 'ash.ini' initialization file handling has improved since any
  974.      valid ASH commands are now allowed.
  975.  
  976.    - Script speed and memory usage has improved since ASH recurses now.
  977.  
  978.    - Scripts inherit the calling ASH's set variables and can modify them if
  979.      called with the dot command.
  980.  
  981.    - The cp command works much faster now.  It's comparable to desktop
  982.      drags.
  983.  
  984.  
  985.  
  986.                                   - 15 -
  987.  
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.                                  ASH V0.70
  995.  
  996.  
  997.  
  998.    - The ls command now has a -h option for hidden/system files.
  999.  
  1000.    - The opr command now has a -oN option to offset the left margin.
  1001.  
  1002.    - The opr command now has a way to initialize the printer with the
  1003.      OPRINIT set variable.
  1004.  
  1005.    - The mkdir and rmdir commands now take multiple  directory arguments.
  1006.  
  1007.    - If you ever wondered what to do with those slanty function keys ASH
  1008.      now gives you the ability to program them using set variables.  See
  1009.      the SET VARIABLES section above.
  1010.  
  1011.    - There is a new attr command which allows you to change the read and
  1012.      write attributes of a file to read only and back again.  This
  1013.      implements file protection as requested by several people.
  1014.  
  1015.    - There is a new unset command which allows you delete variables from
  1016.      the defined list of set variables.
  1017.  
  1018.    - You now have the ability to repeat (^R) a range of command lines from
  1019.      the command history buffer.
  1020.  
  1021. I plan to add several more features to ASH in the future.  Aliasing of
  1022. command names and some type of flow control commands like IF/FOR/WHILE are
  1023. on my list.  I'm willing to consider suggestions for other improvements.
  1024. Please mail your suggestions to the address in the beginning of this
  1025. document.  Thanks.
  1026.  
  1027.  
  1028.  
  1029.  
  1030.  
  1031.  
  1032.  
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.                                   - 16 -
  1053.  
  1054.  
  1055.  
  1056.  
  1057. əəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəə