Scriban 5.12.1

Prefix Reserved
dotnet add package Scriban --version 5.12.1                
NuGet\Install-Package Scriban -Version 5.12.1                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Scriban" Version="5.12.1" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Scriban --version 5.12.1                
#r "nuget: Scriban, 5.12.1"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Scriban as a Cake Addin
#addin nuget:?package=Scriban&version=5.12.1

// Install Scriban as a Cake Tool
#tool nuget:?package=Scriban&version=5.12.1                

scriban Build Status Coverage Status NuGet

<img align="right" width="160px" height="160px" src="img/scriban.png">

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 like MyMethodIsNice will be exposed as my_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 a MemberRenamer delegate

New in 3.0+

  • AST is now fully visitable with ScriptVisitor. You can now access Parent on any ScriptNode 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 or 0b101010
    • 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.g a?.b?.c)
    • Conditional expressions: cond ? a : b
  • Separate language mode (via ScriptLang enum) from template/scripting parsing mode (ScriptMode).
  • New language parsing mode Scientific, in addition to default Scriban and Liquid language mode.
  • More fine-grained options on the TemplateContext to define scripting behaviors (EnableRelaxedTargetAccess, EnableRelaxedMemberAccess, EnableRelaxedFunctionAccess, EnableRelaxedIndexerAccess, EnableNullIndexer)
  • New object.eval and object.eval_template function to evaluate Scriban expressions/templates at runtime.
  • Better support for IFormattable objects.

Features

  • An extensible sandbox execution model: You have the full control about which Scripting objects (and so properties and methods) are accessible from Scriban templates.
  • Very efficient, fast parser and a lightweight runtime. CPU and Garbage Collector friendly.
  • Powered by a Lexer/Parser providing a full 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, with Template.ToText, allowing to manipulate scripts in memory and re-save them to the disk, useful for roundtrip script update scenarios
  • Compatible with liquid by using the Template.ParseLiquid method
    • While the liquid language is less powerful than scriban, this mode allows to migrate from liquid to scriban language easily
    • With the AST to text mode, you can convert a liquid script to a scriban script using Template.ToText on a template parsed with Template.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 document liquid support in scriban for more details.
  • Extensible runtime providing many extensibility points
  • Support for async/await evaluation of scripts (e.g Template.RenderAsync)
  • Precise control of whitespace text output
  • Full featured language including if/else/for/while, expressions (x = 1 + 2), conditions... etc.
  • Function calls and pipes (myvar | string.capitalize)
  • Complex objects (javascript/json like objects x = {mymember: 1}) and arrays (e.g x = [1,2,3,4])
  • Allow to pass a block of statements to a function, typically used by the wrap statement
  • Several built-in functions:
  • 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

Syntax Coloring

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

Documentation

Binaries

Scriban is available as a NuGet package: NuGet

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.

Source Embedding

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 property PackageScribanIncludeSource to true in your project:
    <PropertyGroup>
      <PackageScribanIncludeSource>true</PackageScribanIncludeSource>
    </PropertyGroup>
    
  • Add the 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+

License

This software is released under the BSD-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
  • NTypewriter: VS extension to turn C# code into documentation/TypeScript/anything using Scriban templates

Online Demo

Sponsors

Supports this project with a monthly donation and help me continue improving it. [Become a sponsor]

<img src="https://github.com/lilith.png?size=200" width="64px;" style="border-radius: 50%" alt="lilith"/> Lilith River, author of Imageflow Server, an easy on-demand image editing, optimization, and delivery server

Credits

Adapted logo Puzzle by Andrew Doane from the Noun Project

Author

Alexandre Mutel aka xoofx.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (164)

Showing the top 5 NuGet packages that depend on Scriban:

Package Downloads
Volo.Abp.TextTemplating.Scriban

Package Description

Mediator.SourceGenerator

A high performance .NET Mediator pattern implemenation using source generation.

Serenity.CodeGenerator

Generates server and script side code for Serenity platform applications

Miru.Core

Package Description

RecommendationsGatewayModule.Data

Package Description

GitHub repositories (44)

Showing the top 5 popular GitHub repositories that depend on Scriban:

Repository Stars
abpframework/abp
Open-source web application framework for ASP.NET Core! Offers an opinionated architecture to build enterprise software solutions with best practices on top of the .NET. Provides the fundamental infrastructure, cross-cutting-concern implementations, startup templates, application modules, UI themes, tooling and documentation.
spectreconsole/spectre.console
A .NET library that makes it easier to create beautiful console applications.
dodyg/practical-aspnetcore
Practical samples of ASP.NET Core 9, 8.0, 7.0, 6.0, 5.0, 3.1, 2.2, and 2.1,projects you can use. Readme contains explanations on all projects.
openiddict/openiddict-core
Flexible and versatile OAuth 2.0/OpenID Connect stack for .NET
focus-creative-games/luban
luban是一个强大、易用、优雅、稳定的游戏配置解决方案。luban is a powerful, easy-to-use, elegant and stable game configuration solution.
Version Downloads Last updated
5.12.1 3,183 12/18/2024
5.12.0 62,603 11/13/2024
5.11.0 41,179 11/1/2024
5.10.0 1,531,239 4/12/2024
5.9.1 720,946 1/9/2024
5.9.0 1,595,991 9/6/2023
5.8.0 8,927 9/1/2023
5.7.0 1,395,240 2/25/2023
5.6.0 140,103 2/3/2023
5.5.2 280,839 1/4/2023
5.5.1 287,006 11/18/2022
5.5.0 1,589,438 7/11/2022
5.4.6 569,386 5/29/2022
5.4.5 31,652 5/22/2022
5.4.4 2,546,831 4/9/2022
5.4.3 55,720 4/3/2022
5.4.2 10,188 3/31/2022
5.4.1 88,749 3/15/2022
5.4.0 189,863 2/6/2022
5.3.0 2,720 2/6/2022
5.2.0 8,059 2/6/2022
5.1.0 2,532 2/5/2022
5.0.0 922,935 10/20/2021
4.1.0 39,420 10/7/2021
4.0.2 685,753 9/22/2021
4.0.1 848,742 6/3/2021
4.0.0 4,730 6/2/2021
3.9.0 23,431 5/31/2021
3.8.2 25,912 5/27/2021
3.8.1 67,538 5/25/2021
3.8.0 2,269 5/25/2021
3.7.0 124,518 5/1/2021
3.6.0 1,127,399 3/20/2021
3.5.0 252,640 2/13/2021
3.4.2 49,604 2/1/2021
3.4.1 42,905 1/23/2021
3.4.0 15,211 1/21/2021
3.3.3 89,814 1/14/2021
3.3.2 139,528 12/30/2020
3.3.1 51,803 12/30/2020
3.3.0 2,674 12/29/2020
3.2.2 4,567 12/24/2020
3.2.1 17,985 12/22/2020
3.2.0 2,369 12/22/2020
3.1.0 7,946 12/21/2020
3.0.7 27,715 12/15/2020
3.0.6 135,715 12/6/2020
3.0.5 250,481 12/1/2020
3.0.4 5,921 11/30/2020
3.0.3 3,976 11/29/2020
3.0.2 74,091 11/23/2020
3.0.1 2,560 11/22/2020
3.0.0 18,777 11/15/2020
3.0.0-alpha.9 5,100 8/20/2020
3.0.0-alpha.8 471 8/7/2020
3.0.0-alpha.7 309 7/31/2020
3.0.0-alpha.6 323 7/31/2020
3.0.0-alpha.5 627 7/25/2020
3.0.0-alpha.4 379 7/25/2020
3.0.0-alpha.3 16,913 7/16/2020
3.0.0-alpha.2 356 7/6/2020
3.0.0-alpha.1 441 6/18/2020
2.1.4 544,592 8/16/2020
2.1.3 938,283 6/5/2020
2.1.2 353,828 3/8/2020
2.1.1 381,453 12/6/2019
2.1.0 333,357 6/30/2019
2.0.1 579,756 5/11/2019
2.0.0 190,366 3/8/2019
2.0.0-alpha-006 592 3/7/2019
2.0.0-alpha-005 3,998 1/15/2019
2.0.0-alpha-004 1,386 1/4/2019
2.0.0-alpha-003 627 1/3/2019
2.0.0-alpha-002 713 1/1/2019
2.0.0-alpha-001 643 12/28/2018
1.2.9 119,281 12/21/2018
1.2.8 7,719 12/17/2018
1.2.7 225,293 10/6/2018
1.2.6 10,184 9/26/2018
1.2.5 10,841 8/29/2018
1.2.4 3,923 8/21/2018
1.2.3 108,410 7/20/2018
1.2.2 7,736 7/3/2018
1.2.1 27,676 6/1/2018
1.2.0 27,880 2/10/2018
1.1.1 5,931 1/22/2018
1.1.0 1,147 1/22/2018
1.0.0 144,242 12/24/2017
1.0.0-beta-006 1,034 12/12/2017
1.0.0-beta-005 855 12/3/2017
1.0.0-beta-004 1,137 11/19/2017
1.0.0-beta-003 1,092 11/19/2017
1.0.0-beta-002 1,067 11/13/2017
1.0.0-beta-001 1,054 11/12/2017
0.16.0 19,106 11/12/2017
0.15.0 10,497 11/9/2017
0.14.0 1,326 11/7/2017
0.13.0 1,325 11/7/2017
0.12.1 1,332 11/6/2017
0.12.0 1,311 11/6/2017
0.11.0 1,333 11/4/2017
0.10.0 1,287 11/1/2017
0.9.1 1,294 10/27/2017
0.9.0 1,267 10/25/2017
0.9.0-pre100 1,107 10/23/2017
0.7.0 27,597 10/12/2017
0.6.0 1,677 5/16/2017
0.5.0 1,124 5/16/2017
0.4.0 1,109 5/8/2017
0.3.1 1,130 4/4/2017
0.3.1-pre028 905 4/4/2017
0.3.0 1,119 3/9/2017
0.2.2 1,180 2/2/2017
0.2.1 1,207 2/1/2017
0.2.0 1,877 6/27/2016
0.1.0 6,519 5/31/2016