Changes between Initial Version and Version 1 of Documentation/ARexxAPI


Ignore:
Timestamp:
Sep 22, 2013, 8:15:24 PM (15 months ago)
Author:
AmigaPhil
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Documentation/ARexxAPI

    v1 v1  
     1== Reference - ARexx interface
     2
     3
     4With the help of ARexx scripts, you can add new functions to YAM or
     5let it do things automatically.  YAM offers a set of commands (listed
     6in this documentation both [[rexx| by name ]] and [[rexl| by function ]]) which can be called
     7through the '''YAM''' ARexx port.  They are explained along the following
     8subchapters using the following format:
     9
     10
     11'''NAME'''
     12     The name of the command, a short description of what it does and
     13     the YAM version where the command was implemented.
     14
     15'''TEMPLATE'''
     16     Arguments and options accepted by the command.  The template uses
     17     special characters that indicate the particular type of argument
     18     expected, following the AmigaDOS template style:
     19
     20          /A   The parameter is compulsory\\
     21          /K   The parameter must be preceeded by the keyword\\
     22          /N   Numerical argument or result\\
     23          /M   Argument or result is a list of zero or more elements\\
     24          /S   The parameter works as a switch; the switch is in use when the parameter is given\\
     25
     26'''FUNCTION'''
     27     Describes what the command will do.
     28
     29'''INPUTS'''
     30     Describes in detail the parameters accepted by the command.
     31     Be careful when passing arguments containing spaces; for instance,
     32
     33          sub = 'Hello World'\\
     34          'WRITESUBJECT' sub
     35
     36     won't work!  It must be written as
     37
     38          'WRITESUBJECT "'sub'"'
     39
     40     or
     41
     42          'WRITESUBJECT "Hello World"'
     43
     44
     45     Please note that because of the internal use of the ReadArgs() function,
     46     the ARexx Host requires to escape certain special characters like a newline
     47     (0x0a) or escape character (0x1b) if you want to have it included in your
     48     final string or otherwise it is stripped by the ReadArgs() function.
     49
     50     This means that you have to use the following escape sequences in your
     51     provided strings:
     52
     53      *N substitutes to 0x0a\\
     54      *E substitutes to 0x1b\\
     55      !** substitutes to *\\
     56      *" substitutes to "\\
     57
     58     For example the following command would write a string to a texteditor
     59     containing a newline:
     60
     61     'WRITEEDITOR "TEXT Hello Joe,*N I would like to meet you."'
     62
     63'''RETURNS'''
     64     Returned info to be expected from the command.  Commands may return
     65     results in three different kinds; let's look at these examples which
     66     use the FOLDERINFO command:
     67
     68
     69          FOLDERINFO
     70            -> RESULT = "0 Incoming incoming 10 2 4 23030 1"
     71
     72          FOLDERINFO VAR fi
     73            -> fi = "0 Incoming incoming 10 2 4 23030 1"
     74
     75          FOLDERINFO STEM fi.
     76            -> fi.number = 0\\
     77                fi.name = "Incoming"\\
     78                fi.path = "incoming"\\
     79                fi.total = 10\\
     80                fi.new = 2\\
     81                fi.unread = 4\\
     82                fi.size = 23030\\
     83                fi.type = 1\\
     84
     85     Another example which returns a result of type /M:
     86
     87          ADDRFIND STEM found. "Marcel Beck" NAMEONLY
     88            -> found.alias.count = 2\\
     89                found.alias.0 = "Mars"\\
     90                found.alias.1 = "mbe"\\
     91
     92'''WARNING'''
     93     Any sort of vital information you should be aware of when using
     94     this command.
     95
     96'''NOTES'''
     97     Various notes about the command.
     98
     99'''EXAMPLE'''
     100     A fragment of ARexx code to illustrate the usage of the command.
     101
     102'''BUGS'''
     103     Problems that are known or have already been fixed with this command.
     104
     105'''SEE ALSO'''
     106     Links to other related commands.