Skip to content

Latest commit

 

History

History
136 lines (96 loc) · 7.15 KB

CONTRIBUTING.md

File metadata and controls

136 lines (96 loc) · 7.15 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.

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 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 using #if.

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:

  • 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: