SideDiff & 17/01/21 ROM

you need key$ = “,quit/K/S,”

Thanks. That works. However after looking at the documentation, I can’t see WHY it works. What I am sure of is that this is unlike parsers I’ve used before. With those you are asking “is this key present, anywhere, and if so, what’s its value?”. This one seems to need “is parameter N present with this key?”

I did discover the zero-terminated bit. The good thing is that this strips the quotes from the file if they were present, so the return value will not change with the new ROM code.

is parameter N present with this key?

Not quite sure I follow you on that.

OS_ReadArgs will scan the string looking for the parameters as specified in R0 but will put them into the buffer in the positions according to the keyword definition in R0.
So, these command lines are all equivalent as far as OS_ReadArgs is concerned:
BASIC -quit ABC
-quit BASIC ABC

and if you use “,quit/K/S,” then “BASIC” will be at location +0, the quit flag at +4, and “ABC” at +8, as “BASIC” is the first unnamed parameter and “ABC” is the second.

Doing: “ABC BASIC -quit”, however, will put “BASIC” at +8 and “ABC” at +0 because “ABC” is now the first unnamed parameter and “BASIC” the second but the quit flag will still be at +4.

Hopefully that makes sense.

And it’s best to use XOS_ReadArgs and to check the V flag and then report a syntax error if you get V is set.

Also having a switch that starts with “q” such as “-quiet” can cause some head scratching if you shorten it to “-q” because that will give you an Argument repeated error, until you realise that it’s matching “-q” with “-quit”. The way round it is to specify an alias: “quiet=q/S” rather than just “quiet/S”.

And if you want to get a filename passed as a parameter to your program, eg “Launcher MyFile” then I suggest using: “,quit/K/S,,/G” as the “/G” will cause variables and pathnames to get expanded so you can handle: “Launcher APath:MyFile”. But then you can’t read the filename using OS_GenerateError as the GSTransed string isn’t zero terminated but has 2 bytes giving the length of the string followed by the actual string.

Thanks for all that. I followed most of it. The bit that confuses me is the commas in the key definition. I can’t see why the leading one is necessary, and had assumed it meant “look for quit as the second part of the input”.

“,quit/K/S,,/G”

Again confusing. the /K/S obviously apply to quit, but why 2 commas before /G? I’m assuming the /G on its own means it applies to (the first? all?) unnamed parameters. The documentation describes the key definition as a sequence of keywords. There’s no explanation of why some of them need to be null.

Digging further. The RiscOS 3 PRM volume 1 doesn’t mention null values in the keyword definition. The online documentation does, but is so terse as to make your eyes water in other respects. Between them I’m getting the impression that the rule may be: The keyword definition needs to have the same number of values as the input string. (If so, what happens if you are testing whether a value is present? Is it rather “at least as many values”?)

The PRM documentation seems to be clear that the fields in the input don’t have to be in the same order as in the definition. In that case, does anything restrict the order in the definition?
For example “,quit/K/S,,/G” could also be “quit/K/S,,,/G” ?

I feel a dedicated test programme coming on.

Keywords don’t need to be null, it’s just that they can be null.
Page 1-466 in the PRM talks about it, though it doesn’t talk about null keywords, but nameless keywords.

A worked example might help.

So let’s pretend you’ve written your program “Launcher” in C, and it takes 2 parameters: an input filename and an output filename.

For OS_ReadArgs to process the command line you can set the keyword definition to just: “,,” which says to OS_ReadArgs expect to process 3 parameters.

Thus the command line: “Launcher FileIn FileOut”
will be in the output buffer as:
+0 → “Launcher”
+4 → “FileIn”
+8 → “FileOut”

So what OS_ReadArgs is doing is reading the first part of the command line (ie program name “Launcher”) and seeing if it has a match in the keyword definition. It doesn’t so it puts it in the first unused location in the output buffer ( +0).
It reads the next part (“FileIn”), no match and so puts it in the next unused location ( +4).
And then the final part (“FileOut”), again no match and so into the next unused location ( +8).

Which is why the command line: “Launcher FileOut FileIn”
will be in the output buffer as:
+0 → “Launcher”
+4 → “FileOut”
+8 → “FileIn”

And if your program assumes that the input filename will always be at +4 and the output filename will always be at +8 in the output buffer then you could be in trouble!

And so what keywords enable you to do is to make sure that the output buffer has the parameters in the positions you want them in.
So if we want the input filename to always be at +4 and the output filename to always be at +8 then we set the keyword definition to be: “,input,output”.

That way the user can then specify “Launcher -input FileIn -output FileOut” or “Launcher -output FileOut -input FileIn”, it matters not because OS_ReadArgs will put the input filename FileIn at +4 and the output at +8 because that’s what the keyword definition says.
And it puts the program name at +0 because that just happens to be the first unused location.

Think of the keyword definition as saying to OS_ReadArgs I want this parameter to be at this location in the output buffer.

So if you want the output filename to always be at +0, the input filename to always be at +4 and the program name to always be at +8 then you would set the keyword definition to “output,input,”.

And so as ReadArgs processes the command line, it will read the program name, it has no match in the keyword definition and so it would go in the first unused location which in this case is +8 in the output buffer.
It will then read the -output which matches a keyword and put the next parameter “FileOut” to its location at +0.
It will then read the -input which again matches a keyword and puts the next parameter “FileIn” to its location at +4.
And the output buffer will be:
+0 → “FileOut”
+4 → “FileIn”
+8 → “Launcher”

The problem will come if you use that keyword definition and the user types on the command line: “Launcher FileIn FileOut” because it wont fill in the output buffer as above (the keywords -input and -output are currently optional), which is where the keyword qualifiers come in.

To force the user to specify the -input and -output on the command line you would use /K against the relevant keyword, in this case: “output/K,input/K,”.
Now if the user types: “Launcher FileIn FileOut” it will cause an error because they must specify -input and -output.

But they could still type: “Launcher -input FileIn” without specifying an output file. So let’s say you can take input from the keyboard but the output must be to a file, so to make input optional on the command line but output mandatory you would set the keyword definition to be: “output/A/K,input/K,”
That way if they type: “Launcher -input FileIn” they will get an error, but if they type: “Launcher -output FileOut” it will work just fine with the output buffer being:
+0 → “FileOut”
+4 → ""
+8 → “Launcher”

As will “Launcher -input FileIn -output FileOut”, and the output buffer will be as you expect:
+0 → “FileOut”
+4 → “FileIn”
+8 → “Launcher”

The qualifiers /E, /G and /S can also be specified if you want against a particular keyword, so if you wanted the output to be GSTransed but not the input, then use: “output/A/K/G,input/K,”
if just the input then use: “output/A/K,input/K/G,”
If both, then: “output/A/K/G,input/K/G,”

But with BASIC programs we get “BASIC -quit” added to the start of the command line, and so the “,quit/K/S” at the start of the keyword ensures that “BASIC -quit” gets handled without causing an error, which it would do if you were to use “output/A/K,input/K,” as we have been using here.

And so to keep FileOut and FileIn at +0 and +4 in the output buffer, the keyword definition needs to be amended to be: “output/A/K,input/K,,,quit/K/S”
The output buffer will then be:
+0 → “FileOut”
+4 → “FileIn”
+8 → “BASIC”
+12 → “Launcher”
+16 → A non-zero value

You’ll notice that the name of our program “Launcher” has moved to +12 and that “BASIC” is now at +8, and the -quit switch is at +16.

But yes, knocking up a quick test program will help you understand what’s happening.

“quit/K/S,,,/G”

In summation then – it’s very powerful but it’s a bit of a mindscrew, so there’s probably a reason why people look for a quote character in BASIC programs and parse the rest themselves (with varying degrees of success ;) ).

Thanks Richard. So the most important part that the PRM doesn’t explain is that the order of fields in the definition controls the mapping to the output buffer, not the more obvious mapping to the input fields, and that the number of definition fields must be at least as many as the input fields.

It also means that my initial thought of wrapping it in a generalised function is not going to work (at least not easily) because, for one thing, trying to read the string value from the buffer when the parameter is a switch is going to give an error.

Using the DCL parser on VMS was a lot easier, or at least more clearly documented.

there’s probably a reason why people look for a quote character in BASIC programs and parse the rest themselves (with varying degrees of success ;) ).

Yes, as Richard said of the documentation.

A worked example might help

An observation of the situation:
The documentation (PRM’s) was written by deeply techie characters in Acorn and (partially) translated to human to be published as the PRM’s.
Much (most?) software was written by people that never saw a copy of the PRM and even if they did see a copy then finding worked examples was as likely as finding a QAnon adherent with a brain cell.

The one advantage of the current situation is that the wiki pages are open to be edited, so they could have worked examples added (or pages of worked examples could be linked in)

Alan, this is taken from my CLOC program, you should be able to adapt to your needs.
I did do some work on a general purpose function, I’ll see what state it’s in, and I’ll try and take a look at the wiki as well.

buf_size% 1024 : DIM buffer% buf_size%
PROCreadArgs
IF argc% = 0 THEN
  PRINT "Syntax: cloc [-nowarn] [-nolist] [-noignore] [-quiet] [-stats] <file spec>"
  PRINT "  -nowarn      Suppress warnings"
  PRINT "  -nolist      Don't list individual files"
  PRINT "  -noignore    Don't list files that are ignored"
  PRINT "  -quiet       No output whilst processing files"
  PRINT "  -stats       Display extra stats: Max and average line lengths, and timings"
  PRINT "  <file spec>  File or Directory to process. Wildcards may be used"
  END
ENDIF


DEF PROCreadArgs
  REM Read and process command line arguments
  LOCAL i%, addr%, syntax$, flags%

  argc% = 0
  REM Syntax: cloc [-nowarn] [-nolist] [-noignore] [-quiet] [-stats] <file spec>
  syntax$ = "basic,quit/K/S,progname,/G,help/S,nowarn=nw/S,nolist=nl/S,noignore=ni/S,quiet=q/S,stats/S"
  SYS "OS_GetEnv" TO i%
  SYS "XOS_ReadArgs",syntax$,i%,buffer%,buf_size% TO ;flags%
  IF ((flags% AND 1) = 1) THEN ENDPROC
  IF buffer%!12 <> 0 THEN argc% = 1 : REM File spec
  IF buffer%!16 <> 0 THEN argc% = 0 : REM -help
  DIM arg$(argc%)
  SYS "XOS_GenerateError",buffer%!8 TO arg$(0) : REM Program name
  IF argc% THEN
    addr% = buffer%!12 : REM GSTransed file spec stored as 2 byte length followed by non-terminated string
    FOR i% = 2 TO (?addr% + ((addr%?1)*256) + 1) : arg$(1) += CHR$(addr%?i%) : NEXT
    warn%         = (buffer%!20 = 0)  : REM -nowarn
    list_files%   = (buffer%!24 = 0)  : REM -nolist
    show_ignored% = (buffer%!28 = 0)  : REM -noignore
    quiet%        = (buffer%!32 <> 0) : REM -quiet
    stats%        = (buffer%!36 <> 0) : REM -stats
    IF quiet% THEN warn% = FALSE : list_files% = FALSE : show_ignored% = FALSE : REM Don't display anything
  ENDIF
ENDPROC

Edit: Just noticed I’ve got “basic” and “progname” in the syntax string, obviously left over from some early testing – they can be safely removed but make sure you keep the commas.

Thanks for the help. That wiki does need some work.

When working on VMS there were two sorts of manuals – the technical manual and the user guide, best used together. This piece of current documentation is an extreme example of the technical manual. Generally it says what things do, but not why.

If you look at the OS_ReadArgs Input String page, it lists examples of things that match and things that don’t. The obvious omission is an explanation of why the latter don’t match. I think the first is because file is missing, and the second because number is defined twice, but it would be nice to have that confirmed.

While I don’t need to take it any further than I currently have – I’ve got the path to the program which is the only bit my current software needs – my curiosity (and the prospect of at least another month of totally spare time) make me want to explore this further. With luck I should be able to produce something like the user manual part.

So watch this space maybe.

 syntax$ = "basic,quit/K/S,progname,/G,help/S,nowarn=nw/S,nolist=nl/S,noignore=ni/S,quiet=q/S,stats/S"

I’m still curious here why the /G is between commas, not appended to filename.

Edit after further study: It seems to me that buffer!0 contains “basic”, Buffer!4 contains “quit”, buffer!8 contains the filename since it is the first unmatched keyword, buffer!12 contains the filename GStransed. Does it really process filename twice?

This is theoretical, i.e. I haven’t done any experiments…

OS_ReadArgs doesn’t consume or destroy the input string, so the string can be parsed any number of times. It seems to me, therefore, that, if you don’t know which switches are going to be provided by the user, it’s possible to use OS_ReadArgs to test for the existence of the switches, one at a time, using a different keyword definition each time. Finally, parse for real, having constructed a keyword definition from the earlier tests.

if you don’t know which switches are going to be provided by the user, it’s possible to use OS_ReadArgs to test for the existence of the switches, one at a time,

I can’t see why you could not test for presence of all switches in one go. Each one would get a zero/non-zero value in the appropriate buffer location.

Actually I’m not sure you need to do that either – this is a case where the switches are optional, so adding /A to them will result in a null string if they are absent, and a value if one is defined. However if the input string contained “-input” rather than “-input fred.txt” it would produce the same as -input not being present. There might be another switch letter to make that case into an error.

Some reverse-engineering seems to be in order.

I think the first is because file is missing, and the second because number is defined twice

Yes “thingy” doesn’t match because there are no empty keywords in the definition – it needs to have “-file” in front of it.
And yes with “number” as it is specified as “-number 20” and again with “-times 4”, because “times” is an alias for “number”.

I’m still curious here why the /G is between commas, not appended to filename.

“progname” will match the program name, in this case “CLOC” (which is automatically GSTransed for you, so no need to specify /G), and yes it gets put into buffer%!8, whilst the “/G” between commas will match “file spec” which is the GSTransed file/directory that the program is going to process and which goes into buffer%!12, but no it doesn’t process it twice.

However if the input string contained “-input” rather than “-input fred.txt” it would produce the same as -input not being present.

If you have “input/A” as your keyword and you specify “-input” on the command line rather than “-input fred.txt” then you’ll get the error “Parameters not recognised” because you’ve stated that this keyword must always have a value, therefore not to supply a value on the command line is an error. The keyword itself (-input) does not need to be on the command line but there must be something there, so just specifying “fred.txt” and not preceding it with “-input” on the command line would work. To get an empty string replace “fred.txt” with quotes ("").

OS_ReadArgs doesn’t consume or destroy the input string, so the string can be parsed any number of times

Correct, the input string is left untouched, so you could parse it any number of times though I can’t think why you’d want to as all the information is there on the first pass in the output buffer.
The keywords tell OS_ReadArgs which switches your program will accept and OS_ReadArgs then sees if any of them are on the command line, and if they are then it sets the appropriate entry in the output buffer, so you only need to call OS_ReadArgs once and then process the output buffer, setting your variables as appropriate, which is what is happening in PROCreadArgs – arg$(0) contains the program name, and arg$(1) contains the “file spec” (which has been GSTRansed) and then the switches just set a bunch of booleans.

it’s very powerful but it’s a bit of a mindscrew,

;-)

It took me a bit of effort to comprehend, but I think all that is needed is in the PRM. There is a page in my Basalt StrongHelp manual under the keyword ARGS that is intended to ‘simplify’ things. ;-)

One recommendation is that keywords in the syntax$ are the same as the variable names used to hold the data. That implies that you do not use empty fields between commas, which can be confusing. The “basic” and “progname” above follow that premiss.

I have a BASIC routine that only requires the syntax$ as a parameter and creates the necessary variables. ;-)

An observation: there is no point in the /K in quit/K/S because all switches are necessarily keywords.

Crunchie handles a very large number of parameters and the syntax is actually too long for a BASIC variable. It is quite open if you want to look and see how that is done.

There is a page in my Basalt StrongHelp manual under the keyword ARGS that is intended to ‘simplify’ things.

Here is that page translated to HTML by my own program from long ago. ;-)

Edit:

The line about OS_EvaluateExpression and only numeric is a limitation imposed by Basalt.

string$=RETURN$(pointer%) is the Basalt equivalent of using XOS_GenerateError.

Perhaps these lines, adapted from the manual, might be useful, too.

Edit:

This could have something about “Argument repeated” error added.

The fields are filled from items in the command line that are separated by spaces; a string in quotes is one item.

might be worth adding (if I have this correct) “and the quotes are removed.”

If /E is used, you can also get errors from OS_EvaluateExpression back from OS_ReadArgs. This includes the cryptic ‘(Number)’ – try evaluating &O123 (and yes, that is a letter O)
The same may be true of /G and OS_GSTrans errors.

None of the errors returned by OS_ReadArgs give any indication which item or field is causing the problem, which can be frustrating.

This, indeed, is a pain.

Better errors from those SWI’s would be nice.

Better errors from SYS would be nice.
I was thinking about this on the way home. It is rather inexcusable that SYS "OS_GetEnv" TO cmd$ returns an empty string if the string is too long to fit. It ought to return the error “String too long” if a to-$ conversion fails, so it can at least be trapped and either faulted as an error, or handled a different way.

I’ve updated the OS_ReadArgs wiki and added an examples page.

I’ve updated the OS_ReadArgs wiki and added an examples page

Noticed that. Good work.

It is rather inexcusable that SYS “OS_GetEnv” TO cmd$ returns an empty string if the string is too long to fit. It ought to return the error “String too long” if a to-$ conversion fails, so it can at least be trapped and either faulted as an error, or handled a different way.

Set me thinking.

Why doesn’t Obey utilise the length / existence testing of OS_ReadVarVal?

Similarly, people parsing variables to find the length when the OS has the answer.