PandocFilters 0.3.41
See the version list below for details.
dotnet add package PandocFilters --version 0.3.41
NuGet\Install-Package PandocFilters -Version 0.3.41
<PackageReference Include="PandocFilters" Version="0.3.41" />
paket add PandocFilters --version 0.3.41
#r "nuget: PandocFilters, 0.3.41"
// Install PandocFilters as a Cake Addin #addin nuget:?package=PandocFilters&version=0.3.41 // Install PandocFilters as a Cake Tool #tool nuget:?package=PandocFilters&version=0.3.41
PandocFilters
Write Pandoc filters in .NET, using strongly-typed data structures for the Pandoc AST.
Pandoc filters
Pandoc is a command-line program and Haskell library for converting documents from and to many different formats. Documents are translated from the input format to an AST (defined in the Text.Pandoc.Definition module), which is then used to create the output format.
Pandoc allows writing filters — programs that intercept the AST as JSON from standard input, modify the AST, and write it back out to standard output. Filters can be run using the pipe operator (|
on Linux, >
on Windows):
pandoc -s input.md -t json | my-filter | pandoc -s -f json -o output.html
or using the Pandoc --filter
command-line option:
pandoc -s input.md --filter my-filter -o output.html
Pandoc AST
Much of the JSON-serialized AST comes in the form of objects with a t
and c
property<sup>1</sup>:
{
"t": "Para",
"c": [
]
}
This corresponds to a Para
object with properties filled with the values at the c
property.
The library defines types and base classes for both levels:
Type level | Description | Namespace | Visitor base class |
---|---|---|---|
Raw | Objects with a t and c property |
PandocFilters.Raw |
RawVisitorBase |
Higher-level AST | e.g. Para type |
PandocFilters.Ast |
VisitorBase |
The library also includes two predefined visitors — DelegateVisitor
and RawDelegateVisitor
— which can be extended by adding delegates via the Add
method, instead of defining a new class (see below for sample).
<sup>1. All the types in pandoc-types except for the root Pandoc type and the Citation type.</sup>
Usage
- Create a console application.
- Install the
PandocFilters
NuGet package. - Define your visitor — either
- write a class that inherits from one of the visitor base classes, and create an instance of the class, or
- create an instance of the appropriate delegate visitor class, and append delegates using the
Add
methods.
- Pass the instance into
Filter.Run
. - Either pass your program to Pandoc using
--filter
; or pipe the JSON output from Pandoc into your program, and pipe the outout back into Pandoc.
Note that Filter.Run
takes an arbitrary number of visitors — you can create multiple visitors and pass them into Filter.Run
.
Sample
using System.Diagnostics;
using System.Linq;
using PandocFilters;
using PandocFilters.Types;
var visitor = new RemoveImagePositioning();
Filter.Run(visitor);
class RemoveImagePositioning : VisitorBase {
public override Image VisitImage(Image image) =>
image with {
Attr = image.Attr with {
KeyValuePairs =
img.Attr.KeyValuePairs
.Where(x => x.Item1 != "height" && x.Item1 != "width"))
.ToImmutableList()
}
};
}
Using the delegate visitor:
using System.Diagnostics;
using System.Linq;
using PandocFilters;
using PandocFilters.Types;
var visitor = new DelegateVisitor();
visitor.Add((Image image) => image with {
Attr = image.Attr with {
KeyValuePairs =
img.Attr.KeyValuePairs
.Where(x => x.Item1 != "height" && x.Item1 != "width"))
.ToImmutableList()
}
});
Filter.Run(visitor);
For a real-world usage example with multiple visitors (and the reason I wrote this in the first place), see DlrDocsProcessor.
Credits
- John McFarlane and contributors for Pandoc
- @mcintyre321, for OneOf
- dbramucci and Lalaithion42 for their help in understanding Haskell data types
Notes
- PandocFilters is written against the types in pandoc-types 1.22. When pandoc-types is updated, code written against the raw types will successfully receive the JSON-source data structures; while code written against the higher-level types will conceivably fail in the JSON parsing stage.
- The library uses C# 9 record types (and System.Collections.Immutable) to enforce immutability; otherwise we'd have to check for circular references before serializing. If you're using C# 9 or later, you can use the
with
keyword to clone/initialize the returned instance; otherwise you'll have to pass in all arguments to the constructor.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 is compatible. 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 was computed. 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. |
-
.NETStandard 2.0
- Microsoft.CSharp (>= 4.7.0)
- Newtonsoft.Json (>= 13.0.1)
- OneOf (>= 3.0.205)
- OneOf.Extended (>= 3.0.205)
- System.Collections.Immutable (>= 6.0.0)
- ZSpitz.Util (>= 0.1.116)
-
net5.0
- Microsoft.CSharp (>= 4.7.0)
- Newtonsoft.Json (>= 13.0.1)
- OneOf (>= 3.0.205)
- OneOf.Extended (>= 3.0.205)
- System.Collections.Immutable (>= 6.0.0)
- ZSpitz.Util (>= 0.1.116)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
0.3.42 | 435 | 12/22/2021 |
0.3.41 | 282 | 12/22/2021 |
0.3.36 | 390 | 1/26/2021 |
0.3.35 | 335 | 1/26/2021 |
0.3.34 | 348 | 1/26/2021 |
0.3.33 | 340 | 1/14/2021 |
0.3.32 | 347 | 1/14/2021 |
0.3.31 | 332 | 1/14/2021 |
0.3.30 | 344 | 1/14/2021 |
0.3.29 | 356 | 1/13/2021 |
0.3.28 | 372 | 1/13/2021 |
0.3.27 | 370 | 1/12/2021 |
0.3.26 | 341 | 1/11/2021 |
0.3.25 | 352 | 1/10/2021 |
0.3.24 | 356 | 1/9/2021 |
0.3.23 | 386 | 1/5/2021 |
0.2.21 | 362 | 1/5/2021 |
0.2.18 | 364 | 1/5/2021 |
0.2.13 | 354 | 12/30/2020 |
0.1.6 | 429 | 12/9/2020 |