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.
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
.
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.
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 aSystem.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.
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 theCharStream
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.
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 ofisAnyOf
,isNoneOf
,anyOf
,skipAnyOf
,noneOf
andskipNoneOf
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. -
DEBUG_STATIC_MAPPING
-
This option does not affect the Low‐Trust version of FParsec.