FSharp.Formatting


BinderScriptNotebook

Code formatting

This page demonstrates how to use FSharp.Formatting.CodeFormat to tokenize F# source code, obtain information about the source code (mainly tooltips from the type-checker) and how to turn the code into a nicely formatted HTML.

First, we need to load the assembly and open necessary namespaces:

open FSharp.Formatting.CodeFormat
open System.Reflection

If you want to process multiple snippets, it is a good idea to keep the formatting agent around if possible. The agent needs to load the F# compiler (which needs to load various files itself) and so this takes a long time.

Processing F# source

The formatting agent provides a CodeFormatAgent.ParseAndCheckSource method (together with an asynchronous version for use from F# and also a version that returns a .NET Task for C#). To call the method, we define a simple F# code as a string:

let source =
    """
    let hello () =
      printfn "Hello world"
  """

let snippets, diagnostics =
    CodeFormatter.ParseAndCheckSource("C:\\snippet.fsx", source, None, None, ignore)

When calling the method, you need to specify a file name and the actual content of the script file. The file does not have to physically exist. It is used by the F# compiler to resolve relative references (e.g. #r) and to automatically name the module including all code in the file.

You can also specify additional parameters, such as *.dll references, by passing a third argument with compiler options (e.g. "-r:Foo.dll -r:Bar.dll").

This operation might take some time, so it is a good idea to use an asynchronous variant of the method. It returns two arrays - the first contains F# snippets in the source code and the second contains any errors reported by the compiler. A single source file can include multiple snippets using the same formatting tags as those used on fssnip.net as documented in the about page.

Working with returned tokens

Each returned snippet is essentially just a collection of lines and each line consists of a sequence of tokens. The following snippet prints basic information about the tokens of our sample snippet:

// Get the first snippet and obtain list of lines
let (Snippet (title, lines)) = snippets |> Seq.head

// Iterate over all lines and all tokens on each line
for (Line (_, tokens)) in lines do
    for token in tokens do
        match token with
        | TokenSpan.Token (kind, code, tip) ->
            printf "%s" code

            tip
            |> Option.iter (fun spans -> printfn "%A" spans)
        | TokenSpan.Omitted _
        | TokenSpan.Output _
        | TokenSpan.Error _ -> ()

    printfn ""

The TokenSpan.Token is the most important kind of token. It consists of a kind (identifier, keyword, etc.), the original F# code and tool tip information. The tool tip is further formatted using a simple document format, but we simply print the value using the F# pretty printing, so the result looks as follows:

let hello[Literal "val hello : unit -> unit"; ...] () =
  printfn[Literal "val printfn : TextWriterFormat<'T> -> 'T"; ...] "Hello world"

The Omitted token is generated if you use the special (*[omit:...]*) command. The Output token is generated if you use the // [fsi:...] command to format output returned by F# interactive. The Error command wraps code that should be underlined with a red squiggle if the code contains an error.

Generating HTML output

Finally, the CodeFormat type also includes a method CodeFormat.FormatHtml that can be used to generate nice HTML output from an F# snippet. This is used, for example, on F# Snippets. The following example shows how to call it:

let prefix = "fst"
let html = CodeFormat.FormatHtml(snippets, prefix)

// Print all snippets, in case there is more of them
for snip in html.Snippets do
    printfn "%s" snip.Content

// Print HTML code that is generated for ToolTips
printfn "%s" html.ToolTip

If the input contains multiple snippets separated using the //[snippet:...] comment, e.g.:

1: 
2: 
3: 
4: 
5: 
6: 
7: 
// [snippet: First sample]
printf "The answer is: %A" 42
// [/snippet]
// [snippet: Second sample]
printf "Hello world!"
// [/snippet]

then the formatter returns multiple HTML blocks. However, the generated tool tips are shared by all snippets (to save space) and so they are returned separately.

Multiple items
namespace FSharp

--------------------
namespace Microsoft.FSharp
namespace FSharp.Formatting
namespace FSharp.Formatting.CodeFormat
namespace System
namespace System.Reflection
val source: string
val snippets: Snippet[]
val diagnostics: SourceError[]
module CodeFormatter from FSharp.Formatting.CodeFormat
<summary> Uses agent to handle formatting requests </summary>
val ParseAndCheckSource: file: string * source: string * options: string option * defines: string option * onError: (string -> unit) -> Snippet[] * SourceError[]
<summary> Parse, check and annotate the source code specified by 'source', assuming that it is located in a specified 'file'. Optional arguments can be used to give compiler command line options and preprocessor definitions </summary>
union case Option.None: Option<'T>
<summary>The representation of "No value"</summary>
val ignore: value: 'T -> unit
<summary>Ignore the passed value. This is often used to throw away results of a computation.</summary>
<param name="value">The value to ignore.</param>
<example id="min-example"><code lang="fsharp"> ignore 55555 // Evaluates to () </code></example>
Multiple items
union case Snippet.Snippet: string * Line list -> Snippet

--------------------
type Snippet = | Snippet of string * Line list
<summary> An F# snippet consists of a snippet title and a list of lines </summary>
val title: string
val lines: Line list
module Seq from Microsoft.FSharp.Collections
<summary>Contains operations for working with values of type <see cref="T:Microsoft.FSharp.Collections.seq`1" />.</summary>
val head: source: seq<'T> -> 'T
<summary>Returns the first element of the sequence.</summary>
<param name="source">The input sequence.</param>
<returns>The first element of the sequence.</returns>
<exception cref="T:System.ArgumentNullException">Thrown when the input sequence is null.</exception>
<exception cref="T:System.ArgumentException">Thrown when the input does not have any elements.</exception>
<example id="head-1"><code lang="fsharp"> let inputs = ["banana"; "pear"] inputs |&gt; Seq.head </code> Evaluates to <c>banana</c></example>
<example id="head-2"><code lang="fsharp"> [] |&gt; Seq.head </code> Throws <c>ArgumentException</c></example>
Multiple items
union case Line.Line: originalLine: string * tokenSpans: TokenSpans -> Line

--------------------
type Line = | Line of originalLine: string * tokenSpans: TokenSpans
<summary> Represents a line of source code as a list of TokenSpan values. This is a single case discriminated union with Line constructor. </summary>
val tokens: TokenSpans
val token: TokenSpan
type TokenSpan = | Token of TokenKind * string * ToolTipSpans option | Error of ErrorKind * string * TokenSpans | Omitted of string * string | Output of string
<summary> A token in a parsed F# code snippet. Aside from standard tokens reported from the compiler (Token), this also includes Error (wrapping the underlined tokens), Omitted for the special [omit:...] tags and Output for the special [output:...] tag </summary>
union case TokenSpan.Token: TokenKind * string * ToolTipSpans option -> TokenSpan
val kind: TokenKind
val code: string
val tip: ToolTipSpans option
val printf: format: Printf.TextWriterFormat<'T> -> 'T
<summary>Print to <c>stdout</c> using the given format.</summary>
<param name="format">The formatter.</param>
<returns>The formatted result.</returns>
<example>See <c>Printf.printf</c> (link: <see cref="M:Microsoft.FSharp.Core.PrintfModule.PrintFormat``1" />) for examples.</example>
module Option from Microsoft.FSharp.Core
<summary>Contains operations for working with options.</summary>
<category>Options</category>
val iter: action: ('T -> unit) -> option: 'T option -> unit
<summary><c>iter f inp</c> executes <c>match inp with None -&gt; () | Some x -&gt; f x</c>.</summary>
<param name="action">A function to apply to the option value.</param>
<param name="option">The input option.</param>
<example id="iter-1"><code lang="fsharp"> None |&gt; Option.iter (printfn "%s") // does nothing Some "Hello world" |&gt; Option.iter (printfn "%s") // prints "Hello world" </code></example>
val spans: ToolTipSpans
val printfn: format: Printf.TextWriterFormat<'T> -> 'T
<summary>Print to <c>stdout</c> using the given format, and add a newline.</summary>
<param name="format">The formatter.</param>
<returns>The formatted result.</returns>
<example>See <c>Printf.printfn</c> (link: <see cref="M:Microsoft.FSharp.Core.PrintfModule.PrintFormatLine``1" />) for examples.</example>
union case TokenSpan.Omitted: string * string -> TokenSpan
union case TokenSpan.Output: string -> TokenSpan
union case TokenSpan.Error: ErrorKind * string * TokenSpans -> TokenSpan
Multiple items
type LiteralAttribute = inherit Attribute new: unit -> LiteralAttribute
<summary>Adding this attribute to a value causes it to be compiled as a CLI constant literal.</summary>
<category>Attributes</category>


--------------------
new: unit -> LiteralAttribute
val prefix: string
val html: FormattedContent
type CodeFormat = static member FormatFsx: snippets: seq<Snippet> -> FormattedContent static member FormatHtml: snippets: Snippet[] * prefix: string * ?openTag: string * ?closeTag: string * ?lineNumbers: bool * ?openLinesTag: string * ?closeLinesTag: string * ?addErrors: bool * ?tokenKindToCss: (TokenKind -> string) -> FormattedContent static member FormatLatex: snippets: Snippet[] * ?openTag: string * ?closeTag: string * ?lineNumbers: bool -> FormattedContent
<summary> Exposes functionality of the F# code formatter with a nice interface </summary>
static member CodeFormat.FormatHtml: snippets: Snippet[] * prefix: string * ?openTag: string * ?closeTag: string * ?lineNumbers: bool * ?openLinesTag: string * ?closeLinesTag: string * ?addErrors: bool * ?tokenKindToCss: (TokenKind -> string) -> FormattedContent
val snip: FormattedSnippet
property FormattedContent.Snippets: FormattedSnippet[] with get
<summary> Returns the processed snippets as an array </summary>
property FormattedSnippet.Content: string with get
<summary> Returns the formatted content code for the snipet </summary>
property FormattedContent.ToolTip: string with get
<summary> Returns string with ToolTip elements for all the snippets </summary>