workbench/utilities/Installer/Documentation

   1 Parsing the script
   2 ------------------
   3         Read in 'tokens' and braces and save into tree structure.
   4         Actually there is no "pre-compiling" done as stated in the
   5         original Installer docs.
   6
   7
   8 Data Types
   9 ----------
  10 <int>
  11         is an integer of type (long int)
  12         Its representation is a decimal number or
  13         $xxx will be considered as HEX and
  14         %xxxx as binary numbers.
  15         Boolean arguments are 0 for FALSE and non-0 for TRUE.
  16         Boolean functions return 1 as TRUE.
  17
  18 <string>
  19         is a quoted ("..." or '...') string
  20
  21 Arguments without quotes are considered to be variables
  22         Variables are typeless and converted to the functions needs
  23         (exception is ( <format-string> <arguments>... ) where the variable
  24           is checked for a non-NULL string or the integer value will be
  25           used which will be 0 for unset variables
  26         )
  27         and therefore being exchanged by their values at runtime
  28         ( <string> is converted via atol( <string> );
  29           <int> is converted via sprintf( string, "%ld", <int> );
  30         )
  31         Unset variables are NULL in string and 0 in integer value.
  32         Commands can be used as arguments, too, as the return value
  33         will be taken.
  34         Example: ( set sum ( + a b ) )
  35
  36
  37 Executing the script
  38 --------------------
  39 Arguments in [...] are optional.
  40
  41 ( (...)... )
  42   Blocks. If the first argument in brackets is a command (...) all
  43   others have to be commands, too.
  44   The return value is the return value of the last command in the block.
  45   Empty blocks are not allowed.
  46
  47   If a command is not recognized an error SCRIPTERROR is produced.
  48
  49
  50 ( abort [<string>...] )
  51   Shows strings and executes trap or onerror statements if present and
  52   exits abnormally.
  53   This function never returns.
  54
  55
  56 ( and   <int> <int> )
  57 ( or    <int> <int> )
  58 ( xor   <int> <int> )
  59 ( bitand <int> <int> )
  60 ( bitor  <int> <int> )
  61 ( bitxor <int> <int> )
  62 ( <>    <int> <int> )
  63 ( <     <int> <int> )
  64 ( <=    <int> <int> )
  65 ( =     <int> <int> )
  66 ( >     <int> <int> )
  67 ( >=    <int> <int> )
  68 ( -     <int> <int> )
  69 ( /     <int> <int> )
  70 ( shiftleft <int> <int> )
  71 ( shiftrght <int> <int> )
  72   These functions return the result of the operations on the two integers.
  73   For logical operations 1 is returned as TRUE and 0 as FALSE.
  74   ( / <int> <int> ) checks 2nd arg == zero and produces an error BADPARAMETER.
  75
  76
  77 ( cat <any>... )
  78   Concatenates all args as strings. This function was intended to be the only
  79   valid function for converting <int> to <string>
  80   (Well, except ( "..." ... ), too )
  81   The return value is the quoted string.
  82
  83
  84 ( complete <int> )
  85   Tells the user how much ( in percent ) is already done.
  86   The return value is the percentage.
  87   NOTE: We do not check for percentage < 0 or > 100 !!!
  88
  89
  90 ( debug <any>... )
  91   If run from Shell and DEBUG was specified in the command line
  92   the arguments (strings, integers, variables) will be printf()'ed
  93   to the shell separated by spaces.
  94   The return value is the quoted string of all concatenated arguments.
  95
  96
  97 ( exit [(quiet)] [<string>...] )
  98   Shows the strings separated by a linefeed and exits normally.
  99   A summarizing message with information on where the app was installed
 100   and the log-file can be found will be displayed unless (quiet) is
 101   specified as a parameter.
 102   This function never returns.
 103
 104
 105 ( if <int> <then> [<else>] )
 106   <int> is checked for !=0 and returns <then> otherwise <else> or 0 if
 107   <else> is left out. If <then> is a string and <else> is omitted this
 108   function returns an empty string as the false value.
 109   <int>, <then> and <else> may be functions, too.
 110
 111
 112 ( in <base-int> <bit-int>... )
 113   This function returns <base-int>'s bits given in <bit-int>... (mask).
 114
 115
 116 ( not <int> )
 117 ( bitnot <int> )
 118   Returns logical/bitwise negation of argument.
 119
 120
 121 ( + <int>... )
 122   Returns the sum of all integers, 0 for no arguments.
 123
 124
 125 ( * <int>[...] )
 126   Returns the product of all integers. Needs at least one <int>
 127
 128
 129 ( procedure <name> [<arg>...] (...) )
 130   Procedures are defined during parsing. The name has to be a non-quoted
 131   string which must not begin with digits. Consider using a prefix like
 132   "P_" for your procedures to avoid a conflict with future extensions of
 133   Installer.
 134   <arg>... is an optional list of variables which will be set when calling
 135   the procedure. However, you can call the procedure with less than the
 136   specified arguments; in this case the unset variables retain their old
 137   values (example from original Installer docs):
 138   ( procedure P_ADDMUL arg1 arg2 arg3
 139       ( * ( + arg1 arg2 ) arg3 )
 140   )
 141   ( message ( P_ADDMUL 1 2 3 ) )        ; shows 9
 142   ( message ( P_ADDMUL 4 5 ) )          ; shows 27, arg3 stays the same
 143
 144   Note that there are no local variables, so that a call
 145   ( P_ADDMUL 1 2 3 )
 146   is the same as
 147   ( set arg1 1 arg2 2 arg3 3 )
 148   ( P_ADDMUL )
 149
 150   Though the ( procedure ... ) command is ignored at run-time it returns 0.
 151
 152
 153 ( select <int> [<any>...] )
 154   Returns the value of the <int>th <any>-item or 0 if <int> < 1 or
 155   <int> > number of <any>.
 156
 157
 158 ( strlen <string> )
 159   Returns the length of <string> or 0 if argument is an integer.
 160
 161
 162 ( until <int> (...) )
 163   Executes the block (post-checked) until <int> statement is TRUE.
 164   Returns the (last) value of the executed block.
 165
 166
 167 ( while <int> (...) )
 168   Executes the block (pre-checked) while <int> statement is TRUE.
 169   Returns the (last) value of the executed block or 0 if block has
 170   not been executed.
 171
 172
 173 ( set <var-name> <value> ... )
 174   Use (set ...) to set variables.
 175   Variable names have to be unquoted strings -- commands are not accepted
 176   Values can be anything.
 177   Consider using a prefix like '#' to avoid conflicts with future versions
 178   of Installer. The prefix '@' is reserved for internal variables. They
 179   can be set to other values, too.
 180
 181
 182 ( symbolset <var-name> <value> ... )
 183   With this functions you can use quoted strings as varnames (quotes will be
 184   stripped). This allows to have "dynamic" variables like ( "var%ld" n )
 185   Therefore commands as varnames will be executed.
 186   NOTE: sole integers as variables are not allowed, though ( "1" ) will
 187   work, but is not recommended to use.
 188
 189
 190 ( symbolval <var-name> )
 191   Use this functions to have access to "dynamic" variables set with
 192   ( symbolset ... )
 193   Same naming conventions as in symbolset apply here.
 194
 195
 196 ( askbool [( help <string>... )]
 197           [( prompt <string>... )]
 198           [( default <int> )]
 199           [( choices <yesstring> [<nostring>] )]
 200 )
 201   Asks the user to select yes or no unless user is NOVICE
 202   (ie. @user-level = 0 ). Returns 0 for "No" and 1 for "Yes".
 203   Defaults to 0 = "No".
 204
 205
 206 ( asknumber [( help <string>... )]
 207             [( prompt <string>... )]
 208             [( default <int> )]
 209             [( range <min-int> <maxint>] )]
 210 )
 211   Asks the user for a number unless user is NOVICE (ie. @user-level = 0 ).
 212   defaults to 0
 213   range defaults to non-negative numbers, unless default is negative which
 214   causes range to be extended to include the default number.
 215
 216
 217 ( askstring [( help <string>... )]
 218             [( prompt <string>... )]
 219             [( default <int> )]
 220 )
 221   Asks the user for a string unless user is NOVICE (ie. @user-level = 0 ).
 222   defaults to ""
 223
 224
 225 ( askchoice [( help <string>... )]
 226             [( prompt <string>... )]
 227             [( default <int> )]
 228             ( choices <string>... )
 229 )
 230   Asks the user to select one item out of N unless user is NOVICE
 231   (ie. @user-level = 0 ).
 232   defaults to 0
 233   choices is list of strings listed as items of the requester
 234   NULL strings will not be displayed.
 235   The Return value is the number of the selected item, starting with 0 as
 236   the first item.
 237
 238   NOTE: Original Installer docs read:
 239   >>  return value is a bitmask [...] maximum of 32 items.
 240   Tests showed that the number is passed - not a bitmask, but choices are
 241   nevertheless limited to 32!
 242
 243   >>  NOTE: "<ESC>[2p" sequence at beginning of one item leads to
 244   >>  proportional rendering (>V42)
 245   This is not implemented now!
 246
 247
 248 ( <format-string> <argument>... )
 249   This construct works like C printf() and returns the resulting string
 250   after substituting '%d' and '%s'. An 'sprintf(var,"format", args... )'
 251   can be achieved by '( set var ( "format" <args>... ) )'
 252   Installer uses RawDoFmt() and does not check correctness of arguments.
 253
 254
 255 ( substr <string> <start> [<count>] )
 256   Returns the substring of <string>, beginning with offset <start>
 257   (offset 0 is the first character) and including <count> characters.
 258   If <count> is omitted, then the rest of the string is returned.
 259
 260
 261 ( transcript [<string>...] )
 262   Concatenates all strings writes them to the logfile and appends a
 263   newline character.
 264   Returns the concatenated strings.
 265
 266
 267 ( user <int>|<"novice"|"average"|"expert"> )
 268   Changes the user level (@user-level) to the given value.
 269   Specify an integer 0 = novice 1 = average 2 = expert or the (quoted)
 270   strings "novice" "average" or "expert"
 271   Use this function only to debug your own scripts. In official releases
 272   this function shouldn't appear.
 273   Returns the new user-level.
 274
 275
 276 ( welcome <string>... )
 277   Displays the strings instead of
 278   "Welcome to <APPNAME> App installation utility."
 279   and asks for the user level.
 280   Without this function appearing in the script the user level is requested
 281   straight at the beginning.
 282
 283
 284 ( message <string>...
 285           [(help <string>... )]
 286           [(all)]
 287 )
 288   Displays the strings and offers "Proceed", "Abort" and "Help" buttons.
 289   The message is not displayed in NOVICE mode unless (all) is specified.
 290   Please, do not confuse the novice user.
 291
 292
 293 ( working <string>... )
 294   Displays the concatenated strings under a standard line reading
 295   "Working on Installation". This can be used to tell the user what's
 296   going on when doing long operations except copying which has its own
 297   status display.
 298
 299
 300 ( execute <file>
 301       [(safe)]
 302 )
 303 Execute an AmigaDOS script.
 304
 305
 306 ( run <string>...
 307       [(prompt <string>... )]
 308       [(help <string>... )]
 309       [(confirm)]
 310       [(safe)]
 311 )
 312   This function returns the primary result of the called program and
 313   the secondary is passed in '@ioerr'.
 314
 315
 316 ( textfile )
 317 # tests with original Installer showed:
 318 # ( append )s are collected
 319 # ( include )s are replaced, i.e. only the last ( include ) is taken
 320 # first (append)s are printed then last (include)
 321 ## Distinguish between overriding and appending parameters and introduce
 322 ## according functions to collect args. Or always append/collect as multiple
 323 ## strings and let function behave as desired.
 324
 325
 326 ( askdir )
 327  /* Ask user for a directory */
 328
 329
 330 ( askdisk )
 331  /* Ask user insert a disk */
 332
 333
 334 ( askfile )
 335  /* Ask user for a file */
 336
 337
 338 ( askoptions )
 339  /* Ask user to choose multiple items */
 340
 341
 342 ( database <feature> )
 343  /* Return information on the hardware Installer is running on */
 344  <feature> is one of:
 345  "vblank"
 346  "cpu"
 347    -> "68000" "68010" "68020" "68030" "68040" "68060"
 348       "80386" "80486"
 349       "Pentium" "PentiumPro" "Celeron" "PentiumII" "PentiumIII"
 350       "K6" "K6-II" "K6-III" "Athlon"
 351  "graphics-mem"
 352    -> Size of free CHIP RAM (via AvailMem(MEMF_CHIP))
 353  "total-mem"
 354    -> Total size of free RAM (via AvailMem(MEMF_TOTAL))
 355  "fpu"
 356    -> "68881" "68882" "FPU40" "80387" "80486" "NOFPU"
 357  "chiprev"
 358    -> "AA" "ECS" "AGNUS" "VGA"
 359  Return-type is always a string except for free RAM size.
 360
 361
 362 ( onerror (...) )
 363   Use this function to define code to be executed after an error occurred.
 364   This can be used to delete installed stuff if an error occurs or user
 365   aborted installation. This function is mutually exclusive with trap command.
 366
 367
 368 ( trap <trapflag> (...) )
 369   Use this function to set an error handling routine.
 370   When an error occurs and ( trap ... ) has been set before, the statements
 371   of the trap command are executed. Use this to clean up if an abnormal
 372   termination of the script occurs. If no trap is set for a specific errorcode
 373   the more general ( onerror ... ) statements are executed if declared before.
 374   Error codes:
 375     1 := User aborted
 376     2 := Ran out of memory
 377     3 := Error in script
 378     4 := DOS error (more infos in @ioerr , see below )
 379     5 := Bad parameter data
 380
 381
 382 ( startup <name-string>
 383       [(prompt <string>... )]
 384       [(help <string>... )]
 385       [(confirm)]
 386       (command <string>... )
 387 )
 388   Inserts a section
 389
 390 ;BEGIN <name-string>
 391 ...
 392 ;END <name-string>
 393
 394   into S:User-Startup. If a section with this name already exists the section
 395   will be replaced by this new one.
 396   The commands between the markers are given in (command ...).
 397   The user will only be prompted to confirm this action if in Expert mode.
 398
 399
 400 ( delete <filename>
 401       [(prompt <string>... )]
 402       [(help <string>... )]
 403       [(confirm)]
 404       [(optional <option>... )]
 405       [(delopts <option>... )]
 406       [(delopts)]
 407       [(safe)]
 408 )
 409   Delete a file. (only plain deletion is implemented by now!)
 410   options are:
 411     force   - unprotect file
 412     askuser - ask user if file should be unprotected,
 413               in novice the automatic answer is "no"
 414
 415
 416 ( exists <name>
 417       [(noreq)]
 418 )
 419   Checks if a <name> exists.
 420   Returns 0 if non-existent, 1 for a file or 2 for a directory.
 421   If (noreq) is specified, then no requester will pop up if
 422   <name> should be on a not-mounted volume.
 423
 424
 425 ( makedir <name>
 426       [(prompt <string>... )]
 427       [(help <string>... )]
 428       [(infos)]
 429       [(confirm)]
 430       [(safe)]
 431 )
 432   Create a directory.
 433   (infos) creates also an icon for the new directory (not yet implemented).
 434
 435
 436 ( rename <oldname> <newname>
 437       [(prompt <string>... )]
 438       [(help <string>... )]
 439       [(confirm)]
 440       [(disk)]
 441       [(safe)]
 442 )
 443   Renames the file "oldname" to "newname". If the parameter (disk) is
 444   passed, then this command relabels the disk "oldname" to "newname".
 445   When relabeling disks *only* include a colon ":" in the oldname.
 446   The function proceeds silently unless (confirm) is passed where the
 447   (prompt) is shown and (help) is available. If (safe) is passed then
 448   the renaming will be done even when in PRETEND mode.
 449   This function returns 1 on success and 0 on failure.
 450
 451
 452 ( fileonly <pathname> )
 453   Returns the file part of <pathname>.
 454   Example:
 455     (fileonly "A:BC/def/gh") -> "gh"
 456
 457
 458 ( pathonly <pathname> )
 459   Returns the path part of <pathname>.
 460   Example:
 461     (pathonly "A:BC/def/gh") -> "A:BC/def"
 462
 463
 464 ( earlier <file1> <file2> )
 465   Returns TRUE if file1 is older (earlier) than file2.
 466
 467
 468 ( getdiskspace <pathname> )
 469   Returns the number free bytes on the device.  If the pathname is bad or
 470   no info could not be obtained, -1 is returned.
 471
 472
 473 ( getenv <name> )
 474   Returns the value of an ENV: variable (through DOS/GetVar(name,...))
 475
 476
 477 ( getsize <name> )
 478   Returns the size of file <name> in bytes or 0 if file does not exist.
 479
 480
 481 ( makeassign <assign> [<path>]
 482       [(safe)]
 483 )
 484   Assigns assign to path. If path is not specified, the assign is removed.
 485   If (safe) is passed then the assign will be done even when in PRETEND mode.
 486   Returns 1 on success and 0 on failure.
 487
 488
 489 ( getassign <name> [<option>])
 490   Returns the path of <name>. The default is to return the logical assignments.
 491   <Option> can be one of:
 492         'a': match logical assignments only (default)
 493         'v': match volumes only
 494         'd': match devices only
 495
 496   If <name> does not exist as the specified type, an empty string is returned.
 497
 498   Note that you must specify the device/volume/assign without the trailing
 499   colon. The return value will be a true path, ie. with the colon.
 500   If <option> is device and <name> is a device, its volume name is reported,
 501   unless it doesn't exist in which case the device name is returned.
 502
 503
 504 ( getdevice <path> )
 505   Returns the volume name on which <path> exists or an empty string if
 506   <path> does not exist.
 507
 508
 509 ( tackon <path> <file> )
 510   Returns the combined pathname of <path>+<file>.
 511
 512   NOTE: Currently DOS.library/AddPart() cannot cope with a leading '/' in the
 513   <file> parameter.
 514
 515
 516 ( expandpath <path> )
 517   Expands the <path>. For example "C:Mount" will become "System:C/Mount"
 518
 519
 520 /* Unimplemented commands */
 521 ( copyfiles )
 522 ( copylib )
 523 ( foreach )
 524 ( getsum )
 525 ( getversion )
 526 ( patmatch )
 527 ( protect )
 528 ( rexx )
 529 ( tooltype )
 530
 531 /* Here are all tags, first the ones which have to be executed */
 532
 533 ( delopts )
 534  /* unset copying/deleting options if we are called global */
 535  /* as parameter to a function we have got an ignore=1 before */
 536  "fail"
 537  "nofail"
 538  "oknodelete"
 539  /* These may be combined in any way */
 540  "force"
 541  "askuser"
 542
 543 ( optional )
 544  /* set copying/deleting options if we are called global */
 545  /* as parameter to a function we have got an ignore=1 before */
 546  "fail"
 547  "nofail"
 548  "oknodelete"
 549  /* These may be combined in any way */
 550  "force"
 551  "askuser"
 552
 553
 554 ( all )
 555 ( append )
 556 ( assigns )
 557 ( choices )
 558 ( command )
 559 ( confirm )
 560 ( default )
 561 ( dest )
 562 ( disk )
 563 ( files )
 564 ( fonts )
 565 ( help )
 566 ( include )
 567 ( infos )
 568 ( newname )
 569 ( newpath )
 570 ( nogauge )
 571 ( noposition )
 572 ( pattern )
 573 ( prompt )
 574 ( range )
 575 ( safe )
 576 ( setdefaulttool )
 577 ( setstack )
 578 ( settooltype )
 579 ( source )
 580 ( swapcolors )
 581 ( quiet )
 582