On Using '$<n>' vs 'SAY' Constructs

[tajmone]

@thoni56,

I noticed that the Library currently uses always the long say [the|an] obj form in the output strings:

Syntax
  eat = eat (obj)
    Where obj IsA object
      else "You can't eat" say an obj. "!"

whereas it would be much less verbose to use the $<n> special parameter interpolations:

Syntax
  eat = eat (obj)
    Where obj IsA object
      else "You can't eat $01!"

I'm aware that using the say <object> from is safer because it allow compile-time checking, whereas the $<n> notation is not checked at compile time; but is this really an issue? I mean, we'll be testing thoroughly all libraries via some test suite, so chances are that it's unlikely that such a gross error as parameters mismatching would occur in these places.

Is the reason we don't see usage of the $<n> notation in Lib 0.6's code due to the fact that these parameter symbols were not available at the time (2007)?

Or was it a deliberate choice not to use them?

Personally, I prefer using the $<n> notation whenever it's possible, for it doesn't break up strings and makes them more readable.

Should we tweak the libraries code to use $<n> symbols instead of say constructs, wherever it's possible? Or are there specific reasons why we'd rather stick to the say notation?

This is also a topic worth mentioning the Contributors' Guidelines doc.

[thoni56]

As far as I can remember, $<n> predates the Say forms. But there are also a couple of reasons for selecting Say. (I'm not sure that it was a conscious decision at the time, though. Perhaps more a tendency to use the more "modern" construct.)

1. Semantic checking of types and attributes etc. (as you already mentioned).
2. Parameters are referenced by name, which is important in two situations:
   • If you have synonym syntaxes, "give (item) to (actor)" and "give (actor) (item)", for which you want to have the same actions. In this case numbers will not work. Probably we already have exactly this in the English library. This would either break your game or force you to duplicate all code for the two sets of verb actions.
   • If you are translating from English and the target language have the parameters in different order. This is more of a covenience, but would prevent certain kinds of translation mishaps, unless you have 100% testing of the new language library.

I seem to recall that I thought about actually deprecating $<n> because of the problem with semantic checking, the same reason, partially, that made $o obsolete. I never did that because I was thinking about implementing some kind of string interpolation first. This was at the time that other languages, like Python, also introduced this, or at least when I started seeing this more often. I never got around to that, so $<n> stayed.

But this would be nice, right:

"You take {the object} and give it to {the actor}."

[tajmone]

As far as I can remember, $<n> predates the Say forms.

That's interesting, I though it was the contrary.

If you have synonym syntaxes, "give (item) to (actor)" and "give (actor) (item)", for which you want to have the same actions. In this case numbers will not work. Probably we already have exactly this in the English library. This would either break your game or force you to duplicate all code for the two sets of verb actions.

I'm 100% sure that's not the case, and that the first Syntax definition becomes the reference for the canonical order/numbering of the parameters.

In the StdLib (English and Italian) we use shared string attributes (defined on the my_game instance) to store commonly shared responses, thus avoiding duplicates and centralizing maintenance.

E.g. the verb consult has two syntaxes:

1. consult (source) about (topic)!
2. 'look' 'up' (topic) 'in' (source).

yet we use strings with $<n> notation in the various responses, as can be seen in lib_verbs.i (LL 1647–):

SYNTAX consult = consult (source) about (topic)!
  WHERE source ISA OBJECT
  [...]
  consult = 'look' 'up' (topic) 'in' (source).

ADD TO EVERY THING
  VERB consult
    WHEN source
      CHECK [...]
      [...]
      AND source IS reachable AND source IS NOT distant
        ELSE
          IF source IS NOT reachable
            THEN
              IF source IS NOT plural
                THEN SAY check_obj_reachable_sg OF my_game.
                ELSE SAY check_obj_reachable_pl OF my_game.

where check_obj_reachable_sg and check_obj_reachable_pl of my_game are defined in lib_messages_library.i as:

HAS check_obj_reachable_sg    "$+1 is out of your reach.".
HAS check_obj_reachable_pl    "$+1 are out of your reach.".

Even though the verb has two alternative syntaxes, with parameters in swapped order, the reference numbers in the parameters interpolations always follows the first definition ($1 = source; $2 = topic).

In Italian alternative syntaxes with parameters in swapped order are even more frequent than in English, due to the language nature. So much so, that in order to take advantage of the shared sting attributes I had to ensure that the first syntax matches the parameters order found in the shared attributes, although it might be the less used of the two alternatives.

I seem to recall that I thought about actually deprecating $<n> because of the problem with semantic checking, the same reason, partially, that made $o obsolete.

I really hope you won't, for they are very practical, especially when there are many commonly shared response snippets that could justify storing them on same abstract entity and re-use them by multiple verbs. With the evolution of memory and processing power in computers, today is no longer an issue if VERBs bodies exploit this techniques — and in big libraries, it actually ends up saving quite some space, since redundant strings are replaced by "pointers" to a same strings instead. Also, you can only achieve this via $<n>, since any SAY construct would interrupt the attribute strings, and won't allow this trick.

I never did that because I was thinking about implementing some kind of string interpolation first. This was at the time that other languages, like Python, also introduced this, or at least when I started seeing this more often. I never got around to that, so $<n> stayed.

But this would be nice, right:

"You take {the object} and give it to {the actor}."

Indeed, nice. But also a huge breaking change too.

It reminds me of how Inform7 handles string interpolations, which is quite smart for (IIRC) "you take [the noun]" in i7 would cover all definite article and pronoun cases, regardless of whether it's singular or plural. Furthermore, you can also insert conditional keywords inside strings like "[if <expre>]some text[else]alternative text[end if]", or a list of entries to be picked randomly. Also say "[here]", say "[now]", etc.

Basically, there's very little in i7 that you can't interpolate inside a say string. Quite powerful stuff, and very user friendly and prose-like too — for more details, see:

• Writing with Inform:
  • Ch. 5: Text
  • Ch. 14: Adaptive Text and Responses

Maybe ALAN could eventually benefit of from some additional interpolations that would allow to store inside string attributes things like text of obj, e.g. using "The text reads: $1{text}", where the $<n>{<attr>} notation would allow attributes chaining like $1{owner:age} representing age of owner of obj, etc. But then, if the compiler doesn't check advanced interpolations like these, it might be problematic since it's easy to forget about such snippets when refactoring a big adventure (especially and old one).

[thoni56]

As far as I can remember, $<n> predates the Say forms.

That's interesting, I though it was the contrary.

The order of implementation of related concepts is (from memory, I haven't consulted git ;-) :

1. $v & $o, for simple verb/object syntaxes
2. Then realizing the need for more complex syntaxes we introduced $<n>
3. Then the Forms where invented to support more grammatically correct wordings, together with Say statement
4. Then the $+, $0, etc. shortcuts where added to support those forms embedded in strings

If you have synonym syntaxes, "give (item) to (actor)" and "give (actor) (item)", for which you want to have the same actions. In this case numbers will not work. Probably we already have exactly this in the English library. This would either break your game or force you to duplicate all code for the two sets of verb actions.

I'm 100% sure that's not the case, and that the first Syntax definition becomes the reference for the canonical order/numbering of the parameters.

You are correct of course. I know they are mapped on each other, the manual even says so, but I think which becomes the canonical numbering actually is an implementation dependent detail, at least it doesn't look to be documented.

<excellent arguments for keeping $<n> removed>

I seem to recall that I thought about actually deprecating $<n> because of the problem with semantic checking, the same reason, partially, that made $o obsolete.

I really hope you won't, for they are very practical, especially when there are many commonly shared response snippets that could justify storing them on same abstract entity and re-use them by multiple verbs. With the evolution of memory and processing power in computers, today is no longer an issue if VERBs bodies exploit this techniques — and in big libraries, it actually ends up saving quite some space, since redundant strings are replaced by "pointers" to a same strings instead. Also, you can only achieve this via $<n>, since any SAY construct would interrupt the attribute strings, and won't allow this trick.

The issue of space should no longer be considered, our biggest concern is now duplication, so, even though you refer to "space", I think this is a brilliant application of that principle, avoiding duplicate strings for similar handling, and one that Alan should try to support. So, no, I have no longer any thoughts about deprecating $<n>. I'm more inclined to investigate semantic analysis of those embedded tokens, instead. Also the number mapping should be documented and pinned with tests.

As a side-note, in the comment about strings you might see a glimpse of history on this matter:

The use of $o is deprecated. The variants are better, but the recommended use is to refer to the parameters using their parameter names in a Say statement instead. This will ensure full reference analysis by the compiler protecting against any runtime error.

I never did that because I was thinking about implementing some kind of string interpolation first. This was at the time that other languages, like Python, also introduced this, or at least when I started seeing this more often. I never got around to that, so $<n> stayed.
But this would be nice, right:

"You take {the object} and give it to {the actor}."

Indeed, nice. But also a huge breaking change too.

It doesn't have to be breaking. It would be completely possible to have string interpolation, too. Given that care is taken when selecting the "interpolation" characters. The example was just, an ... example. Probably a better alternative from that perspective would be

"You take ${the object} and give it to ${the actor}."

It reminds me of how Inform7 handles string interpolations, which is quite smart for (IIRC) "you take [the noun]" in i7 would cover all definite article and pronoun cases, regardless of whether it's singular or plural. Furthermore, you can also insert conditional keywords inside strings like "[if <expre>]some text[else]alternative text[end if]", or a list of entries to be picked randomly. Also say "[here]", say "[now]", etc.

Basically, there's very little in i7 that you can't interpolate inside a say string. Quite powerful stuff, and very user friendly and prose-like too — for more details, see:

• Writing with Inform:

  • Ch. 5: Text
  • Ch. 14: Adaptive Text and Responses

I'm not familiar with how i7 does this, but this was quite easy to add to dynamic languages where you only have to split the string and feed the expression to the REPL. So this is where the trend started, I think. For compiled languages it requires more implementation, but might be worth the work.

Maybe ALAN could eventually benefit of from some additional interpolations that would allow to store inside string attributes things like text of obj, e.g. using "The text reads: $1{text}", where the $<n>{<attr>} notation would allow attributes chaining like $1{owner:age} representing age of owner of obj, etc. But then, if the compiler doesn't check advanced interpolations like these, it might be problematic since it's easy to forget about such snippets when refactoring a big adventure (especially and old one).

Yes, agreed. I think that more advanced string interpolation can only be implemented if it is checked. And that sounds like a fun project for some future time ;-)

Incidentally, the form "owner:age" is already a part of the Alan language, but not used much it seems.

[tajmone]

You are correct of course. I know they are mapped on each other, the manual even says so, but I think which becomes the canonical numbering actually is an implementation dependent detail, at least it doesn't look to be documented.

In the Italian StdLib, where I had to recreate all library attribute-string messages from scratch (due to the dual need of singular vs plural forms) I never encountered any problems, and the test suite covers every syntax, including their alternatives. So I can confidently say that its an intuitive feature to use, and a safe one too (obviously, provided their context usage is correct and the author knows what he/she's doing, since there are no compile time checks).

Thanks for the history of when these features were added, and their order in time and associated constructs. The history of ALAN (especially everything before ALAN v1) is enshrouded in mystery — I couldn't really find much info on it, and it's a pity for I always love to learn about how IF tools started out and how they evolved, because this tells not only a story of how practical needs forged these tools, but also provide inspiration for defining the ROADMAP of new tools which are similar (you can always learn from the experience of others, we all stand on the shoulders of those who preceded us).

The history of ALAN is that of a success story, so I feel it needs to be written out, read and learned.

I think that more advanced string interpolation can only be implemented if it is checked. And that sounds like a fun project for some future time ;-)

This is indeed an area where new features could make great differences, so even seeing a new interpolation being added now and then is going to be exciting.

Incidentally, the form "owner:age" is already a part of the Alan language, but not used much it seems.

I personally use it a lot, and in the upcoming StdLib 2.2 release I've changed most of the attr OF entity notations to entity:attr, especially when doing so makes the code more readable.

E.g., these (hypothetical code snippets):

SET my_game:restricted_response_bak
 TO my_game:restricted_response.

IF  THIS:headcover  <> 0
AND THIS:total_weight  <= item:weight
  THEN ...
END IF.

are more readable than:

SET restricted_response_bak OF my_game
 TO restricted_response OF my_game.

IF  headcover OF THIS  <> 0
AND total_weight OF THIS  <= weight OF item
  THEN ...
END IF.

just in virtue of how they align on the screen, thus making it easier to rapidly sift through the code and find something.

In other cases, when there are no practical benefits, I tend to use the attr OF entity notation, which is more "natural language". But for library messages, I always use the my_game:message_ID notation, since it's more intuitive. E.g.

SYNTAX give = 'give' (obj) 'to' (recipient)
  WHERE obj IsA OBJECT
    ELSE SAY my_game:illegal_parameter_obj.
  AND recipient IsA ACTOR
    ELSE
      IF recipient IS NOT plural
        THEN SAY my_game:illegal_parameter2_to_sg.
        ELSE SAY my_game:illegal_parameter2_to_pl.
      END IF.

So, I personally find the entity:attr alternative notation very practical, especially in libraries and extensions. But I tend to avoid it in tutorials and examples, where a more prose-like and natural syntax is more forthcoming to newbie authors with no programming experience.