goopts

README

goopts, a Go library to parse arguments given in command line to a program.

goopts is a powerful and flexible library designed to simplify the parsing of command-line arguments in Go applications. Inspired by popular argument parsing libraries from other languages, goopts aims to provide developers with a robust, easy-to-use interface for handling various argument types, including positional arguments, named options, flags, and more. The library also supports advanced features like argument groups, mutually exclusive options, and dependency handling, making it an excellent choice for building feature-rich CLI tools.

Whether you are developing a simple utility or a complex command-line application, goopts offers the tools you need to parse and manage user input efficiently and effectively.

Purpose

The purpose of goopts is to:

• Provide a straightforward and intuitive way to define and parse command-line arguments.
• Support multiple types of arguments including strings, integers, booleans, lists, and maps.
• Enable the grouping of arguments, including mutually exclusive groups and dependent arguments.
• Offer clear, customizable help messages for your command-line tools.
• Allow for flexible configuration and easy integration into existing Go projects.

Documentation

• 1. Getting Started
  • 1.1 Installation Instructions
  • 1.2 Basic Example of Setting Up goopts
  • 1.3 Positional vs. Named Arguments
• 2. Examples
  • 2.1. Basic Example
  • 2.2. Parsing HTTP Headers and Other Advanced Use Cases
  • 2.3. Complex CLI Tool with Multiple Groups
• 3. Positionals
  • 3.1. Integer Argument
  • 3.2. String Argument
• 4. Arguments
  • 3. Simple Argument Types
    • 4.3.1. Boolean Argument
    • 4.3.2. Integer Argument
    • 4.3.3. String Argument
  • 4. Complex Argument Types
    • 4.4.1. TCP Port
    • 4.4.2. List of Strings
    • 4.4.3. Map of HTTP Headers
• 5. Argument Groups
  • 1. Mutually Exclusive Argument Groups
  • 2. Dependent Argument Groups
• 6. Best Practices
  • 1. Organizing Your Code with goopts
  • 2. Common Pitfalls and How to Avoid Them

Example code

Here is an example code to illustrate a few of the features of goopts:

import (
	"fmt"

	"github.com/p0dalirius/goopts/parser"
)

var (
	// Positional arguments
	filePath     string
	outputFolder string

	// Authentication flags
	dbHost     string
	dbUsername string
	dbPassword string
	dbPort     int

	// Server settings flags
	serverIP   string
	serverPort int

	// Feature flags
	enableLogging     bool
	disableEncryption bool
)

func parseArgs() {
	// Create a new arguments parser with a custom banner
	ap := parser.ArgumentsParser{Banner: "PoC of goopts parsing v.1.1 - by Remi GASCOU (Podalirius)"}

	// Define positional arguments
	ap.NewStringPositionalArgument(&filePath, "filepath", "Path to the input file.")
	ap.NewStringPositionalArgument(&outputFolder, "outputfolder", "Destination folder for output.")

	// Define global flags
	ap.NewBoolArgument(&enableLogging, "-l", "--enable-logging", true, "Enable logging during execution.")
	ap.NewBoolArgument(&disableEncryption, "-e", "--disable-encryption", false, "Disable encryption for data transfer.")

	// Define an argument group for database authentication
	group_dbAuth, err := ap.NewArgumentGroup("Database Authentication")
	if err != nil {
		fmt.Printf("[error] Error creating ArgumentGroup: %s\n", err)
	} else {
		group_dbAuth.NewStringArgument(&dbHost, "-H", "--db-host", "", true, "Hostname or IP of the database server.")
		group_dbAuth.NewStringArgument(&dbUsername, "-U", "--db-username", "", true, "Username for database authentication.")
		group_dbAuth.NewStringArgument(&dbPassword, "-P", "--db-password", "", true, "Password for database authentication.")
		group_dbAuth.NewIntArgument(&dbPort, "-p", "--db-port", 3306, false, "Port number of the database server.")
	}

	// Define an argument group for server settings
	group_serverSettings, err := ap.NewArgumentGroup("Server Settings")
	if err != nil {
		fmt.Printf("[error] Error creating ArgumentGroup: %s\n", err)
	} else {
		group_serverSettings.NewStringArgument(&serverIP, "-i", "--server-ip", "", true, "IP address of the server to connect.")
		group_serverSettings.NewTcpPortArgument(&serverPort, "-s", "--server-port", 8080, false, "Port on which the server listens.")
	}

	// Parse the flags
	ap.Parse()
}

This results in the following arguments and usage printing:

Contributing

Pull requests are welcome. Feel free to open an issue if you want to add other features.

Credits

• @p0dalirius for the creation of the goopts library before transferring it to TheManticoreProject.