World: r3wp

What exactly it is you *would want* to see?

@Ladislav Thanks for clearing that up!  At the moment, I'm simply 
reading http://www.rebol.com/docs/words/wswitch.htmland trying out 
the snippets to do 2 things:
1. Learn to use the REBOL console
2. Learn REBOL syntax etc


Entering those multiline snippets is what was a problem - until now. 
The console prints a "[" after each CR. For a noob, this chars looks 
and feel just like the ones IN the code. :))

I do understand, but that does not answer my question. As far as 
I am concerned, I use the

    do read clipboard://

approach when trying some code snippets

But, anyway, what it is you would want to see?

here's a cheap'n'cheerful console replacement that concatenates an 
expression until it reads a blank line. Then it executes it. (Two 
blank lines to exit).

Feel free to change the console prompt characters.

my-con: func [
  /local
   in-line
   in-buff
   err
][
forever [
    in-buff: copy ""
    in-line: copy ""
    forever [ 
      in-line: ask "In > "
      if in-line = "" [break]
      append in-buff join " " in-line
      ]
 if in-buff = "" [break]
 err: none
 if error? err: try [print ["Out > " do in-buff] true] [
    print ["Oops > " mold disarm err]
    ]
 ]
 exit
]

Duke - I think that in fact it is not much of an issue? How often 
do you use multiline expression in REBOL interactive console session? 
It does not allow you to go back anyway, so ...

@Sunanda Thanks! Can't wait to try it out! :)

@Ladislav  [quote]do read clipboard://[/quote]


I see! I'm on a Linux Xubuntu box - so I just highlight the text, 
and then right-click paste it into the REBOL console. I get to "see" 
the code, then the results, after a CR. Your method works OK, but 
all I get is the results -- don't seem like "a full meal deal" :)) 
Thanks ...

@Sunanda  Works like a HOT DAMN!!  Thanks! BTW, the command history 
still works after the result is printed - so a person can go back 
and re-do everything, and fix errors.

This code:

val: 123
switch type?/word [
    integer! [print "it's integer"]
    decimal! [print "it's decimal"]
    date! [print "it's a date"]


produces an error msg in v2.7.8 Is it R3 speciffic? It is from the 
R3 docs, but it seemed fairly generic to me.

Looks like you are missing:

-- val after type?/word -- so REBOL knows which word's type  you 
are switching on
-- a closing ]
No idea why R3 is happy with that. This works for R2:

val: 123
switch type?/word val [
    integer! [print "it's integer"]
    decimal! [print "it's decimal"]
    date! [print "it's a date"]
   ]

Thanks Sunanda! Then there is an error in the docs at http://www.rebol.com/r3/docs/functions/switch.html.
Who do I alert?

I just did a "Help type? at the console, and got:

TYPE? value /word


Does this output not seem counter-intuitive to you guys? Especially 
when the syntax is:

TYPE?/word/ value   ; I used the / char to indicate an option


This tells me that the type? word is followed by an optional refinement, 
but always needs a "value" - in that order. The console help output 
seems to have it reversed. What do you think?

All the refinements are optional, it's a bit confusing for a beginner 
but otherwise it will be more confusing. Try:  help find

There are lots of refinement. HELP shows the normal usage and then 
the optional refinements and their arguments.

Hmm, looks that I forgot (once again) how to log in to the R3 docs.

Duke, refinements can have arguments as well, so the order as shown 
in the help is exactly the same as when you define a function header.

@Henrik So in the case of the word TYPE?, is "value" an argument 
of the refinement, or of the word itself? Because it seems to be 
used as if it was an argument of the /word refinement.

The format is name, followed by arguments to that name. So VALUE 
is an argument to TYPE and the /WORD refinement has no arguments.

Refinements are options, sometimes used in twos or threes, and the 
disadvantage here is that the argument list then can become hard 
to read. It's a good skill to create functions without too many refinements. 
I personally consider refinements to be one of the less stellar parts 
of REBOL.

If you type:

source type?


you will see the function header as it is stated for the function. 
It comes in the same order as in the help documentation.

So, why isn't it just the other way around, like in the help? You 
could in principle do that. It just gives you many more arguments 
that you would be forced to type.

TYPE? could look like this:

type? 5 word

So, if you didn't want the refinement, you would have to type:

type? 5 none


For functions with many arguments, you would have to type something 
like:

my-function 1 none none none none none none

which is no fun to type directly.

@Henrik But Sunanda responded above to my original question by indicating 
that the syntax was:

switch type?/word val [


So val is an argument to TYPE?, but it's written after the refinement?? 
That is NOT intuitive to me!!

A refinement is latched onto a function, so that you know that the 
refinement is part of that function. Hence, you must type out the 
function name, followed directly by the refinement without spacing. 
Then you type the function arguments and after that, the refinement 
arguments.

The arguments has the same order with refinements after the non-optional 
arguments:

with a function that requires 2 arguments and have 2 refinements 
should be used as:


myfunc/ref1/ref2 arg1-to-func arg2-to-func arg-to-ref1 arg-to-ref2

@Henrik  Thanks for the examples ..

@Endo     That's what I needed - a definitive HOWTO.  IMHO, the Help 
system should be worded that way as well, in order to sync with actual 
usage

If you study some unloaded data:

a: [now/precise now /precise]


a/1 is of type path!, which can be reduced to calling NOW with the 
/PRECISE refinement.


a/2 is of type word!, which can be reduced to calling NOW without 
any refinements.


a/3 is of type refinement!, which doesn't reduce. In principle, that 
refinement could be an argument to the function. What types you can 
pass to a function is almost entirely free-form.

>> reduce a

== [25-Oct-2011/17:39:39.218+2:00 25-Oct-2011/17:39:39+2:00 /precise]

The problem with wording the help differently is that arguments and 
their orders passed, might be different, depending on which refinements 
you use. Therefore help is formatted the same as function headers. 
A way to understand it, is that anything that comes directly after 
the function name is obligatory. When the first refinement appears 
in the help string, anything after that is optional.

Example:

my-func/boo 6

Does the 6 argument belong to the function or the refinement?

I'm getting TOTALLY confused here! I'm going to have to stop here 
and go study this - including all of you guys' advise - a bit more 
....

ok :-)

Yeah, that can be confusing! :)

>> f: func [arg /ref1 ref-arg] [print [arg /ref1 ref-arg]]     
>> f/ref1 /ref2 /ref3
ref2 ref1 ref3

>> f/ref1 'arg 'ref-arg
arg ref1 ref-arg

Duke: Don't be confused.

my-func/boo 6


If my-func requires an argument and /boo refinement does not require 
and additional argument, then 6 is for my-func.

if my-func and /boo both require args then you will get an error. 
my-func expects more arg.

if my-func doesn't require an arg but /boo does then it belongs to 
/boo

I personally consider refinements to be one of the less stellar parts 
of REBOL.


Henrik, do you prefer one additional function for each new way of 
calling a function, instead of refinements?

I should have made my example more like this:

>> f: func [arg /ref1 ref-arg] [print [arg ref1 ref-arg]] 
>> f/ref1 /ref2 /ref3
ref2 true ref3

I faced a problem when I use a refinements, my function had an ref. 
/any

Then I forgot it and use ANY native. It gives error about using none, 
because the function wasn't called /any, so the word ANY was defined 
and its value was NONE. It was difficult to find the problem.

Maybe refinements for functions are more clear with examples like 
this: Let's say, we want a sine function, which default operate with 
radians, but you can give degrees refinement, if you like, exactly 
opposite of the normal SINE function:


>> sin: func [value /deg] [either deg [sine value] [sine/radians 
value]]
>> sin pi / 6
== 0.5
>> sin/deg 30
== 0.5

Another example with additional argument, when refinement is used. 
The normal COPY function:

>> copy "abc"
== "abc"
>> copy/part "abc" 2
== "ab"

And checking help for COPY:

>> ? copy
USAGE:
    COPY value /part range /deep

Read that as:
- COPY takes one argument called VALUE

- If you choose to use the /part refinement, you then need to give 
an additional RANGE argument

- If you choose to use the /deep refinement, no additional argument 
is needed.

@Geomol  I now understand the syntax of function arguments, function 
refinements and THEIR arguments. Endo summarized it well. However, 
I still think that the REBOL Help sub-system should reflect EXACTLY 
how the function should be written. Thta should be the programmer's 
first line of help. Like the Unix man pages. So, assuming that the 
* char indicates optional syntax, IMHO, ?copy should say:
USAGE: 
    COPY */part, /deep* VALUE */deep range* 


To me, that tells me exactly the order in which the optional refinements, 
the required function argument, and the optional refinement argument 
should be written. To me this makes more sense. :D

COPY */part, /deep* VALUE */deep range*

 - not sure I understand this order, as it will fail to explain where 
 VALUE belongs and where RANGE belongs (it does not belong with /DEEP). 
 Anyhow, the notation is standard and should not change anywhere. 
 You only need to learn it once, so hopefully, this is not too much 
 of a hurdle.

I still think that the REBOL Help sub-system should reflect EXACTLY 
how the function should be written

 - this is easy. If you find a better way how to display the help, 
 then simply propose it. In REBOL, it is easier to write the code, 
 than to invent what the code should do.

But, do not forget, that it must be something that describes what 
do you want, not a description what you do not like.

It would certainly suffice if you wrote a couple of examples, how 
it should look

Aha, you tried to write something above. Well, I do not quite understand 
the stars you used - where should they be put?

The REBOL help system is remarkable concise and acts, usually, as 
an excellent aide memoire.


It has weaknesses too -- for example, it does not give hints as to 
which refinements are incompatible with others. eg HELP TRIM gives 
no clue that TRIM/HEAD/WITH is not acceptable.

A fresh look at the HELP system may help improve it.

Nor I did understand how can I recognize that VALUE is a parameter 
of COPY, not of the /DEEP refinement

The

    COPY value /part range /deep

actually means, that you can use any of:

    COPY value
    COPY/part value range
    COPY/deep value
    COPY/part/deep value range
    COPY/deep/part value range

(I must admit, that I never tried some of the above)

eg HELP TRIM gives no clue that TRIM/HEAD/WITH is not acceptable

 - yes, but that can be cured even without a change to the help system, 
 it might suffice to just add that as a new information into the main 
 help string.