Package: py-ssd
SSD - Simple Service & Data DescriptionAbout - What is SSD?First and foremost it's supposed to be data format for describing data structures and services.
Additionally it provides tooling to work with the aforementioned format, which simplifies writing custom code generators.History - Why did I make this?In one of the companies I was working we programmed in Delphi and we had a bunch of structs that needed to
be serialized. In order to serialize stuff in Delphi you need build the objects manually,
which was really error prone and annoying to work with. So I wrote a small (closed source)
code generator usingD,SDLangand a template engine.After a few months it was clear, that the template engine made certain things way harder to maintain and reason
about. Which is why I decided to rewrite the whole thing in C#. This time I used a custom parser to allow for more
streamlined data files and I built the generator in a way, that the actual code generation would be done through
C# DLLs. This way you could still use a template engine if you want by embedding it into a DLL and using that.I was even allowed to open source everything except the custom code generation plugin we used internally.
The source code can be found here:https://github.com/hardliner66/codegeneratorI was still not really satisfied, as using the codegen in a cross platform way was still tricky and require mono.
After some time I was starting to use rust more and found out about webassembly,
which is what motivated me to start a third attempt. This time the goal was to allow plugins to be written in wasm,
to allow people to write their generators in whatever language they're comfortable with.I called the project SSDCG first, which stood forSimpleService andData description format andCodeGenerator. But the name was kinda hard to remember and the focus was always more on the unified data description
language, with the code generation being something that was the main use case for that language.The project has already outgrown it's initial goal by supporting not only WASM,
but also Rhai (script language) and three different template engines, that can all work with the same unified data
model. Once your model is written, you can choose whatever technology fits your need the best to generate whatever
you want out from the model.The data format also evolved quite a bit from the older versions and supports describing DataTypes, Enums, Imports,
Services with functions and events, as well as custom attributes on all of these to allow for even more customization.
It's modelled to be similar to a simplified rust, because I personally like the syntax quite a bit and it was a
natural choice, as the whole thing is written in rust itself as well.ATTENTION: BREAKING CHANGES!As long as the crate version is below 1.0.0, breaking changes are to be expected.Breaking changes so far:VersionChange0.8.0I changed the syntax fromhandlestofnand the field fromhandlerstofunctions0.9.0Rename crate to ssd0.10.0Move AST to separate crate for use in wasm plugins0.11.0Restrict places where comments can appear. This simplifies auto-formatting.0.12.0Rename SsdcFile to SsdFile so it matches the project name0.13.0Doc-Comments are now officially part of the exposed data.0.14.0Remove liquid templates to simplify the code and remove code duplication. Tera seems close enough anyway.0.15.0Put Ron behind a feature gate, as I already had some problems with it before and provide rsn (similar format) instead.0.16.0Change representation of properties from indexmap to vec of tuple.0.17.0RenamedSsdFiletoSsdModule. Removedwasmandterafrom the default features.FeaturesCustom description language (basics are done, but some things are still missing)ImportsDataTypesEnumsServicesCustom AttributesThese can be used to implement custom features that are missing from the languageSome features will get added later, others will always rely on attributes, because they aren't generic enoughListsFixed Size (property: 5 of u8)Dynamic Size (property: list of u8)GenericsAuto formatScript LanguagesRhaiPython through PyO3Template EnginesHandlebarsTeraWasm (throughextism)Data Export for use with other tools (JSON, Yaml, Toml)Use raw data (JSON, Yaml, Toml, Rsn) instead of predefined ssd formatThis allows the same tool to be used, even when working with data from somewhere elseBasic sanity checksCargo Featuresdefaultiswasm,tera,handlebarsteraenables support for tera templateshandlebarsenables support for handlebars templateswasmenables support for wasm pluginsronenables support forronallenables everythingData SpecificationIt's mostly "what you see is what you get", as seen here:data/test.svcto 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 followingdata Test {
    a: i32, /// test
    b: i32,
}will get formatted to:data Test {
    a: i32,
    /// test
    b: i32,
}Test it outTo test it out, install the command, clone the repository and use the following command:ssdgeneraterhaiexample-generators/cpp-like.rhaidata/test.svcExamplesYou can check out the files:example-generators/cpp-like.rhaito see what a generator could look like.example-generators/cpp-like.rhai.tymto see what a typemapping file looks like.example-generators/simple.hbsto see what a simple handlebars template looks like.example-generators/simple.terato see what a simple tera template looks like.example-generators/wasm-example/README.mdto see what a simple generator in rust (wasm) looks like.InstallEither install through cargo:cargoinstall--lockedssdor download pre-built package fromreleases page.UsageGeneral➜ssdhelpSimpleServiceDescription

Usage:ssd[COMMAND]Commands:debugPrintdebugrepresentationoftheparsedfileprettyPrettyprinttheparsedfilegenerateGeneratesourcecodehelpPrintthismessageorthehelpofthegivensubcommand(s)Options:-h,--helpPrinthelpGenerate➜ssdgeneratehelpGeneratesourcecode

Usage:ssdgenerate<COMMAND>

Commands:rhaiUsearhaibasedgeneratorhandlebarsUseahandlebarsbasedtemplate.https://handlebarsjs.com/teraUseaterabasedtemplate.https://tera.netlify.app/wasmUseawasmbasedgeneratordataOutputasserializeddataforexternalusehelpPrintthismessageorthehelpofthegivensubcommand(s)Options:-h,--helpPrinthelpRhai➜ssdgeneraterhai--help
Usearhaibasedgenerator

Usage:ssdgeneraterhai[OPTIONS]<SCRIPT><FILE>

Arguments:<SCRIPT>Thescripttousetogeneratethefile<FILE>whichfiletouse

Options:-d,--debugEnablesdebugmode(printanddebugfunctioninthescript)--no-mapdonotusetypemappings--typemap<TYPEMAP>Afilecontainingtypemappings.Ifafilewiththesamenameasthescriptfile,butwiththeextensiontym,itwillbeusedautomatically.e.g.:Ifthereisafile`/generator/script.rhai`andacorresponding`/generator/script.tym`,itwillgetusedautomatically.-r,--rawuserawdatafileasinputinsteadofthessddataformat-o,--out<OUT>Thefilewhichshouldgetwrittenwiththeoutputfromthegenerator-h,--helpPrinthelp(seeasummarywith'-h')HandlebarsAlias:ssd generate hbs➜ssdgeneratehandlebars--help
Useahandlebarsbasedtemplate.https://handlebarsjs.com/

Usage:ssdgeneratehandlebars[OPTIONS]<TEMPLATE><FILE>

Arguments:<TEMPLATE>Thetemplatetousetogeneratethefile<FILE>whichfiletouse

Options:--no-mapdonotusetypemappings--typemap<TYPEMAP>Afilecontainingtypemappings.Ifafilewiththesamenameasthescriptfile,butwiththeextensiontym,itwillbeusedautomatically.e.g.:Ifthereisafile`/generator/script.rhai`andacorresponding`/generator/script.tym`,itwillgetusedautomatically.-r,--rawuserawdatafileasinputinsteadofthescddataformat-o,--out<OUT>Thefilewhichshouldgetwrittenwiththeoutputfromthegenerator-h,--helpPrinthelp(seeasummarywith'-h')Tera➜ssdgeneratetera--help
Useaterabasedtemplate.https://tera.netlify.app/

Usage:ssdgeneratetera[OPTIONS]<TEMPLATE_DIR><TEMPLATE_NAME><FILE>

Arguments:<TEMPLATE_DIR>Globpathforwheretosearchfortemplates<TEMPLATE_NAME>Thetemplatetousetogeneratethefile<FILE>whichfiletouse

Options:--no-mapdonotusetypemappings--typemap<TYPEMAP>Afilecontainingtypemappings.Ifafilewiththesamenameasthescriptfile,butwiththeextensiontym,itwillbeusedautomatically.e.g.:Ifthereisafile`/generator/script.rhai`andacorresponding`/generator/script.tym`,itwillgetusedautomatically.-r,--rawuserawdatafileasinputinsteadofthescddataformat-o,--out<OUT>Thefilewhichshouldgetwrittenwiththeoutputfromthegenerator-h,--helpPrinthelp(seeasummarywith'-h')Wasm➜ssdgeneratewasm--help
Useawasmbasedgenerator

Usage:ssdgeneratewasm[OPTIONS]<WASM><FILE>

Arguments:<WASM>Thewasmplugintousetogeneratethefile<FILE>whichfiletouse

Options:--no-mapdonotusetypemappings--typemap<TYPEMAP>Afilecontainingtypemappings.Ifafilewiththesamenameasthescriptfile,butwiththeextensiontym,itwillbeusedautomatically.e.g.:Ifthereisafile`/generator/script.rhai`andacorresponding`/generator/script.tym`,itwillgetusedautomatically.-r,--rawuserawdatafileasinputinsteadofthescddataformat-o,--out<OUT>Thefilewhichshouldgetwrittenwiththeoutputfromthegenerator-h,--helpPrinthelp(seeasummarywith'-h')Python / PyO3Install through pip:pip3installpy_ssdUsage>>>importpy_ssd>>>model=py_ssd.parse_file(".","./data/test.svc")[src/parser.rs:509]key="Rect"# the namespace is generated from the file path (second parameter),# with the base path removed (first parameter)>>>model['namespace']{'components':['data','test']}>>>model['data_types'].keys()dict_keys(['Rect'])>>>model['data_types']['Rect']['properties']['x']{'typ':{'components':['i32']},'attributes':[{'name':{'components':['test']},'parameters':[]}],'comments':[]}