Add comprehensive CLI documentation and examples #2220
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,119 @@ | ||
| # GoFr CLI Examples | ||
|
|
||
| This directory contains examples demonstrating how to build Command-Line Interface (CLI) applications using the GoFr framework. | ||
|
|
||
| ⚠️ **Version Note**: These examples are designed for the current stable GoFr version where automatic argument parsing (`ctx.Args()` / `ctx.Flags()`) is not yet available. Arguments and flags are therefore parsed manually using `os.Args` and helper functions. | ||
|
|
||
| --- | ||
|
|
||
| ## Example 1: Multiple Subcommands with Manual Argument Parsing | ||
|
|
||
| **File**: `example1-mutli-sub-command/main.go` | ||
|
|
||
| This example demonstrates a robust GoFr CLI application supporting multiple subcommands (`hello` and `goodbye`). It showcases how to manually parse both flag-based and positional arguments using `os.Args` and a custom helper function. | ||
|
|
||
| ### Purpose | ||
| - Define multiple subcommands: `hello` and `goodbye`. | ||
| - Handle `--name` flag and positional arguments (e.g., `hello John`, `goodbye Jane`). | ||
| - Provide default values if no argument is supplied for either subcommand. | ||
| - Output results using `ctx.Out.Println`. | ||
|
|
||
| ### How to Run | ||
|
|
||
| First, ensure you have the `example1-mutli-sub-command/main.go` file created in this directory (content provided below). | ||
|
|
||
| Navigate to your GoFr project root and execute the following commands: | ||
|
|
||
| 1. **Run `hello` subcommand with default value (no arguments):** | ||
| ```bash | ||
| go run examples/cli-example/example1-mutli-sub-command/main.go hello | ||
| # Output: Hello, World! | ||
| ``` | ||
|
|
||
| 2. **Run `hello` subcommand with a positional argument:** | ||
| ```bash | ||
| go run examples/cli-example/example1-mutli-sub-command/main.go hello John | ||
| # Output: Hello, John! | ||
| ``` | ||
|
|
||
| 3. **Run `hello` subcommand with a flag argument:** | ||
| ```bash | ||
| go run examples/cli-example/example1-mutli-sub-command/main.go hello --name Jane | ||
| # Output: Hello, Jane! | ||
| ``` | ||
|
|
||
| 4. **Run `goodbye` subcommand with default value (no arguments):** | ||
| ```bash | ||
| go run examples/cli-example/example1-mutli-sub-command/main.go goodbye | ||
| # Output: Goodbye, Friend! | ||
| ``` | ||
|
|
||
| 5. **Run `goodbye` subcommand with a positional argument:** | ||
| ```bash | ||
| go run examples/cli-example/example1-mutli-sub-command/main.go goodbye Mark | ||
| # Output: Goodbye, Mark! | ||
| ``` | ||
|
|
||
| 6. **Run `goodbye` subcommand with a flag argument:** | ||
| ```bash | ||
| go run examples/cli-example/example1-mutli-sub-command/main.go goodbye --name Susan | ||
| # Output: Goodbye, Susan! | ||
| ``` | ||
|
|
||
| ### Key Concepts Demonstrated | ||
| - **`app.NewCMD()`**: Initializes a new GoFr CLI application. | ||
| - **`app.SubCommand("name", handler)`**: Registers multiple subcommands with their respective handler functions. | ||
| - **Manual Argument Parsing**: `os.Args` is used directly with a helper function (`getFlagValue`) to extract flag values (e.g., `--name`) and positional arguments within each subcommand's handler. | ||
| - **`ctx.Out.Println()`**: Prints output directly to the standard CLI output stream. | ||
| - **Subcommand Handler Signature:** | ||
| ```go | ||
| func(ctx *gofr.Context) (any, error) | ||
| ``` | ||
| This is the required signature for all subcommand handlers, returning an optional result and an error. | ||
|
|
||
| --- | ||
|
|
||
| ## Example 2: Single Subcommand with Manual Argument Parsing | ||
|
|
||
| **File**: `example2-single-sub-command/main.go` | ||
|
|
||
| This example demonstrates a basic GoFr CLI application with a single subcommand (`hello`), focusing on manual argument parsing. | ||
|
|
||
| ### Purpose | ||
| - Define a single subcommand: `hello`. | ||
| - Handle `--name` flag and positional arguments (e.g., `hello John`). | ||
| - Provide default values if no argument is supplied. | ||
| - Output results using `ctx.Out.Println`. | ||
|
|
||
| ### How to Run | ||
|
|
||
| Navigate to your GoFr project root and execute: | ||
|
|
||
| 1. **Run with default value (no arguments):** | ||
| ```bash | ||
| go run examples/cli-example/example2-single-sub-command/main.go hello | ||
| # Output: Hello, World! | ||
| ``` | ||
|
|
||
| 2. **Run with a positional argument:** | ||
| ```bash | ||
| go run examples/cli-example/example2-single-sub-command/main.go hello John | ||
| # Output: Hello, John! | ||
| ``` | ||
|
|
||
| 3. **Run with a flag argument:** | ||
| ```bash | ||
| go run examples/cli-example/example2-single-sub-command/main.go hello --name Jane | ||
| # Output: Hello, Jane! | ||
| ``` | ||
|
|
||
| ### Key Concepts Demonstrated | ||
| - **`app.NewCMD()`**: Initializes a new GoFr CLI application. | ||
| - **`app.SubCommand("name", handler)`**: Registers a subcommand with its handler function. | ||
| - **Manual Argument Parsing**: Use `os.Args` with a helper function (`getFlagValue`) to extract flag values (e.g., `--name`). | ||
| - **`ctx.Out.Println()`**: Prints output directly to the standard CLI output stream. | ||
| - **Subcommand Handler Signature:** | ||
| ```go | ||
| func(ctx *gofr.Context) (any, error) | ||
| ``` | ||
| This is required for all subcommand handlers, returning an optional result and an error. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| package main | ||
|
|
||
| import ( | ||
| "fmt" | ||
| "os" | ||
| "strings" | ||
|
|
||
| "gofr.dev/pkg/gofr" | ||
| ) | ||
|
|
||
| // helper function to parse flags manually | ||
| func getFlagValue(args []string, flag string, defaultValue string) string { | ||
| for i := 0; i < len(args); i++ { | ||
| if args[i] == flag && i+1 < len(args) { | ||
| return args[i+1] | ||
| } | ||
| } | ||
| return defaultValue | ||
| } | ||
|
|
||
| func main() { | ||
| app := gofr.NewCMD() | ||
|
|
||
| // ----------------------- | ||
| // Subcommand: hello | ||
| // ----------------------- | ||
| app.SubCommand("hello", func(ctx *gofr.Context) (any, error) { | ||
| args := os.Args[2:] // arguments after "hello" | ||
| name := getFlagValue(args, "--name", "") | ||
| if name == "" && len(args) > 0 && !strings.HasPrefix(args[0], "--") { | ||
| name = args[0] // fallback to positional arg | ||
| } | ||
| if name == "" { | ||
| name = "World" | ||
| } | ||
| ctx.Out.Println(fmt.Sprintf("Hello, %s!", name)) | ||
| return nil, nil | ||
| }) | ||
|
|
||
| // ----------------------- | ||
| // Subcommand: goodbye | ||
| // ----------------------- | ||
| app.SubCommand("goodbye", func(ctx *gofr.Context) (any, error) { | ||
| args := os.Args[2:] // arguments after "goodbye" | ||
| name := getFlagValue(args, "--name", "") | ||
| if name == "" && len(args) > 0 && !strings.HasPrefix(args[0], "--") { | ||
| name = args[0] | ||
| } | ||
| if name == "" { | ||
| name = "Friend" | ||
| } | ||
| ctx.Out.Println(fmt.Sprintf("Goodbye, %s!", name)) | ||
| return nil, nil | ||
| }) | ||
|
|
||
| // Run the CLI app | ||
| app.Run() | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| package main | ||
|
|
||
| import ( | ||
| "fmt" | ||
| "os" | ||
| "strings" | ||
|
|
||
| "gofr.dev/pkg/gofr" | ||
| ) | ||
|
|
||
| // Helper function to manually parse flags | ||
| func getFlagValue(args []string, flag string, defaultValue string) string { | ||
| for i := 0; i < len(args); i++ { | ||
| if args[i] == flag && i+1 < len(args) { | ||
| return args[i+1] | ||
| } | ||
| } | ||
| return defaultValue | ||
| } | ||
|
|
||
| func main() { | ||
| app := gofr.NewCMD() | ||
|
|
||
| // ----------------------- | ||
| // Subcommand: hello | ||
| // ----------------------- | ||
| app.SubCommand("hello", func(ctx *gofr.Context) (any, error) { | ||
| args := os.Args[2:] // arguments after "hello" | ||
| name := getFlagValue(args, "--name", "") | ||
|
|
||
| // fallback to positional argument if --name not provided | ||
| if name == "" && len(args) > 0 && !strings.HasPrefix(args[0], "--") { | ||
| name = args[0] | ||
| } | ||
|
|
||
| if name == "" { | ||
| name = "World" | ||
| } | ||
|
|
||
| ctx.Out.Println(fmt.Sprintf("Hello, %s!", name)) | ||
| return nil, nil | ||
| }) | ||
|
|
||
| // Run the CLI application | ||
| app.Run() | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,3 +1,3 @@ | ||
| package version | ||
|
|
||
|
There was a problem hiding this comment. This change is not needed please revert it. |
||
| const Framework = "v1.44.0" | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I feel all the changes in the
go.work.sumare not related to scope of this PR so please revert them back.