7 |
8 |
16 |
17 | Using Chessie with Paket
18 | ------------------------
19 |
20 | Chessie is a single-file module, so it's convienient to get it with [Paket GitHub dependencies][deps].
21 | To do so, just add following line to your `paket.dependencies` file:
22 |
23 | github fsprojects/Chessie src/Chessie/ErrorHandling.fs
24 |
25 | and following line to your `paket.references` file for the desired project:
26 |
27 | File:ErrorHandling.fs .
28 |
29 |
30 | Samples & documentation
31 | -----------------------
32 |
33 | * Read the [tutorial](railway.html) to see how to use Chessie for railway-oriented programming.
34 | * [API Reference](reference/index.html) contains automatically generated documentation for all types, modules and functions in the library.
35 | This includes additional brief samples on using most of the functions.
36 |
37 | Contributing and copyright
38 | --------------------------
39 |
40 | The project is hosted on [GitHub][gh] where you can [report issues][issues], fork
41 | the project and submit pull requests. If you're adding a new public API, please also
42 | consider adding [samples][content] that can be turned into a documentation. You might
43 | also want to read the [library design notes][readme] to understand how it works.
44 |
45 | The library is available under Apache 2.0 license, which allows modification and
46 | redistribution for both commercial and non-commercial purposes. For more information see the
47 | [License file][license] in the GitHub repository.
48 |
49 | [content]: https://github.com/fsprojects/Chessie/tree/master/docs/content
50 | [gh]: https://github.com/fsprojects/Chessie
51 | [issues]: https://github.com/fsprojects/Chessie/issues
52 | [readme]: https://github.com/fsprojects/Chessie/blob/master/README.md
53 | [license]: https://github.com/fsprojects/Chessie/blob/master/LICENSE.txt
54 | [deps]: https://fsprojects.github.io/Paket/github-dependencies.html
55 |
--------------------------------------------------------------------------------
/docs/content/pass-warn-fail.fsx:
--------------------------------------------------------------------------------
1 | (*** hide ***)
2 | #I "../../bin"
3 |
4 | #r "Chessie.dll"
5 | open Chessie.ErrorHandling
6 |
7 | open System
8 | open System.Drawing
9 |
10 | (**
11 | Combining terminal and non-terminal errors
12 | ===
13 |
14 | One feature of programming with "two-track" data is that once a value is on the _failure track_
15 | operations against it may be skipped if they expect a value on the _passing track_. However, this
16 | is not always the desired behavior. In many cases, we will want to perform mulitple operations on a
17 | value and record any unusual or interesting results, but still keep thing on the _passing track_.
18 | One obvious scenario is when we want to validate multiple pieces of input (such as might be
19 | received from an HTTP request).
20 | *)
21 |
22 | type Applicant =
23 | { FullName :string * string
24 | DateOfBirth :DateTime
25 | FavoriteColor :Color option }
26 |
27 | (**
28 | Given some aggregate user-supplied data, we want to check each datum.
29 | *)
30 |
31 | let checkName getName msg request =
32 | let name = getName request
33 | if String.IsNullOrWhiteSpace name
34 | then // note the invalid datum, but stay on the _passing_ track
35 | request |> warn msg
36 | else // no issues, proceed on the "happy path"
37 | request |> pass
38 |
39 | let checkFirstName = checkName (fun {FullName = (name,_)} -> name) "First name is missing"
40 | let checkLastName = checkName (fun {FullName = (_,name)} -> name) "Last name is missing"
41 |
42 | let checkAge request =
43 | let dob = request.DateOfBirth
44 | let diff = DateTime.Today.Subtract dob
45 | if diff < TimeSpan.FromDays (18.0 * 365.0)
46 | then // note the invalid datum, but stay on the _passing_ track
47 | request |> warn "DateOfBirth is too recent"
48 | else // no issues, proceed on the "happy path"
49 | request |> pass
50 |
51 | (**
52 | Now we can combine our individual checks, returning the original value along-side any issues.
53 | *)
54 |
55 | (*** define-output: warnings ***)
56 | let checkApplicant request =
57 | request
58 | |> checkAge
59 | |> bind checkFirstName
60 | |> bind checkLastName
61 |
62 | let processRequest request =
63 | match checkApplicant request with
64 | | Pass _ -> printfn "All Good!!!"
65 | | Warn (_,log) -> printfn "Got some issues:"
66 | for msg in log do printfn " %s" msg
67 | | _ -> printfn "Something went horribly wrong."
68 |
69 |
70 | // good request
71 | processRequest {FullName = "John","Smith"
72 | DateOfBirth = DateTime (1995,12,21)
73 | FavoriteColor = None}
74 | // bad request
75 | processRequest {FullName = "Beck",""
76 | DateOfBirth = DateTime (2005,04,13)
77 | FavoriteColor = Some Color.Gold}
78 |
79 | (*** include-output: warnings ***)
80 |
81 | (**
82 | We can also mixed warnings in with operations that are terminal. In other words, we can still build
83 | workflows where certain operations switch the data over to the _failure track_.
84 | *)
85 |
86 | (*** define-output: two-and-three-track ***)
87 | let disallowPink request =
88 | match request.FavoriteColor with
89 | | Some c // no idea why we're being mean to this particular color
90 | when c = Color.Pink -> fail "Get outta here with that color!"
91 | | _ -> pass request
92 |
93 | let recheckApplicant request =
94 | request
95 | |> checkAge
96 | |> bind disallowPink
97 | |> bind checkFirstName
98 | |> bind checkLastName
99 |
100 | let reportMessages request =
101 | match recheckApplicant request with
102 | | Pass _ -> printfn "Nothing to report"
103 | | Warn (_,log) -> printfn "Got some issues:"
104 | for msg in log do printfn " %s" msg
105 | | Fail errors -> printfn "Got errors:"
106 | for msg in errors do printfn " %s" msg
107 |
108 | // terminal request
109 | reportMessages {FullName = "John","Smith"
110 | DateOfBirth = DateTime (1995,12,21)
111 | FavoriteColor = Some Color.Pink}
112 |
113 | // non-terminal request with warnings
114 | reportMessages {FullName = "","Smith"
115 | DateOfBirth = DateTime (1995,12,21)
116 | FavoriteColor = Some Color.Green}
117 | // good request
118 | reportMessages {FullName = "Bob","Smith"
119 | DateOfBirth = DateTime (1995,12,21)
120 | FavoriteColor = Some Color.Green}
121 |
122 | (*** include-output: two-and-three-track ***)
123 |
124 | (**
125 | In effect, we've turned "two-track" data into "three-track" data. But we can also flip this around.
126 | That's is, run operations over the data accumlating warnings. Then at the end, if we have any
127 | messages at all, switch to the _failure track_.
128 | *)
129 |
130 | (*** define-output: fail-on-warn ***)
131 | let warnOnNoColor request =
132 | match request.FavoriteColor with
133 | | None -> request |> warn "No color provided"
134 | | Some _ -> pass request
135 |
136 | let ``checkApplicant (again)`` request =
137 | request
138 | |> checkAge
139 | |> bind checkFirstName
140 | |> bind checkLastName
141 | |> bind warnOnNoColor
142 |
143 | let ``processRequest (again)`` request =
144 | // turn any warning messages into failure messages
145 | let result = request
146 | |> ``checkApplicant (again)``
147 | |> failOnWarnings
148 | // now we only have 2 tracks on which the data may lay
149 | match result with
150 | | Fail errors -> for x in errors do printfn "ERROR! %s" x
151 | | _ -> printfn "SUCCESS!!!"
152 |
153 | // terminal request
154 | ``processRequest (again)`` {FullName = "",""
155 | DateOfBirth = DateTime.Today
156 | FavoriteColor = None}
157 |
158 | (*** include-output: fail-on-warn ***)
159 |
--------------------------------------------------------------------------------
/docs/content/railway.fsx:
--------------------------------------------------------------------------------
1 | (*** hide ***)
2 | #I "../../bin"
3 |
4 | (**
5 |
6 | Using Chessie for Railway-oriented programming (ROP)
7 | ====================================================
8 |
9 | This tutorial is based on an article about [Railway-oriented programming](http://fsharpforfunandprofit.com/posts/recipe-part2/) by Scott Wlaschin.
10 |
11 | Additional resources:
12 |
13 | * Railway Oriented Programming by Scott Wlaschin - A functional approach to error handling
14 | * [Slide deck](http://www.slideshare.net/ScottWlaschin/railway-oriented-programming)
15 | * [Video](https://vimeo.com/97344498)
16 |
17 | We start by referencing Chessie and opening the ErrorHandling module:
18 | *)
19 |
20 | #r "Chessie.dll"
21 |
22 | open Chessie.ErrorHandling
23 |
24 | (**
25 | Now we define some simple validation functions:
26 | *)
27 |
28 | type Request =
29 | { Name : string
30 | EMail : string }
31 |
32 | let validateInput input =
33 | if input.Name = "" then fail "Name must not be blank"
34 | elif input.EMail = "" then fail "Email must not be blank"
35 | else ok input // happy path
36 |
37 | let validate1 input =
38 | if input.Name = "" then fail "Name must not be blank"
39 | else ok input
40 |
41 | let validate2 input =
42 | if input.Name.Length > 50 then fail "Name must not be longer than 50 chars"
43 | else ok input
44 |
45 | let validate3 input =
46 | if input.EMail = "" then fail "Email must not be blank"
47 | else ok input
48 |
49 | let combinedValidation =
50 | // connect the two-tracks together
51 | validate1
52 | >> bind validate2
53 | >> bind validate3
54 |
55 | (**
56 | Let's use these with some basic combinators:
57 | *)
58 |
59 | { Name = ""; EMail = "" }
60 | |> combinedValidation
61 | // [fsi:val it : Chessie.ErrorHandling.Result
9 |
14 |
15 |
10 | The Chessie library can be installed from NuGet:
11 |
13 | PM> Install-Package Chessie12 |
24 |
32 |
60 |
25 |
29 |
31 | @Properties["project-name"]
30 |32 |
33 |
59 |
34 | @RenderBody()
35 |
36 |
37 | 
38 |
57 |
58 |
38 |
57 | 
61 |
62 |
63 |
--------------------------------------------------------------------------------
/global.json:
--------------------------------------------------------------------------------
1 | {
2 | "projects": [ "src", "tests" ]
3 | }
4 |
--------------------------------------------------------------------------------
/lib/README.md:
--------------------------------------------------------------------------------
1 | This file is in the `lib` directory.
2 |
3 | Any **libraries** on which your project depends and which are **NOT managed via NuGet** should be kept **in this directory**.
4 | This typically includes custom builds of third-party software, private (i.e. to a company) codebases, and native libraries.
5 |
6 | ---
7 | NOTE:
8 |
9 | This file is a placeholder, used to preserve directory structure in Git.
10 |
11 | This file does not need to be edited.
12 |
--------------------------------------------------------------------------------
/paket.dependencies:
--------------------------------------------------------------------------------
1 | source https://nuget.org/api/v2
2 |
3 | nuget FSharp.Core redirects:force
4 |
5 | group Build
6 |
7 | source https://nuget.org/api/v2
8 |
9 | nuget FSharp.Formatting
10 | nuget FAKE
11 | nuget SourceLink.Fake
12 |
13 | github fsharp/FAKE modules/Octokit/Octokit.fsx
14 |
15 | group Test
16 |
17 | source https://nuget.org/api/v2
18 |
19 | nuget NUnit ~> 2
20 | nuget NUnit.Runners ~> 2
21 |
22 | github forki/FsUnit FsUnit.fs
--------------------------------------------------------------------------------
/paket.lock:
--------------------------------------------------------------------------------
1 | NUGET
2 | remote: https://www.nuget.org/api/v2
3 | FSharp.Core (4.0.0.1) - redirects: force
4 |
5 | GROUP Build
6 | NUGET
7 | remote: https://www.nuget.org/api/v2
8 | FAKE (4.34.2)
9 | FSharp.Compiler.Service (2.0.0.6)
10 | FSharp.Formatting (2.14.4)
11 | FSharp.Compiler.Service (2.0.0.6)
12 | FSharpVSPowerTools.Core (>= 2.3 < 2.4)
13 | FSharpVSPowerTools.Core (2.3)
14 | FSharp.Compiler.Service (>= 2.0.0.3)
15 | Microsoft.Bcl (1.1.10) - framework: net10, net11, net20, net30, net35, net40, net40-full
16 | Microsoft.Bcl.Build (>= 1.0.14)
17 | Microsoft.Bcl.Build (1.0.21) - import_targets: false, framework: net10, net11, net20, net30, net35, net40, net40-full
18 | Microsoft.Net.Http (2.2.29) - framework: net10, net11, net20, net30, net35, net40, net40-full
19 | Microsoft.Bcl (>= 1.1.10)
20 | Microsoft.Bcl.Build (>= 1.0.14)
21 | Octokit (0.20)
22 | Microsoft.Net.Http - framework: net10, net11, net20, net30, net35, net40, net40-full
23 | SourceLink.Fake (1.1)
24 | GITHUB
25 | remote: fsharp/FAKE
26 | modules/Octokit/Octokit.fsx (e83eb21f41e71ed7e0cd28e0205a931037266677)
27 | Octokit (>= 0.20)
28 | GROUP Test
29 | NUGET
30 | remote: https://www.nuget.org/api/v2
31 | NUnit (2.6.4)
32 | NUnit.Runners (2.6.4)
33 | GITHUB
34 | remote: forki/FsUnit
35 | FsUnit.fs (f536bd5ed0eba8b38d2b01ae79d64e4e14fbd0a6)
--------------------------------------------------------------------------------
/src/Chessie/AssemblyInfo.fs:
--------------------------------------------------------------------------------
1 | namespace System
2 | open System.Reflection
3 | open System.Runtime.CompilerServices
4 |
5 | [