2022-09-18 04:50:51 +03:00
|
|
|
|
interface Program
|
2022-09-19 22:21:52 +03:00
|
|
|
|
exposes [Program, ExitCode, noArgs, withArgs, quick, withEnv, exitCode, exit]
|
2022-09-19 17:27:44 +03:00
|
|
|
|
imports [Task.{ Task }, InternalProgram.{ InternalProgram }, InternalTask, Effect]
|
2022-09-18 04:50:51 +03:00
|
|
|
|
|
2022-09-17 06:20:54 +03:00
|
|
|
|
## A [command-line interface](https://en.wikipedia.org/wiki/Command-line_interface) program.
|
2022-09-18 04:50:51 +03:00
|
|
|
|
Program : InternalProgram
|
|
|
|
|
|
2022-09-19 22:21:52 +03:00
|
|
|
|
## An [exit status](https://en.wikipedia.org/wiki/Exit_status) code.
|
|
|
|
|
ExitCode := U8
|
|
|
|
|
|
|
|
|
|
## Converts a [U8] to an [ExitCode].
|
|
|
|
|
##
|
|
|
|
|
## If you already have a [Task] and want to convert its success type
|
|
|
|
|
## from `{}` to [ExitCode], you may find [Program.exit] convenient.
|
|
|
|
|
exitCode : U8 -> ExitCode
|
|
|
|
|
exitCode = @ExitCode
|
|
|
|
|
|
|
|
|
|
## Attach an [ExitCode] to a task.
|
|
|
|
|
##
|
|
|
|
|
## Stderr.line "I hit an error and couldn't continue."
|
|
|
|
|
## |> Program.exit 1
|
|
|
|
|
##
|
|
|
|
|
## Note that this does not terminate the current process! By design, this platform does not have
|
|
|
|
|
## a [Task] which terminates the current process. Instead, error handling should be consistently
|
|
|
|
|
## done through task failures.
|
|
|
|
|
##
|
|
|
|
|
## To convert a [U8] directly into an [ExitCode], use [Program.exitCode].
|
|
|
|
|
exit : Task {} [] fx, U8 -> Task ExitCode [] fx
|
|
|
|
|
exit = \task, code ->
|
|
|
|
|
Task.map task \{} -> @ExitCode code
|
|
|
|
|
|
2022-09-17 06:20:54 +03:00
|
|
|
|
## A program which runs the given task and discards the values it produces on success or failure.
|
|
|
|
|
## One use for this is as an introductory [Program] when teaching someone how to use this platform.
|
|
|
|
|
##
|
2022-09-18 05:46:45 +03:00
|
|
|
|
## If the task succeeds, the program will exit with a [status](https://en.wikipedia.org/wiki/Exit_status)
|
|
|
|
|
## of 0. If the task fails, the program will exit with a status of 1.
|
|
|
|
|
## If the task crashes, the program will exit with a status of 2.
|
2022-09-17 06:20:54 +03:00
|
|
|
|
##
|
|
|
|
|
## For a similar program which specifies its exit status explicitly, see [Program.noArgs].
|
|
|
|
|
quick : Task * * * -> Program
|
2022-09-18 05:46:45 +03:00
|
|
|
|
quick = \task ->
|
|
|
|
|
effect =
|
|
|
|
|
InternalTask.toEffect task
|
|
|
|
|
|> Effect.map \result ->
|
|
|
|
|
when result is
|
|
|
|
|
Ok _ -> 0
|
|
|
|
|
Err _ -> 1
|
|
|
|
|
|
|
|
|
|
InternalProgram.fromEffect effect
|
2022-09-17 06:20:54 +03:00
|
|
|
|
|
|
|
|
|
## A program which uses no [command-line arguments](https://en.wikipedia.org/wiki/Command-line_interface#Arguments)
|
|
|
|
|
## and specifies an [exit status](https://en.wikipedia.org/wiki/Exit_status) [U8].
|
|
|
|
|
##
|
|
|
|
|
## Note that the task's failure type must be `[]`. You can satisfy that by handling all
|
|
|
|
|
## the task's potential failures using something like [Task.attempt].
|
|
|
|
|
##
|
|
|
|
|
## For a similar program which does use command-line arguments, see [Program.withArgs].
|
2022-09-19 22:21:52 +03:00
|
|
|
|
noArgs : Task ExitCode [] * -> Program
|
2022-09-18 05:46:45 +03:00
|
|
|
|
noArgs = \task ->
|
|
|
|
|
effect =
|
|
|
|
|
InternalTask.toEffect task
|
2022-09-20 22:30:25 +03:00
|
|
|
|
|> Effect.map \Ok (@ExitCode u8) -> u8
|
2022-09-18 05:46:45 +03:00
|
|
|
|
|
|
|
|
|
InternalProgram.fromEffect effect
|
2022-09-18 04:50:51 +03:00
|
|
|
|
|
2022-09-17 06:20:54 +03:00
|
|
|
|
## A program which uses [command-line arguments](https://en.wikipedia.org/wiki/Command-line_interface#Arguments)
|
|
|
|
|
## and specifies an [exit status](https://en.wikipedia.org/wiki/Exit_status) [U8].
|
|
|
|
|
##
|
|
|
|
|
## Note that the task's failure type must be `[]`. You can satisfy that by handling all
|
|
|
|
|
## the task's potential failures using something like [Task.attempt].
|
|
|
|
|
##
|
|
|
|
|
## If any command-line arguments contain invalid Unicode, the invalid parts will be replaced with
|
|
|
|
|
## the [Unicode replacement character](https://unicode.org/glossary/#replacement_character)
|
|
|
|
|
## (`<60>`).
|
2022-09-19 22:21:52 +03:00
|
|
|
|
withArgs : (List Str -> Task ExitCode [] *) -> Program
|
2022-09-18 05:46:45 +03:00
|
|
|
|
withArgs = \toTask ->
|
|
|
|
|
effect = Effect.after Effect.args \args ->
|
|
|
|
|
toTask args
|
2022-09-18 04:50:51 +03:00
|
|
|
|
|> InternalTask.toEffect
|
2022-09-20 22:30:25 +03:00
|
|
|
|
|> Effect.map \Ok (@ExitCode u8) -> u8
|
2022-09-18 05:46:45 +03:00
|
|
|
|
|
|
|
|
|
InternalProgram.fromEffect effect
|
2022-09-18 04:50:51 +03:00
|
|
|
|
|
2022-09-17 06:20:54 +03:00
|
|
|
|
## A program which uses [command-line arguments](https://en.wikipedia.org/wiki/Command-line_interface#Arguments)
|
|
|
|
|
## and a dictionary of [environment variables](https://en.wikipedia.org/wiki/Environment_variable).
|
|
|
|
|
##
|
2022-09-19 22:21:52 +03:00
|
|
|
|
## This is a combination of [Program.withArgs] and `Env.dict`. Note that the task's failure type
|
2022-09-17 06:20:54 +03:00
|
|
|
|
## must be `[]`. You can satisfy that by handling all the task's potential failures using
|
|
|
|
|
## something like [Task.attempt].
|
|
|
|
|
##
|
|
|
|
|
## If any command-line arguments contain invalid Unicode, the invalid parts will be replaced with
|
|
|
|
|
## the [Unicode replacement character](https://unicode.org/glossary/#replacement_character)
|
|
|
|
|
## (`<60>`).
|
2022-09-19 22:21:52 +03:00
|
|
|
|
withEnv : (List Str, Dict Str Str -> Task ExitCode [] *) -> Program
|
2022-09-18 05:46:45 +03:00
|
|
|
|
withEnv = \toTask ->
|
|
|
|
|
effect =
|
|
|
|
|
args <- Effect.args |> Effect.after
|
|
|
|
|
dict <- Effect.envDict |> Effect.after
|
|
|
|
|
|
|
|
|
|
toTask args dict
|
|
|
|
|
|> InternalTask.toEffect
|
2022-09-20 22:30:25 +03:00
|
|
|
|
|> Effect.map \Ok (@ExitCode u8) -> u8
|
2022-09-18 05:46:45 +03:00
|
|
|
|
|
|
|
|
|
InternalProgram.fromEffect effect
|
2022-09-17 06:20:54 +03:00
|
|
|
|
|
|
|
|
|
# ## A combination of [Program.withArgs] and [Env.decodeAll], with the output of [Env.decodeAll]
|
|
|
|
|
# ## being passed after the command-line arguments.
|
|
|
|
|
# decodedEnv : (List Str, Result env [EnvDecodingFailed Str]* -> Task U8 [] *) -> Program
|
2022-09-20 03:07:23 +03:00
|
|
|
|
# | env has Decode
|