[REBOL] Re: email command Bot
From: carl:cybercraft at: 27-Mar-2004 15:13
On 26-Mar-04, Mauro Fontana wrote:
> [small rant]
> I am not a Rebol genius, though I have been using it (discontinued)
> for some time now. There are still many things I have problems to
> understand, mainly due to its "compactness" in the syntax, which I
> though it was a thing the language wanted to avoid. See those neat
> examples in the library to see what I mean. No doubts they are nice
> pieces of code that run well, but they are quite ermetic (cryptic
> syntax)and often use some undocumented parts of the language (like
> the use of internal ports, sub-ports, system objects etc...) which
> make them quite "mysterious".
> I think this is the first problem novices meet when starting
> grasping with the language. The use of forms like :word 'word
> to-lit-word! to-lit-path! set get etc... can be quite powerful but
> can also make the code a mess (like doing things in C like c
> *(unsinged short *) &value[]). And often they are done just to keep
> the code short instead of making it clear.
I agree that it's often hard to figure out a REBOL script, and doubly
so for newcomers. I think the problem is that most programmers don't
start a script intending it to be an example. More likely it was
written with some purpose in mind and then uploaded to somewhere
because the programmer thought it might be of use to others. Ideally
they'd go through it first and comment it and change any cryptic
words to more meaningful ones, but that might take as long or longer
as writing the original script, hence it doesn't get done.
As an example, the programmer will know what a particular function
does and the types it should be given and so may not bother to make
it explicit in the code as their script only every supplies the right
types. (Or so the programmer thinks;) The newcomer on the other
hand just sees a function they think could be of use, then wonders why
it breaks.
What would a newcomer make of this for instance...
>> build-url: func [domain file][join domain file]
? It looks pretty self-explainatory, but there's any number of ways it
won't work...
>> build-url "www.nowhere.not" "story.txt"
== "www.nowhere.notstory.txt"
>> build-url "http://www.nowhere.not" "story.txt"
== "http://www.nowhere.notstory.txt"
>> build-url http://www.nowhere.not story.txt
** Script Error: story.txt has no value
** Near: build-url http://www.nowhere.not story.txt
>> build-url http://www.nowhere.not http://story.txt
== http://www.nowhere.nothttp://story.txt
>> build-url http://www.nowhere.not %story.txt
== http://www.nowhere.notstory.txt
plus a couple that will produce a correct URL...
>> build-url http://www.nowhere.not/ %story.txt
== http://www.nowhere.not/story.txt
>> build-url http://www.nowhere.not/ "story.txt"
== http://www.nowhere.not/story.txt
Confusing and discouraging, and HELP's not a lot of help either...
>> help build-url
USAGE:
BUILD-URL domain file
DESCRIPTION:
(undocumented)
ARGUMENTS:
domain -- (Type: any)
file -- (Type: any)
So much better if they'd written the function thus...
build-url: func [
"Builds an URL by joining a domain-name's URL to a file-path."
domain [url!] "Domain-name. Trailing slash required."
file [file! string!] "File-path."
][
join domain file
]
Much clearer and more errors will now show up (at the right place -
when the function's used) and be more explicit...
>> build-url "www.nowhere.not" "story.txt"
** Script Error: build-url expected domain argument of type: url
** Near: build-url "www.nowhere.not" "story.txt"
>> build-url "http://www.nowhere.not" "story.txt"
** Script Error: build-url expected domain argument of type: url
** Near: build-url "http://www.nowhere.not" "story.txt"
>> build-url http://www.nowhere.not http://story.txt
** Script Error: build-url expected file argument of type: file string
** Near: build-url http://www.nowhere.not http://story.txt
Plus HELP now becomes useful too...
>> help build-url
USAGE:
BUILD-URL domain file
DESCRIPTION:
Builds an URL by joining a domain-name's URL to a file-path.
BUILD-URL is a function value.
ARGUMENTS:
domain -- Domain-name. Trailing slash required. (Type: url)
file -- File-path. (Type: file string)
Perhaps functions in example code should all be this descriptive, but
the downside would be scripts that are quite a bit longer and at
first glance more complicated. Which takes longer for a human to
parse - the one-line function above or the fully fleashed-out
version? I'd say the one-liner.
That said, the one REBOL refresher-course us long-time users should
take every now and then is to re-read its style-guide...
http://www.rebol.com/docs/core23/rebolcore-5.html#section-5
--
Carl Read
