Skip to content

Latest commit

 

History

History
128 lines (88 loc) · 6.56 KB

CONTRIBUTING.md

File metadata and controls

128 lines (88 loc) · 6.56 KB
Raw

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.

    • Easier tasks to get started with are marked with the up-for-grabs tag.

Solution files

The root directory contains a number of Visual Studio solutions (*.sln) files 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 *.fsx and *.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 both .NET Framework 4.5 (net45) and .NET Standard 2.0 (netstandard2.0). We also need a design time component for each, to be able to to host the type provider in .NET Core-based tooling.

The runtime components are in the following project:

  • FSharp.Data

The design time components are in the following project:

  • FSharp.Data.DesignTime

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 Common and 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 Providers folder (in the 2 design time projects) and contain the ProvidedTypes helpers from the F# team, 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 StructureInference.fs.

  • 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).

Source code

Debugging

To debug the type generation, the best way is to change FSharp.Data.DesignTime project to a Console application, rename Test.fsx to 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.

Documentation

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 content directory 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 tutorials folder (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.fsx script (GitHub link) which builds the documentation.

Related articles

If you want to learn more about writing type providers in general, here are some useful resources: