A fast, powerful, safe and lightweight scripting language and engine for .NET
BSD-2-CLAUSE License
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 parsing liquid
templates.
Today, not only Scriban can be used in text templating scenarios, but also can be integrated as a general scripting engine: For example, Scriban is at the core of the scripting engine for kalk, a command line calculator application for developers.
// Parse a scriban template
var template = Template.Parse("Hello {{name}}!");
var result = template.Render(new { Name = "World" }); // => "Hello World!"
Parse a Liquid template using the Liquid language:
// Parse a liquid template
var template = Template.ParseLiquid("Hello {{name}}!");
var result = template.Render(new { Name = "World" }); // => "Hello World!"
The language is very versatile, easy to read and use, similar to liquid templates:
var template = 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>
");
var result = 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
ScriptVisitor
. You can now access Parent
on any ScriptNode
object and navigate the AST.
{{
and exit}}
0x1ef
or 0b101010
func sub(x,y = 1, z...); ret x - y - z[0]; end
sub(x,y) = x - y
?.
instead of regular .
(e.g a?.b?.c
)cond ? a : b
ScriptLang
enum) from template/scripting parsing mode (ScriptMode
).Scientific
, in addition to default Scriban and Liquid language mode.TemplateContext
to define scripting behaviors (EnableRelaxedTargetAccess
, EnableRelaxedMemberAccess
, EnableRelaxedFunctionAccess
, EnableRelaxedIndexerAccess
, EnableNullIndexer
)object.eval
and object.eval_template
function to evaluate Scriban expressions/templates at runtime.IFormattable
objects.Template.ToText
, allowing to manipulate scripts in memory and re-save them to the disk, useful for roundtrip script update scenarios
liquid
by using the Template.ParseLiquid
method
liquid
language is less powerful than scriban, this mode allows to migrate from liquid
to scriban
language easilyliquid
script to a scriban script using Template.ToText
on a template parsed with Template.ParseLiquid
async
/await
evaluation of scripts (e.g Template.RenderAsync
)if
/else
/for
/while
, expressions (x = 1 + 2
), conditions... etc.myvar | string.capitalize
)
func
statement and allow function pointers/delegates via the alias @ directive
x = {mymember: 1}
) and arrays (e.g x = [1,2,3,4]
)wrap
statement{{...}}
You can install the Scriban Extension for Visual Studio Code to get syntax coloring for scriban scripts (without HTML) and scriban html files.
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 the Scriban.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:
PackageScribanIncludeSource
to true
in your project:
<PropertyGroup>
<PackageScribanIncludeSource>true</PackageScribanIncludeSource>
</PropertyGroup>
IncludeAssets="Build"
to the NuGet PackageReference for Scriban:
<ItemGroup>
<PackageReference Include="Scriban" Version="3.2.1" IncludeAssets="Build"/>
</ItemGroup>
If you are targeting netstandard2.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>
<PackageReference Include="Microsoft.CSharp" Version="4.5.0" />
<PackageReference Include="System.Threading.Tasks.Extensions" Version="4.5.0" />
</ItemGroup>
NOTE: In this mode, all Scriban types are marked as
internal
.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+
This software is released under the BSD-Clause 2 license.
Adapted logo Puzzle
by Andrew Doane from the Noun Project
Alexandre Mutel aka xoofx.