elm-pages 3.0.12 → 3.0.14

package/src/BackendTask/Do.elm

@@ -0,0 +1,233 @@
+module BackendTask.Do exposing
+    ( do
+    , allowFatal
+    , noop
+    , exec, command
+    , glob, log, env
+    , each, failIf
+    )
+
+{-|
+
+
+## **This is an optional and experimental module.** It is for doing a continuation style with your [`BackendTask`s](BackendTask).
+
+Note that in order for this style to be usable, you'll need to use a special formatting script that allows you to use
+continuation style syntax without indenting each level in the continuation.
+
+
+## Custom Formatting Script
+
+It is a bit advanced and cumbersome, so beware before committing to this style. That said, here is a script you can use to
+apply continuation-style formatting to your Elm code:
+
+<https://gist.github.com/xarvh/1b65cb00e7240f1ccfa0bdbf30f97c62>
+
+You can see more discussion of continuation style in Elm in this Discourse post: <https://discourse.elm-lang.org/t/experimental-json-decoding-api/2121>.
+
+@docs do
+@docs allowFatal
+
+
+## Defining Your Own Continuation Utilities
+
+`do` is also helpful for building your own continuation-style utilities. For example, here is how [`glob`](#glob) is defined:
+
+    glob : String -> (List String -> BackendTask FatalError a) -> BackendTask FatalError a
+    glob pattern =
+        do <| Glob.fromString pattern
+
+To define helpers that have no resulting value, it is still useful to have an argument of `()` to allow the code formatter to
+recognize it as a continuation chain.
+
+    sh :
+        String
+        -> List String
+        -> (() -> BackendTask FatalError b)
+        -> BackendTask FatalError b
+    sh command args =
+        do <| Shell.sh command args
+
+@docs noop
+
+
+## Shell Commands
+
+@docs exec, command
+
+
+## Common Utilities
+
+@docs glob, log, env
+
+@docs each, failIf
+
+-}
+
+import BackendTask exposing (BackendTask)
+import BackendTask.Env as Env
+import BackendTask.Glob as Glob
+import FatalError exposing (FatalError)
+import Pages.Script as Script
+
+
+{-| A do-style helper for [`Script.log`](Pages-Script#log).
+
+    example : BackendTask FatalError ()
+    example =
+        log "Starting script..." <|
+            \() ->
+                -- ...
+                log "Done!" <|
+                    \() ->
+                        noop
+
+-}
+log : String -> (() -> BackendTask error b) -> BackendTask error b
+log string then_ =
+    do (Script.log string) then_
+
+
+{-| Use any `BackendTask` into a continuation-style task.
+
+    example : BackendTask FatalError ()
+    example =
+        do
+            (Script.question "What is your name? ")
+        <|
+            \name ->
+                \() ->
+                    Script.log ("Hello " ++ name ++ "!")
+
+-}
+do : BackendTask error a -> (a -> BackendTask error b) -> BackendTask error b
+do fn requestInfo =
+    BackendTask.andThen requestInfo fn
+
+
+{-| A `BackendTask` that does nothing. Defined as `BackendTask.succeed ()`.
+
+It's a useful shorthand for when you want to end a continuation chain.
+
+    example : BackendTask FatalError ()
+    example =
+        exec "ls" [ "-l" ] <|
+            \() ->
+                log "Hello, world!" <|
+                    \() ->
+                        noop
+
+-}
+noop : BackendTask error ()
+noop =
+    BackendTask.succeed ()
+
+
+{-| Same as [`do`](#do), but with a shorthand to call `BackendTask.allowFatal` on it.
+
+    import BackendTask exposing (BackendTask)
+    import FatalError exposing (FatalError)
+    import BackendTask.File as BackendTask.File
+    import BackendTask.Do exposing (allowFatal, do)
+
+    example : BackendTask FatalError ()
+    example =
+        do (BackendTask.File.rawFile "post-1.md" |> BackendTask.allowFatal) <|
+            \post1 ->
+                allowFatal (BackendTask.File.rawFile "post-2.md") <|
+                    \post2 ->
+                        Script.log (post1 ++ "\n\n" ++ post2)
+
+-}
+allowFatal : BackendTask { error | fatal : FatalError } data -> (data -> BackendTask FatalError b) -> BackendTask FatalError b
+allowFatal =
+    do << BackendTask.allowFatal
+
+
+{-| A continuation-style helper for [`Glob.fromString`](BackendTask-Glob#fromString).
+
+In a shell script, you can think of this as a stand-in for globbing files directly within a command. The [`BackendTask.Stream.command`](BackendTask-Stream#command)
+which lets you run shell commands sanitizes and escapes all arguments passed, and does not do glob expansion, so this is helpful for translating
+a shell script to Elm.
+
+This example passes a list of matching file paths along to an `rm -f` command.
+
+    example : BackendTask FatalError ()
+    example =
+        glob "src/**/*.elm" <|
+            \elmFiles ->
+                log ("Going to delete " ++ String.fromInt (List.length elmFiles) ++ " Elm files") <|
+                    \() ->
+                        exec "rm" ("-f" :: elmFiles) <|
+                            \() ->
+                                noop
+
+-}
+glob : String -> (List String -> BackendTask FatalError a) -> BackendTask FatalError a
+glob pattern =
+    do <| Glob.fromString pattern
+
+
+{-|
+
+    checkCompilationInDir : String -> BackendTask FatalError ()
+    checkCompilationInDir dir =
+        glob (dir ++ "/**/*.elm") <|
+            \elmFiles ->
+                each elmFiles
+                    (\elmFile ->
+                        Shell.sh "elm" [ "make", elmFile, "--output", "/dev/null" ]
+                            |> BackendTask.quiet
+                    )
+                <|
+                    \_ ->
+                        noop
+
+-}
+each : List a -> (a -> BackendTask error b) -> (List b -> BackendTask error c) -> BackendTask error c
+each list fn then_ =
+    do
+        (list
+            |> List.map fn
+            |> BackendTask.sequence
+        )
+    <|
+        then_
+
+
+{-| A do-style helper for [`BackendTask.failIf`](BackendTask#failIf).
+-}
+failIf : Bool -> FatalError -> (() -> BackendTask FatalError b) -> BackendTask FatalError b
+failIf condition error =
+    do <| BackendTask.failIf condition error
+
+
+{-| A do-style helper for [`Script.exec`](Pages-Script#exec).
+-}
+exec : String -> List String -> (() -> BackendTask FatalError b) -> BackendTask FatalError b
+exec command_ args_ =
+    do <| Script.exec command_ args_
+
+
+{-| A do-style helper for [`Script.command`](Pages-Script#command).
+-}
+command : String -> List String -> (String -> BackendTask FatalError b) -> BackendTask FatalError b
+command command_ args_ function =
+    Script.command command_ args_
+        |> BackendTask.andThen function
+
+
+{-| A do-style helper for [`Env.expect`](BackendTask-Env#expect).
+
+    example : BackendTask FatalError ()
+    example =
+        env "API_KEY" <|
+            \apiKey ->
+                allowFatal (apiRequest apiKey) <|
+                    \() ->
+                        noop
+
+-}
+env : String -> (String -> BackendTask FatalError b) -> BackendTask FatalError b
+env name then_ =
+    do (Env.expect name |> BackendTask.allowFatal) <| then_

package/src/BackendTask/File.elm

@@ -66,12 +66,14 @@ frontmatter frontmatterDecoder =
 
     import BackendTask exposing (BackendTask)
     import BackendTask.File as File
-    import Decode exposing (Decoder)
+    import FatalError exposing (FatalError)
+    import Json.Decode as Decode exposing (Decoder)
 
-    blogPost : BackendTask BlogPostMetadata
+    blogPost : BackendTask FatalError BlogPostMetadata
     blogPost =
         File.bodyWithFrontmatter blogPostDecoder
             "blog/hello-world.md"
+            |> BackendTask.allowFatal
 
     type alias BlogPostMetadata =
         { body : String
@@ -102,11 +104,13 @@ It's common to parse the body with a markdown parser or other format.
 
     import BackendTask exposing (BackendTask)
     import BackendTask.File as File
-    import Decode exposing (Decoder)
+    import FatalError exposing (FatalError)
     import Html exposing (Html)
+    import Json.Decode as Decode
 
     example :
         BackendTask
+            FatalError
             { title : String
             , body : List (Html msg)
             }
@@ -126,6 +130,7 @@ It's common to parse the body with a markdown parser or other format.
                     )
             )
             "foo.md"
+                |> BackendTask.allowFatal
 
     markdownToView :
         String
@@ -191,13 +196,15 @@ just the metadata.
 
     import BackendTask exposing (BackendTask)
     import BackendTask.File as File
-    import Decode exposing (Decoder)
+    import FatalError exposing (FatalError)
+    import Json.Decode as Decode exposing (Decoder)
 
-    blogPost : BackendTask BlogPostMetadata
+    blogPost : BackendTask FatalError BlogPostMetadata
     blogPost =
         File.onlyFrontmatter
             blogPostDecoder
             "blog/hello-world.md"
+            |> BackendTask.allowFatal
 
     type alias BlogPostMetadata =
         { title : String
@@ -281,10 +288,13 @@ Hey there! This is my first post :)
 ```
 
     import BackendTask exposing (BackendTask)
+    import BackendTask.File as File
+    import FatalError exposing (FatalError)
 
-    data : BackendTask String
+    data : BackendTask FatalError String
     data =
-        bodyWithoutFrontmatter "blog/hello-world.md"
+        File.bodyWithoutFrontmatter "blog/hello-world.md"
+            |> BackendTask.allowFatal
 
 Then data will yield the value `"Hey there! This is my first post :)"`.
 
@@ -314,10 +324,12 @@ You could read a file called `hello.txt` in your root project directory like thi
 
     import BackendTask exposing (BackendTask)
     import BackendTask.File as File
+    import FatalError exposing (FatalError)
 
-    elmJsonFile : BackendTask String
+    elmJsonFile : BackendTask FatalError String
     elmJsonFile =
         File.rawFile "hello.txt"
+            |> BackendTask.allowFatal
 
 -}
 rawFile : String -> BackendTask { fatal : FatalError, recoverable : FileReadError decoderError } String
@@ -331,8 +343,10 @@ The Decode will strip off any unused JSON data.
 
     import BackendTask exposing (BackendTask)
     import BackendTask.File as File
+    import FatalError exposing (FatalError)
+    import Json.Decode as Decode
 
-    sourceDirectories : BackendTask (List String)
+    sourceDirectories : BackendTask FatalError (List String)
     sourceDirectories =
         File.jsonFile
             (Decode.field
@@ -340,6 +354,7 @@ The Decode will strip off any unused JSON data.
                 (Decode.list Decode.string)
             )
             "elm.json"
+            |> BackendTask.allowFatal
 
 -}
 jsonFile :