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 Visual Studio project and solution files (e.g. in the Build/VS11 subfolder) 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.
To use FParsec in your own projects, you just need to reference the FParsecCS.dll and FParsec.dll assemblies produced by the FParsec project files. Alternatively, you can use the NuGet package manager to download precompiled FParsec assemblies and setup the references.
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 PCL profile 259 versions of the FParsec assemblies.
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
You can find the precise configuration options used to built the two NuGet packages below. Should you
measure a significant performance degradation when switching to the Big Data edition, you’re probably inadvertently
recreating the same
isNoneOf‐based parsers again and
again, as explained here and here.
The NuGet packages are strongly signed. Their assembly version numbers will only be incremented for breaking changes.
For every published FParsec NuGet package a corresponding symbol package with PDBs and source files is uploaded to SymbolSource.org. So, if you enable source server support in the Visual Studio debugging options and configure symbolsource.org as a symbol server, you can step into the FParsec code in the debugger.
3.2 Getting the source
FParsec’s source code repository is hosted on BitBucket at: bitbucket.org/fparsec/main
It’s an FParsec project policy to check only stable and tested code into the BitBucket repository, so you can normally just work with the “tip” version of FParsec.
TortoiseHG is a great Mercurial GUI for Windows.
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
FParsecCS.dll before you reference
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 with Visual Studio
The folder Build/VS11 contains a solution file for Visual Studio 2012 and later. The folder Build/VS14‐PCL contains a solution specifically configured to compile FParsec for PCL profile 259. The PCL build requires Visual Studio 2015 / F# 4.0 due to a bug in the PCL support of earlier versions of F#.
When you build FParsec with these solution files, the compiled assemblies will be put into the bin/Debug or bin/Release subfolders, depending on the project configuration. For example, the VS11 solution will put the assemblies into the folders Build/VS11/bin/Debug and Build/VS11/bin/Release.
The Test project in the solution files contains the unit tests for FParsec.
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.
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 such as PCL profile 259.
The next section explains how you can set a conditional compiler symbol. If you want to use the Low‐Trust version of FParsec, you need to
compile each of the
Test projects with the
The Low‐Trust version of FParsec has the following two major limitations:
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.
You can set conditional compilation symbols either in the Visual Studio project configuration in the “Build” tab (multiple symbols can be separated by semicolons) or on the compiler command‐line with the /define:SYMBOL option (the F# compiler requires a separate /define: option for each symbol).
Compile for a CLR version ≥ 4.
Compile for a CLR version ≥ 4.5.
This option allows annotating methods with the new
Compile for a PCL subset of the .NET API.
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.
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.
Do not force inlining of certain parser combinators.
This option enables you to step through the respective combinators during debugging.
StaticMapping.createStaticCharIndicatorFunctionfor the implementation of
skipNoneOffor 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
StaticMappingmodule for more information.