Contributing to F# Data
This page should provide you with some basic information if you're thinking about contributing to the F# Data package. It gives a brief summary of the library structure, how type providers are written and how the F# Data library handles multi-targeting (to make the providers available for Desktop as well as Portable libraries).
This page can be edited by sending a pull request to F# Data on GitHub, so if you learn something when playing with F# Data, please record your findings here!
If you want to discuss a feature (a good idea!), or if you want to look at suggestions how you might contribute, check out the Issue list on GitHub or send an email to the F# Open-Source mailing list.
The root directory contains a number of Visual Studio solutions (
that group the projects in the main logical groups:
FSharp.Data.sln contains the main projects that implement the F# Data functionality (such as runtime and design-time type provider libraries).
FSharp.Data.Tests.sln is a library with tests for F# Data and it also contains the content of this web site (as
*.md) files. Look here if you want to edit the documentation!
Projects and multi-targeting
One problem with developing type providers is supporting multiple versions of the .NET platform. Type providers consist of two components:
Runtime is the part of the type provider that is actually used when the compiled F# code that uses the provider runs. This assembly also has the non type-provider components of FSharp.Data: the CSV, HTML and JSON parsers, and the HTTP utilities.
Design time is the part that is used when editing F# code that uses type provider in your favourite editor or when compiling code. For example, in the CSV provider, this component does the type inference and generates types (that are mapped to runtime components by the compiler).
To support multiple targets, we need a runtime component for every single target (.NET Framework 4.0, PCL profile 7, PCL profile 47, PCL profile 259). However, we only need one design time component, because that is always going to be executed on desktop .NET in Visual Studio or Xamarin Studio.
So, there are 3 versions of runtime components and 1 version of design time
components. At the moment, this is done by having separate project file for each
component, but they share the same files - the project just defines some symbols that
are then used to include/exclude parts that are not available on certain platforms
If you open
FSharp.Data.sln, you'll see the following projects for runtime components:
- FSharp.Data - .NET Framework 4.0
- FSharp.Data.Portable7 - PCL profile 7 (.NET Framework 4.5, Windows 8)
- FSharp.Data.Portable47 - PCL profile 47 (.NET Framework 4.5, Silverlight 5, Windows 8)
- FSharp.Data.Portable259 - PCL profile 259 (.NET Framework 4.5, Windows 8, Windows Phone 8.1, Windows Phone Silverlight 8)
The design time components are in the following project:
Type provider structure
Several of the F# Data type providers have similar structure - the CSV, JSON, XML and HTML
providers all infer the types from structure of a sample input. In addition, they all
have a runtime component (CSV parser, HTML parser, JSON parser, and wrapper for
XDocument type in .NET).
So, how is a typical type provider implemented? First of all, there are some shared
files - in
Library subdirectories of the projects. These contain common
runtime components (such as parsers, HTTP helpers, etc.)
Next, there are some common design-time components. These can be found in
folder (in the 2 design time projects) and contain the
ProvidedTypes helpers from the
StructureInference.fs (which implements type inference for structured data)
and a couple of other helpers.
A type provider, such as JSON provider, is then located in a single folder with a number of files, typically like this:
JsonRuntime.fs- the only runtime component. Contains JSON parser and other objects that are called by code generated by the type provider.
JsonInference.fs- design-time component that infers the structure using the common API in
JsonGenerator.fs- implements code that generates provided types, adds properties and methods etc. This uses the information infered by inference and it generates calls to the runtime components.
JsonProvider.fs- entry point that defines static properties of the type provider, registers the provided types etc.
The WorldBank provider is different. It doesn't need inference, but it still distinguishes between runtime and design-time components, so you'll find at least two files (and possibly some additional helpers).
To debug the type generation, the best way is to change
FSharp.Data.DesignTime project to a Console application, rename
Test.fs and hit the Run command in the IDE, setting the breakpoints where you need them. This will invoke all the type providers manually without locking the files in Visual Studio / Xamarin Studio. You'll also see in the console output the complete dump of the generated types and expressions. This is also the process used for the signature tests.
The documentation for the F# Data library is automatically generated using the
F# Formatting library. It turns
*.md (Markdown with embedded code snippets) and
*.fsx files (F# script file with
embedded Markdown documentation) to a nice HTML documentation.
The code for all the documents can be found in the
contentdirectory on GitHub. If you find a bug or add a new feature, make sure you document it!
Aside from direct documentation for individual types, there is also a
tutorialsfolder (on GitHub) where you can add additional samples and tutorials that show some interesting aspects of F# Data.
If you want to build the documentation, simply run the
build.fsxscript (GitHub link) which builds the documentation.
If you want to learn more about writing type providers in general, here are some useful resources:
F# 3.0 Sample Pack contains a number of examples ranging from quite simple, to very complex.