Also add a "core modules" section to the API reference

[masak]

Because, as soon as we have modules/imports, and as soon as we have some kind of language-extending pragmas, they're going to be in modules, modules that we'll want to describe.

I think there might be around syntax-extending 20 modules to describe among the issues.

[masak]

I had some time to spare today, so I put together a list. I kinda like the result.

I've also marked in bold the ones needed for #324. Seems like a good place to start.

Operators

• syntax.op.assign (#152)
• syntax.op.incdec (#122)
• syntax.op.conditional (#163)
• syntax.op.reduce (#176)
• syntax.op.safenav (#229)
• syntax.op.amb (#13)
• syntax.op.capture (#237)
• syntax.op.bitwise.c (#461)
• syntax.op.bitwise.p6 (#461)
• syntax.op.arrayconcat (#465)
• syntax.op.xor (#464)
• syntax.op.ff (#207)
• syntax.op.delete (#290)
• syntax.op.exists (#292)

Terms

• syntax.term.hex (#283)
• syntax.term.do (#200)

Methods

• syntax.method.assign (#203)
• syntax.method.chaining (#221)
• syntax.method.unbound (#202, #248)

Statements

• syntax.stmt.unless
• syntax.stmt.until
• syntax.stmt.given
• syntax.stmt.gather (#241)
• syntax.stmt.with (#156)
• syntax.stmt.modifier (#165)
• syntax.stmt.repeat (#160)
• syntax.stmt.loop (#280)
• syntax.stmt.once (#327)
• syntax.stmt.goto (#509)
• syntax.stmt.label (#509)

Parameters

• syntax.param.optional (#112)
• syntax.param.default (#112)
• syntax.param.rest (#112)

Destructuring

• syntax.destructure (#306)
  • syntax.expr.destructure
  • syntax.param.destructure

Spreads

• syntax.spread
  • syntax.call.spread
  • syntax.array.spread
  • syntax.dict.spread

Functions

• syntax.func.generator
• syntax.func.arrow.p6 (#215)
• syntax.func.arrow.js (#215)

Arrays

• syntax.array.slice (#291)

Junctions (and each)

• syntax.junction (#210)
• syntax.each (#158)

Loop control

• syntax.loop.previous (#186)
• syntax.loop.changed (#211)

Misc

• swap (#218)
• range
• typing (#33)
• syntax.str.template (#134)
• test (#417)
• codegen (#145)

[masak]

Oh, what the heck. Let's go all-out on this one.

The "cheating" referred to in #324 can be extended to all of the core modules in the list in this issue. Let's cheat everywhere in the short run.

This will have two advantages:

1. 007 will (externally) have more of its true shape. We can write more idiomatic programs using the core modules. It's good early feedback.

2. Even though it will increase technical debt considerably, it will also create a kind of "pressure" pushing us to do these modules natively, using pure 007.

[masak]

All of the above modules are fairly orthogonal (to the extent grammar-modifying modules ever are orthogonal), expect for syntax.stmt.modifier. Conceivably, you'd get "all" of the statement keywords as modifiers by importing this module. But "all" isn't well-defined in a language where the statement keywords form an open set! Uh-oh.

So, do we:

• Only import the "core" ones? (Boring! And then I could never do next unless condition();.)

• Only import the ones in scope at the time of the import? (So you'd better import syntax.stmt.modifier late, or else.)

• Import all of them, somehow — maybe with a reliable syntax transform — kind of in analogy with #152?

I feel the last one, if we can pull it off, is the nicest one. But it'd require some more design.

[masak]

Coming back to this issue, it's pretty clear there was a bit of a "pressure valve" being released here; the issue started out talking about just documenting all of our modules, but it's also helped along the way to bring into focus that 007 will have all these modules in the first place, and that much of the development focus will go into them.

https://github.com/masak/007/issues/401#issuecomment-465883705 is a course correction, but I want to make it clear that it's (way) out of scope of the issue itself, which is still about documenting the modules. Work-wise, I'd say this can happen any time after the completion of #385.

Adding the "currently-blocked" label to indicate that we're still waiting for #385.

[masak]

I think there might be around syntax-extending 20 modules to describe among the issues.

48, at last count.