Add an example for context cancellation

Author: FollowTheProcess

README.md

@@ -50,7 +50,7 @@ go get go.followtheprocess.codes/cli@latest
 package main
 
 import (
-	  "context"
+    "context"
     "fmt"
     "os"
 

docs/img/cancel.gif

@@ -0,0 +1,42 @@
+Output ./docs/img/cancel.gif
+
+Set FontSize 18
+Set FontFamily "Geist Mono"
+Set Theme "Catppuccin Macchiato"
+Set WindowBar Colorful
+Set Padding 5
+Set Height 800
+Set Width 1200
+Set Margin 40
+Set MarginFill "#7983FF"
+Set BorderRadius 10
+Set TypingSpeed 100ms
+
+# Setup
+Hide
+Type "go build -o ./cancel ./examples/cancel && clear" Sleep 2s
+Enter
+Sleep 2s
+Show
+Sleep 1s
+
+Type "./cancel --help" Sleep 500ms Enter
+
+Sleep 6s
+
+Type "clear" Sleep 500ms Enter
+
+Sleep 1s
+
+Type "./cancel" Sleep 500ms Enter
+
+Sleep 8s
+
+Ctrl+c
+
+Sleep 1s
+
+# Cleanup
+Hide
+Type "rm -f ./cancel"
+Enter

docs/src/cancel.tape

@@ -7,6 +7,7 @@ This directory contains a bunch of example programs built with `cli` to show you
   - [`./quickstart`](#quickstart)
   - [`./subcommands`](#subcommands)
   - [`./namedargs`](#namedargs)
+  - [`./cancel`](#cancel)
     - [TODO](#todo)
 
 ## `./cover`
@@ -31,6 +32,12 @@ A CLI with named positional arguments that may or may not have default values. S
 
 ![namedargs](../docs/img/namedargs.gif)
 
+## `./cancel`
+
+This examples shows how `cli` requiring you to pass a `context.Context` to your run functions leads to elegant and resilient cancellation and `CTRL+C` handling.
+
+![cancel](../docs/img/cancel.gif)
+
 ### TODO
 
 - Replicate one or two well known CLI tools as an example

examples/README.md

@@ -0,0 +1,26 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"go.followtheprocess.codes/cli"
+)
+
+func BuildCLI() (*cli.Command, error) {
+	return cli.New(
+		"cancel",
+		cli.Short("Cancel me!"),
+		cli.Run(func(ctx context.Context, cmd *cli.Command) error {
+			for {
+				select {
+				case <-ctx.Done():
+					return ctx.Err()
+				case <-time.After(1 * time.Second):
+					fmt.Fprintln(cmd.Stdout(), "working...")
+				}
+			}
+		}),
+	)
+}

examples/cancel/cli.go

@@ -0,0 +1,31 @@
+// Package cancel demonstrates how to handle CTRL+C and cancellation/timeouts
+// easily with cli.
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/signal"
+)
+
+func main() {
+	if err := run(); err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		os.Exit(1)
+	}
+}
+
+func run() error {
+	ctx := context.Background()
+
+	ctx, cancel := signal.NotifyContext(ctx, os.Interrupt)
+	defer cancel()
+
+	cli, err := BuildCLI()
+	if err != nil {
+		return err
+	}
+
+	return cli.Execute(ctx)
+}