FsVerbalExpressions

The FsVerbalExpressions library provides composable F# functionality for nearly all the capabilites of the .NET Regex class, supporting uniform pipe forward |> composability and all Regex features except timeouts. Optionally you can compose F# verbal expressions in natural language. Lazy evaluation ensures natural language composition imposes no performance penalty.

PM> Install-Package FsVerbalExpressions

Introduction

The FsVerbalExpressions library brings a composable regular expression experience to F#.

• FsRegEx - Module contains composable functions representing all available Regex functionality (except timeouts) with the target input string uniformly the last parameter to better support pipe forward |> composition and partial application.

• Collections returned as F# arrays rather than Regex special collections for better composability (but sacrificing lazy match evaluation and timeout support).

• Short-cut functions like capture on group name make common multi-step processes a single function.

• FsMatch - A composable F# wrapper type over System.Text.RegularExpressions.Match.

• FsGroup - A composable F# wrapper type over System.Text.RegularExpressions.Group.

• VerbEx - A composable F# wrapper type over System.Text.RegularExpressions.Regex for natural language regular expression composition.

• Basic functional operations on VerbEx (exists, fold, foldBack, iter, and map), among other composable functions.

• VerbEx speciall collections are returned as arrays. This does lose the advantange of lazy match evaluation the special collections provide. The underlying object can always be returned from the wrapper. A future release may include matches returned as a lazy list.

Better F# Composition

 1: 
 2: 
 3: 
 4: 
 5: 
 6: 
 7: 
 8: 
 9: 
10: 
11: 
12: 

open FsVerbalExpressions.FsRegEx

let carRegExp = @"(\w+)\s+(car)"

sprintf "%s %s %s" "One car" "red car" "blue car"
|> matches carRegExp
|> Array.map (fun m -> m.Value)
|> Array.iter(fun x -> printfn "%s" x)

// One car
// red car
// blue car

Short-cut common procedures to a single function

1: 
2: 
3: 
4: 
5: 
6: 
7: 
8: 

let groupNumberRegExp = @"COD(?<GroupNumber>[0-9]{3})END"
let groupNumberName = "GroupNumber"

sprintf "%s" "COD123END"
|> capture groupNumberRegExp groupNumberName
|> printfn "%s"

// 123

Natural Language Regular Expressions

 1: 
 2: 
 3: 
 4: 
 5: 
 6: 
 7: 
 8: 
 9: 
10: 
11: 
12: 
13: 
14: 
15: 
16: 
17: 
18: 
19: 
20: 
21: 
22: 
23: 
24: 
25: 
26: 
27: 
28: 
29: 
30: 

open FsVerbalExpressions
open System.Text.RegularExpressions
open VerbalExpression

let allXs = new VerbEx("x+")

let verbEx =
    CommonVerbEx.Email
    |> verbExOrVerbEx RegexOptions.None CommonVerbEx.Url
    |> verbExOrVerbEx RegexOptions.None allXs

let foundEmail =
    verbEx
    |> isMatch "test@github.com"

let foundUrl =
    verbEx
    |> isMatch "http://www.google.com"

let foundAllXs =
    verbEx
    |> isMatch "xxxxx"

printfn "%b" foundEmail
printfn "%b" foundUrl
printfn "%b" foundAllXs

// true
// true
// true

The library also provides the composable Verbal Expressions language for constructing simple regular expressions in a readable fashion.

 1: 
 2: 
 3: 
 4: 
 5: 
 6: 
 7: 
 8: 
 9: 
10: 
11: 
12: 
13: 

let groupName =  "GroupNumber"
 
VerbEx()
|> add "COD"
|> beginCaptureNamed groupName
|> any "0-9"
|> repeatPrevious 3
|> endCapture
|> then' "END"
|> capture "COD123END" groupName
|> printfn "%s"

// 123

A comparison of using Regex natively, and Verbex to retrieve the database parameter from a connection string:

 1: 
 2: 
 3: 
 4: 
 5: 
 6: 
 7: 
 8: 
 9: 
10: 
11: 
12: 
13: 
14: 
15: 
16: 
17: 

let TestConnString = 
    """<add name="MyConnString" connectionString="Server=MyServer;Database=MyDatabase;User ID=me;Password=secret;Encrypt=True;TrustServerCertificate=True;Enlist=False;" />"""

let databaseFromRegex connectionString =
        
    Regex.Match(connectionString, "[dD]atabase=(?<database>.*?);").Groups.["database"].Value

let databaseFromVerbEx connectionString =

    VerbEx()
    |> add "[dD]atabase=(?<database>.*?);"
    |> capture connectionString "database"

(databaseFromRegex TestConnString) = (databaseFromVerbEx TestConnString) 
|> printfn "%b"

// true

This example shows the more verbose and desctriptive Verbal Expressions:

 1: 
 2: 
 3: 
 4: 
 5: 
 6: 
 7: 
 8: 
 9: 
10: 
11: 
12: 
13: 
14: 
15: 

let databaseFromVerboseVerbEx connectionString =

    VerbEx()
    |> anyOf "dD"
    |> then' "atabase="
    |> beginCaptureNamed "database"
    |> add ".*?"
    |> endCapture
    |> then' ";"
    |> capture connectionString "database"

(databaseFromRegex TestConnString) = (databaseFromVerboseVerbEx TestConnString) 
|> printfn "%b"

// true

Documentation

FsVerbalExpressions comes with comprehensive API documentation and a tutorial.

• API Reference contains documentation for all types, modules, and functions in the library.

• F# Verbal Expressions Tutorial contains further explanation of FsVerbalExpressions natural language syntax and many more usage examples.

• For enhanced debugging and API documentation experience, FsVerbalExpressions implements SourceLink

Versioning

FsVerbalExpressions adheres to Semantic Versioning. So long as the project is pre-1.0.0 minor versions may be breaking. Once the project reaches 1.0.0 minor enhancements will be backwards-compatible.

Contributing and copyright

FsVerbalExpressions is hosted on GitHub where you can report issues, fork the project, and submit pull requests, so long as pull requests:

• include excellent unit test coverage
• include correct intellisense documentation
• adhere to the concepts of composability and Verbal Expressions

FsVerbalExpressions is available under Public Domain license, which allows modification and redistribution for both commercial and non-commercial purposes. For more information see the License file in the GitHub repository.

• FSharpVerbalExpressions
• Home page
• Get Library via NuGet
• Source Code on GitHub
• License
• Release Notes
• Getting started
• F# Verbal Expressions Tutorial
• Examples
• Matching
• Match Groups
• Replace and Split
• Capture
• Documentation
• API Reference