Improve command example (#391)

* improve command example

* improve comments

* correction

* show envs fn too

Author: Anton-4

ci/expect_scripts/command.exp

@@ -10,9 +10,19 @@ source ./ci/expect_scripts/shared-code.exp
 spawn $env(EXAMPLES_DIR)command
 
 
-expect -exact "EXEC\r\nFOO=BAR\r\nBAZ=DUCK\r\nFOO=BAR\r\n" {
-    expect eof {
-        check_exit_and_segfault
+expect "Hello\r\n" {
+    expect "Command output: Hi\r\n" {
+        expect "Command output: BAZ=DUCK\r\n" {
+            expect "FOO=BAR\r\n" {
+                expect "XYZ=ABC\r\n" {
+                    expect "Yo\r\n" {
+                        expect eof {
+                            check_exit_and_segfault
+                        }
+                    }
+                }
+            }
+        }
     }
 }
 

examples/command.roc

@@ -1,6 +1,7 @@
 app [main!] { pf: platform "../platform/main.roc" }
 
 import pf.Stdout
+import pf.Stderr
 import pf.Cmd
 import pf.Arg exposing [Arg]
 
@@ -11,48 +12,85 @@ import pf.Arg exposing [Arg]
 main! : List Arg => Result {} _
 main! = |_args|
 
-    # Simplest way to execute a command
-    exec_example!({})?
+    # Simplest way to execute a command (prints to your terminal).
+    Cmd.exec!("echo", ["Hello"]) ? |err| EchoHelloFailed(err)
 
-    # To execute and capture the output (includes stderr)
-    output_example!({})?
+    # To execute and capture the output (stdout, stderr, and exit code) without inheriting your terminal.
+    output_example!({}) ? |err| OutputExampleFailed(err)
 
-    # To execute and get the exit code
-    status_example!({})?
+    # To run a command with an environment variable.
+    env_example!({}) ? |err| EnvExampleFailed(err)
+
+    # To execute and just get the exit code (prints to your terminal).
+    status_example!({}) ? |err| StatusExampleFailed(err)
 
     Ok({})
 
-exec_example! : {} => Result {} _
-exec_example! = |{}| Cmd.exec!("echo", ["EXEC"])
+# Execute command and capture the output (stdout, stderr, and exit code)
+output_example! : {} => Result {} _
+output_example! = |{}|
 
-# Run "env" with verbose option, clear all environment variables, and pass in
-# "FOO" and "BAZ".
-status_example! : {} => Result {} _
-status_example! = |{}|
-    result =
-        Cmd.new("env")
-        |> Cmd.arg("-v")
-        |> Cmd.clear_envs
-        |> Cmd.envs([("FOO", "BAR"), ("BAZ", "DUCK")])
-        |> Cmd.status!
+    cmd_output =
+        Cmd.new("echo")
+        |> Cmd.args(["Hi"])
+        |> Cmd.output!
 
-    when result is
-        Ok(exit_code) if exit_code == 0 -> Ok({})
-        Ok(exit_code) -> Stdout.line!("Child exited with non-zero code: ${Num.to_str(exit_code)}")
-        Err(err) -> Stdout.line!("Error executing command: ${Inspect.to_str(err)}")
+    print_output!(cmd_output)
+
+
+print_output! : Cmd.Output => Result {} _
+print_output! = |cmd_output|
 
-# Run "env" with verbose option, clear all environment variables, and pass in
-# only as an environment variable "FOO"
-output_example! : {} => Result {} _
-output_example! = |{}|
 
-    output =
+    when cmd_output.status is
+        Ok(0) ->
+            stdout_utf8 = Str.from_utf8(cmd_output.stdout)?
+            Stdout.line!("Command output: ${stdout_utf8}")
+
+        Ok(exit_code) ->
+            stdout_utf8 = Str.from_utf8_lossy(cmd_output.stdout)
+            stderr_utf8 = Str.from_utf8_lossy(cmd_output.stderr)
+            err_data =
+                """
+                Command failed:
+                - exit code: ${Num.to_str(exit_code)}
+                - stdout: ${stdout_utf8}
+                - stderr: ${stderr_utf8}
+                """
+
+            Stderr.line!(err_data)
+
+        Err(err) ->
+            Stderr.line!("Failed to get exit code for command, error: ${Inspect.to_str(err)}")
+
+
+# Run command with an environment variable
+env_example! : {} => Result {} _
+env_example! = |{}|
+
+    cmd_output =
         Cmd.new("env")
-        |> Cmd.clear_envs
+        |> Cmd.clear_envs # You probably don't need to clear all other environment variables, this is just an example.
         |> Cmd.env("FOO", "BAR")
+        |> Cmd.envs([("BAZ", "DUCK"), ("XYZ", "ABC")]) # Set multiple environment variables at once with `envs`
         |> Cmd.args(["-v"])
         |> Cmd.output!
 
-    msg = Str.from_utf8(output.stdout) |> Result.with_default("Failed to decode stdout")
+    print_output!(cmd_output)
+
+# Execute command and capture the exit code
+status_example! : {} => Result {} _
+status_example! = |{}|
+    cmd_result =
+        Cmd.new("echo")
+        |> Cmd.args(["Yo"])
+        |> Cmd.status!
+
+    when cmd_result is
+        Ok(0) -> Ok({})
+
+        Ok(exit_code) ->
+            Stderr.line!("Command failed with exit code: ${Num.to_str(exit_code)}")
 
-    Stdout.write!(msg)
+        Err(err) ->
+            Stderr.line!("Failed to get exit code for command, error: ${Inspect.to_str(err)}")

platform/Cmd.roc

@@ -32,6 +32,17 @@ Cmd := InternalCmd.Command
 ##
 Output : InternalCmd.Output
 
+# This hits a compiler bug: Alias `6.IdentId(11)` not registered in delayed aliases! ...
+# ## Converts output into a utf8 string. Invalid utf8 sequences in stderr are ignored.
+# to_str : Output -> Result Str [BadUtf8 { index : U64, problem : Str.Utf8Problem }]
+# to_str = |output|
+#     InternalCmd.output_to_str(output)
+
+# ## Converts output into a utf8 string, ignoring any invalid utf8 sequences.
+# to_str_lossy : Output -> Str
+# to_str_lossy = |output|
+#     InternalCmd.output_to_str_lossy(output)
+
 ## Create a new command to execute the given program in a child process.
 new : Str -> Cmd
 new = |program|
@@ -119,15 +130,15 @@ output! = |@Cmd(cmd)|
     Host.command_output!(cmd)
     |> InternalCmd.from_host_output
 
-## Execute command and inherit stdin, stdout and stderr from parent
+## Execute command and inherit stdin, stdout and stderr from parent. Returns the exit code.
 ##
 status! : Cmd => Result I32 [CmdStatusErr InternalIOErr.IOErr]
 status! = |@Cmd(cmd)|
     Host.command_status!(cmd)
     |> Result.map_err(InternalIOErr.handle_err)
     |> Result.map_err(CmdStatusErr)
 
-## Execute command and inherit stdin, stdout and stderr from parent
+## Simplest way to execute a command while inheriting stdin, stdout and stderr from parent.
 ##
 ## ```
 ## # Call echo to print "hello world"

platform/InternalCmd.roc

@@ -20,6 +20,34 @@ Output : {
     stderr : List U8,
 }
 
+# This hits a compiler bug: Alias `6.IdentId(11)` not registered in delayed aliases! ...
+# output_to_str : Output -> Result Str [BadUtf8 { index : U64, problem : Str.Utf8Problem }]
+# output_to_str = |cmd_output|
+#     stdout_utf8 = Str.from_utf8(cmd_output.stdout)?
+#     stderr_utf8 = Str.from_utf8_lossy(cmd_output.stderr)
+
+#     Ok(
+#         output_str_template(cmd_output.status, stdout_utf8, stderr_utf8)
+#     )
+
+# output_to_str_lossy : Output -> Str
+# output_to_str_lossy = |cmd_output|
+#     stdout_utf8 = Str.from_utf8_lossy(cmd_output.stdout)
+#     stderr_utf8 = Str.from_utf8_lossy(cmd_output.stderr)
+
+    
+#     output_str_template(cmd_output.status, stdout_utf8, stderr_utf8)
+
+# output_str_template : Result I32 InternalIOErr.IOErr, Str, Str -> Str
+# output_str_template = |status, stdout_utf8, stderr_utf8|
+#     """
+#     Output {
+#         status: ${Inspect.to_str(status)}
+#         stdout: ${stdout_utf8}
+#         stderr: ${stderr_utf8}
+#     }
+#     """
+    
 from_host_output : OutputFromHost -> Output
 from_host_output = |{ status, stdout, stderr }| {
     status: Result.map_err(status, InternalIOErr.handle_err),