The DM4’s Table 3 (DM4 Tables) and the inform executable’s built-in help (via inform -h2) both say that the purpose of the -l switch is “list every statement run through Inform”. What does this mean? What are the “statements” being referenced?
I’ve tried using it, and it primarily seems to report opening/closing various files (the original source and those accessed via Include directives).
I looked into the 6.34 source code to try to figure this out.
The switch is used in inform.c to set a global variable called line_trace_level to 1 instead of its default 0.
The line_trace_level variable is used in two places:
files.c - This is where is triggers the output about file open/close activity.directs.c - Inside of function parse_given_directive() – in a section labeled “Trace dictionary” via comment block, in its main switch block’s TRACE_CODE case – line_trace_level is used to define the pointer value of a local variable trace_level if global variable (?) token_value is set to constant LINES_TK. This seems like it might result in reassignment of the value of line_trace_level (via dereference of trace_level) in a following switch block’s default case.#2 above is the only reference to LINES_TK in the source code. The comments for the TRACE_CODE section and constant name LINES_TK imply that the intended use is for handling of Trace directives. Inform Technical Manual section 12.1 Using the “Trace” directive has a table showing available values for the directive; in this table, there is a line:
"lines" --- (currently inoperable)
It seems like maybe this switch is either a vestigial bit leftover from previous iterations of Inform (5.5 or earlier) or it was for planned functionality that was never implemented.
Should the output for the -h2 switch be updated to reflect the switch’s current actual function of printing out file open/close notifications?
(And if anyone is taking action on this, should the -h2 output’s text be updated to distinguish -h1 and -h2 and to properly indicate that “this information” – i.e. that from -h2 – is output by -h2 instead of -h as claimed?)
Thanks for looking into this. Your conclusions look right to me.
Right. This is the Trace directive, which lets you set various trace options on or off. So writing
Trace lines on;
is equivalent to the -l option.
Should the output for the
-h2switch be updated to reflect the switch’s current actual function of printing out file open/close notifications?
There’s an opportunity to fill out the originally intended functionality. But I have never run into the need for “printing every line”, whatever that means. When trying to figure out Inform’s code generation, the -a or -t switch is sufficient.
So I’m happy to update the docs, although I’d rather note that the feature is “not implemented”.
I dunno. Do you think it should?
I guess it might mean printing every line that will actually get compiled, accounting for #Include, #Ifdef, and similar directives, like printing the output from the C preprocessor (e.g. clang -E).
(That can be handy occasionally to see the result of C/C++ macros when not using an IDE that can display the expansion on the fly, but probably not that useful for Inform given that it doesn’t have macros.)
Yeah, agreed. On the rare occasions that I’m confused about what the #ifdefs are doing, I add some Message directives until it’s clear.
Well, at present the -h switch yields the usage overview, the output of which mentions the existence of the -h1 switch (yielding path name defaults and example invocations) and -h2 switch (ostensibly yielding the complete list of available switches). The output for the -h2 switch only mentions the -h switch (omitting -h1 and -h2), and it says that the output of -h should be the output of -h2, which it’s not. So… yes.
Regarding making use of the opportunity to fill in the inoperable functionality: I agree that it seems like unnecessary duplication to make -l work like -a or -t. Do you know if -l ever worked in previous versions? I might be able to try to interpret its previous function from outdated source code, if it can be found in the IF Archive.
Makes sense.
I took a look at Inform 5. It had the same -a, -t, -l switches as I6.
% ./inform5 -a test.inf
Unix Inform 5.5 (v1502/a)
5 [ Main
6* @je x 0 ?~_f1
7* @ . _f1
9 ]
9* @rtrue
% ./inform5 -t test.inf
<Routine 0, 'Main' begins at 0000; 0 locals>
0006 00381 je 41 10 00 00 07
0007 00386 print b2 13 ca e0 b2
._f1
<Routine ends>
0009 0080b rtrue b0
# ...followed by the same assembly again because I5 was a two-pass compiler.
% ./inform5 -l test.inf
Unix Inform 5.5 (v1502/a)
1 Global x
3 Object rock "rock"
5 [ Main
6 if ( x == 0 )
6* @je x 0 ?~_f1
6* {
7 print "Yes."
7
7* }
7* @ . _f1
9 ]
9* @rtrue
Closing file
9* #end
So -l did indeed print all the source lines as they were parsed, including directives (like Global and Object.) And also the assembly, same as -a. The assembly part is redundant since we still have -a. The source lines are a feature that disappeared in the transition to I6, but, again, not an extremely desirable feature.
OK. Well, if the previous function is duplicative of -a and/or -t, then either adjusting the -l switch description in -h2 output to its actual current function or replacing/enhancing current function seems desirable.
I had a vague idea looking at this last night that it might be useful for -l to list out all directives encountered and/or their resolution, though I don’t have a firm idea of any practical value for that. @ArdiMaster’s idea of spitting out post-#if* directive source seems potentially useful, especially given that it sounds like you personally might have made use of that in the past (to save yourself the trouble of having to add debug Message directives). I could make use of it in some of my own explorations of StdLib 6.12.4, to have Z-code and Glulx versions of the source in separate files for search purposes.
I was saying that it wouldn’t have saved me much trouble, really.
But if someone wants to write up a PR, I’ll happily look it over.