SSD - Simple Service Description
ATTENTION: BREAKING CHANGES!
As long as the create version is below 1.0.0, breaking changes are to be expected.
Breaking changes so far:
| Version | Change |
|---|---|
| 0.8.0 | I changed the syntax from handles to fn and the field from handlers to functions |
| 0.9.0 | Rename crate to ssd |
| 0.10.0 | Move AST to separate crate for use in wasm plugins |
| 0.11.0 | Restrict places where comments can appear. This simplifies auto-formatting. |
| 0.12.0 | Rename SsdcFile to SsdFile so it matches the project name |
Features
- Custom description language (basics are done, but some things are still missing)
- Run RHAI scripts to generate output
- Run WASM plugins to generate output
- Auto format
- Basic sanity checks
Data Specification
It's mostly "what you see is what you get", as seen here:
- data/test.svc to see what the description language looks like.
Only restriction for now, is that auto-format will always put comments before the element right after. This means the following
data Test {
a: i32, /// test
b: i32,
}
will get formatted to:
data Test {
a: i32,
/// test
b: i32,
}
You can check out the files:
- generators/cpp-like.rhai to see what a generator could look like.
- generators/cpp-like.rhai.tym to see what a typemapping file looks like.
- generators/simple.hbs to see what a simple handlebars template looks like.
- generators/simple.lqd to see what a simple liquid template looks like.
- generators/simple.tera to see what a simple tera template looks like.
- generators/wasm-example/README.md to see what a simple generator in rust (wasm) looks like.
Install
cargo install --locked ssd
Usage
General
➜ ssd help
Simple Service Description & Code Generator
Usage: ssd [COMMAND]
Commands:
debug Print debug representation of the parsed file
generate Generate source code
rhai-metadata Print script engine metadata (function definitions, etc.) as json
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
Generate
➜ ssd generate help
Generate source code
Usage: ssd generate <COMMAND>
Commands:
rhai Use a rhai based generator
handlebars Use a handlebars based template. https://handlebarsjs.com/
tera Use a tera based template. https://tera.netlify.app/
liquid Use a liquid based templates. https://shopify.github.io/liquid/
wasm Use a wasm based generator
data Output as serialized data for external use
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
Rhai
➜ ssd generate rhai --help
Use a rhai based generator
Usage: ssd generate rhai [OPTIONS] <SCRIPT> <FILE>
Arguments:
<SCRIPT>
The script to use to generate the file
<FILE>
which file to use
Options:
-d, --debug
Enables debug mode (print and debug function in the script)
--no-map
do not use type mappings
--typemap <TYPEMAP>
A file containing type mappings.
If a file with the same name as the script file, but with the extension tym, it will be used automatically. e.g.: If there is a file
`/generator/script.rhai` and a corresponding `/generator/script.tym`, it will get used automatically.
-o, --out <OUT>
The file which should get written with the output from the generator
-h, --help
Print help information (use `-h` for a summary)
Handlebars
Alias: ssd generate hbs
➜ ssd generate handlebars --help
Use a handlebars based template. https://handlebarsjs.com/
Usage: ssd generate handlebars [OPTIONS] <TEMPLATE> <FILE>
Arguments:
<TEMPLATE>
The template to use to generate the file
<FILE>
which file to use
Options:
--no-map
do not use type mappings
--typemap <TYPEMAP>
A file containing type mappings.
If a file with the same name as the script file, but with the extension tym, it will be used automatically. e.g.: If there is a file
`/generator/script.rhai` and a corresponding `/generator/script.tym`, it will get used automatically.
-o, --out <OUT>
The file which should get written with the output from the generator
-h, --help
Print help (see a summary with '-h')
Tera
➜ ssd generate tera --help
Use a tera based template. https://tera.netlify.app/
Usage: ssd generate tera [OPTIONS] <TEMPLATE_DIR> <TEMPLATE_NAME> <FILE>
Arguments:
<TEMPLATE_DIR> Glob path for where to search for templates
<TEMPLATE_NAME> The template to use to generate the file
<FILE> which file to use
Options:
--typemap <TYPEMAP> A file containing type mappings
-o, --out <OUT> The file which should get written with the output from the generator
-h, --help Print help
Liquid
Alias: ssd generate lqd
➜ ssd generate liquid --help
Use a liquid based templates. https://shopify.github.io/liquid/
Usage: ssd generate liquid [OPTIONS] <TEMPLATE> <FILE>
Arguments:
<TEMPLATE>
The template to use to generate the file
<FILE>
which file to use
Options:
--no-map
do not use type mappings
--typemap <TYPEMAP>
A file containing type mappings.
If a file with the same name as the script file, but with the extension tym, it will be used automatically. e.g.: If there is a file
`/generator/script.rhai` and a corresponding `/generator/script.tym`, it will get used automatically.
-o, --out <OUT>
The file which should get written with the output from the generator
-h, --help
Print help (see a summary with '-h')
Wasm
➜ ssd generate wasm --help
Use a wasm based generator
Usage: ssd generate wasm [OPTIONS] <WASM> <FILE>
Arguments:
<WASM>
The wasm plugin to use to generate the file
<FILE>
which file to use
Options:
--no-map
do not use type mappings
--typemap <TYPEMAP>
A file containing type mappings.
-o, --out <OUT>
The file which should get written with the output from the generator
-h, --help
Print help (see a summary with '-h')
To test it out you can use the following command:
ssd generate rhai generators/cpp-like.rhai data/test.svc