Changes between Version 10 and Version 11 of Documentation/ARexxAPI


Ignore:
Timestamp:
Feb 4, 2014 11:39:54 AM (7 months ago)
Author:
damato
Comment:

beautified page

Legend:

Unmodified
Added
Removed
Modified
  • Documentation/ARexxAPI

    v10 v11  
    44== Reference - ARexx interface 
    55 
    6  
    76With the help of ARexx scripts, you can add new functions to YAM or let it do things automatically.\\ 
    87YAM 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 
    98subchapters using the following format: 
    109 
     10 NAME:: 
     11   The name of the command, a short description of what it does and the YAM version where the command was implemented. 
    1112 
    12 '''NAME''' 
    13      The name of the command, a short description of what it does and the YAM version where the command was implemented. 
     13 TEMPLATE:: 
     14   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: 
    1415 
    15 '''TEMPLATE''' 
    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: 
     16   `/A` The parameter is compulsory\\ 
     17   `/K` The parameter must be preceeded by the keyword\\ 
     18   `/N` Numerical argument or result\\ 
     19   `/M` Argument or result is a list of zero or more elements\\ 
     20   `/S`  The parameter works as a switch; the switch is in use when the parameter is given\\ 
    1721 
    18           /A   The parameter is compulsory\\ 
    19           /K   The parameter must be preceeded by the keyword\\ 
    20           /N   Numerical argument or result\\ 
    21           /M   Argument or result is a list of zero or more elements\\ 
    22           /S   The parameter works as a switch; the switch is in use when the parameter is given\\ 
     22 FUNCTION:: 
     23   Describes what the command will do. 
    2324 
    24 '''FUNCTION''' 
    25      Describes what the command will do. 
     25 INPUTS:: 
     26   Describes in detail the parameters accepted by the command. 
     27   Be careful when passing arguments containing spaces; for instance, 
    2628 
    27 '''INPUTS''' 
    28      Describes in detail the parameters accepted by the command. 
    29      Be careful when passing arguments containing spaces; for instance, 
     29   {{{#!urbiscript 
     30   sub = 'Hello World' 
     31   'WRITESUBJECT' sub 
     32   }}} 
     33           
     34   won't work. It must be written as 
    3035 
    31           sub = 'Hello World'\\ 
    32           'WRITESUBJECT' sub 
     36   {{{#!urbiscript 
     37   'WRITESUBJECT "'sub'"' 
     38   }}} 
    3339 
    34      won't work. It must be written as 
     40   or 
    3541 
    36           'WRITESUBJECT "'sub'"' 
     42   {{{#!urbiscript 
     43   'WRITESUBJECT "Hello World"' 
     44   }}} 
    3745 
    38      or 
     46   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. 
    3947 
    40           'WRITESUBJECT "Hello World"' 
     48   This means that you have to use the following escape sequences in your provided strings: 
    4149 
     50   `*N` substitutes to 0x0a (newline \n) \\ 
     51   `*E` substitutes to 0x1b (escape)\\ 
     52   `!**` substitutes to *\\ 
     53   `*` substitutes to "\\ 
    4254 
    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. 
     55   For example the following command would write a string to a texteditor containing a newline: 
    4456 
    45      This means that you have to use the following escape sequences in your provided strings: 
     57   {{{#!urbiscript 
     58    'WRITEEDITOR "TEXT Hello Joe,*N I would like to meet you."' 
     59   }}} 
    4660 
    47       *N substitutes to 0x0a\\ 
    48       *E substitutes to 0x1b\\ 
    49       !** substitutes to *\\ 
    50       *" substitutes to "\\ 
     61   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". 
    5162 
    52      For example the following command would write a string to a texteditor containing a newline: 
     63 RETURNS:: 
     64   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: 
    5365 
    54      'WRITEEDITOR "TEXT Hello Joe,*N I would like to meet you."' 
     66   {{{#!urbiscript 
     67   FOLDERINFO 
     68   -> RESULT = "0 Incoming incoming 10 2 4 23030 1" 
     69   }}} 
    5570 
    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". 
     71   {{{#!urbiscript 
     72   FOLDERINFO VAR fi 
     73   -> fi = "0 Incoming incoming 10 2 4 23030 1" 
     74   }}} 
    5775 
    58 '''RETURNS''' 
    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: 
     76   {{{#!urbiscript 
     77   FOLDERINFO STEM fi. 
     78   -> fi.number = 0 
     79        fi.name = "Incoming" 
     80        fi.path = "incoming" 
     81        fi.total = 10 
     82        fi.new = 2 
     83        fi.unread = 4 
     84        fi.size = 23030 
     85        fi.type = 1 
     86   }}} 
    6087 
     88   Another example which returns a result of type `/M`: 
    6189 
    62           FOLDERINFO 
    63             -> RESULT = "0 Incoming incoming 10 2 4 23030 1" 
     90   {{{#!urbiscript 
     91   ADDRFIND STEM found. "Marcel Beck" NAMEONLY 
     92    -> found.alias.count = 2 
     93         found.alias.0 = "Mars" 
     94         found.alias.1 = "mbe" 
     95    }}} 
    6496 
    65           FOLDERINFO VAR fi 
    66             -> fi = "0 Incoming incoming 10 2 4 23030 1" 
    67  
    68           FOLDERINFO STEM fi. 
    69             -> fi.number = 0\\ 
    70                 fi.name = "Incoming"\\ 
    71                 fi.path = "incoming"\\ 
    72                 fi.total = 10\\ 
    73                 fi.new = 2\\ 
    74                 fi.unread = 4\\ 
    75                 fi.size = 23030\\ 
    76                 fi.type = 1\\ 
    77  
    78      Another example which returns a result of type /M: 
    79  
    80           ADDRFIND STEM found. "Marcel Beck" NAMEONLY 
    81             -> found.alias.count = 2\\ 
    82                 found.alias.0 = "Mars"\\ 
    83                 found.alias.1 = "mbe"\\ 
    84  
    85 '''WARNING''' 
     97 WARNING:: 
    8698     Any sort of vital information you should be aware of when using this command. 
    8799 
    88 '''NOTES''' 
     100 NOTES:: 
    89101     Various notes about the command. 
    90102 
    91 '''EXAMPLE''' 
     103 EXAMPLE:: 
    92104     A fragment of ARexx code to illustrate the usage of the command. 
    93105 
    94 '''BUGS''' 
     106 BUGS:: 
    95107     Problems that are known or have already been fixed with this command. 
    96108 
    97 '''SEE ALSO''' 
     109 SEE ALSO:: 
    98110     Links to other related commands. 
    99111