Changes between Version 10 and Version 11 of Documentation/ARexxAPI


Ignore:
Timestamp:
Feb 4, 2014, 11:39:54 AM (11 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