Bug bug? pre-script statements available at start of any block

[fredg1]

Branching off of https://kolmafia.us/threads/ash-language-server-features.26098/post-162481

MCroft, BigD and I are planning to try to add Language Server features to mafia, so that making scripts is easier. This would be done using Language Server Protocol for (4) Java.

We're starting with ASH (we'll have to see how adding the javascript part goes afterwards).

The first problems encountered are :

1. textui is very poorly documented. I'm currently trying to understand it as best as I can, but if possible, can anyone with a greater understanding of this explain the inner workings of textui/parsetree? More precisely, Scope, BasicScope and ParseTreeNode, if possible?
2. I noticed that script, notify, since and/or import statements are allowed at the start of literally any block, like so:
   

   script this_script_is_called_abc.ash_now;
   notify Fronobulax;
   since 20.1;
   import a.ash;
   import b.ash;
   
   static {
       script this_script_is_called_aaa.ash_now;
       notify Veracity;
       since 20.2;
       import c.ash;
       import d.ash;
   }
   
   string a_funtion() {
       script this_script_is_called_foo.ash_now;
       notify MCroft;
       since 20.3;
       import e.ash;
       import f.ash;
      
       for x from 1 to 10 by 5 {
           script this_script_is_called_bar.ash_now;
           notify Gausie;
           since 20.4;
           import g.ash;
           import h.ash;
       }
      
       return "";
   }
   
   {
       import i.ash;
       {
           import j.ash;
           {
               import k.ash;
           }
       }
   }

   
   (the script name and notify recipient don't actually get changed, since they can only be set once per script)
   
   Is this what-I-can-only-call-an-abheration intentional?

This looks like a bug. The docs say you can't do this.

Fredg, did you try not having first notify? If it's only in static or the functions, does the first one fire in any listed context? I think we should split this off from the feature request. And I think the language server should act as the docs say the language acts, in this case.

My main concern is: who *made* the docs? Is it someone who truly *knew* what ash was supposed/wants to do, or is it someone who *interpreted* it?

Well, turns out that hola wrote notify and hola wrote that text on the forum, and Zarqon copied hola's text from 2006 into the wiki in 2009. But in general, we only need to rely on the wiki for things we can't deduce from code.

But it would also be really handy to see where they two diverge (as in the case you mention). Again, recommend we split this off, because it's really a different topic...

 

[MCroft]

I'm going to try having it in two functions and call the second one first and see what happens. I think the documented functionality is what was planned many years ago.

That said, other than possibly being in a strange place, or being part of an imported function, or even just not behaving as documented, how serious a flaw is it?

 

[fredg1]

There is no inherent flaw in this. The only impact would be with the Language Server support, making resolution way harder (since a script imported in a block inherits all the scope from outside that block), which, linking back to what I said about this not being an attempt at forcing a protocol on ASH, is why I want to be absolutely certain that this is unintended (and preferably not used by anyone)

 

[MCroft]

Hola's notes in ancient threads (or actually found as quotes in ancient threads, sort of like we know about certain greek plays only because people who at one time had access to them mentioned them...) say...

For more general purposes, however, I've added a new start-of-script directive that makes this kind of intention crystal clear, and I'd prefer that everyone use it. Just prior to any import directives you may have in your script, you may optionally provide a "notify" directive, which will send the documented person a notification email stating that the given script was executed.

notify <holatuwol>;

Only one of these may exist in a script (it must be present BEFORE the import statement), and only the one at the top level execution will be honored (ie, all scripts further down in the chain will be ignored). Basically, because it must be at the beginning, it will be absolutely clear that you want your script to phone home. As this is intended for knowing who ran your script, the phone home will only happen once per script, even if multiple players use it, and message sending will not happen again unless the person deletes their global preferences or uses KoLmafia in a fresh directory, or the script decides to delete the property which tracks this.

Being above import means it's not going to pick a notify up from an imported script, but it sounds like the code to enforce this got relaxed or removed. The intent was clear, unless it's been changed. The docs match this and honestly, I suspect no one has touched the function itself since 2006...