Bruce/nomsu
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Added hyperlinks to files mentioned in the README.

Browse Source
This commit is contained in:
Bruce Hill 2018-08-29 13:55:39 -07:00
parent 5ee9bcb7fb
commit af5ca18fc3
1 changed files with 23 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
README.md
View File

@ -16,7 +16,7 @@ Nomsu's only dependencies are [Lua 5.2+](https://www.lua.org/) or [Luajit 2.0+](
## Examples
There's a more complete set of example code in `examples/how_do_i.nom`, but roughly, Nomsu looks like:
There's a more complete set of example code in [examples/how\_do\_i.nom](src/master/examples/how_do_i.nom), but roughly, Nomsu looks like:
```
say "Hello"
@ -44,36 +44,36 @@ If you enjoy Nomsu so much that you'd like to tinker with it or have it in your
All `.moon` files have been precompiled into corresponding `.lua` files, so you don't need to have [Moonscript](http://moonscript.org/) installed to run the Nomsu compiler.
* `nomsu` - A shell script that selects between different installed versions of Nomsu (using the `-V` flag). You can use this script to, for example, run `nomsu -V 1.2 your_script.nom` to run with the latest version of Nomsu that matches `1.2.?.?`. All flags and arguments are passed along to whichever Nomsu compiler is chosen.
* `nomsu.moon` - The source code for the Nomsu command line runner. This handles launching the compiler and running the REPL.
* [nomsu](src/master/nomsu) - A shell script that selects between different installed versions of Nomsu (using the `-V` flag). You can use this script to, for example, run `nomsu -V 1.2 your_script.nom` to run with the latest version of Nomsu that matches `1.2.?.?`. All flags and arguments are passed along to whichever Nomsu compiler is chosen.
* [nomsu.moon](src/master/nomsu.moon) - The source code for the Nomsu command line runner. This handles launching the compiler and running the REPL.
* `nomsu.*.peg` - The [Parsing Expression Grammar](https://en.wikipedia.org/wiki/Parsing_expression_grammar) used to define each version of Nomsu's syntax. The format of this file is a slightly modified version of the format accepted by LPEG's `re` module.
* `nomsu_compiler.moon` - **The actual Nomsu compiler**. This file can be imported and used without going through the regular command line interface (e.g. for applications that want to embed the compiler).
* `parser.moon` - The Nomsu parser. This file can also be imported and used directly for applications that only need to *parse* Nomsu, not compile it.
* `syntax_tree.moon` - Datastructures used for Nomsu Abstract Syntax Trees.
* `code_obj.moon` - Datastructures used for incrementally building generated code, while preserving code origins.
* `error_handling.moon` - The logic for producing good error messages within Lua that reference the Nomsu source code that led to them.
* `utils.lua` - A set of utility actions used by nomsu.moon.
* `uuid.lua` - A simple Universally Unique Identifier implementation (RFC 4122) used internally to give each object a randomized unique ID.
* `consolecolors.lua` - Lua module that defines ANSI color codes for colored console output (used internally in nomsu.moon).
* `examples/how_do_i.nom` - A simple walkthrough of some of the features of Nomsu, written in Nomsu code. **This is a good place to start.**
* `core/*.nom` - Core language definitions of stuff like control flow, operators, and metaprogramming, broken down into different files.
* `lib/*.nom` - Optional language libraries for stuff you might want, like interfacing with the OS, or doing Object Oriented Programming.
* `compatibility/*.nom` - Code for automatically upgrading Nomsu code from old versions to the current version.
* `tools/*.nom` - A set of utilities useful for doing code manipulation actions.
* `Makefile` - Rules for building/installing the compiler.
* `LICENSE` - The software license (MIT).
* `README.md` - This file.
* [nomsu\_compiler.moon](src/master/nomsu_compiler.moon) - **The actual Nomsu compiler**. This file can be imported and used without going through the regular command line interface (e.g. for applications that want to embed the compiler).
* [parser.moon](src/master/parser.moon) - The Nomsu parser. This file can also be imported and used directly for applications that only need to *parse* Nomsu, not compile it.
* [syntax\_tree.moon](src/master/syntax_tree.moon) - Datastructures used for Nomsu Abstract Syntax Trees.
* [code\_obj.moon](src/master/code_obj.moon) - Datastructures used for incrementally building generated code, while preserving code origins.
* [error\_handling.moon](src/master/error_handling.moon) - The logic for producing good error messages within Lua that reference the Nomsu source code that led to them.
* [utils.lua](src/master/utils.lua) - A set of utility actions used by nomsu.moon.
* [uuid.lua](src/master/uuid.lua) - A simple Universally Unique Identifier implementation (RFC 4122) used internally to give each object a randomized unique ID.
* [consolecolors.lua](src/master/consolecolors.lua) - Lua module that defines ANSI color codes for colored console output (used internally in nomsu.moon).
* [examples/how\_do\_i.nom](src/master/examples/how_do_i.nom) - A simple walkthrough of some of the features of Nomsu, written in Nomsu code. **This is a good place to start.**
* [core/\*.nom](src/master/core) - Core language definitions of stuff like control flow, operators, and metaprogramming, broken down into different files.
* [lib/\*.nom](src/master/lib) - Optional language libraries for stuff you might want, like interfacing with the OS, or doing Object Oriented Programming.
* [compatibility/\*.nom](src/master/compatibility) - Code for automatically upgrading Nomsu code from old versions to the current version.
* [tools/\*.nom](src/master/tools) - A set of utilities useful for doing code manipulation actions.
* [Makefile](src/master/Makefile) - Rules for building/installing the compiler.
* [LICENSE](src/master/LICENSE) - The software license (MIT).
* [README.md](src/master/README.md) - This file.
## Versioning
Nomsu uses the following versioning scheme: `[syntax version].[core library API version].[compiler internal API version].[lib/ API version]`. Which means:
* Any code that parses on `Nomsu X.a.b.c.d` will also parse on Nomsu `X.p.w.r.s`
* Any code that compiles on Nomsu `X.Y.a.b.c` will also compile on Nomsu `X.Y.p.q.r` and run without any differences, as long as it only depends on the behavior of the core library functions (i.e. stuff defined in `core/*.nom`), and doesn't mess with the compiler internals at all.
* Any code that compiles on Nomsu `X.Y.Z.a.b` will also compile on Nomsu `X.Y.Z.p.q` and run without any differences, even if it messes with the compiler internals, as long as it doesn't use anything from `lib/*.nom`.
* Any code that compiles on Nomsu `X.Y.Z.W` will also compile on any other Nomsu `X.Y.Z.W` and run without any differences, even if it uses stuff from `lib/*.nom`.
* Any code that compiles on Nomsu `X.Y.a.b.c` will also compile on Nomsu `X.Y.p.q.r` and run without any differences, as long as it only depends on the behavior of the core library functions (i.e. stuff defined in [core/\*.nom](src/master/core)), and doesn't mess with the compiler internals at all.
* Any code that compiles on Nomsu `X.Y.Z.a.b` will also compile on Nomsu `X.Y.Z.p.q` and run without any differences, even if it messes with the compiler internals, as long as it doesn't use anything from [lib/\*.nom](src/master/lib).
* Any code that compiles on Nomsu `X.Y.Z.W` will also compile on any other Nomsu `X.Y.Z.W` and run without any differences, even if it uses stuff from [lib/\*.nom](src/master/lib).
When Nomsu is istalled via `make install`, all of Nomsu's lua files and `core/*.nom` and `lib/*.nom` files are stored in `$PREFIX/lib/nomsu/$NOMSU_VERSION` and the Nomsu executable is installed to `$PREFIX/bin/nomsu$NOMSU_VERSION`, along with the file `nomsu` (the version-selection script), which goes to `$PREFIX/bin/nomsu`. When `make uninstall` is run, all those files are deleted (except for `nomsu`, if there are other versions installed).
When Nomsu is istalled via `make install`, all of Nomsu's lua files and [core/\*.nom](src/master/core) and [lib/\*.nom](src/master/lib) files are stored in `$PREFIX/lib/nomsu/$NOMSU_VERSION` and the Nomsu executable is installed to `$PREFIX/bin/nomsu$NOMSU_VERSION`, along with the file `nomsu` (the version-selection script), which goes to `$PREFIX/bin/nomsu`. When `make uninstall` is run, all those files are deleted (except for `nomsu`, if there are other versions installed).
To run different versions, use the `-V` flag, which will select the latest version matching the specified pattern. For example, if you have v1.0.0.0, v1.0.2.1, and 1.1.0.0 installed, then `nomsu` will run v1.1.0.0, `nomsu -V 1.0` will run v1.0.2.1, and `nomsu -V 1.0.0.0` will run v1.0.0.0.