README

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

phel-getopt

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.

Latest version(v0.28.0) of phel normalize argv so that the same arguments are available regardless of how a program is executed (file, namespace, or compiled PHP).

With this improvement in phel itself, phel-getopt focuses solely on providing clear, predictable, and phel-friendly command-line parsing.

Why phel-getopt?

Even with normalized argv, parsing command-line options remains a non-trivial task.

PHP’s built-in getopt() has several characteristics that make it awkward to use from phel:

• It enforces PHP-specific conventions
• It has unintuitive behavior for long options
• It is tightly coupled to PHP’s global state
• It does not feel natural in a Lisp-style language

phel-getopt exists to offer a simpler and more explicit alternative designed for phel programs.

What This Library Does

phel-getopt provides:

• Parsing of short and long options
• Separation of options and positional arguments
• A clear and explicit data structure as the result
• Behavior suitable for CLI tools written in phel

It does not attempt to handle execution-method differences or argv normalization — those concerns are handled by phel itself.

Design Goals

• Simple and explicit parsing rules
• No reliance on global state
• Predictable behavior
• Easy to reason about in phel code
• Small surface area and minimal magic

The goal is not to replicate every feature of GNU getopt, but to provide a practical and understandable tool for everyday phel CLI programs.

When to Use phel-getopt

Use this library if you are:

• Writing CLI tools in phel
• Looking for an alternative to PHP’s getopt()
• Wanting explicit control over options and arguments
• Preferring a small, focused dependency

When Not to Use It

You may not need phel-getopt if:

• Your program accepts no command-line options
• You are comfortable using PHP’s getopt() directly
• You need full GNU getopt compatibility

Background

Earlier versions of this library also addressed differences in argv caused by various phel execution methods.

As of recent phel releases, argv is normalized by phel itself. This library has since narrowed its scope to option and argument parsing only.

Summary

phel-getopt is a lightweight command-line parsing library for phel.

It assumes a normalized argv and focuses on doing one thing well: turning command-line arguments into a clear and usable structure for phel CLI programs.

Composer Install

composer require smeghead/phel-getopt

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 "*program*:" *program*)
(println "argv:" argv)
(println "options:" (result :options))
(println "arguments:" (result :args))

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

Development

Initial

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