F Sharp Programming/Modules and Namespaces

F# : Modules and Namespaces

Modules and Namespaces are primarily used for grouping and organizing code.

Defining Modules

No code is required to define a module. If a codefile does not contain a leading namespace or module declaration, F# code will implicitly place the code in a module, where the name of the module is the same as the file name with the first letter capitalized.

To access code in another module, simply use . notation: moduleName.member. Notice that this notation is similar to the syntax used to access static members—this is not a coincidence. F# modules are compiled as classes which only contain static members, values, and type definitions.

Let's create two files:

DataStructures.fs

type 'a Stack =
    | EmptyStack
    | StackNode of 'a * 'a Stack

let rec getRange startNum endNum =
    if startNum > endNum then EmptyStack
    else StackNode(startNum, getRange (startNum+1) endNum)

Program.fs

let x =
    DataStructures.StackNode(1,
        DataStructures.StackNode(2,
            DataStructures.StackNode(3, DataStructures.EmptyStack)))
            
let y = DataStructures.getRange 5 10
            
printfn "%A" x
printfn "%A" y

This program outputs:

StackNode (1,StackNode (2,StackNode (3,EmptyStack)))
StackNode
  (5,
   StackNode
     (6,StackNode (7,StackNode (8,StackNode (9,StackNode (10,EmptyStack))))))

Note: Remember, order of compilation matters in F#. Dependencies must come before dependents, so DataStructures.fs comes before Program.fs when compiling this program.

Like all modules, we can use the open keyword to give us access to the methods inside a module without fully qualifying the naming of the method. This allows us to revise Program.fs as follows:

open DataStructures

let x = StackNode(1, StackNode(2, StackNode(3, EmptyStack)))
let y = getRange 5 10
            
printfn "%A" x
printfn "%A" y

Submodules

Its very easy to create submodules using the module keyword:

(* DataStructures.fs *)

type 'a Stack =
    | EmptyStack
    | StackNode of 'a * 'a Stack

module StackOps =
    let rec getRange startNum endNum =
        if startNum > endNum then EmptyStack
        else StackNode(startNum, getRange (startNum+1) endNum)

Since the getRange method is under another module, the fully qualified name of this method is DataStructures.StackOps.getRange. We can use it as follows:

(* Program.fs *)

open DataStructures

let x =
    StackNode(1, StackNode(2, StackNode(3, EmptyStack)))
            
let y = StackOps.getRange 5 10
            
printfn "%A" x
printfn "%A" y

F# allows us to create a module and a type having the same name, for example the following code is perfectly acceptable:

type 'a Stack =
    | EmptyStack
    | StackNode of 'a * 'a Stack

module Stack =
    let rec getRange startNum endNum =
        if startNum > endNum then EmptyStack
        else StackNode(startNum, getRange (startNum+1) endNum)

Note: Its possible to nest submodules inside other submodules. However, as a general principle, its best to avoid creating complex module hierarchies. Functional programming libraries tend to be very "flat" with nearly all functionality accessible in the first 2 or 3 levels of a hierarchy. This is in contrast to many other OO languages which encourage programmers to create deeply nested class libraries, where functionality might be buried 8 or 10 levels down the hierarchy.

Extending Types and Modules

F# supports extension methods, which allow programmers to add new static and instance methods to classes and modules without inheriting from them.

Extending a Module

The Seq module contains several pairs of methods:

iter/iteri
map/mapi

Seq has a forall member, but does not have a corresponding foralli function, which includes the index of each sequence element. We add this missing method to the module simply by creating another module with the same name. For example, using fsi:

> module Seq =
    let foralli f s =
        s
        |> Seq.mapi (fun i x -> i, x)        (* pair item with its index *)
        |> Seq.forall (fun (i, x) -> f i x) (* apply item and index to function *)

let isPalindrome (input : string) =
    input
    |> Seq.take (input.Length / 2)
    |> Seq.foralli (fun i x -> x = input.[input.Length - i - 1]);;

module Seq = begin
  val foralli : (int -> 'a -> bool) -> seq<'a> -> bool
end
val isPalindrome : string -> bool

> isPalindrome "hello";;
val it : bool = false
> isPalindrome "racecar";;
val it : bool = true

Extending a Type

The System.String has many useful methods, but let's say we thought it was missing a few important functions, Reverse and IsPalindrome. Since this class is marked as sealed or NotInheritable, we can't create a derived version of this class. Instead, we create a module with the new methods we want. Here's an example in fsi which demonstrates how to add new static and instance methods to the String class:

> module Seq =
    let foralli f s =
        s
        |> Seq.mapi (fun i x -> i, x)        (* pair item with its index *)
        |> Seq.forall (fun (i, x) -> f i x) (* apply item and index to function *)

module StringExtensions =
    type System.String with           
        member this.IsPalindrome =
            this
            |> Seq.take (this.Length / 2)
            |> Seq.foralli (fun i x -> this.[this.Length - i - 1] = x)
    
        static member Reverse(s : string) =
            let chars : char array =
                let temp = Array.zeroCreate s.Length
                let charsToTake = if temp.Length % 2 <> 0 then (temp.Length + 1) / 2 else temp.Length / 2
                    
                s
                |> Seq.take charsToTake
                |> Seq.iteri (fun i x ->
                    temp.[i] <- s.[temp.Length - i - 1]
                    temp.[temp.Length - i - 1] <- x)
                temp
            new System.String(chars)

open StringExtensions;;

module Seq = begin
  val foralli : (int -> 'a -> bool) -> seq<'a> -> bool
end
module StringExtensions = begin
end

> "hello world".IsPalindrome;;
val it : bool = false
> System.String.Reverse("hello world");;
val it : System.String = "dlrow olleh"

Module Signatures

By default, all members in a module are accessible from outside the module. However, a module often contain members which should not be accessible outside itself, such as helper functions. One way to expose only a subset of a module's members is by creating a signature file for that module. (Another way is to apply .Net CLR access modifiers of public, internal, or private to individual declarations).

Signature files have the same name as their corresponding module, but end with a ".fsi" extension (f-sharp interface). Signature files always come before their implementation files, which have a corresponding ".fs" extension. For example:

DataStructures.fsi

type 'a stack =
    | EmptyStack
    | StackNode of 'a * 'a stack
    
module Stack =
    val getRange : int -> int -> int stack
    val hd : 'a stack -> 'a
    val tl : 'a stack -> 'a stack
    val fold : ('a -> 'b -> 'a) -> 'a -> 'b stack -> 'a
    val reduce : ('a -> 'a -> 'a) -> 'a stack -> 'a

DataStructures.fs

type 'a stack =
    | EmptyStack
    | StackNode of 'a * 'a stack

module Stack =
    (* helper functions *)
    let internal_head_tail = function
        | EmptyStack -> failwith "Empty stack"
        | StackNode(hd, tail) -> hd, tail
        
    let rec internal_fold_left f acc = function
        | EmptyStack -> acc
        | StackNode(hd, tail) -> internal_fold_left f (f acc hd) tail
    
    (* public functions *)
    let rec getRange startNum endNum =
        if startNum > endNum then EmptyStack
        else StackNode(startNum, getRange (startNum+1) endNum)
            
    let hd s = internal_head_tail s |> fst
    let tl s = internal_head_tail s |> snd
    let fold f seed stack = internal_fold_left f seed stack
    let reduce f stack = internal_fold_left f (hd stack) (tl stack)

Program.fs

open DataStructures

let x = Stack.getRange 1 10
printfn "%A" (Stack.hd x)
printfn "%A" (Stack.tl x)
printfn "%A" (Stack.fold ( * ) 1 x)
printfn "%A" (Stack.reduce ( + ) x)
(* printfn "%A" (Stack.internal_head_tail x) *) (* will not compile *)

Since Stack.internal_head_tail is not defined in our interface file, the method is marked private and no longer accessible outside of the DataStructures module.

Module signatures are useful to building a code library's skeleton, however they have a few caveats. If you want to expose a class, record, or union in a module through a signature, then the signature file must expose all of the objects members, records fields, and union's cases. Additionally, the signature of the function defined in the module and it's corresponding signature in the signature file must match exactly. Unlike OCaml, F# does not allow a function in a module with the generic type 'a -> 'a -> 'a to be restricted to int -> int -> int in the signature file.

Defining Namespaces

A namespace is a hierarchical categorization of modules, classes, and other namespaces. For example, the System.Collections namespace groups together all of the collections and data structures in the .NET BCL, whereas the System.Security.Cryptography namespace groups together all classes which provide cryptographic services.

Namespaces are primarily used to avoid name conflicts. For example, let's say we were writing an application incorporated code from several different vendors. If Vendor A and Vendor B both have a class called Collections.Stack, and we wrote the code let s = new Stack(), how would the compiler know whether which stack we intended to create? Namespaces can eliminate this ambiguity by adding one more layer of grouping to our code.

Code is grouped under a namespace using the namespace keyword:

DataStructures.fsi

namespace Princess.Collections
    type 'a stack =
        | EmptyStack
        | StackNode of 'a * 'a stack
        
    module Stack =
        val getRange : int -> int -> int stack
        val hd : 'a stack -> 'a
        val tl : 'a stack -> 'a stack
        val fold : ('a -> 'b -> 'a) -> 'a -> 'b stack -> 'a
        val reduce : ('a -> 'a -> 'a) -> 'a stack -> 'a

DataStructures.fs

namespace Princess.Collections

    type 'a stack =
        | EmptyStack
        | StackNode of 'a * 'a stack

    module Stack =
        (* helper functions *)
        let internal_head_tail = function
            | EmptyStack -> failwith "Empty stack"
            | StackNode(hd, tail) -> hd, tail
            
        let rec internal_fold_left f acc = function
            | EmptyStack -> acc
            | StackNode(hd, tail) -> internal_fold_left f (f acc hd) tail
        
        (* public functions *)
        let rec getRange startNum endNum =
            if startNum > endNum then EmptyStack
            else StackNode(startNum, getRange (startNum+1) endNum)
                
        let hd s = internal_head_tail s |> fst
        let tl s = internal_head_tail s |> snd
        let fold f seed stack = internal_fold_left f seed stack
        let reduce f stack = internal_fold_left f (hd stack) (tl stack)

Program.fs

open Princess.Collections

let x = Stack.getRange 1 10
printfn "%A" (Stack.hd x)
printfn "%A" (Stack.tl x)
printfn "%A" (Stack.fold ( * ) 1 x)
printfn "%A" (Stack.reduce ( + ) x)

Where is the DataStructures Module?

You may have expected the code in Program.fs above to open Princess.Collections.DataStructures rather than Princess.Collections. According to the F# spec, F# treats anonymous implementation files (which are files without a leading module or namespace declaration) by putting all code in an implicit module which matches the code's filename. Since we have a leading namespace declaration, F# does not create the implicit module.

.NET does not permit users to create functions or values outside of classes or modules. As a consequence, we cannot write the following code:

namespace Princess.Collections

    type 'a stack =
        | EmptyStack
        | StackNode of 'a * 'a stack
        
    let somefunction() = 12   (* <--- functions not allowed outside modules *)

    (* ... *)

If we prefer to have a module called DataStructures, we can write this:

namespace Princess.Collections
    module DataStructures
        type 'a stack =
            | EmptyStack
            | StackNode of 'a * 'a stack
            
        let somefunction() = 12

        (* ... *)

Or equivalently, we define a module and place it a namespace simultaneously using:

module Princess.Collections.DataStructures
    type 'a stack =
        | EmptyStack
        | StackNode of 'a * 'a stack
        
    let somefunction() = 12

    (* ... *)

Adding to Namespace from Multiple Files

Unlike modules and classes, any file can contribute to a namespace. For example:

DataStructures.fs

namespace Princess.Collections

    type 'a stack =
        | EmptyStack
        | StackNode of 'a * 'a stack

    module Stack =
        (* helper functions *)
        let internal_head_tail = function
            | EmptyStack -> failwith "Empty stack"
            | StackNode(hd, tail) -> hd, tail
            
        let rec internal_fold_left f acc = function
            | EmptyStack -> acc
            | StackNode(hd, tail) -> internal_fold_left f (f acc hd) tail
        
        (* public functions *)
        let rec getRange startNum endNum =
            if startNum > endNum then EmptyStack
            else StackNode(startNum, getRange (startNum+1) endNum)
                
        let hd s = internal_head_tail s |> fst
        let tl s = internal_head_tail s |> snd
        let fold f seed stack = internal_fold_left f seed stack
        let reduce f stack = internal_fold_left f (hd stack) (tl stack)

MoreDataStructures.fs

namespace Princess.Collections
    
    type 'a tree when 'a :> System.IComparable<'a> =
        | EmptyTree
        | TreeNode of 'a * 'a tree * 'a tree
        
    module Tree =
        let rec insert (x : #System.IComparable<'a>) = function
            | EmptyTree -> TreeNode(x, EmptyTree, EmptyTree)
            | TreeNode(y, l, r) as node ->
                match x.CompareTo(y) with
                | 0 -> node
                | 1 -> TreeNode(y, l, insert x r)
                | -1 -> TreeNode(y, insert x l, r)
                | _ -> failwith "CompareTo returned illegal value"

Since we have a leading namespace declaration in both files, F# does not create any implicit modules. The 'a stack, 'a tree, Stack, and Tree types are all accessible through the Princess.Collections namespace:

Program.fs

open Princess.Collections

let x = Stack.getRange 1 10
let y =
    let rnd = new System.Random()
    [ for a in 1 .. 10 -> rnd.Next(0, 100) ]
    |> Seq.fold (fun acc x -> Tree.insert x acc) EmptyTree
    
printfn "%A" (Stack.hd x)
printfn "%A" (Stack.tl x)
printfn "%A" (Stack.fold ( * ) 1 x)
printfn "%A" (Stack.reduce ( + ) x)
printfn "%A" y

Controlling Class and Module Accessibility

Unlike modules, there is no equivalent to a signature file for namespaces. Instead, the visibility of classes and submodules is controlled through standard accessibility modifiers:

namespace Princess.Collections
    
    type 'a tree when 'a :> System.IComparable<'a> =
        | EmptyTree
        | TreeNode of 'a * 'a tree * 'a tree
        
    (* InvisibleModule is only accessible by classes or
       modules inside the Princess.Collections namespace*)
    module private InvisibleModule =
        let msg = "I'm invisible!"

    module Tree =
        (* InvisibleClass is only accessible by methods
           inside the Tree module *)
        type private InvisibleClass() =
            member x.Msg() = "I'm invisible too!"
    
        let rec insert (x : #System.IComparable<'a>) = function
            | EmptyTree -> TreeNode(x, EmptyTree, EmptyTree)
            | TreeNode(y, l, r) as node ->
                match x.CompareTo(y) with
                | 0 -> node
                | 1 -> TreeNode(y, l, insert x r)
                | -1 -> TreeNode(y, insert x l, r)
                | _ -> failwith "CompareTo returned illegal value"

Previous: Events

Index

Next: Units of Measure