Merge pull request #312 from wallymathieu/try-parse

Documenation and plantuml rendering

FSharpPlus.sln

@@ -94,6 +94,8 @@ Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FSharpPlus.TypeLevel", "src
 EndProject
 Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FSharpPlus.Providers", "src\FSharpPlus\Providers\FSharpPlus.Providers.fsproj", "{9B93F5E5-3D53-42F1-96E2-06E6A7B496A0}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CSharpLib", "tests\CSharpLib\CSharpLib.csproj", "{7A5B766E-8141-4D8A-B3EB-91422FDBDF71}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -168,6 +170,18 @@ Global
 		{9B93F5E5-3D53-42F1-96E2-06E6A7B496A0}.Release|x64.Build.0 = Release|Any CPU
 		{9B93F5E5-3D53-42F1-96E2-06E6A7B496A0}.Release|x86.ActiveCfg = Release|Any CPU
 		{9B93F5E5-3D53-42F1-96E2-06E6A7B496A0}.Release|x86.Build.0 = Release|Any CPU
+		{7A5B766E-8141-4D8A-B3EB-91422FDBDF71}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{7A5B766E-8141-4D8A-B3EB-91422FDBDF71}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{7A5B766E-8141-4D8A-B3EB-91422FDBDF71}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{7A5B766E-8141-4D8A-B3EB-91422FDBDF71}.Debug|x64.Build.0 = Debug|Any CPU
+		{7A5B766E-8141-4D8A-B3EB-91422FDBDF71}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{7A5B766E-8141-4D8A-B3EB-91422FDBDF71}.Debug|x86.Build.0 = Debug|Any CPU
+		{7A5B766E-8141-4D8A-B3EB-91422FDBDF71}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{7A5B766E-8141-4D8A-B3EB-91422FDBDF71}.Release|Any CPU.Build.0 = Release|Any CPU
+		{7A5B766E-8141-4D8A-B3EB-91422FDBDF71}.Release|x64.ActiveCfg = Release|Any CPU
+		{7A5B766E-8141-4D8A-B3EB-91422FDBDF71}.Release|x64.Build.0 = Release|Any CPU
+		{7A5B766E-8141-4D8A-B3EB-91422FDBDF71}.Release|x86.ActiveCfg = Release|Any CPU
+		{7A5B766E-8141-4D8A-B3EB-91422FDBDF71}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -178,6 +192,7 @@ Global
 		{FED64B0A-3FD7-4357-98B6-0B01A3A26EC7} = {ED8079DD-2B06-4030-9F0F-DC548F98E1C4}
 		{B725BEFA-524E-4FD8-BFFF-4AEBCD03D8CF} = {81F5F559-FD23-4E90-9EE6-3E2A2C1A7F96}
 		{9B93F5E5-3D53-42F1-96E2-06E6A7B496A0} = {81F5F559-FD23-4E90-9EE6-3E2A2C1A7F96}
+		{7A5B766E-8141-4D8A-B3EB-91422FDBDF71} = {ED8079DD-2B06-4030-9F0F-DC548F98E1C4}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {789B5FFA-7891-4F60-831E-42C3C5ED2C51}

docsrc/content/index.fsx

@@ -36,6 +36,8 @@ The additions can be summarised as:
  * A polymorphic [Lenses/Optics](tutorial.html#Lens) to easily read and update
    parts of immutable data
 
+ * Generic methods that help you with [parsing](parsing.html)
+
 Note, however, that F#+ does not go into solving a specific thing for a specific
 technology, such as JSON parsing.
 

docsrc/content/operators-common.fsx

@@ -7,22 +7,19 @@
 open FSharpPlus
 
 (**
-Operators - Common Combinators
-===============================
+# Operators - Common Combinators
 
 These generic functions and operators are used commonly and are not part
 of any other abstraction.
 
 You can find these in the API docs: [Operators.fs](reference/operators.html)
 
-flip
-====
+## flip
 
 Creates a new function with first two arguments flipped.
 
 
-konst
-=====
+## konst
 
 Create a function that always returns the given argument.
 This is known as a 'constant' function.
@@ -36,8 +33,7 @@ let a = [1;2;3] |> filter (konst true);;
 // val a : int list = [1; 2; 3]
 
 (**
-curry, uncurry, curryN, uncurryN
-================================
+## curry, uncurry, curryN, uncurryN
 
 Currying is the process of taking a function expecting a tuple, and returning a
 function with the same number of arguments as the tuple size.
@@ -56,8 +52,7 @@ let b = curryN addThreeNums 1 2 3;;
 // val it : int = 6
 
 (**
-Functions as operators - </ />
-==============================
+## Functions as operators - </ />
 
 A pair of operators `</` and `/>` are defined to allow any function to be used as
 an operator. It will flip the args of your function so that it makes sense when
@@ -72,8 +67,7 @@ let c = 10 </biggerThan/> 3;;
 // val c : bool = true
 
 (**
-tap
-===
+## tap
 
 Tap executes a side-effect function, then returns the original input value.
 Consider this as 'tapping into' a chain of functions.
@@ -91,8 +85,7 @@ names |> map String.toUpper |> tap (printfn "%A") |> map String.toLower;;
 // val it : string list = ["john"; "smith"]
 
 (**
-either
-======
+## either
 
 Extracts the value inside a Result from either side - whether Ok or Error.
 
@@ -123,8 +116,7 @@ Don't confuse the `either` function with `result` which lifts a value into a
 Functor, just like `return` when in a computation expression.
 
 
-option
-======
+## option
 
 Takes a function, a default value and a option value. If the option value is None, the function returns the default value.
 Otherwise, it applies the function to the value inside Some and returns the result.
@@ -133,8 +125,7 @@ let inline option f n = function Some x -> f x | None -> n
 
 (**
 
-tuple2, tuple3, ...tuple8
-=========================
+## tuple2, tuple3, ...tuple8
 
 Functions that generate a tuple. The number indicates the number of arguments
 that are defined, and the corresponding size of tuple.
@@ -147,3 +138,48 @@ let inline tuple5 a b c d e       = a,b,c,d,e
 let inline tuple6 a b c d e f     = a,b,c,d,e,f
 let inline tuple7 a b c d e f g   = a,b,c,d,e,f,g
 let inline tuple8 a b c d e f g h = a,b,c,d,e,f,g,h
+
+
+(**
+## Explicit
+
+Explicit allows you to use `explicit` generic method for standard types and types that implement the static explicit type cast signature.
+
+### Minimal definition
+
+In order to use the `explicit` generic method together with a type it needs to implement the following:
+*)
+
+(**
+```f#
+static member op_Explicit (x:'r) :'T
+```
+or in C#
+```c#
+public static explicit operator T(R s)
+```
+
+This is useful when dealing with C# libraries that make heavy use of explicit conversions.
+*)
+
+(**
+## Implicit
+
+Implicit allows you to use `implicit` generic method for standard types and types that implement the static implicit type cast signature.
+
+### Minimal definition
+
+In order to use the `implicit` generic method together with a type it needs to implement the following:
+*)
+
+(**
+```f#
+static member op_Implicit (x:'r) :'T
+```
+or in C#
+```c#
+public static implicit operator T(R s)
+```
+
+This is useful when dealing with C# libraries that make heavy use of implicit conversions.
+*)

docsrc/content/parsing.fsx

@@ -0,0 +1,76 @@
+(*** hide ***)
+// This block of code is omitted in the generated HTML documentation. Use 
+// it to define helpers that you do not want to show in the documentation.
+#I "../../bin"
+open System
+#r @"../../src/FSharpPlus/bin/Release/net45/FSharpPlus.dll"
+open FSharpPlus
+(**
+# Parsing
+
+F#+ provides several helper methods in order to simplify building parsers and parsing like tasks. 
+*)
+
+(**
+## Parse
+
+Parse allows you to use `parse` generic method for standard types and types that implement a static Parse method with the correct signature.
+
+
+### Minimal definition
+
+*)
+
+(**
+```f#
+static member Parse (x:'r) :'T
+```
+or
+
+```f#
+static member Parse (x:'r, c:CultureInfo) :'T
+```
+
+*)
+
+(**
+## TryParse
+
+TryParse allows you to use `tryParse` generic method for standard types and types that implement a static TryParse method with the correct signature.
+
+### Minimal definition
+
+In order to use `tryParse` together with a type the type needs to implement a TryParse like static method.
+
+*)
+
+(**
+You can use F# style TryParse:
+```f#
+static member TryParse(value:'r) : 'T option
+```
+or C# style TryParse:
+```f#
+static member TryParse (x:'r, [<Out>] result: 'T byref) :bool
+```
+expressed in C# that would be:
+```c#
+public static bool TryParse (string x, out T result) 
+```
+
+A neat thing when you have types that implement the above definition is that it's simple to define active patterns:
+*)
+
+let (|Port|_|) : _-> UInt16 option = tryParse
+let (|IPAddress|_|) :_->System.Net.IPAddress option = tryParse
+
+(**
+## sscanf, trySscanf and friends
+
+In F# you have some nice utility functions for creating printf style string writer function. In F#+ we find the inverse: sscanf and trySscanf.
+
+For instance if you want to parse based on known format of a url:
+*)
+
+let route1 x = trySscanf "/api/resource/%d" x
+let parsed : int option = route1 "/api/resource/1"

docsrc/content/type-cont.fsx

@@ -17,7 +17,7 @@ by reading [Real World Functional Programming by Tomas Petricek with Jon Skeet](
 Examples
 --------
 
-In order to get an idea about this style, let us contrast some of the examples and how they look in when using f#+ or without help.  
+In order to get an idea about this style, let us contrast some of the examples and how they look in when using F#+ or without help.  
 
 *)
 

docsrc/tools/Program.fs

@@ -178,7 +178,8 @@ let main argv =
         Target.create "ReleaseDocs" (fun _ ->
             let tempDocsDir = rootDir @@ "temp/gh-pages"
             Shell.cleanDir tempDocsDir
-            Git.Repository.cloneSingleBranch rootDir (gitHome + "/" + gitName + ".git") "gh-pages" tempDocsDir
+            let repoUrl = Git.Config.remoteOriginUrl rootDir
+            Git.Repository.cloneSingleBranch rootDir repoUrl "gh-pages" tempDocsDir
             let docDir = rootDir @@ "docs"
             Shell.copyRecursive docDir tempDocsDir true |> Trace.tracefn "%A"
             Git.Staging.stageAll tempDocsDir

docsrc/tools/doclib.fs

@@ -1206,7 +1206,17 @@ module Git =
             sprintf "clone -b %s --single-branch %s %s" branchName repoUrl toPath
             |> runSimpleGitCommand workingDir
             |> Trace.trace
-
+    module Config = 
+        /// Get remote origin url
+        /// ## Parameters
+        ///
+        ///  - `workingDir` - The working directory.
+        let remoteOriginUrl workingDir =
+            let url = 
+                "config --get remote.origin.url"
+                |> runSimpleGitCommand workingDir
+            url.Trim([|'\n';'\r';'\t';' '|])
+
 
 
 module DotNet =

docsrc/tools/generate.fs

@@ -77,11 +77,6 @@ let evaluationOptions =
 let compilerOptions = 
     String.concat " " ( Array.toList evaluationOptions)
 
-// PlantUml processing
-let abstractions = Path.templates </> "abstractions.plantuml"
-let plantUMLDiag = toUrl (IO.File.ReadAllText abstractions)
-let customize (doc:LiterateDocument) = doc.With (paragraphs = (doc.Paragraphs |>> function InlineBlock (x,y) -> InlineBlock ((replace "{plantUMLDiag}" plantUMLDiag x),y) | x -> x))
-
 let parseFsx path =
 
     let doc = 
@@ -90,7 +85,7 @@ let parseFsx path =
                   compilerOptions = compilerOptions,
                   fsiEvaluator = FSharp.Literate.FsiEvaluator(evaluationOptions))
 
-    let body = FSharp.Literate.Literate.FormatLiterateNodes(doc, OutputKind.Html, "", true, true) |> customize
+    let body = FSharp.Literate.Literate.FormatLiterateNodes(doc, OutputKind.Html, "", true, true)
     for err in doc.Errors do
         Printf.printfn "%A" err
     body, body.FormattedTips
@@ -102,7 +97,7 @@ let parseMd path =
                   path,
                   compilerOptions = compilerOptions,
                   fsiEvaluator = FSharp.Literate.FsiEvaluator(evaluationOptions))
-    let body = FSharp.Literate.Literate.FormatLiterateNodes(doc, OutputKind.Html, "", true, true) |> customize
+    let body = FSharp.Literate.Literate.FormatLiterateNodes(doc, OutputKind.Html, "", true, true)
     for err in doc.Errors do
         Printf.printfn "%A" err
     body, body.FormattedTips
@@ -142,5 +137,6 @@ let copyFiles () =
 let buildDocumentation () =
   Directory.copyRecursive Path.files Path.output
   IO.Directory.EnumerateFiles Path.content
+  |> Seq.filter (fun file-> not <| file.EndsWith(".DS_Store"))
   |> Seq.iter (processFile Path.output)
 

docsrc/tools/manually_build_docs.sh

@@ -6,7 +6,7 @@ dotnet tool restore
 
 # Build
 # Note: some bug means can't build debug
-dotnet build -c Release
+dotnet build -c Release FSharpPlus.sln
 
 # Gen docs
 #mkdir -p bin/FSharpPlus/netstandard2.0/