module
name dk_ahnfelt_haxe_peg
version 1.1.0
license MIT
export
Grammar * # The Grammar type and all it's methods
Emitter (emit) # The Emitter type and it's emit method
Expression # The Expression type but none of it's methods
import
org_foo_regex (Pattern) # Import the Pattern type (and all methods) from org_foo_regex
org_bar_tool bartool # Import all from org_bar_tool and use bartool as prefix
com_example (X, Y) # Import X and Y from com_example
net_zoo 1.0 * # Import all from net_zoo version 1.0 or above
net_zar 1.0 2.0 * # Import all from net_zar, any version between 1.0 and 2.0 inclusive
description \
A Packrat parser generator for Parsing Expression Grammars
with actions written in Haxe.
contributors
Ahnfelt
name "Joakim Ahnfelt-Rønne"
email joakim.ahnfelt@gmail.com
url http://ahnfelt.dk
organization Foobar
role programmer
The above is an example of a module description file (OGDL serialization, UTF-8).
A module is a collection of files. Each file can contain zero or more symbol definitions, as well as local variables and functions.
A module exports zero or more symbols - only those who have been exported can be imported by other modules.
Imported symbols are visible in the whole module.
All symbols defined in a module is visible in the whole module.
Variables do not count as symbols, and only top level symbols are considered.
In a file system a module is represented by a directory with a module description file, and some optional directories:
mymoduledir/ # module directory
module.ogdl # module description file
main/ # main source file directory
Grammar.source
Emitter.source
test/ # unit test directory
Corner.source
Case.source
static/ # resource directory
icon.png
help.html
The static resources are available at runtime for read access.
Modules are supposed to be small and self contained, with as few dependencies as possible. It should be possible for one person to keep the details of an entire module in her head all at once. A medium sized project would typically involve dozens of it's own modules. There is no concept of sub modules, although the implied relation of x_y and x_y_z can be exploited in navigation.
Any tool that only needs basic information about a module only needs to parse the module file. In some cases it will be sufficient to simply show the configuration file, as it is fairly readable.
Since the matter of visibility is isolated to the module description file, there is no syntax to deal with this in source files. This means that there is no module declaration, no imports and no public/protected/private boilerplate in each source file.
Since several files in a package often needs the same imports, it also reduces the amount of repetition, as does the wildcard in the export (no need to declare each method public if they all are).
Modules should be treated as the unit of a dependency.
An automated tool for dependency management would only need to look at the imported module names and their version to discover the dependencies of a module. Multiple different versions should be usable by using different prefixes.
Online repositories could act as suppliers of modules (where the name and version is the key). They should be cached locally for efficiency and availability. The user should control which repositories she wants to use.
Modules may be signed by the authors - certificates for x.foo.org should be silently accepted for org_foo_x modules and those that are longer (although this is somewhat dangerous with shared hosting). The user can also manually add mappings from certificates to module names. In any other case it should be treated as if the module was not signed at all.
It might be possible to remove modules from the local cache automatically, but otherwise do it manually.
A package name matches the regular expression ^[a-z][a-z0-9]*(_[a-z][a-z0-9]*)+$ - ie. two or more lowercase identifiers separated by underscores. It's recommended that you use a domain name in your possession for the package name, or x_name where name is whatever you like.
A prefix must match the regular expression ^[a-z][a-z0-9]*$ - ie. be a lowercase identifier without underscores.
A type name must match the regular expression ^[A-Z][a-zA-Z0-9]$ - ie. use Camel Case (beginning with an uppercase letter) and contain no underscores.
Any other name must match the regular expression ^[a-z][a-zA-Z0-9]$ - ie. use Camel Case (beginning with a lowercase letter) and contain no underscores.
License should be the license type, not the complete license - that should be provided separately. The license type, which may be "other" (default), "MIT", "GPL", "BSD", "CCSA" etc. A full list of allowable values should be specified somewhere.
It's possible that a language should define a scripting language version, and that normal files could only contain declarations (ie. no side effects from loading such a file). Then the initialization could be concentrated in the script, eliminating the concern of what order to initialize in. If modules can't have circular dependencies, then the global initialization order is quite easy to figure out.
If the overall information is moved to the module description file, and modules are not huge, then doc comments can simply be a description - tags like @author etc. would already be covered, and @param, @return etc. rarely give more information than a good general description of the method anyway.
It's possible that the module description file should accept plugins - dependencies on external tools, and settings for these. For example, the unit tests could be a plugin, and maybe the dependency management tool. Maybe a webhost. Maybe active records. Who knows?