Changes between Version 9 and Version 10 of Documentation/ARexxAPI


Ignore:
Timestamp:
Nov 27, 2013 9:03:59 AM (12 months ago)
Author:
tboeckel
Comment:

Added a section about correct handling of file names containing spaces. This closes #20.

Legend:

Unmodified
Added
Removed
Modified
  • Documentation/ARexxAPI

    v9 v10  
    55 
    66 
    7 With the help of ARexx scripts, you can add new functions to YAM or 
    8 let it do things automatically.\\ 
    9 YAM offers a set of commands (listed 
    10 in this documentation both [[ARexx API/List by Name| by name ]] and [[ARexx API/List by Function| by function ]]) which can be called 
    11 through the '''YAM''' ARexx port.  They are explained along the following 
     7With the help of ARexx scripts, you can add new functions to YAM or let it do things automatically.\\ 
     8YAM offers a set of commands (listed in this documentation both [[ARexx API/List by Name| by name ]] and [[ARexx API/List by Function| by function ]]) which can be called through the '''YAM''' ARexx port.  They are explained along the following 
    129subchapters using the following format: 
    1310 
    1411 
    1512'''NAME''' 
    16      The name of the command, a short description of what it does and 
    17      the YAM version where the command was implemented. 
     13     The name of the command, a short description of what it does and the YAM version where the command was implemented. 
    1814 
    1915'''TEMPLATE''' 
    20      Arguments and options accepted by the command.  The template uses 
    21      special characters that indicate the particular type of argument 
    22      expected, following the AmigaDOS template style: 
     16     Arguments and options accepted by the command. The template uses special characters that indicate the particular type of argument expected, following the AmigaDOS template style: 
    2317 
    2418          /A   The parameter is compulsory\\ 
     
    3832          'WRITESUBJECT' sub 
    3933 
    40      won't work! It must be written as 
     34     won't work. It must be written as 
    4135 
    4236          'WRITESUBJECT "'sub'"' 
     
    4741 
    4842 
    49      Please note that because of the internal use of the ReadArgs() function, 
    50      the ARexx Host requires to escape certain special characters like a newline 
    51      (0x0a) or escape character (0x1b) if you want to have it included in your 
    52      final string or otherwise it is stripped by the ReadArgs() function. 
     43     Please note that because of the internal use of the ReadArgs() function, the ARexx Host requires to escape certain special characters like a newline (0x0a) or escape character (0x1b) if you want to have it included in your final string or otherwise it is stripped by the ReadArgs() function. 
    5344 
    54      This means that you have to use the following escape sequences in your 
    55      provided strings: 
     45     This means that you have to use the following escape sequences in your provided strings: 
    5646 
    5747      *N substitutes to 0x0a\\ 
     
    6050      *" substitutes to "\\ 
    6151 
    62      For example the following command would write a string to a texteditor 
    63      containing a newline: 
     52     For example the following command would write a string to a texteditor containing a newline: 
    6453 
    6554     'WRITEEDITOR "TEXT Hello Joe,*N I would like to meet you."' 
    6655 
     56     If a parameter represents a file name you should keep in mind that file names on AmigaOS might contain spaces or other special characters which will cause ARexx to treat the name as multiple words instead of a single word. Hence a file name should '''always''' be surrounded by quotes, no matter if it contains spaces or not. Scripts can very easily be tested for this case by letting them handle a file in the Amiga RAM disk, i.e. "RAM Disk:/foo/bar". 
     57 
    6758'''RETURNS''' 
    68      Returned info to be expected from the command.  Commands may return 
    69      results in three different kinds; let's look at these examples which 
    70      use the FOLDERINFO command: 
     59     Returned info to be expected from the command.  Commands may return results in three different kinds; let's look at these examples which use the FOLDERINFO command: 
    7160 
    7261 
     
    9584 
    9685'''WARNING''' 
    97      Any sort of vital information you should be aware of when using 
    98      this command. 
     86     Any sort of vital information you should be aware of when using this command. 
    9987 
    10088'''NOTES'''