layout: post
title: “F# syntax: indentation and verbosity”
description: “Understanding the offside rule”
nav: thinking-functionally
seriesId: “Expressions and syntax”

seriesOrder: 5

The syntax for F# is mostly straightforward. But there are a few rules that you should understand if you want to avoid common indentation errors. If you are familiar with a language like Python that also is whitespace sensitive, be aware that that the rules for indentation in F# are subtly different.

Indentation and the “offside” rule

In soccer, the offside rule says that in some situations, a player cannot be “ahead” of the ball when they should be behind or level with it. The “offside line” is the line the player must not cross. F# uses the same term to describe the line at which indentation must start. As with soccer, the trick to avoiding a penalty is to know where the line is and not get ahead of it.

Generally, once an offside line has been set, all the expressions must align with the line.

  1. //character columns
  2. //3456789
  3. let f = 
  4.   let x=1     // offside line is at column 3
  5.   let y=1     // this line must start at column 3
  6.   x+y         // this line must start at column 3 
  8. let f = 
  9.   let x=1     // offside line is at column 3 
  10.    x+1        // oops! don't start at column 4
  11.               // error FS0010: Unexpected identifier in binding
  13. let f = 
  14.   let x=1    // offside line is at column 3 
  15.  x+1         // offside! You are ahead of the ball!
  16.              // error FS0588: Block following this 
  17.              // 'let' is unfinished

Various tokens can trigger new offside lines to be created. For example, when the F# sees the “=“ used in a let expression, a new offside line is created at the position of the very next symbol or word encountered.

  1. //character columns
  2. //34567890123456789
  3. let f =   let x=1  // line is now at column 11 (start of "let x=")
  4.           x+1      // must start at column 11 from now on
  6. //        |        // offside line at col 11 
  7. let f =   let x=1  // line is now at column 11 (start of "let x=")
  8.          x+1       // offside!
  11. // |        // offside line at col 4
  12. let f =  
  13.    let x=1  // first word after = sign defines the line 
  14.             // offside line is now at column 4
  15.    x+1      // must start at column 4 from now on

Other tokens have the same behavior, including parentheses, “then“, “else“, “try“, “finally“ and “do“, and “->“ in match clauses.

  1. //character columns
  2. //34567890123456789
  3. let f = 
  4.    let g = (         
  5.     1+2)             // first char after "(" defines 
  6.                      // a new line at col 5
  7.    g 
  9. let f = 
  10.    if true then
  11.     1+2             // first char after "then" defines 
  12.                     // a new line at col 5
  14. let f = 
  15.    match 1 with 
  16.    | 1 ->
  17.        1+2          // first char after match "->" defines 
  18.                     // a new line at col 8

The offside lines can be nested, and are pushed and popped as you would expect:

  1. //character columns
  2. //34567890123456789
  3. let f = 
  4.    let g = let x = 1 // first word after "let g =" 
  5.                      // defines a new offside line at col 12
  6.            x + 1     // "x" must align at col 12
  7.                      // pop the offside line stack now
  8.    g + 1             // back to previous line. "g" must align
  9.                      // at col 4

New offside lines can never go forward further than the previous line on the stack:

  1. let f = 
  2.    let g = (         // let defines a new line at col 4
  3.   1+2)               // oops! Cant define new line less than 4
  4.    g

Special cases

There are number of special cases which have been created to make code formatting more flexible. Many of them will seem natural, such as aligning the start of each part of an if-then-else expression or a try-catch expression. There are some non-obvious ones, however.

Infix operators such as “+”, “|>” and “>>” are allowed to be outside the line by their length plus one space:

  1. //character columns
  2. //34567890123456789
  3. let x =  1   // defines a new line at col 10
  4.        + 2   // "+" allowed to be outside the line
  5.        + 3
  7. let f g h =   g   // defines a new line at col 15
  8.            >> h   // ">>" allowed to be outside the line

If an infix operator starts a line, that line does not have to be strict about the alignment:

  1. let x =  1   // defines a new line at col 10
  2.         + 2   // infix operators that start a line don't count
  3.              * 3  // starts with "*" so doesn't need to align
  4.          - 4  // starts with "-" so doesn't need to align

If a “fun“ keyword starts an expression, the “fun” does not start a new offside line:

  1. //character columns
  2. //34567890123456789
  3. let f = fun x ->  // "fun" should define a new line at col 9
  4.    let y = 1      // but doesn't. The real line starts here.
  5.    x + y

Finding out more

There are many more details as to how indentation works, but the examples above should cover most of the common cases. If you want to know more, the complete language spec for F# is available from Microsoft as a downloadable PDF, and is well worth reading.

“Verbose” syntax

By default, F# uses indentation to indicate block structure — this is called “light” syntax. There is an alternative syntax that does not use indentation; it is called “verbose” syntax. With verbose syntax, you are not required to use indentation, and whitespace is not significant, but the downside is that you are required to use many more keywords, including things like:

  • “in“ keywords after every “let” and “do” binding
  • “begin“/“end“ keywords for code blocks such as if-then-else
  • “done“ keywords at the end of loops
  • keywords at the beginning and end of type definitions

Here is an example of verbose syntax with wacky indentation that would not otherwise be acceptable:

  1. #indent "off"
  3.       let f = 
  4.     let x = 1 in
  5.   if x=2 then 
  6. begin "a" end else begin
  7. "b" 
  8. end
  10. #indent "on"

Verbose syntax is always available, even in “light” mode, and is occasionally useful. For example, when you want to embed “let” into a one line expression:

  1. let x = let y = 1 in let z = 2 in y + z

Other cases when you might want to use verbose syntax are:

  • when outputting generated code
  • to be compatible with OCaml
  • if you are visually impaired or blind and use a screen reader
  • or just to gain some insight into the abstract syntax tree used by the F# parser

Other than these cases, verbose syntax is rarely used in practice.