Skip to content

Latest commit

 

History

History
94 lines (64 loc) · 4.68 KB

CONTRIBUTING.md

File metadata and controls

94 lines (64 loc) · 4.68 KB
Raw

Contributing to FSharp.Data

This page should provide you with some basic information if you're thinking about contributing to the FSharp.Data package. It gives a brief summary of the library structure, how type providers are written and how the FSharp.Data package 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 FSharp.Data on GitHub, so if you learn something when playing with FSharp.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.

General info about developing type providers

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

We need a runtime component for .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 FSharp.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).

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

Docs and samples are in the docs directory. To update docs on your own machine, run the following command:

dotnet fsdocs watch

You can now edit documentation and the file watcher will pick up changes, regenerate the docs, and serve them up locally for you to view in a browser.

Docs updates are pushed to the website every time a pull request is merged.