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 (Implement +=, *= and all the other assignment operators #152)
• syntax.op.incdec (Implement postfix:<++> and postfix:<--> #122)
• syntax.op.conditional (Implement conditional/ternary/trinary operator (?? !!) as an 'is parsed' macro #163)
• syntax.op.reduce (Introduce reduce metaops #176)
• syntax.op.safenav (Implement safe navigation/null-coalescing operator #229)
• syntax.op.amb (Make it possible to define the amb declarator #13)
• syntax.op.capture (Make a <( ... )> term that can make the value of a whole expression the value of a subexpression #237)
• syntax.op.bitwise.c (Introduce bitwise operators (in a module) #461)
• syntax.op.bitwise.p6 (Introduce bitwise operators (in a module) #461)
• syntax.op.arrayconcat (Provide infix:<++> for array concatenation (in a module) #465)
• syntax.op.xor (Implement infix:<^^> (in a module) #464)
• syntax.op.ff (Implement infix:<ff> and family #207)
• syntax.op.delete (Implement a prefix:<delete> macro #290)
• syntax.op.exists (Implement a prefix:<exists> operator #292)

Terms

• syntax.term.hex (Hexadecimal integers #283)
• syntax.term.do (Provide a do term, which allows you to inject a statement into an expression #200)

Methods

• syntax.method.assign (Implement postfix:<.=> mutating method call #203)
• syntax.method.chaining (Implement Smalltalk-style method chaining syntax #221)
• syntax.method.unbound (Language support for unbound methods #202, Implement Python-style bound methods #248)

Statements

• syntax.stmt.unless
• syntax.stmt.until
• syntax.stmt.given
• syntax.stmt.gather (Make a gather/take construct #241)
• syntax.stmt.with (Implement a with statement macro #156)
• syntax.stmt.modifier (Implement statement modifiers as syntax macros #165)
• syntax.stmt.repeat (Implement a 'repeat while' macro #160)
• syntax.stmt.loop (Create a 'loop' macro #280)
• syntax.stmt.once (Implement the 'once' block macro #327)
• syntax.stmt.goto (Implement labels and goto #509)
• syntax.stmt.label (Implement labels and goto #509)

Parameters

• syntax.param.optional (Make it possible to switch on optional parameters/parameter defaults/rest parameters #112)
• syntax.param.default (Make it possible to switch on optional parameters/parameter defaults/rest parameters #112)
• syntax.param.rest (Make it possible to switch on optional parameters/parameter defaults/rest parameters #112)

Destructuring

• syntax.destructure (Variable and parameter destructuring #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 (Implement ES6-style arrow functions  #215)
• syntax.func.arrow.js (Implement ES6-style arrow functions  #215)

Arrays

• syntax.array.slice (Implement Python's slice syntax instead of .slice and .splice #291)

Junctions (and each)

• syntax.junction (Implement junctions as syntactic constructs through inside-out macros #210)
• syntax.each (Implement each() macro #158)

Loop control

• syntax.loop.previous (Lagging loop variables #186)
• syntax.loop.changed (Make a changed(somevar) macro for loops #211)

Misc

• swap (Implement a swap macro #218)
• range
• typing (Implement type checking, orthogonally to everything else #33)
• syntax.str.template (ES6-style template literals #134)
• test (Build a testing module #417)
• codegen (Expose control flow as an API #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 Implement +=, *= and all the other assignment operators #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.

#401 (comment) 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.