home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 6 File / 06-File.zip / dfsee510.zip / dfsyntax.txt < prev    next >
Text File  |  2003-01-14  |  9KB  |  247 lines
  1.   Display File Systems; version 5.08 01-01-2003  (c) 1994-2003; Jan van Wijk
  2.  ----------------------------[ www.dfsee.com ]-------------------------------
  3.  
  4.  
  5. C O N T E N T S:
  6. ================
  7.  
  8.   Syntax rules            = General syntax rules for DFSee
  9.   Option syntax           = syntax for individual options or switches
  10.   Parameter syntax        = syntax for individual parameters or arguments
  11.   DFSee command syntax    = Notes on DFSee command options and parameters
  12.   General settings        = Notes on DFSee program switches and arguments
  13.   Documentation           = Notes on how the command syntax is documented
  14.  
  15.  
  16.  
  17. S Y N T A X    R U L E S
  18. ========================
  19.  
  20. The DFSee program uses the same 'parser' module to process the general
  21. settings on the DFSee commandline and to process each DFSee command
  22. encountered in an interactive session or DFSee script.
  23.  
  24. Because of this, the syntax rules for both are very similar.
  25. This chapter describes the rules and possibilities of the syntax.
  26.  
  27. In general, most programs require some information to specify what task
  28. has to be done, and what data should be used for that task.
  29. Programs that are command-line based, like DFSee use command-line items
  30. to represent that information. GUI based programs would most likely use
  31. dialog windows with entry-fields, buttons and selections lists for this.
  32.  
  33. The information for command-line programs often comes in two forms:
  34.  
  35. 1) OPTIONS:    Information that has a 'name' and an optional value.
  36.                Because each option has a unique name, they can be
  37.                identified easily and can appear in any order.
  38.  
  39.                Note: Options are sometimes called "switches"
  40.  
  41.  
  42. 2) PARAMETERS: Information that consists of the value itself without an
  43.                explicit name. When more than one parameter is present,
  44.                they need to be identified by the position they appear on
  45.                the command-line (1st parameter, 2nd parameter and so on)
  46.  
  47.                Note: Parameters are sometimes called "arguments"
  48.  
  49.  
  50.  
  51. As a simple example, not related to DFSee at all, consider:
  52.  
  53.  
  54. XCOPY  *.txt  d:\tmp  /s /r
  55.  
  56. In this command-line we see five different parts:
  57.  
  58. 'XCOPY'         the command
  59. '*.txt'         the first parameter, here the source for the copy
  60. 'd:\tmp'        the second parameter, the destination
  61. '/s'            an option for the command, here a 'subdirectory' indicator
  62. '/r'            an option for the command, her a read-only indicator
  63.  
  64. Note that the order of the parameters IS significant (source and destination)
  65. but the order of the options is not, '/r /s' would be fine too.
  66.  
  67. Also note that the options are preceded by a special character '/' that
  68. makes them easy to recognize. This is often called the 'switch-character'.
  69. On UNIX and Linux this is the '-' character and on DOS (and similar)
  70. systems it is the '/' character and most DOS and OS/2 programs actually
  71. accept both of them as valid.
  72.  
  73. Within DFSee, the ONLY valid option- or switch-character is the hyphen: '-'
  74.  
  75.  
  76. O P T I O N   S Y N T A X
  77. =========================
  78.  
  79. The syntax for every option (or 'switch') is:
  80.  
  81.    -name[:value[,unit]]
  82.  
  83.     -      = the mandatory switch or option-character, a hyphen
  84.  
  85.     name   = name for the option, only the FIRST character is significant
  86.              so the options '-volume:test' and '-v:test' are equivalent.
  87.  
  88.     :      = the optional separator between name and value of the option
  89.  
  90.     value  = the optional value for this option, it can take two forms:
  91.  
  92.              - a number, either decimal or hexa-decimal
  93.                To force a decimal-numeric, start the number with '0'
  94.                To force a hexa-decimal-numeric, start it with '0x'
  95.  
  96.              - a string, either a single word or multiple words
  97.                enclosed in double-quotes
  98.  
  99.     ,      = the optional seperator between value and unit
  100.  
  101.     unit   = A unit specifier like 'cylinder', 'mb' or 'sector'
  102.              Only numeric options can take a unit specifier.
  103.              (also see description of 'mcs-number' in DFSTERMS.TXT)
  104.  
  105.    Often options or switches are used to signal an ON/OFF or SET/NOT-SET
  106.    condition (boolean value). In that case the presence of the option is
  107.    interpreted as 'option ON' and the absence of the option as 'option OFF'
  108.    This is equivalent to numeric value '0' meaning 'OFF' and any other
  109.    numeric value or a string meaning 'ON'.
  110.  
  111.    There is one special form to explicitly set an option to 'OFF' that is
  112.    usefull for switches and options that have a default value of 'ON':
  113.  
  114.    -o-
  115.  
  116.    This is interpreted as 'option 'o' is explicitly set to 'OFF'
  117.  
  118.    No spaces can occur within an option, except when inside a
  119.    double-quoted string value.
  120.  
  121.    Some examples of valid options with a short descrition:
  122.  
  123.  
  124.    -a                             ;option 'a' is set (ON)
  125.    -a-                            ;option 'a' is not set (OFF)
  126.    -absolute:0                    ;option 'a' is not set (OFF)
  127.    -abs:50                        ;option 'a' has numeric value 50
  128.    -abs:50,c                      ;option 'a' has numeric value 50 cylinders
  129.    -abs:0x20                      ;option 'a' has hexadecimal value 20
  130.    -name:test                     ;option 'n' has string value "test"
  131.    -n:"another one"               ;option 'n' has string value "another one"
  132.  
  133.  
  134.  
  135. P A R A M E T E R   S Y N T A X
  136. ===============================
  137.  
  138. The syntax for parameters is quite simple, a parameter is a single word,
  139. or multiple words enclosed in double quotes.
  140.  
  141.  
  142. D F S E E   C O M M A N D   S Y N T A X
  143. =======================================
  144.  
  145. DFSee commands consist of the command-word followed by any number
  146. of options and parameters. As said before the parameters need to be
  147. in the right order (for this command) but the options may appear at
  148. any position after the command-word, which is always the FIRST word.
  149.  
  150. Options can even appear between parameters, this is called a FREE-FORM
  151. syntax. However the place an option is seen has NO influence on the
  152. meaning or the scope of that option.
  153.  
  154. Some examples of valid commands with options and parameters are:
  155.  
  156. PART -q  3                        ;select partition 3 quietly
  157. PART 3  -q                        ;select partition 3 quietly
  158.  
  159. CR  log hpfs  -size:100 -e        ;create logical 100Mb HPFS at end
  160. CR  log -e -size:100  hpfs        ;create logical 100Mb HPFS at end
  161.  
  162. Note on the 'CR' example that the order of the options changed, but
  163. the parameters 'log' and 'hpfs' are in the same order.
  164.  
  165.  
  166. When using options in DFSee, you don't NEED parameters, they serve
  167. the same purpose. It is just for convenience and backward compatibility
  168. that positional parameters are still supported on some commands.
  169.  
  170. As an example, see the description if the "CR" command (or CREATE) in
  171. DFSFDISK.TXT. There you will see a full list of parameters (old style)
  172. and options (new style) for the same information to be used.
  173.  
  174. Options are more readable and flexible than positional-parameters
  175. so I try to use them for as many commands as possible.
  176.  
  177.  
  178.  
  179. Multi-commands
  180. --------------
  181.  
  182. DFSee allows multiple commands to be combined onto a single commandline.
  183. This can be very usefull in scripts (see DFSUNFD.CMD).
  184.  
  185. The syntax for such multiple-commands is:
  186.  
  187.         command-1#command-2#command-3 ...#command-n
  188.  
  189. Each command must contain a command-word, and can contain options and
  190. parameters as described above.
  191.  
  192.  
  193.  
  194. G E N E R A L   S E T T I N G S
  195. ===============================
  196.  
  197. The executable 'DFSee' program itself, can receive information from
  198. the operating-system commandline too. DFSee uses these to allow some
  199. general settings to be made, and to pass commands to be executed.
  200.  
  201. Because the 'parameters' passed to the DFSee EXE are 'DFSee commands'
  202. there might be confusion about some options, are they 'general' ones
  203. for the executable, or specific for the command specified ?
  204.  
  205. To solve this potential dilemma, all options that appear before the
  206. first parameter (a DFSee command) are considered as general settings
  207. or 'switches'. All options AFTER that are options for the command.
  208.  
  209. An example to illustrate this is:
  210.  
  211.         DFSOS2.EXE  -w- -Q  part -t- -m
  212.  
  213. Here the first parameter is the command 'part' and the options
  214. that appear before it: '-w- -Q' are switches for the executable
  215. while 't' -m' are two options for the 'part' command.
  216.  
  217.  
  218. Available switches are listed with: "DFSOS2.EXE  -?"
  219.  
  220.  
  221. Note: Substitute DFSDOS.EXE or DFSWIN.EXE for DOS or Windows-NT respectively.
  222.  
  223.  
  224.  
  225. D O C U M E N T A T I O N
  226. =========================
  227.  
  228. About the sections you see in the documentation files (like DFSCMDS.TXT),
  229. they usually start with a single line as a summary for the command, and then
  230.  
  231. Purpose:        Short description about the 'why' ...
  232. Parameters:     Description of the parameter(s)
  233. Options:        Description of the options
  234. Output:         Description of what kind of output goes to the screen
  235. Examples:       Example commandlines with this command
  236. Remarks:        Any additional on the command or its usage
  237.  
  238.  
  239. Not all commands have (or need) all these sections and since documenation is
  240. written over time, it is not 100% consistent either, but I try to clean it up
  241. whenever I make changes to it.
  242.  
  243.  
  244.  
  245.  ----------------------------[ www.dfsee.com ]-------------------------------
  246.  
  247.