Repository files navigation

Scriban is a fast, powerful, safe and lightweight scripting language and engine for .NET, which was primarily developed for text templating with a compatibility mode for parsingliquid templates.

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

Parse a Liquid template using the Liquid language:

// Parse a liquid templatevartemplate=Template.ParseLiquid("Hello {{name}}!");varresult=template.Render(new{Name="World"});// => "Hello World!"

The language is very versatile, easy to read and use, similar toliquid templates:

vartemplate=Template.Parse(@"<ul id='products'>  {{ for product in products }}    <li>      <h2>{{ product.name }}</h2>           Price: {{ product.price }}           {{ product.description | string.truncate 15 }}    </li>  {{ end }}</ul>");varresult=template.Render(new{Products=this.ProductList});

Scriban can also be used in pure scripting context without templating ({{ and}}) and can help you to create your own small DSL.

NOTICE

By default, Properties and methods of .NET objects are automatically exposed with lowercase and_ names. It means that a property likeMyMethodIsNice will be exposed asmy_method_is_nice. This is the default convention, originally to match the behavior of liquid templates.If you want to change this behavior, you need to use aMemberRenamer delegate

• AST is now fully visitable withScriptVisitor. You can now accessParent on anyScriptNode object and navigate the AST.
  • Improve AST round-trip by preserving whitespaces around template enter{{ and exit}}
• Several new language features:
  • Hexadecimal/binary numbers:0x1ef or0b101010
  • Support for large integers
  • New parametric functions:func sub(x,y = 1, z...); ret x - y - z[0]; end
  • New inline functions:sub(x,y) = x - y
  • Optional member access with?. instead of regular. (e.ga?.b?.c)
  • Conditional expressions:cond ? a : b
• Separate language mode (viaScriptLang enum) from template/scripting parsing mode (ScriptMode).
• New language parsing modeScientific, in addition to default Scriban and Liquid language mode.
• More fine-grained options on theTemplateContext to define scripting behaviors (EnableRelaxedTargetAccess,EnableRelaxedMemberAccess,EnableRelaxedFunctionAccess,EnableRelaxedIndexerAccess,EnableNullIndexer)
• Newobject.eval andobject.eval_template function to evaluate Scriban expressions/templates at runtime.
• Better support forIFormattable objects.

• Veryefficient,fast parser and alightweight runtime. CPU and Garbage Collector friendly. Check thebenchmarks for more details.
• Powered by a Lexer/Parser providing afull Abstract Syntax Tree, fast, versatile and robust, more efficient than regex based parsers.
  • Precise source code location (path, column and line) for error reporting
  • Write an AST to a script textual representation, withTemplate.ToText, allowing to manipulate scripts in memory and re-save them to the disk, useful forroundtrip script update scenarios
• Compatible withliquid by using theTemplate.ParseLiquid method
  • While theliquid language is less powerful than scriban, this mode allows to migrate fromliquid toscriban language easily
  • With theAST to text mode, you can convert aliquid script to a scriban script usingTemplate.ToText on a template parsed withTemplate.ParseLiquid
  • As the liquid language is not strictly defined and there are in fact various versions of liquid syntax, there are restrictions while using liquid templates with scriban, see the documentliquid support in scriban for more details.
• Extensible runtime providing many extensibility points
• Support forasync/await evaluation of scripts (e.gTemplate.RenderAsync)
• Precise control of whitespace text output
• Full featured language includingif/else/for/while,expressions (x = 1 + 2), conditions... etc.
• Function calls and pipes (myvar | string.capitalize)
  • Custom functions directly into the language viafunc statement and allowfunction pointers/delegates via thealias @ directive
  • Bind.NET custom functions from the runtime API withmany options for interfacing with .NET objects.
• Complex objects (javascript/json like objectsx = {mymember: 1}) andarrays (e.gx = [1,2,3,4])
• Allow to passa block of statements to a function, typically used by thewrap statement
• Severalbuilt-in functions:
  • arrays functions
  • date
  • html
  • maths functions
  • object
  • regex functions
  • string functions
  • timespan
• Multi-line statements without having to embrace each line by{{...}}
• Safe parser andsafe runtime, allowing you to control what objects and functions are exposed

You can install theScriban Extension for Visual Studio Code to get syntax coloring for scriban scripts (without HTML) and scriban html files.

• See theLanguage document for a description of the language syntax.
• See theBuilt-in functions document for the list of the built-in functions.
• See theRuntime document for a description of the .NET runtime API to compile and run templates.
• See theLiquid support document for more details about the support of liquid templates.
• See my blog post "Implementing a Text Templating Engine for .NET" for some behind the scene details.

Scriban is available as a NuGet package:

Compatible with the following .NET Standard 2.0+ (New in 3.0)

For support for older framework (.NET 3.5, 4.0, 4.5, .NET Standard 1.1, 1.3, they are only provided in older Scriban 2.x, which is no longer supported.

Also theScriban.Signed NuGet package provides signed assemblies.

Starting with Scriban 3.2.1+, the package comes with source included so that you can internalize your usage of Scriban into your project. This can be useful in an environment where you can't easily consume NuGet references (e.g Roslyn Source Generators).

WARNING: Currently, the Scriban sources are not set as readonly, so you should not modify Scriban sources in that mode as it will modify the sources for other projects using Scriban on your machine. Use this feature at your own risks!

In order to activate this feature you need to:

• Set the propertyPackageScribanIncludeSource totrue in your project:

  <PropertyGroup>  <PackageScribanIncludeSource>true</PackageScribanIncludeSource></PropertyGroup>

• Add theIncludeAssets="Build" to the NuGet PackageReference for Scriban:

  <ItemGroup>  <PackageReferenceInclude="Scriban"Version="3.2.1"IncludeAssets="Build"/></ItemGroup>

If you are targetingnetstandard2.0 or.NET Framework 4.7.2+, in order to compile Scriban you will need these NuGet package references (that can come from a dependency that you already have):

<ItemGroup>    <PackageReferenceInclude="Microsoft.CSharp"Version="4.5.0" />    <PackageReferenceInclude="System.Threading.Tasks.Extensions"Version="4.5.0" /></ItemGroup>

NOTE: In this mode, all Scriban types are marked asinternal.

You should see a Scriban folder and empty subfolders in your project. This is an issue with Visual Studio 2019 16.8.x (and before) and it will be fixed in VS 2019 16.9+

Scriban is blazing fast! For more details, you can check thebenchmarks document.

This software is released under theBSD-Clause 2 license.

• 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
• Textrude: UI and CLI tools to turn CSV/JSON/YAML models into code using Scriban templates

• (https://scribanonline.azurewebsites.net/): ASP.NET Core Sample.

Adapted logoPuzzle byAndrew Doane from the Noun Project

Alexandre Mutel akaxoofx.