All STAF services provide a HELP command that lists basic service syntax
information and we recommend that external service writers also provide a
HELP command. However, STAF doesn't provide an API that generates this
help text from a STAF Command Parser that you created. If you look at the
source code for any STAF service, you'll see that there is a handleHelp()
method that is implemented that documents the service syntax, but it
doesn't use STAFCommandParser methods to construct the help text.
Adding a way to automatically generate the help syntax for a STAF service
based on the STAF Command Parser is a good idea, especially for services
whose syntax is changed often (but we haven't done it yet). It would be
great if you wanted to implement this and contribute it back to the STAF
project following the process documented at
http://staf.sourceforge.net/contributions.php.
Section "7.1 General ServiceSyntax" in the STAF User's Guide at
http://staf.sourceforge.net/current/STAFUG.htm#HDRSYNTAXSRV provides some
documentation on the standard syntax STAF uses to document service
requests. Also, note that STAF services use ... to indicate that an
option can occur multiple times.
"Appendix B. Service Command Reference" in the STAF User's Guide at
http://staf.sourceforge.net/current/STAFUG.htm#HDRCMDREF may be helpful in
seeing how we document the syntax for all the STAF C++ services.
For example, the following RESPOOL service's ADD request syntax is as
follows where it requires that you specify 1 or more ENTRY options:
ADD POOL <PoolName> ENTRY <Value> [ENTRY <Value>]...
And the following ZIP services's UNZIP request syntax is as follows where
it allows you to optionally specify 0 or more FILE and/or DIRECTORY
options:
UNZIP ZIPFILE <Name> TODIRECTORY <Name>
[FILE <Name>]... [DIRECTORY <Name>]...
[RESTOREPERMISSION] [REPLACE]
--------------------------------------------------------------
Sharon Lucas
IBM Austin, luc...@us.ibm.com
(512) 286-7313 or Tieline 363-7313
"jander...@talentex.co.uk" <jander...@talentex.co.uk>
10/19/2009 11:21 AM
To
staf <staf-users@lists.sourceforge.net>
cc
Subject
[staf-users] Documenting a parser?
Is there a standard way of documenting a STAF parser? I can see that I
can extract the information easily enough, but before I do it my own
way, I just though I should check, so I don't reinvent the wheel. What I
want to make is something that can dump out a help text like, eg:
INFARES
REQUEST
RESTYPE <restype string>
[RESCLASS <RDBMS | FILE | ...>]
[RESNAME <name string>]
[RESVERSION <version string>]
[TIMEOUT <Number>[s|m|h|d|w]]
[LOC <location>]
[OS <osname>]
[OSVERSION <version string>]
[OSBITS <31|32|64>]
[DISK <diskspec>]
[ROLE <res.role>]
[ACCESS <access role>]
[SCHEMA <schema>]
[INSTANCE <instance name>]
[DURATION <time string> | PERSISTENT]
[LOCKNAME <string>]
LIST
RESTYPE <restype string>
[RESCLASS <RDBMS | FILE | ...>]
[RESNAME <name string>]
[RESVERSION <version string>]
[LOC <location>]
[OS <osname>]
[OSVERSION <version string>]
[OSBITS <31|32|64>]
[DISK <diskspec>]
etc
It shouldn't be too hard to make, although I am not quite sure how to
indicate things like how many times an option can occur in this notation
and how they are grouped.
/jan
------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
staf-users mailing list
staf-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/staf-users
------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
staf-users mailing list
staf-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/staf-users
