Deinit AppRunner in examples

Fixes #73

Author: sam701

README.md

@@ -1,54 +1,53 @@
-# ZIG-CLI
-[![Zig Docs](https://img.shields.io/badge/docs-zig-%23f7a41d)](https://sam701.github.io/zig-cli)
+# zig-cli
 
+[![Zig Docs](https://img.shields.io/badge/docs-zig-%23f7a41d)](https://sam701.github.io/zig-cli)
 
 A simple package for building command line apps in Zig.
 
 Inspired by [urfave/cli](https://github.com/urfave/cli) Go package.
 
 ## Features
-* command line arguments are parsed into zig values
-* long and short options: `--option1`, `-o`
-* optional `=` sign: `--address=127.0.0.1` equals `--address 127.0.0.1`
-* concatenated short options: `-a -b -c` equals `-abc`
-* subcommands: `command1 -option1 subcommand2 -option2`
-* multiple option values: `--opt val1 --opt val2 --opt val3`
-* enums as option values: `--opt EnumValue1`
-* options value can be read from environment variables with a configured prefix
-* positional arguments can be mixed with options: `--opt1 val1 arg1 -v`
-* stops option parsing after `--`: `command -- --abc` will consider `--abc` as a positional argument to `command`.
-* errors on missing required options: `ERROR: option 'ip' is required`
-* prints help with `--help`
-* colored help messages when TTY is attached
+
+- Arguments parsed directly into Zig values
+- Long and short options: `--option`, `-o`
+- Optional `=` sign: `--address=127.0.0.1` equals `--address 127.0.0.1`
+- Concatenated short options: `-a -b -c` equals `-abc`
+- Subcommands: `cmd -opt subcmd -opt2`
+- Multiple option values: `--opt val1 --opt val2 --opt val3`
+- Enums as option values: `--opt EnumValue1`
+- Positional arguments (required and optional), mixed with options: `--opt val arg1 -v`
+- Option values read from environment variables with a configured prefix
+- Stops option parsing after `--`: `cmd -- --abc` treats `--abc` as a positional argument
+- Errors on missing required options: `ERROR: missing required option '--port'`
+- App version and author metadata
+- Built-in `--help` flag with colored output when a TTY is attached
 
 ## Usage
+
 [API Documentation](https://sam701.github.io/zig-cli)
+
 ```zig
 const std = @import("std");
 const cli = @import("cli");
 
-// Define a configuration structure with default values.
 var config = struct {
     host: []const u8 = "localhost",
     port: u16 = undefined,
 }{};
 
 pub fn main(init: std.process.Init) !void {
     var r = cli.AppRunner.init(&init);
+    defer r.deinit();
 
-    // Create an App with a command named "short" that takes host and port options.
     const app = cli.App{
         .command = cli.Command{
-            .name = "short",
+            .name = "server",
             .options = try r.allocOptions(&.{
-                // Define an Option for the "host" command-line argument.
                 .{
                     .long_name = "host",
                     .help = "host to listen on",
                     .value_ref = r.mkRef(&config.host),
                 },
-
-                // Define an Option for the "port" command-line argument.
                 .{
                     .long_name = "port",
                     .help = "port to bind to",
@@ -57,32 +56,40 @@ pub fn main(init: std.process.Init) !void {
                 },
             }),
             .target = cli.CommandTarget{
-                .action = cli.CommandAction{ .exec = run_server },
+                .action = cli.CommandAction{ .exec = run },
             },
         },
     };
     return r.run(&app);
 }
 
-// Action function to execute when the "short" command is invoked.
-fn run_server() !void {
-    // Log a debug message indicating the server is listening on the specified host and port.
-    std.log.debug("server is listening on {s}:{d}", .{ config.host, config.port });
+fn run() !void {
+    std.log.info("listening on {s}:{d}", .{ config.host, config.port });
 }
 ```
 
-### Using with the Zig package manager
-Add `cli` to your `build.zig.zon`
-```
-# For zig master
+### Installing with the Zig package manager
+
+**1. Fetch the package:**
+
+```sh
+# For zig master and zig 0.16
 zig fetch --save git+https://github.com/sam701/zig-cli
 
 # For zig 0.15
 zig fetch --save git+https://github.com/sam701/zig-cli#zig-0.15
 ```
 
-## Printing help
-See [`simple.zig`](./examples/simple.zig)
+**2. Wire it up in `build.zig`:**
+
+```zig
+const cli_dep = b.dependency("cli", .{});
+exe.root_module.addImport("cli", cli_dep.module("cli"));
+```
+
+## Help output
+
+See [`simple.zig`](./examples/simple.zig) for a full example with subcommands.
 
 ```
 $ ./zig-out/bin/simple sub1 --help
@@ -107,4 +114,5 @@ OPTIONS:
 ```
 
 ## License
+
 MIT

build.zig.zon

@@ -1,6 +1,6 @@
 .{
     .name = .cli,
     .fingerprint = 0x48f6513cff9ee2d9,
-    .version = "0.10.0",
+    .version = "0.11.0",
     .paths = .{ "./src", "./build.zig", "./build.zig.zon" },
 }

examples/short.zig

@@ -1,28 +1,24 @@
 const std = @import("std");
 const cli = @import("cli");
 
-// Define a configuration structure with default values.
 var config = struct {
     host: []const u8 = "localhost",
     port: u16 = undefined,
 }{};
 
 pub fn main(init: std.process.Init) !void {
     var r = cli.AppRunner.init(&init);
+    defer r.deinit();
 
-    // Create an App with a command named "short" that takes host and port options.
     const app = cli.App{
         .command = cli.Command{
-            .name = "short",
+            .name = "server",
             .options = try r.allocOptions(&.{
-                // Define an Option for the "host" command-line argument.
                 .{
                     .long_name = "host",
                     .help = "host to listen on",
                     .value_ref = r.mkRef(&config.host),
                 },
-
-                // Define an Option for the "port" command-line argument.
                 .{
                     .long_name = "port",
                     .help = "port to bind to",
@@ -31,15 +27,13 @@ pub fn main(init: std.process.Init) !void {
                 },
             }),
             .target = cli.CommandTarget{
-                .action = cli.CommandAction{ .exec = run_server },
+                .action = cli.CommandAction{ .exec = run },
             },
         },
     };
     return r.run(&app);
 }
 
-// Action function to execute when the "short" command is invoked.
-fn run_server() !void {
-    // Log a debug message indicating the server is listening on the specified host and port.
-    std.log.debug("server is listening on {s}:{d}", .{ config.host, config.port });
+fn run() !void {
+    std.log.info("listening on {s}:{d}", .{ config.host, config.port });
 }

examples/simple.zig

@@ -49,10 +49,7 @@ fn sub3(r: *cli.AppRunner) !cli.Command {
     };
 }
 
-fn parseArgs(init: *const std.process.Init) cli.AppRunner.Error!cli.ExecFn {
-    // This allocator will be used to allocate config.ip and config.arg2.
-    var r = cli.AppRunner.init(init);
-
+fn parseArgs(r: *cli.AppRunner) cli.AppRunner.Error!cli.ExecFn {
     const sub2 = cli.Command{
         .name = "sub2",
         .target = cli.CommandTarget{
@@ -62,10 +59,9 @@ fn parseArgs(init: *const std.process.Init) cli.AppRunner.Error!cli.ExecFn {
         },
     };
 
-    // Since we call r.getAction in this fuction, all r.alloc* invocation are unnecessary.
-    // We can directly pass slices of commands, options, and posititional arguments,
+    // Since we call r.getAction in this function, all r.alloc* invocation are unnecessary.
+    // We can directly pass slices of commands, options, and positional arguments,
     // like `.options = &.{....}`
-
     const app = cli.App{
         .option_envvar_prefix = "CLI_",
         .command = cli.Command{
@@ -113,7 +109,7 @@ fn parseArgs(init: *const std.process.Init) cli.AppRunner.Error!cli.ExecFn {
                             },
                         }),
                         .target = cli.CommandTarget{
-                            .subcommands = try r.allocCommands(&.{ sub2, try sub3(&r) }),
+                            .subcommands = try r.allocCommands(&.{ sub2, try sub3(r) }),
                         },
                     },
                 }),
@@ -127,20 +123,23 @@ fn parseArgs(init: *const std.process.Init) cli.AppRunner.Error!cli.ExecFn {
 }
 
 pub fn main(init: std.process.Init) anyerror!void {
-    const action = try parseArgs(&init);
+    var r = cli.AppRunner.init(&init);
+    defer r.deinit();
+
+    const action = try parseArgs(&r);
     return action();
 }
 
 fn run_sub3() !void {
     const c = &config;
-    std.log.debug("int: {}", .{c.int});
-    std.log.debug("sub3: arg1: {}", .{c.arg1});
+    std.log.info("int: {}", .{c.int});
+    std.log.info("sub3: arg1: {}", .{c.arg1});
     for (c.arg2) |arg| {
-        std.log.debug("sub3: arg2: {s}", .{arg});
+        std.log.info("sub3: arg2: {s}", .{arg});
     }
 }
 
 fn run_sub2() !void {
     const c = &config;
-    std.log.debug("running sub2: ip={s}, bool={any}, float={any}", .{ c.ip, c.bool, c.float });
+    std.log.info("running sub2: ip={s}, bool={any}, float={any}", .{ c.ip, c.bool, c.float });
 }

src/app_runner.zig

@@ -10,12 +10,13 @@ const Printer = @import("Printer.zig");
 const command = @import("command.zig");
 const help = @import("./help.zig");
 
+/// Owns all memory allocated during argument parsing and action setup.
+/// Call `deinit` to free everything at once (typically via `defer r.deinit()`).
 pub const AppRunner = struct {
-    // Arena allocator for temporary data during parsing (ValueRefs, argument slices, etc.)
-    // that is freed immediately after parsing completes.
-    // The original allocator is used for data that outlives the parsing phase.
+    /// Arena that backs all allocations made by this runner, including parsed values
+    /// that outlive `getAction`. Publicly accessible so callers can allocate additional
+    /// data with the same lifetime and have it freed together on `deinit`.
     arena: ArenaAllocator,
-    orig_allocator: Allocator,
     io: std.Io,
     environ: *const std.process.Environ.Map,
     args: *const std.process.Args,
@@ -24,7 +25,6 @@ pub const AppRunner = struct {
     pub fn init(orig_init: *const std.process.Init) Self {
         return .{
             .arena = ArenaAllocator.init(orig_init.gpa),
-            .orig_allocator = orig_init.gpa,
             .io = orig_init.io,
             .environ = orig_init.environ_map,
             .args = &orig_init.minimal.args,
@@ -63,11 +63,10 @@ pub const AppRunner = struct {
         const iter = try self.args.iterateAllocator(self.arena.allocator());
 
         // Here we pass the child allocator because any values allocated on the client behalf may not be freed.
-        var cr = try Parser(std.process.Args.Iterator).init(app, iter, self.io, self.orig_allocator, self.environ);
+        var cr = try Parser(std.process.Args.Iterator).init(app, iter, self.io, self.arena.allocator(), self.environ);
         defer cr.deinit();
 
         if (cr.parse()) |action| {
-            self.deinit();
             return action;
         } else |err| {
             var buffer: [4096]u8 = undefined;
@@ -79,9 +78,9 @@ pub const AppRunner = struct {
                 try help.print_command_help(
                     &printer,
                     app,
-                    try cr.command_path.toOwnedSlice(self.orig_allocator),
+                    try cr.command_path.toOwnedSlice(self.arena.allocator()),
                     cr.global_options,
-                    self.orig_allocator,
+                    self.arena.allocator(),
                 );
             }
             std.process.exit(1);