Execute JS commands by printing directly into the file stream instead of using `BuildCommand`

[Natrium729]

Here's a suggestion to improve the usability of executing JavaScript commands.

Instead of building a command by concatenating strings/arrays with BuildCommand:

VorpleExecuteJavaScriptCommand(BuildCommand("alert('Score: ", score, "')"));

we would open the stream of the JS eval file and print the command directly into it.

VorpleJavaScriptCommand(); ! Opens the file stream.
print "alert('Score: ", score, "')";
VorpleSendJavaScriptCommand(); ! Closes the file stream and sends the command to Vorple.

There'd still be a way to execute a single string, by giving an argument to VorpleJavaScriptCommand (or by using another function):

VorpleJavaScriptCommand("alert('Hello World')"); ! Executes a single string.

Pros:

• We are not restricted by the 7-argument limit of BuildCommand.
• We can use printing functions, such as print (char) or print (address).
• We can write arbitrary code after opening the stream, so it's possible to use conditions or loops, like in I7 texts. That means it's easier to build complex JavaScript commands.
• There's no need to handle edge cases like in VorpleTooltipElementDuration (where we have to open manually the stream because there are two IntToString working on the same array), since it becomes the standard way to directly print into the stream.
• There's no more the ugly BuildCommand.
• I think we wouldn't need the equally ugly hugehugestr array anymore since we print directly into the file stream, resulting into a smaller and faster story file.
• It's in my opinion more idiomatic in Inform 6 to work on streams instead of working on strings/arrays.

Cons:

• It takes three lines to execute a simple command like above, instead of only one. This should be solvable by making VorpleJavaScriptCommand (or another routine) take arguments and making it print them into the stream: VorpleJavaScriptCommand("alert('Score: ", score, "')").
• It's a breaking change, except if we keep the old functions of course. (But if we keep them, the pro of having a smaller and faster story file doesn't apply anymore.)
• It will lead to strange bugs if the author forgets to close the stream with VorpleSendJavaScriptCommand. (But that shouldn't happen often since it's easy to notice.)
• Authors will have to be careful to handle Unicode in strings and escaping. (But that's easily done with print (VorpleEscape) uni-string.
• We should make sure that everything plays well with other functions that open streams (e.g. print (A) obj opens a memory stream to determine whether the object starts with a vowel).

[Natrium729]

OK, another thought, that solves most of BuildCommand problems, if we don't like what I suggested above (a routine to open the file stream and another to close it and send it to Vorple, with printing the JS command in the middle). But both this suggestion and the one above aren't exclusive.

Since Vorple is now Glulx only, we can make VorpleExecuteJavaScript a _vararg_count function to lift the 7-argument limit. We could also make VorpleExecuteJavaScript print directly into the file stream. I think we can also manage to make it accept routines that will be executed lazily.

Something like that (not tested and I don't really know the internals of Vorple I6, so it's just the idea):

[ VorpleExecuteJavaScriptCommand _vararg_count  i arg routine;
    if (~~isVorpleSupported()) return;

    ! Open file.
    fref_js_eval = make_fref(JS_EVAL_FILE);
    str = open_file(fref_js_eval, JS_EVAL_FILE, filemode_Write);

    ! Iterate through the arguments.
    for (i=0 : i< _vararg_count : i++) {
        ! Pull argument from stack.
        @pull arg;
        ! If `routine` is set, call it with `arg` number of arguments.
        if (routine) {
            @call routine arg 0;
            ! Decrease _vararg_count, since the `@call` pulled some arguments from the stack.
            _vararg_count = _vararg_count - arg;
        } else {
            switch (metaclass(arg)) {
                Routine: routine = arg;
                String: print (string) arg;
                default: print arg;
            }
        }
    }

    ! Close file.
    glk($0044, str, gg_result); ! stream_close
    signalFileToRead(fref_js_eval, JS_EVAL_FILE);
];

You would use it like that:

• VorpleExecuteJavaScriptCommand("alert('Hello')") for a simple command.
• VorpleExecuteJavaScriptCommand("alert('", score, "')") for a command in multiple parts.
• VorpleExecuteJavaScriptCommand(string1, MyRoutine, 2, arg1, arg2, string2) for a complex command.
  • string1 is a string and will be printed normally into the file.
  • MyRoutine is a routine that take 2 arguments.
  • 2 (i.e. a number just after a routine) means "feed the following 2 arguments to the previous routine.
  • arg1 and arg2 are the arguments that will be given to MyRoutine.
  • string2 is a string and will be printed normally into the file.

Still a bit cumbersome, especially when calling routines (except if we find a better way to call them), but more flexible. We keep these pros from the suggestion above:

• We are not restricted by the 7-argument limit of BuildCommand.
• We can use printing functions, such as print (char) or print (address) (by using their associated routines).
• There's no need to handle edge cases like in VorpleTooltipElementDuration (where we have to open manually the stream because there are two IntToString working on the same array), since routines are executed lazily.
• We wouldn't need the equally ugly hugehugestr array anymore since we print directly into the file stream, resulting into a smaller and faster story file.

But there are these cons:

• We lose compatibility with the Z-machine, if that matters.
• I guess it's a breaking change.
• Authors will have to be careful to handle Unicode in strings and escaping. It's a bit cumbersome to handle escapes: VorpleExecuteJavaScriptCommand(VorpleEscape, 1, "My string")
• We should make sure that everything plays well with other functions that open streams.

Of course, we can still implement both suggestions: when using no arguments with VorpleExecuteJavaScriptCommand, the stream could simply be opened.