Naming for parsing words

[ruv]

Naming convention for parsing words

Namely, I consider the words for which compilation semantics include scanning/parsing the input stream, and, if interpretation semantics are defined for the word, they include parsing too. Sometimes the parsed part of the input stream is called "immediate argument".

To compare different variants of naming let's take some particular example. Let's consider a combinator dip (of Factor) that executes a given xt with preserving the top of the stack out of the stack.

This combinator accepts all parameters on the stack and can be defined as follows:

: dip ( i*x x0 xt -- j*x x0 ) swap >r execute r> ;


\ Usage example (1):

: times ( i*x xt u -- j*x ) 0 ?do dup dip loop drop ;
10 20 30 ' . 3 times \ prints "30 20 10"

: ip-in-subnet ( x.ip x.ip-mask x.ip-net -- flag ) ['] and dip = ;
: lt-cstring ( c-addr c-addr -- flag ) ['] count dip count compare -1 = ;

1 2  ' . dip  .  \  prints "1 2"

Now let's consider a variant of the dip combinator that accepts a word to be executed as an immediate argument and generates a more efficient code. Also, this variant can be better readable when the word is known in advance. A temporary name for this combinator is dip_.

: dip_ ( "name" -- ) postpone >r  parse-name evaluate  postpone r>  ; immediate
: dip ( i*x x0 xt -- j*x x0 ) swap dip_ execute ;  \ a postfix form
: dip_ ( i*x "name" -- j*x ) state @  if  postpone dip_  else  '  dip  then ; immediate


\ Usage example (2):

: times ( i*x xt u -- j*x ) 0 ?do dup dip_ execute loop drop ;

: ip-in-subnet ( x.ip x.ip-mask x.ip-net -- flag ) dip_ and = ;
: lt-cstring ( c-addr c-addr -- flag ) dip_ count count compare -1 = ;

1 2 dip_ . .  \  prints "1 2"

In this specific case, an advanced optimizer (having an inliner, and/or with special system-specific hints for dip) can generate for the definitions in (1) the same code as for the definitions in (2).

But more importantly, the form (2) can be better readable. Also, passing a parameter via the stack is not always possible. For example: dip_ recurse cannot be used in the postfix form (we cannot pass the xt of recurse as a run-time parameter on the stack; although, we can use something like itself dip [1,2]). So sometimes you anyway need an immediate argument. But if possible, a postfix form should be also provided.

Well. After all, the question is what a better name for the word dip_, and what is a better naming convention for parsing words in general.

Some variants for naming are following:

• [ ' foo ] [dip] — it's too awkward, too much limited, no ability to copy-and-paste out from a definition body.
• dip: foo — it clashes with a form often used for defining words like x: foo ... ;.
• dip/ foo — it resembles a path name, can be confused with dip/foo.
• dip\ foo — since \ does parsing up to the end of the line, a word having the name endings with \ probably should do the same.
• dip" foo " — it resembles immediate string literal, like abort" foo".
• dip' foo — it says that it parses a word name, a good variant; a trailing tick should not be used for other purposes.
• dip( foo ) — it explicitly shows the boundaries, in the general case it can parse several lexemes.
• dip{ foo } — the same as above, but less confusing with comments.
• dip:foo — it explicitly shows the boundaries, but it requires recognizers.

I don't consider a variant without a special character at all, since it has bad readability — it is confused with ordinary words, it's not obvious that the following word is an immediate argument of the previous one.

Actually, the above list of variants is ordered from the less to more preferable variants according to my rationales in the comments. I think, it's very important to make the boundaries of parsing (boundaries of immediate arguments) explicitly visible.

The usage examples from above can look like the following:

\ via recognizers
: ip-in-subnet ( x.ip x.ip-mask x.ip-net -- flag ) dip:and = ;
: lt-cstring ( c-addr c-addr -- flag ) dip:count count compare -1 = ;
1 2 dip:. .

\ using curly brackets
: ip-in-subnet ( x.ip x.ip-mask x.ip-net -- flag ) dip{ and } = ;
: lt-cstring ( c-addr c-addr -- flag ) dip{ count } count compare -1 = ;
1 2 dip{ . } .

What is your consideration about naming for parsing words?