SushiScript 1.1.1

Library for converting .NET models to different script languages.

Install-Package SushiScript -Version 1.1.1
dotnet add package SushiScript --version 1.1.1
<PackageReference Include="SushiScript" Version="1.1.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add SushiScript --version 1.1.1
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Sushi

Library for converting .NET models to different script languages.

Use server-side classes / models in whatever script language you prefer!
Also generates javascript reference files:<br>
Intellisense preview

Developed by: Jeroen Vorsselman @ 2018<br>
GitHub LinkedIn

Main features

Main framework for generating script files.

  • Write inline code documentation to script
  • Customize templates and formatting
  • Extend by implementing your own script-language
  • Write to file (asynchronous)
  • Detect models to convert in assembly
    • By Interface or Attribute
      <br>
      <br>

Sushi.JavaScript

Implementation for generating JavaScript (EcmaScript) models.

  • EcmaScript V5 and V6
  • Isolated function-block
  • Complete JsDoc support
  • object parsing & validation
  • Class inheritance
    <br>
    <br>

Sushi.JavaScript

Implementation for generating TypeScript models.

  • Able to generate the latest TypeScript specification
  • Able to generate DefinitelyTyped declaration files
    • Use to improve autocomplete for Visual Studio Intellisense
  • Class inheritance
    <br>
    <br>

How to use

  1. Create an instance of the ConversionKernel and pass the assembly with the models to convert.
    • Invoke the LoadXmlDocumentation method to try and load the "PROJECT_NAMESPACE".xml file generated by the VS project.
  2. Create the ModelConverter instance for the requested script-language.
    • Default script-languages have a static method for doing this that are named as follows CreateConverterFor + script-language depending on what Sushi implementation is referenced.
  3. Invoke the Convert() method on the created ModelConverter instance.
    • Iterates through each found DataModel and compiles them.
    • The generated script string will be set on the DataModel.Script property.

Reading the generated script as a string:<br>
Simply invoke the ModelConverter.MergeModelsToString method and pass the converted IEnumerable&lt;DataModel&gt;.
This will iterate through the populated DataModel(s) and join its Script contents to one string.
<br>
<br>
Writing the generated script to a file:<br>
The ModelConverter.WriteToFile&#39;Async&#39; can be used to write the script contents to a file with a given name and path.
This method uses the ModelConverter.MergeModelsToString method internally to join the generated script(s) to one string.
<br>

PLEASE NOTE: The fileName argument does not include its extension. This is defined in the language-specification.

Minifying the generated script:<br>
Basic script minification is supported. This only removes return-newline(s), tabs, comments and leading-whitespaces.
This can be done in the ModelConverter.MergeModelsToString and ModelConverter.WriteToFile&#39;Async&#39; methods. Both have a minify:boolean argument.
<br>
<br>

Creating or modifing a script-language

Sushi contains two base-classes for defining a language, the LanguageSpecification and StatementPipeline.<br>
Directly linked to how certain placeholders in the template are generated so it can best be explained with including the placeholders.

Note: The keys are ALWAYS paired with the '$$' prefix and suffix.

KEY | USAGE | SUMMARY
--- | --- | ---
$$SUMMARY$$ | LanguageSpecification.FormatProperty | The summary doc for the specific PropertyInfo.
$$TYPENAME$$ | ModelConverter.Compile&gt;Replace | The name for the specific Type to compile.
$$TYPE_NAMESPACE$$ | ModelConverter.Compile&gt;Replace | The namespace for the specific Type to compile.
$$VALIDATE_OBJECT$$ | LanguageSpecification.FormatStatements | Placeholder for the Type properties validation.
$$DEFINE_PROPERTIES$$ | LanguageSpecification.FormatPropertyDefinition | Placeholder for the properties that should be defined.
$$SET_PROPERTY_VALUES$$ | LanguageSpecification.FormatProperty | Placeholder for the values that should be set.
$$DEFINED_CHECK$$ | StatementPipeline.ArgumentDefinedStatement | Statement if the Property is defined / has a value.
$$UNDEFINED_CHECK$$ | StatementPipeline.ArgumentUndefinedStatement | Statement if the Property is not defined / has no value.
$$ARGUMENT_NAME$$ | ModelConverter.Compile&gt;Replace | Placeholder for the argument of the object that should be used.
$$SCRIPT_MODELS$$ | ModelConverter.MergeModelsToString | Placeholder for the generated SCRIPT_MODELS. Mainly used for the LanguageSpecification.WrapTemplate.

Using another Template

It is really easy to use another template for generating script models. These templates can also be tested for missing template-keys.
<br>
<br>
How to use another template:

  1. Create an instance of the LanguageSpecification you want to use.
  2. Load the contents of the template into a string.
  3. Invoke LanguageSpecification.UseTemplate(fileContents).

Thats it! You're done. <br>

Testing the integrity of the template:<br>
The template can be checked for the amount of placeholders it uses. A template requires atleast one placeholder.<br>
The template won't be allowed to use if it has no contents or no placeholders.<br><br>
You can test the template if you invoke TemplateConsistency.TestTemplate(fileContents).
This will return the placeholder-keys that arent used by the template.

Wrapping the script models > V1.0.3

The generated script models can now be wrapped in custom code-blocks. <br>
A wrapper for AMD / Dependency Injection / Node and Self Invoking Anonymous Functions are available by default.<br>
You can always choose to use your own wrapper template. This can be done when you invoke LanguageSpecification.UseWrapTemplate.<br>
The method CreateConverterForJavaScript has a new Wrap enum argument that specifies what wrap to use. <br>

Note: A wrap template should always use the $$SCRIPT_MODELS$$ placeholder.
Also: It can use the $$TYPENAME$$ and $$TYPE_NAMESPACE$$ placeholders.

Change notes V1.1.0

  • Customize what data-type should be used for a given type.
  • Better handling for date values, now defaults to 0001-01-01.
    • An ISO 8601 value is always expected to be used.
  • Class instances are now created automatically in the code.
  • SPOT Javascript code, TS now is dependent on Sushi.JavaScript
  • Much better handling for referring other models.
  • Specific code for inheriting models removed, the properties are always generated by default.
  • Enums are not handled as convert-able objects because its not (yet) supported.
  • Fixed TS templates, used modules.
  • Models or testing are more realistic to the API view-models.
  • Fixed generated comments, now simple as it should be.

Sushi

Library for converting .NET models to different script languages.

Use server-side classes / models in whatever script language you prefer!
Also generates javascript reference files:<br>
Intellisense preview

Developed by: Jeroen Vorsselman @ 2018<br>
GitHub LinkedIn

Main features

Main framework for generating script files.

  • Write inline code documentation to script
  • Customize templates and formatting
  • Extend by implementing your own script-language
  • Write to file (asynchronous)
  • Detect models to convert in assembly
    • By Interface or Attribute
      <br>
      <br>

Sushi.JavaScript

Implementation for generating JavaScript (EcmaScript) models.

  • EcmaScript V5 and V6
  • Isolated function-block
  • Complete JsDoc support
  • object parsing & validation
  • Class inheritance
    <br>
    <br>

Sushi.JavaScript

Implementation for generating TypeScript models.

  • Able to generate the latest TypeScript specification
  • Able to generate DefinitelyTyped declaration files
    • Use to improve autocomplete for Visual Studio Intellisense
  • Class inheritance
    <br>
    <br>

How to use

  1. Create an instance of the ConversionKernel and pass the assembly with the models to convert.
    • Invoke the LoadXmlDocumentation method to try and load the "PROJECT_NAMESPACE".xml file generated by the VS project.
  2. Create the ModelConverter instance for the requested script-language.
    • Default script-languages have a static method for doing this that are named as follows CreateConverterFor + script-language depending on what Sushi implementation is referenced.
  3. Invoke the Convert() method on the created ModelConverter instance.
    • Iterates through each found DataModel and compiles them.
    • The generated script string will be set on the DataModel.Script property.

Reading the generated script as a string:<br>
Simply invoke the ModelConverter.MergeModelsToString method and pass the converted IEnumerable&lt;DataModel&gt;.
This will iterate through the populated DataModel(s) and join its Script contents to one string.
<br>
<br>
Writing the generated script to a file:<br>
The ModelConverter.WriteToFile&#39;Async&#39; can be used to write the script contents to a file with a given name and path.
This method uses the ModelConverter.MergeModelsToString method internally to join the generated script(s) to one string.
<br>

PLEASE NOTE: The fileName argument does not include its extension. This is defined in the language-specification.

Minifying the generated script:<br>
Basic script minification is supported. This only removes return-newline(s), tabs, comments and leading-whitespaces.
This can be done in the ModelConverter.MergeModelsToString and ModelConverter.WriteToFile&#39;Async&#39; methods. Both have a minify:boolean argument.
<br>
<br>

Creating or modifing a script-language

Sushi contains two base-classes for defining a language, the LanguageSpecification and StatementPipeline.<br>
Directly linked to how certain placeholders in the template are generated so it can best be explained with including the placeholders.

Note: The keys are ALWAYS paired with the '$$' prefix and suffix.

KEY | USAGE | SUMMARY
--- | --- | ---
$$SUMMARY$$ | LanguageSpecification.FormatProperty | The summary doc for the specific PropertyInfo.
$$TYPENAME$$ | ModelConverter.Compile&gt;Replace | The name for the specific Type to compile.
$$TYPE_NAMESPACE$$ | ModelConverter.Compile&gt;Replace | The namespace for the specific Type to compile.
$$VALIDATE_OBJECT$$ | LanguageSpecification.FormatStatements | Placeholder for the Type properties validation.
$$DEFINE_PROPERTIES$$ | LanguageSpecification.FormatPropertyDefinition | Placeholder for the properties that should be defined.
$$SET_PROPERTY_VALUES$$ | LanguageSpecification.FormatProperty | Placeholder for the values that should be set.
$$DEFINED_CHECK$$ | StatementPipeline.ArgumentDefinedStatement | Statement if the Property is defined / has a value.
$$UNDEFINED_CHECK$$ | StatementPipeline.ArgumentUndefinedStatement | Statement if the Property is not defined / has no value.
$$ARGUMENT_NAME$$ | ModelConverter.Compile&gt;Replace | Placeholder for the argument of the object that should be used.
$$SCRIPT_MODELS$$ | ModelConverter.MergeModelsToString | Placeholder for the generated SCRIPT_MODELS. Mainly used for the LanguageSpecification.WrapTemplate.

Using another Template

It is really easy to use another template for generating script models. These templates can also be tested for missing template-keys.
<br>
<br>
How to use another template:

  1. Create an instance of the LanguageSpecification you want to use.
  2. Load the contents of the template into a string.
  3. Invoke LanguageSpecification.UseTemplate(fileContents).

Thats it! You're done. <br>

Testing the integrity of the template:<br>
The template can be checked for the amount of placeholders it uses. A template requires atleast one placeholder.<br>
The template won't be allowed to use if it has no contents or no placeholders.<br><br>
You can test the template if you invoke TemplateConsistency.TestTemplate(fileContents).
This will return the placeholder-keys that arent used by the template.

Wrapping the script models > V1.0.3

The generated script models can now be wrapped in custom code-blocks. <br>
A wrapper for AMD / Dependency Injection / Node and Self Invoking Anonymous Functions are available by default.<br>
You can always choose to use your own wrapper template. This can be done when you invoke LanguageSpecification.UseWrapTemplate.<br>
The method CreateConverterForJavaScript has a new Wrap enum argument that specifies what wrap to use. <br>

Note: A wrap template should always use the $$SCRIPT_MODELS$$ placeholder.
Also: It can use the $$TYPENAME$$ and $$TYPE_NAMESPACE$$ placeholders.

Change notes V1.1.0

  • Customize what data-type should be used for a given type.
  • Better handling for date values, now defaults to 0001-01-01.
    • An ISO 8601 value is always expected to be used.
  • Class instances are now created automatically in the code.
  • SPOT Javascript code, TS now is dependent on Sushi.JavaScript
  • Much better handling for referring other models.
  • Specific code for inheriting models removed, the properties are always generated by default.
  • Enums are not handled as convert-able objects because its not (yet) supported.
  • Fixed TS templates, used modules.
  • Models or testing are more realistic to the API view-models.
  • Fixed generated comments, now simple as it should be.

Release Notes

- Support for EcmaScript (JavaScript) and TypeScript
     - Write inline code documentation to script
     - Customize templates and formatting
     - Extend by implementing your own script-language
     - Write to file (asynchronous)
     - Detect models to convert in assembly
     
     V1.1
     - Customize what data-type should be used for a given type.
     - Better handling for date values, now defaults to 0001-01-01.
     - An ISO 8601 value is always expected to be used.
     - Class instances are now created automatically in the code.
     - SPOT Javascript code, TS now is dependent on Sushi.JavaScript
     - Much better handling for referring other models.
     - Specific code for inheriting models removed, the properties are always generated by default.
     - Enums are not handled as convert-able objects because its not (yet) supported.
     - Fixed TS templates, used modules.
     - Models or testing are more realistic to the API view-models.
     - Fixed generated comments, now simple as it should be.

Dependencies

This package has no dependencies.

Version History

Version Downloads Last updated
1.1.1 171 5/27/2018
1.1.0 163 5/27/2018
1.0.7 168 4/12/2018
1.0.6 166 4/12/2018
1.0.5 198 4/3/2018
1.0.4 194 4/1/2018
1.0.3 209 4/1/2018
1.0.2 205 3/30/2018
1.0.1 192 3/29/2018