diff options
| -rw-r--r-- | cmd/gt/main.go | 60 | ||||
| -rw-r--r-- | internal/version.go | 45 |
2 files changed, 103 insertions, 2 deletions
diff --git a/cmd/gt/main.go b/cmd/gt/main.go index 795dbe9..c571792 100644 --- a/cmd/gt/main.go +++ b/cmd/gt/main.go @@ -1,3 +1,46 @@ +// Package gt provides a command-line percentage calculator with RPN support. +// +// gt is a versatile calculator that supports both percentage calculations and +// Reverse Polish Notation (RPN) expressions. It can be used in two modes: +// +// 1. Command-line mode: Pass calculations as arguments +// gt 20% of 150 # Calculate 20% of 150 +// gt 3 4 + # RPN expression: 3 + 4 +// +// 2. Interactive REPL mode: Run without arguments to start an interactive session +// gt # Start interactive REPL +// +// Percentage Calculations +// +// The calculator supports various percentage formats: +// - Basic percentage: "20% of 150" → 30 +// - With prefix: "what is 20% of 150" → 30 +// - Reverse percentage: "30 is what % of 150" → 20% +// - Find base: "30 is 20% of what" → 150 +// +// RPN (Reverse Polish Notation) Support +// +// RPN expressions use postfix notation where operators follow operands: +// - Basic operations: "3 4 +" (3 + 4), "5 2 -" (5 - 2) +// - Complex expressions: "3 4 + 4 4 - *" ((3 + 4) * (4 - 4)) +// - Exponentiation: "2 3 ^" (2^3 = 8) +// - Variable assignment: "x 5 = x x +" (assign x=5, then x + x) +// - Stack operations: "dup swap pop show" +// +// Error Handling +// +// Errors from calculations or parsing are printed to stdout with exit code 1. +// Invalid RPN expressions and malformed percentage queries both return errors. +// +// Architecture +// +// The package uses a layered architecture: +// - main.go: Entry point and command routing +// - calculator/: Handles percentage calculation parsing +// - rpn/: Handles RPN expression parsing and evaluation +// - repl/: Provides interactive Read-Eval-Print Loop mode +// +// See the cmd/gt/internal package for version information. package main import ( @@ -12,6 +55,7 @@ import ( "github.com/mattn/go-isatty" ) +// main is the entry point for the gt command-line calculator. func main() { output, err := runCommand(os.Args) if err != nil { @@ -21,6 +65,12 @@ func main() { fmt.Println(output) } +// runCommand processes command-line arguments and executes the appropriate action. +// +// It handles: +// - No arguments: Start REPL mode if stdin is a TTY, otherwise show usage +// - "version" argument: Return the version string +// - Other arguments: Try RPN parsing first, then fall back to percentage calculation func runCommand(args []string) (string, error) { if len(args) < 2 { // No args provided - check if stdin is a TTY for REPL mode @@ -55,7 +105,9 @@ func runCommand(args []string) (string, error) { return result, nil } -// runREPL runs the REPL and handles errors +// runREPL starts the interactive REPL mode. +// +// It wraps repl.RunREPL() and returns an error if the REPL fails to start. func runREPL() error { if err := repl.RunREPL(); err != nil { return fmt.Errorf("REPL error: %w", err) @@ -63,13 +115,17 @@ func runREPL() error { return nil } -// runRPN parses and evaluates an RPN expression +// runRPN parses and evaluates an RPN (Reverse Polish Notation) expression. +// +// It creates a fresh RPN calculator with fresh variable store for each call, +// making it suitable for one-off calculations. func runRPN(input string) (string, error) { vars := rpn.NewVariables() rpnCalc := rpn.NewRPN(vars) return rpnCalc.ParseAndEvaluate(input) } +// printUsage displays the command-line usage information and examples. func printUsage() { fmt.Println("Usage: gt <calculation>") fmt.Println(" gt version") diff --git a/internal/version.go b/internal/version.go index 2137e45..24a97ea 100644 --- a/internal/version.go +++ b/internal/version.go @@ -1,3 +1,48 @@ +// Package internal provides version information for the gt application. +// +// This package contains internal constants that are used across the gt project. +// It is not intended for direct use by external code and may change without notice. +// +// Package Location +// +// The internal package is located at internal/version.go and contains: +// - Version: Current application version string +// +// Version Format +// +// The version string follows semantic versioning (SemVer) format: +// - Major.Minor.Patch (e.g., "v0.3.0") +// - Pre-release versions may include suffixes like "-beta", "-rc1", etc. +// - Build metadata may be appended for development builds +// +// Usage in Code +// +// To access the version from the main command: +// +// import "codeberg.org/snonux/perc/internal" +// +// func main() { +// fmt.Println("gt version", internal.Version) +// } +// +// Version History +// +// Current: v0.3.0 +// +// See the git repository for complete version history and release notes. package internal +// Version is the current version of the gt application. +// +// This constant is defined at build time and can be overridden during builds: +// go build -ldflags="-X 'codeberg.org/snonux/perc/internal.Version=v0.3.0-20240324'" +// +// The version is used in: +// - Command-line output: "gt version" command +// - Help and about information +// - Error messages and diagnostics +// +// Example output: +// $ gt version +// v0.3.0 const Version = "v0.3.0" |