Updates explanation of modules #369
Conversation
| For an inner module, it also includes the modules previously made available by the enclosing | ||
| module (via `import` or `module`). | ||
| * The macro table and symbol table are empty. | ||
| Before any clauses of the module definition are examined, each of these is empty. |
There was a problem hiding this comment.
The modules bindings does not contain $ion or _?
| (clause_N /*...*/)) | ||
| ``` | ||
|
|
||
| In Ion v1.1, there are three supported directive operations: |
There was a problem hiding this comment.
nit
| In Ion v1.1, there are three supported directive operations: | |
| In Ion 1.1, there are three supported directive operations: |
| (import | ||
| bar // Binding | ||
| "com.example.bar" // Module name | ||
| 2) // Module version |
There was a problem hiding this comment.
Version can be omitted here, too, and defaults to 1?
| ```ion | ||
| $ion:: | ||
| (import | ||
| bar // Binding |
There was a problem hiding this comment.
Can you use _ as a binding here?
| For example, consider this encoding directive: | ||
| ```ion | ||
| $ion:: | ||
| (encoding |
There was a problem hiding this comment.
I think we can simplify things both in terms of implementations and also in terms of mental model if we say that the encoding directive cannot create new bindings—it can only specify an ordering of existing bindings.
| (:mod_b::bar) // ERROR: `mod_b` is not in the encoding module sequence | ||
| ``` | ||
|
|
||
| ## Default module |
There was a problem hiding this comment.
To help distinguish it more from "Default encoding module sequence"
| ## Default module | |
| ## The default module |
| // `mod_b` is now available | ||
|
|
||
| $ion:: | ||
| (encoding mod_a) |
There was a problem hiding this comment.
Does this remove _ from the active modules?
| ) | ||
| ``` | ||
|
|
||
| The only exception to this rule is at the top level; stream-level bindings can be redefined. |
There was a problem hiding this comment.
In other words, stream level bindings are mutable (in some sense) whereas anything inside of a module is immutable.
| @@ -4,7 +4,7 @@ Shared modules exist independently of the documents that use them. | |||
| They are identified by a _catalog key_ consisting of a string name and an integer version. | |||
|
|
|||
| The self-declared catalog-names of shared modules are generally long, since they must be more-or-less globally unique. | |||
| When imported by another module, they are given local symbolic names by import declarations. | |||
| When imported by another module, they are given local symbolic names (a "binding") by import declarations. | |||
There was a problem hiding this comment.
Italicize to indicate that it's a technical term that is (or will be) in the glossary.
| When imported by another module, they are given local symbolic names (a "binding") by import declarations. | |
| When imported by another module, they are given local symbolic names (a _binding_) by import declarations. |
| ``` | ||
|
|
||
| Local modules inherit their spec version from the enclosing scope. | ||
| Unlike shared modules, local modules have no content version. |
There was a problem hiding this comment.
I think that the local modules chapter should come before the shared modules chapter, so this might seem out of place to some readers.
Issue #, if available:
Description of changes:
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.