On 07.01.2023 00:00, J Leslie Turriff wrote:
On 2023-01-03 04:25:33 Rony G. Flatscher wrote:
Thanks to everyone for the comments, information and ideas. Enclosed please
find the next iteration of that little script. Invoking it with
"getOoRexxDocs.rex ?" yields the refurbished (hopefully clearer) usage
text:
getOoRexxDocs.rex [directory [needle]]
a utility to download the ooRexx documentation from
SourceForge and save them in a subdirectory "docs.V" of the current
directory where "V" is the specified version (e.g. "5.0.0")
no argument ... download all files from the directory carrying
the highest version number
? or -h ... show this usage information
directory ... the SourceForge documentation directory to
download from, usually named after the ooRexx version (e.g. "4.2.0",
"5.0.0", "5.1.0beta")
needle ... only downloads files from the SourceForge
directory which contain the (caseless) needle in their names (e.g.
"-html.zip", ".pdf", "ref")
N.B.: This program uses "curl" on all platforms. You can find more
information on the Internet or<https://curl.se>
and<https://en.wikipedia.org/wiki/CURL>.
[snip]
Any feedback, ideas?
---rony
I'm curious as to where you obtained the shortcut .resources syntax
used in the usage
handler in this program? It is simply
| say .resources~usage
but the Language Reference only shows
| say .resources[name]~makeString
which is harder to remember.
There are a few things here to know:
* ooRexx is influenced by Smalltalk quite a bit and incorporates the message
paradigm of which
Alan Kay (https://de.wikipedia.org/wiki/Alan_Kay, German, but cites Alan Kay
in English near the
top from https://en.wikipedia.org/wiki/Alan_Kay) says: "I'm sorry that I
long ago coined the
term "objects" for this topic because it gets many people to focus on the
lesser idea. The big
idea is "messaging". In ooRexx there is an explicit message operator, the
tilde (~), left of
which is the receiver and right of it the name of the message.
o In principle, if a programmer wishes that a method routine gets executed
he has to send the
value (a.k.a. "object", "instance") a message by the name of the desired
method routine; the
receiving object (a.k.a. "value", "instance") conceptually then looks up
the inventory of
method routines in its class (a.k.a. "type", "structure") and invokes it
on behalf of the
programmer and returns any result the method routine may produce (ff the
message carries
arguments they get used when the receiving object invokes the method
routine).
o If the receiver cannot find a method routine named after the message, it
will look-up its
super class and look there and if not found in its superclass and so
forth until the root
class (named "Object") has been sought. If no matching method routine is
found, then a
runtime error gets created with the message "97.1 Object xyz does not
understand message
mno" and the program gets stopped.
However, there is an "unknown" mechanism built-into ooRexx: before
raising the syntax error
97.1 a search for a method routine named "unknown" is excercised as
above. Should such a
method routine be available then the receiver will invoke it instead and
supply two
arguments, the name of the message in uppercase and an array that
contains the arguments, if
any, supplied with the message.
In the case of resource directives ooRexx creates a collection (of type
StringTable which is
like the ooRexx Directory) named "RESOURCES" and saves it in the
package's (package is a
normal Rexx program that usually happens to have directives) environment
directory and can
then be referenced by its environment symbol (an environment symbol
always starts with a
dot) '.RESOURCES' . ooRexx then saves each resource directive there
using as the index the
name (in uppercase) and the contained lines as an array. In the program
the name of the
resource is "usage", hence one can fetch that entry from .resources with
".resources['USAGE']".
Now, the StringTable (like the Directory) class have an unknown method
routine defined (cf.
rexxref.pdf, "5.3.17.22. unknown", "5.3.9.23. unknown") for them. This
unknown method will
use the received unknown message name as the index and look-up itself
using that value. So
if one sends ".resources~usage" the StringTable unknown method routine will get
"USAGE" and
use that to look up the StringTable and return the stored array (for
more information look
up the reference manual).
* REXX is a string based language, such that everything is a string. ooRexx in
order to remain
backwardly compatible (becoming able to execute REXX programs as well) makes
sure that REXX BIFs
(built-in-functions) and REXX keyword statements like SAY or PARSE get
strings to work with,
even if they get values supplied that are not strings like is the case with
a value of type
Array. So what happens in this case is that the SAY keyword instruction
requests a string value
from the array value/object/instance and gets it magically. ;) Actually,
there is no magic
involved in this, one just needs to know one more thing in this context: each
class/type/structure in ooRexx possesses a method routine named "STRING"
(this method routine is
defined in the root class named "Object", cf. rexxref.pdf, "5.1.4.25.
string") which will return
a string value (usually that string value contains the name of the
class/type/structure the
value/object/instance got created from). If however there is in addition a
method named
"MAKESTRING" available, then that is executed which is the case for Array
collections (cf.
rexxref.pdf, "5.3.6.24. makeArray").
You may want to look up rexxref.pdf, "4.2.11. Required String Values".
HTH,
---rony
_______________________________________________
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel
