TextScript!

Text templating with .NET comfort

This project is a fork over Scriban

What does this do?

TextScript is a text templating engine. Designed to be powerful yet easy to learn, TextScript aims to provide the same functionality of liquid and more. TextScript is written entirely in .NET, so there's absolutely no need for ruby, python or a boatload of NodeJS npms!

TextScript is initially forked from Scriban in late 2018, and the code base has diverged since. Some primary differences are:

• PowerShell cmdlet with full support for hashtables
• A more terse syntax
• Lesser dependencies
• Built-in LINQ-like functionality

You can read more about a list of differences here.

Show me the money

How about some good old templating done right inside PowerShell?

ipmo TextScript
@{ name = 'Partner' } | ConvertFrom-Template -Template 'Howdy {{ name }}!'
# Howdy Partner!

Same thing in C#:

// Parse a template
var template = Template.Parse("Hello {{name}}!");
var result = template.Render(new { Name = "World" }); // => "Hello World!" 

TextScript borrows from the very popular liquid, which you are encouraged to look at too. In most of the cases, there is no difference at all:

ipmo TextScript
@{
  food = @(
    { name = 'cabbage'; price = '$10'; fullDesc = "Fresh and green" }
    { name = 'banana';  price = '$5';  fullDesc = "Minion's favorite" }
    { name = 'beef';    price = '$50'; fullDesc = "Meatlovers delight"}
  )
} | ConvertFrom-Template @'
<ul id='cart'>
  {{ for item in food }}
    <li>
      <h2>{{ item.name }}</h2>
           Price: {{ item.price }}
           {{ item.full_desc | string.truncate 15 }}
    </li>
  {{ end }}
</ul>
'@

Highlights

• Engineered for speed and efficiency. Near real-time rendering without a dent on the CPU.
• Full access to the lexer. The full AST is exposed in .NET. Regex-based parsers are so yesterday!
  • Pin-point the exact location within the template (path, column and line) when an error occurs.
  • Write an AST to text with Template.ToText. You can manipulate templates in memory and re-save them to disk, which is handy for roundtrip script update scenarios
• liquid compatibility mode with the Template.ParseLiquid method:
  • While the liquid language is less powerful, we know migrating existing code can be a chore. This mode allows for a drop-in replacement for your existing liquid templates.
  • With AST to text mode, you can migrate a liquid template to TextScript automatically (by using Template.ParseLiquid, then Template.ToText) Extensible runtime providing many extensibility points
• OCD level control over whitespace output
• Full feature language, including logic flow control such as if/else, for, and while, expressions (x = 1 + 2), conditions... etc.
• Function calls and pipes. Be functional! myvar | string.capitalize
  • Custom functions. Write your own functions directly inside a template, using the func statement.
  • Support for function pointers and delegates via the alias @ directive
  • Bind .NET custom functions from the runtime API with many options for interfacing with .NET objects.
• Complex objects
  • Construct your objects JavaScript/JSON styled: x = {mymember: 1}
  • Arrays too! x = [1,2,3,4]
• Pass a block of statements to a function, typically used by the wrap statement
• Essential and handy built-in functions:
  • arrays
  • date
  • fs
  • html
  • maths
  • object
  • regex
  • string
  • timespan
• Multi-line statements without having to embrace each line by {{...}}
• Safe parser and safe runtime, allowing you to control what objects and functions are exposed

Documentation

Go to the documentation page to get started.

Binaries

Prebuilt binaries are available in the release tab.

To integrate TextScript in your .NET project, reference our NuGet package in your packages.config or project file:

TextScript can run on the following platforms:

• Windows: .NET 4.6.2
• Linux: NetStandard1.3

To install our PowerShell cmdlet:

Install-Package TextScript

Platform specific implementations for PowerShell:

• Windows Desktop/Server/Core: .NET 4.6.2
• Windows Nano: NETStandard 1.6
• Linux: NETStandard 2.0

Benchmarks

We aim for real-time rendering! Compete results are updated in our benchmarks document.

License

See the LICENSE file for licensing information.

Related projects

We take inspirations from the following repos. For third party licensing info, refer to the third party license file.

• dotliquid: .NET port of the liquid templating engine
• Fluid .NET liquid templating engine
• Nustache: Logic-less templates for .NET
• Handlebars.Net: .NET port of handlebars.js