Adds top level initializer block.

[jaubourg]

The initializer is re-executed at each parse call.

This makes it inadequate and wasteful for code and data structures that are constant throughout multiple calls to parse and, if and when an es module output format is added, impossible to use import statements.

It is possible to use the options argument passed to parse as a workaround to the former but it is quite the anti-pattern.

This PR introduces an optional top-level initializer: a code block that is added at the very top of the generated file.

To distinguish the top-level initializer from the normal one, it is surrounded by double curly braces.

A grammar can have both a top-level initializer and a "classic" initializer. The top-level initializer always appears before the initializer.

{{
   // top level
}}
{
  // function level
}
rule1: <...>
rule2: <...>
<...>
ruleN: <...>

Let me know what you think.

[hildjj]

Interesting. How many other people want this, by show of hands, please?
Is there anyone who feels strongly against it?

Please get the tests to pass, and add yourself to the AUTHORS file.

[jaubourg]

@hildjj done and done. I also added some tests.

I'll raise my hand and say it would be super useful to me for one. Also, if you look at all the examples in the repo itself, the initializer could (and probably should) be top-level. I honestly never understood why the initialiizer wasn't top-level by default and I was just eagerly waiting for pegjs' successor to make this PR (had it in mind for years now).

[hildjj]

We'll also need documentation updates, including some guidance over what sort of thing goes into each block.

[jaubourg]

@hildjj I'll get to it tomorrow!

[jaubourg]

@hildjj I put some documentation / guidance in the readme and the documentation.html document. Not sure the parse level initializer example is that good though and I'll take any feedback.

[StoneCypher]

I don't understand why you don't just put a singleton in the parse block

[StoneCypher]

I honestly never understood why the initialiizer wasn't top-level by default

because then it can intrude on other namespaces and conflict

similar to wrapping it into an iife block

[jaubourg]

I don't understand why you don't just put a singleton in the parse block

Because it won't solve the problem of import statements ? Because it's what I have to do right now and it creates unnecessary clutter ?

I honestly never understood why the initialiizer wasn't top-level by default

because then it can intrude on other namespaces and conflict

similar to wrapping it into an iife block

You mean like you can screw everything up in the parse block with a single assignment or declaration ?

[StoneCypher]

Because it won't solve the problem of import statements?

I apologize. I don't understand this. I'm not saying you're wrong, I just mean I don't get it yet.

Could you please explain?

.

it creates unnecessary clutter

fair

.

You mean like you can screw everything up in the parse block with a single assignment or declaration ?

Yes, essentially. It's just a more severe case.

But if it's useful, it shouldn't be something people can do by accident, so, sure why not

[StoneCypher]

Because it won't solve the problem of import statements?

oh wait. modular grammars. you're right

[jaubourg]

Because it won't solve the problem of import statements?

oh wait. modular grammars. you're right

Yes, that's what I meant :)

My goal here is to make sure we have the whole parse-related code in the grammar itself. Without a top-level initializer, you have to create boilerplate code around the generated parser or awkward / convoluted logic in the parse block. With es-modules, the former is unavoidable without a top-level initializer.

From what I've seen in the wild, most initializers just declare some functions and/or global objects that do not change from one parse to another. If anything, I suspect we'll see more top-level initializer than parse-level intializers, if that makes sense.

[StoneCypher]

Now that I understand you, I am in full agreement.

[hildjj]

Are there any interactions I'm not seeing with options.dependencies, other than making them even less useful?

[hildjj]

typo?

[jaubourg]

I wanted to emphasize the fact the initializer is called repeatedly but I can live without the "everytime and" ;)

[hildjj]

same potential typo as above, regardless, let's reword.

[jaubourg]

see comment in the README.

[hildjj]

you must have bootstrapped this?

[jaubourg]

Yes, I generated the parser with a per-parse initializer first then transformed it into a global initializer and re-generated. It served as a first test ;)

[hildjj]

hm. are there code blocks that could match this for parse-level initializers that happen to start with { and end with }

[jaubourg]

Technically you could have as many curly braces as you'd want so, yes, you could have a per-parse initializer that has double curly braces... but it serves no purpose whatsoever and would be very weird code formatting.

The only situation it would arise is if someone wanted to scope the entire code and do so without indentation... something like:

{{
  let scoped;
  // some code
}}

But:

1. I expect such code to be indented
2. I also expect unscoped code to exist after or before the scoped code

Something like:

{
  {
    let scoped;
    // some code
  }
  // other code
}

The likelihood of a double curly braced initializer in the wild seems extremely low but, yes, it could happen.

[hildjj]

nod. and there's a work-around if it does break something of putting a {{}} in front if you really want.

[jaubourg]

Are there any interactions I'm not seeing with options.dependencies, other than making them even less useful?

None that I can see... options.dependencies are placed before the global initializer and accessible from it. So... yeah... apart from meking them obsolete, not much.

[hildjj]

let's mention both of those things, then. a) {{}} comes after dependencies, and b) don't use dependencies unless you really need output-format-independent imports.

[hildjj]

(sorry about the back and forth here! I appreciate your effort and willingness to take feedback.)

[jaubourg]

let's mention both of those things, then. a) {{}} comes after dependencies, and b) don't use dependencies unless you really need output-format-independent imports.

I made a first batch of changes. Where should I put the new information? I think it could be confusing to do so where initiaizers are introduced. Maybe where options.dependencies is?

[hildjj]

Yes, that sounds right. I think once you get that change done, I'm ready to merge. Do we have opinions about if this is worth a minor version number change?

[jaubourg]

Do we have opinions about if this is worth a minor version number change?

None.

[hildjj]

semver.org says "MINOR version when you add functionality in a backwards compatible manner", which this is, so I think yes. Let's wait a few days before doing a release to see if we can get the rollup change in also -- unless you have an emergent need for a release, @jaubourg ?

[jaubourg]

semver.org says "MINOR version when you add functionality in a backwards compatible manner", which this is, so I think yes. Let's wait a few days before doing a release to see if we can get the rollup change in also -- unless you have an emergent need for a release, @jaubourg ?

Nope, take your time.

I did the dependencies bit as best as I could and rebased the PR (we were touching the same lines in the docs). I took the opportunity to fix a typo and back-port the "es" format where it belongs in documentation.html.