nateradebaugh / ntypewriter

File generator from templates populated with data about your C# code.

NTypewriter

For those who do not know Typewriter:

NTypewriter is files generator from text templates populated with meta-data about your C# code. It is like a specialized and more convenient T4 design-time template.

For those who know Typewriter:

NTypewriter is a younger and more immature brother of beloved Typewriter. They share the same ideas, but with a completely different implementation. NTypwriter uses Scriban as a template engine, thus templates files are completely not interchangeable. While code model api is about 95% compatible between them, there are some differences. NTypewriter code model is 100% pure, without any amenities that helps generate TS files.

Oh, did I forget to mention that NTypewriter also solves most of the awaited issues of the Typewriter that were promised for 2.0 version:

• support for attribute properties/values, statics, indexers, default parameters, nullable, records, constructors
• output multiple types to single file
• include types in CodeModel from referenced assemblies/nugets
• save generated file only when file content has changed
• sharable custom functions
• full control over whitespaces
• CLI is possible
• built-in support for getting all types referenced in class declaration

Index

• Typewriter vs NTypewriter
• Getting started
  • NTypewriter editor for Visual Studio
    • Install
    • CodeModel
    • Capture
    • Save
    • Run
    • When something goes wrong
  • Build your own CLI
• Documentation
  • Language
  • Code model
  • Built-in functions
  • Name vs BareName vs FullName
  • Editor Configuration
    • Install
    • Custom functions
    • AddGeneratedFilesToVSProject
    • NamespacesToBeSearched
    • ProjectsToBeSearched
    • SearchInReferencedProjectsAndAssemblies
• Known issues
• Status of typewriter issues
• Change log

Typewriter vs NTypewriter

-------	Typewriter	NTypewriter
Template file extension	*.tst	*.nt
Syntax	typewriter syntax	scriban scripting language
Lambda filters	present	not available yet
Render template on save	yes (opt-out possible)	not available, only manual
Auto-render when C# files changes	yes (opt-out possible)	not available, only manual
Add generated files to VS project	yes (opt-out possible)	yes (opt-out possible)
can be used from CLI	nope	yes
Supported versions of Visual Studio	2015+	2019+
Custom functions	separate for every template	shared between templates
Full control over whitespaces	nope	yup
Mapping	one input always produces one output file	you can generate as many files as you want
Sync deleted or renamed C# types with generated files	there is a part of the code that should do that but it does not work anymore	yup
Access modifiers	code model contains only public types	code model contains all types
Unit of work	file	there is no concept of a file in NTypewriter, you work on compiled symbols
partial classes	treated as separate units	all parts of the class are treated as a whole unit

Typewriter template:

module App { $Classes(*Model)[
    export class $Name { $Properties[
        public $name: $Type;]
    }]
}

equivalent NTypewriter template will be :

{{- for class in data.Classes | Symbols.WhereNameEndsWith "Model"
        capture output -}}
module App {
    export class {{ class.Name }} {
            {{- for property in class.Properties | Symbols.ThatArePublic }}
        public {{ property.Name | String.ToCamelCase }}: {{ property.Type | Type.ToTypeScriptType }};
            {{- end }}
    }
}
    {{- end 
        filePath =  class.BareName | String.Append ".ts"
        Save output filePath
    end }}

yes, it is more verbose, but maintaining it over time will be much easier. Both templates generate exactly the same output:

module App {
    export class CustomerModel {
        public id: number;
        public name: string;
        public orders: OrderModel[];
    }
}

Getting started with NTypewriter editor for Visual Studio

1. Install NTypewriter editor for Visual Studio
2. Add template file with *.nt extension to your project
3. You gain access to code model from your template by special global variable data. So let us iterate over every class defined in solution, and write its name to output.

{{ for class in data.Classes 
     class.FullName | String.Append "\r\n"
  end }}  

4. Now it is time to decide what part of our template will be saved to a file. We do that by using capture statement capture variableName; end. For this example we want to generate one file with list of all classes defined in solution, thus we should use capture statement outside of the for loop.

{{ capture output
       for class in data.Classes 
             class.FullName | String.Append "\r\n"
       end 
   end}}

5. To create file on disk we use Save whatToSave filePath function

{{ capture output
       for class in data.Classes 
           class.FullName | String.Append "\r\n"
      end
   end
   Save output "index.txt"
}}    

6. We have completed template, now we can run it and generate file.

7. If something goes wrong you can look at NTypewriter output. NTypewriter is very chatty about what is doing at the moment. Most of the errors also will appear on the VS Error List.

Known issues

NTypewriter does not have own a lexer/parser as Typewriter has, and uses Scriban instead to do heavy work. Scriban works very well with fully correct templates, but with incomplete templates during edition not so much. It is the source of the most glitches in the Editor.

Ntypwriter does not listen for changes in your custom config file with custom functions. The Config file is read only once when you open a new editor window in VS. This will be changed in the future, but is not a priority.

Not all built in Scriban functions are available in templates.

Change log

0.1.0 - introduces local configuration that can be used inside template file, to achieve that some breaking changes were made to the structure of global configuration file