This change restructures the source code to the Go RiveScript library to make a few useful things exported and to clean up clutter from the root of the git repo.
Reasons for the Refactor
Expose the RiveScript Parser and Abstract Syntax Tree to third party developers via a standalone exported package: rivescript-go/parser. The AST even supports JSON marshalling! :confetti_ball:
Give a better name to the JavaScript object macro: lang/rivescript_js is renamed to lang/javascript and may be shortly joined by packages like lang/python :wink:
Make the code slightly easier to work with and extend, and make room for experimenting with Python or other object macro handlers. The eventual goal here is that the Go version of RiveScript can be the most OP version with support for Python, JavaScript, Perl, Ruby, and whatever other languages I can get working with Go.
:warning: Breaking Changes :warning:
The import path to the JavaScript macro handler has changed to a better name:
The correct import path now is github.com/aichaos/rivescript-go/lang/javascript for the JavaScript handler.
The Parser and AST
I wanted to make the RiveScript parser exported as its own stand-alone Go package, and I succeeded: github.com/aichaos/rivescript-go/parser
This required renaming the internal data structures for the Abstract Syntax Tree (AST), so that all of the AST types are exported so that they're useful to the parser package.
Previously, the AST types all had lowercased (non-exported) names, for my own sanity, so I don't have to keep track of when to use capital letters and when not to. I created the file src/astmap.go for internal use of the AST; it has all the same types as the exported AST except with private names, and the parser code in the main RiveScript package translates data from the exported AST to the private one. I'll let the docs in astmap.go speak for themselves:
For my own sanity while programming the code, these structs mirror the data
in the 'ast' subpackage but uses non-exported fields for the bot's own use.
The logic is as follows:
The parser subpackage becomes a stand-alone Go module that third party
developers can use to make their own applications around the RiveScript
scripting language itself. To that end, it exports a public AST tree.
In RiveScript's parse() function, it uses the public parser package and
gets back an AST tree full of exported fields. It doesn't need these fields
to be exported, and it copies them into internal fields of similar names.
I don't want to use the exported AST names directly because it makes the
code become a Russian Roulette of capital or non-capital names.
An example of how unwieldy the code would be if I use the direct AST types:
If the ast package structs are updated, update the mappings in this package too.
Changes
Moved the bulk of the RiveScript implementation code into the src/ subpackage, and in its old place created a very light wrapper around the implementation.
The src/ package still exports all the same stuff, but with big warnings to devs not to use the src package directly. (It has to export everything or else the wrapper couldn't work right).
The wrapper package becomes the Source of Truth for the public/official API and documentation.
The package path to the JavaScript handler is changed as above.
Added public facing external packages for the parser, AST, and object macro interface.
Added Changes.md to keep track of change notifications.
This change restructures the source code to the Go RiveScript library to make a few useful things exported and to clean up clutter from the root of the git repo.
Reasons for the Refactor
rivescript-go/parser. The AST even supports JSON marshalling! :confetti_ball:lang/rivescript_jsis renamed tolang/javascriptand may be shortly joined by packages likelang/python:wink::warning: Breaking Changes :warning:
The import path to the JavaScript macro handler has changed to a better name:
The correct import path now is
github.com/aichaos/rivescript-go/lang/javascriptfor the JavaScript handler.The Parser and AST
I wanted to make the RiveScript parser exported as its own stand-alone Go package, and I succeeded:
github.com/aichaos/rivescript-go/parserThis required renaming the internal data structures for the Abstract Syntax Tree (AST), so that all of the AST types are exported so that they're useful to the parser package.
Previously, the AST types all had lowercased (non-exported) names, for my own sanity, so I don't have to keep track of when to use capital letters and when not to. I created the file
src/astmap.gofor internal use of the AST; it has all the same types as the exported AST except with private names, and the parser code in the main RiveScript package translates data from the exported AST to the private one. I'll let the docs inastmap.gospeak for themselves: