3 Download and installation

FParsec is distributed in source code form and as NuGet packages.

If you’re new to FParsec, I’d recommend to start by downloading the source code package and experimenting a bit with the included sample projects. With the project and solution files building the library and the samples is as easy as clicking a button.

The source package also includes a complete copy of the HTML documentation for offline viewing.

3.1 NuGet packages

There are two NuGet packages of FParsec, which are built with different configuration options.

The basic package uses the Low‐Trust version of FParsec, which uses no unverifiable code and is optimized for maximum portability. The main limitation of this version is that any input stream is completely read into a string before parsing, which limits the maximum practical input size. This package also contains assemblies for .NET Standard 2.0.

The “Big Data edition” package uses the non‐Low‐Trust version of FParsec that is optimized for maximum performance and supports extremely large input streams. Since this configuration is also the default configuration of the solution files included with the source code, it is sometimes referred to as the “normal” version of FParsec. This version of FParsec does use “unsafe” (i.e. unverifiable) code involving unmanaged pointers. It also uses code generation in the implementation of isAnyOf, isNoneOf, anyOf, skipAnyOf, noneOf and skipNoneOf. Unfortunately, this version is currently not compatible with .NET Standard/.NET Core.

Should you measure a significant performance degradation when switching to the Big Data edition, you’re probably inadvertently recreating the same isAnyOf‐ or isNoneOf‐based parsers again and again, as explained here and here.

The .NET Framework assemblies in the NuGet packages are strongly signed. Their assembly version numbers will only be incremented for breaking changes. The .NET Standard assembly in the FParsec package is not signed.

The NuGet packages include PDBs and SourceLink support, which should allow you to step through FParsec code in the debugger of your IDE.

3.2 Getting the source

FParsec’s source code repository is hosted on GitHub at: github.com/stephan‐tolksdorf/fparsec

You can clone the source code using Git or you can download it as a zip‐file.

It’s an FParsec project policy to check only stable and tested code into the master branch of the GitHub repository, so you can normally just work with the master version of FParsec.

Tip

Fork is a great free GUI for Git for Windows and MacOS.

3.3 FParsec is built as two DLLs

FParsec’s source code is written in both C# and F#. Since neither the C# nor the F# compiler directly support the other language, the respective components need to be built separately.

Hence, FParsec is built as two DLLs. The C# bits are compiled into the FParsecCS.dll and the F# bits (which depend on the C# bits) are compiled into FParsec.dll.

Projects that use FParsec thus have to reference both DLLs.

If you reference the DLLs in the F# Interactive console, you need to reference FParsecCS.dll before you reference FParsec.dll.

Note

If you don’t want to distribute the FParsec DLLs together with the assembly of your project, you can use the staticlink command‐line option of the F# compiler to merge the FParsec DLLs into your assembly.

Unfortunately, the same option cannot be used to merge FParsecCS.dll into the FParsec.dll, as the public definitions in FParsecCS.dll wouldn’t be reexported by FParsec.dll. For similar reasons it also doesn’t seem to be possible to use tools like ILMerge or il‐repack to obtain a merged FParsec.dll that can be properly consumed by F# programs.

3.4 Building FParsec from source

The solution file FParsec.sln in the root source folder and the associated project files in the subfolders can be used to build FParsec from the command line or with IDEs such as Visual Studio 2019 or JetBrains Rider.

To build the Low‐Trust version of FParsec, you have to specifiy either Debug-LowTrust or Release-LowTrust as the configuration. The Debug and Release configurations build the non‐Low‐Trust version of FParsec, which currently is not compatible with the .NET Core runtime.

Note

In contrast to JetBrains Rider, Visual Studio 2019 currently does not support setting the supported target frameworks depending on the configuration. Due to this issue one currently has to use the separate FParsec-LowTrust.sln solution for building the Low‐Trust version of FParsec in VS 2019.

The Test project in the solution files contains the unit tests for FParsec.

The file .vscode/tasks.json contains some convenient task definitions for Visual Studio Code.

The NuGet packages are built with the pack.ps1 PowerShell script.

3.5 The Low‐Trust version of FParsec

For optimization reasons the normal implementation (the “Big Data edition”) of FParsec involves unverifiable code using unmanaged pointers and runtime code generation.

If you compile FParsec with the LOW_TRUST conditional compiler symbol, the unverifiable code is replaced with a “safe” alternative. This allows FParsec to be run in environments with “reduced trust”, such as medium trust ASP.NET applications, and it also allows FParsec to be compiled against reduced subsets of the .NET API.

In the Debug-LowTrust and Release-LowTrust configurations of the FParsec.sln solution file in the root source folder, LOW_TRUST is automatically defined as true.

The Low‐Trust version of FParsec has the following two major limitations:

  • A CharStream that is constructed from a System.IO.Stream or a file path reads the complete file into a single string during construction. This severely limits the maximum practical input stream size.
  • The StaticMapping module is not supported.

3.6 Configuration options

You can configure FParsec’s source code with a number of conditional compilation symbols (a.k.a. preprocessor defines). Besides the Low‐Trust option, these symbols mostly serve tuning purposes.

Options for FParsecCS.dll
LOW_TRUST

See above.

AGGRESSIVE_INLINING

Requires a version of NET ≥ 4.5.

Annotates some functions with the MethodImplOptions.AggressiveInlining attribute.

PCL

Compile for a PCL subset of the .NET API.

SMALL_STATETAG

Use a 32‐bit StateTag in the CharStream class instead of the default 64‐bit one.

This is an optimization for 32‐bit runtimes. You can find more information about the state tag in section 5.4.3 of the user’s guide.

UNALIGNED_READS

This option does not affect the Low‐Trust version of FParsec.

Optimize for CPUs that support fast unaligned memory reads, i.e. any modern x86‐based CPU.

This option only makes a noticeable difference is some specific situations.

Options for FParsec.dll
LOW_TRUST

See above.

UNALIGNED_READS

See above.

NOINLINE

Do not force inlining of certain parser combinators.

This option enables you to step through the respective combinators during debugging.

USE_STATIC_MAPPING_FOR_IS_ANY_OF

This option does not affect the Low‐Trust version of FParsec.

Use StaticMapping.createStaticCharIndicatorFunction for the implementation of isAnyOf, isNoneOf, anyOf, skipAnyOf, noneOf and skipNoneOf for generating optimized char predicate functions using runtime code generation.

Runtime code generation is a relatively expensive operation, so this optimization is primarily meant for parsers that are applied to large (or lots of) input streams. Please see the remarks for the StaticMapping module for more information.

If you run into noticeable performance problems or memory leaks when enabling this option, you’re probably inadvertently recreating the same isAnyOf‐ or isNoneOf‐based parser again and again, as explained here and here.

DEBUG_STATIC_MAPPING

This option does not affect the Low‐Trust version of FParsec.