README

Natural and safe command-line argument parsing for phel CLI programs.

A small and focused command-line option and argument parser for phel.

Overview

phel-getopt is a library for parsing command-line options and arguments in phel CLI programs. It provides clear, predictable, and phel-friendly command-line parsing with a simple and explicit API.

Installation

composer require smeghead/phel-getopt

Usage

Basic Usage

(ns app\core
  (:require smeghead\getopt\getopt))

(def options ["-a"         # short option `a` without value
              "--output:"  # long option `output` with value(required)
             ])
(def result (getopt/getopt argv options))

(println "options:" (result :options))
(println "arguments:" (result :args))

$ vendor/bin/phel run examples/example.phel -a --output ./output.txt one two
options: {:a true, :output ./output.txt}
arguments: [one two]

Option Definitions

Options are defined as strings with the following format:

Format	Meaning	Example
`"-x"`	Short option without value	`"-a"`
`"-x:"`	Short option with required value	`"-o:"`
`"--name"`	Long option without value	`"--verbose"`
`"--name:"`	Long option with required value	`"--output:"`

The colon suffix (:) indicates that an option requires a value.

Result Structure

The getopt function returns a Result struct with three fields:

:args - Vector of positional arguments
:options - Map of option keywords to their values
:errors - Vector of error messages (empty if successful)

Practical Examples

Multiple Arguments

(def options [])
(def result (getopt/getopt ["one" "two"] options))
;; result: {:args ["one" "two"], :options {}, :errors []}

Short Options with Values

(def options ["-a:"])
(def result (getopt/getopt ["-a" "param" "one" "two"] options))
;; result: {:args ["one" "two"], :options {:a "param"}, :errors []}

Combined Short Options

(def options ["-a:"])
(def result (getopt/getopt ["-aparam" "one" "two"] options))
;; result: {:args ["one" "two"], :options {:a "param"}, :errors []}

Long Options with Values

(def options ["--amazing:"])
(def result (getopt/getopt ["--amazing=man" "one" "two"] options))
;; result: {:args ["one" "two"], :options {:amazing "man"}, :errors []}

Error Handling

(def options ["-a"])
(def result (getopt/getopt ["--unknown" "one" "two"] options))
;; result: {:args ["one" "two"], :options {}, :errors ["Unknown option: \"--unknown\""]}

Stop Parsing with --

(def options ["-a"])
(def result (getopt/getopt ["--" "-a" "one" "two"] options))
;; result: {:args ["-a" "one" "two"], :options {}, :errors []}

API Reference

getopt/getopt

(defn getopt [args options])

args - Vector of command-line arguments (normalized argv)
options - Vector of option definition strings
Returns - Result struct with :args, :options, and :errors fields

Notes

This library assumes a normalized argv provided by Phel v0.28.0+ and focuses solely on option and argument parsing. For development setup instructions, see the original README history.

Development

Initial

composer init
composer require phel-lang/phel-lang:dev-main
vendor/bin/phel init

smeghead / phel-getopt

Maintainers

Details