Initial commit
This commit is contained in:
Zhongwei Li
765
skills/babashka-cli/SKILL.md
Normal file
765
skills/babashka-cli/SKILL.md
Normal file
@@ -0,0 +1,765 @@
|
||||
---
|
||||
name: babashka.cli
|
||||
description: Command-line argument parsing for turning Clojure functions into CLIs
|
||||
---
|
||||
|
||||
# babashka.cli
|
||||
|
||||
Command-line argument parsing library for transforming Clojure functions into CLIs with minimal effort.
|
||||
|
||||
## Overview
|
||||
|
||||
babashka.cli converts command-line arguments into Clojure data structures, supporting both keyword-style (`:opt value`) and Unix-style (`--opt value`) arguments. Designed to minimize friction when creating CLIs from existing Clojure functions.
|
||||
|
||||
**Key Features:**
|
||||
- Automatic type coercion
|
||||
- Flexible argument syntax (`:foo` or `--foo`)
|
||||
- Subcommand dispatch
|
||||
- Validation and error handling
|
||||
- Boolean flags and negative flags
|
||||
- Collection handling for repeated options
|
||||
- Default values
|
||||
|
||||
**Artifact:** `org.babashka/cli`
|
||||
**Latest Version:** 0.8.60
|
||||
**License:** MIT
|
||||
**Repository:** https://github.com/babashka/cli
|
||||
|
||||
## Installation
|
||||
|
||||
Add to `deps.edn`:
|
||||
```clojure
|
||||
{:deps {org.babashka/cli {:mvn/version "0.8.60"}}}
|
||||
```
|
||||
|
||||
Or `bb.edn` for Babashka:
|
||||
```clojure
|
||||
{:deps {org.babashka/cli {:mvn/version "0.8.60"}}}
|
||||
```
|
||||
|
||||
Since babashka 0.9.160, babashka.cli is built-in.
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### Parsing vs. Args Separation
|
||||
|
||||
- `parse-opts` - Returns flat map of parsed options
|
||||
- `parse-args` - Separates into `:opts`, `:cmds`, `:rest-args`
|
||||
|
||||
### Open World Assumption
|
||||
|
||||
Extra arguments don't cause errors by default. Use `:restrict` for strict validation.
|
||||
|
||||
### Coercion Strategy
|
||||
|
||||
Values are coerced based on specifications, not inferred from values alone. This ensures predictable type handling.
|
||||
|
||||
## API Reference
|
||||
|
||||
### Parsing Functions
|
||||
|
||||
#### parse-opts
|
||||
|
||||
Parse command-line arguments into options map.
|
||||
|
||||
```clojure
|
||||
(require '[babashka.cli :as cli])
|
||||
|
||||
;; Basic parsing
|
||||
(cli/parse-opts ["--port" "8080"])
|
||||
;;=> {:port "8080"}
|
||||
|
||||
;; With coercion
|
||||
(cli/parse-opts ["--port" "8080"] {:coerce {:port :long}})
|
||||
;;=> {:port 8080}
|
||||
|
||||
;; With aliases
|
||||
(cli/parse-opts ["-p" "8080"]
|
||||
{:alias {:p :port}
|
||||
:coerce {:port :long}})
|
||||
;;=> {:port 8080}
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `:coerce` - Type coercion map (`:boolean`, `:int`, `:long`, `:double`, `:symbol`, `:keyword`)
|
||||
- `:alias` - Short name to long name mappings
|
||||
- `:spec` - Structured option specifications
|
||||
- `:restrict` - Restrict to specified options only
|
||||
- `:require` - Required option keys
|
||||
- `:validate` - Validation predicates
|
||||
- `:exec-args` - Default values
|
||||
- `:args->opts` - Map positional args to option keys
|
||||
- `:no-keyword-opts` - Only accept `--foo` style (not `:foo`)
|
||||
- `:error-fn` - Custom error handler
|
||||
|
||||
#### parse-args
|
||||
|
||||
Parse arguments with separation of options, commands, and rest args.
|
||||
|
||||
```clojure
|
||||
(cli/parse-args ["--verbose" "deploy" "prod" "--force"]
|
||||
{:coerce {:verbose :boolean :force :boolean}})
|
||||
;;=> {:cmds ["deploy" "prod"]
|
||||
;; :opts {:verbose true :force true}
|
||||
;; :rest-args []}
|
||||
```
|
||||
|
||||
Returns map with:
|
||||
- `:opts` - Parsed options
|
||||
- `:cmds` - Subcommands (non-option arguments)
|
||||
- `:rest-args` - Arguments after `--`
|
||||
|
||||
#### parse-cmds
|
||||
|
||||
Extract subcommands from arguments.
|
||||
|
||||
```clojure
|
||||
(cli/parse-cmds ["deploy" "prod" "--force"])
|
||||
;;=> {:cmds ["deploy" "prod"]
|
||||
;; :args ["--force"]}
|
||||
|
||||
;; Without keyword opts
|
||||
(cli/parse-cmds ["deploy" ":env" "prod"]
|
||||
{:no-keyword-opts true})
|
||||
;;=> {:cmds ["deploy" ":env" "prod"]
|
||||
;; :args []}
|
||||
```
|
||||
|
||||
### Coercion
|
||||
|
||||
#### Type Keywords
|
||||
|
||||
- `:boolean` - True/false values
|
||||
- `:int` - Integer
|
||||
- `:long` - Long integer
|
||||
- `:double` - Floating point
|
||||
- `:symbol` - Clojure symbol
|
||||
- `:keyword` - Clojure keyword
|
||||
|
||||
#### Collection Coercion
|
||||
|
||||
Use empty vector to collect multiple values:
|
||||
|
||||
```clojure
|
||||
(cli/parse-opts ["--path" "src" "--path" "test"]
|
||||
{:coerce {:path []}})
|
||||
;;=> {:path ["src" "test"]}
|
||||
```
|
||||
|
||||
Typed collections:
|
||||
|
||||
```clojure
|
||||
(cli/parse-opts ["--port" "8080" "--port" "8081"]
|
||||
{:coerce {:port [:long]}})
|
||||
;;=> {:port [8080 8081]}
|
||||
```
|
||||
|
||||
#### auto-coerce
|
||||
|
||||
Automatic coercion for unspecified options (enabled by default):
|
||||
|
||||
```clojure
|
||||
(cli/parse-opts ["--enabled" "true" "--count" "42" "--mode" ":prod"])
|
||||
;;=> {:enabled true :count 42 :mode :prod}
|
||||
```
|
||||
|
||||
Converts:
|
||||
- `"true"`/`"false"` → boolean
|
||||
- Numeric strings → numbers via `edn/read-string`
|
||||
- Strings starting with `:` → keywords
|
||||
|
||||
### Boolean Flags
|
||||
|
||||
```clojure
|
||||
;; Flag present = true
|
||||
(cli/parse-opts ["--verbose"])
|
||||
;;=> {:verbose true}
|
||||
|
||||
;; Combined short flags
|
||||
(cli/parse-opts ["-vvv"])
|
||||
;;=> {:v true}
|
||||
|
||||
;; Negative flags
|
||||
(cli/parse-opts ["--no-colors"])
|
||||
;;=> {:colors false}
|
||||
|
||||
;; Explicit values
|
||||
(cli/parse-opts ["--force" "false"]
|
||||
{:coerce {:force :boolean}})
|
||||
;;=> {:force false}
|
||||
```
|
||||
|
||||
### Positional Arguments
|
||||
|
||||
#### Basic args->opts
|
||||
|
||||
Map positional arguments to named options:
|
||||
|
||||
```clojure
|
||||
(cli/parse-opts ["deploy" "production"]
|
||||
{:args->opts [:action :env]})
|
||||
;;=> {:action "deploy" :env "production"}
|
||||
```
|
||||
|
||||
#### Variable Length Collections
|
||||
|
||||
Use `repeat` for collecting remaining args:
|
||||
|
||||
```clojure
|
||||
(cli/parse-opts ["build" "foo.clj" "bar.clj" "baz.clj"]
|
||||
{:args->opts (cons :cmd (repeat :files))
|
||||
:coerce {:files []}})
|
||||
;;=> {:cmd "build" :files ["foo.clj" "bar.clj" "baz.clj"]}
|
||||
```
|
||||
|
||||
#### Mixed Options and Arguments
|
||||
|
||||
```clojure
|
||||
(cli/parse-opts ["--verbose" "deploy" "prod" "--force"]
|
||||
{:coerce {:verbose :boolean :force :boolean}
|
||||
:args->opts [:action :env]})
|
||||
;;=> {:verbose true :action "deploy" :env "prod" :force true}
|
||||
```
|
||||
|
||||
### Validation
|
||||
|
||||
#### Required Options
|
||||
|
||||
```clojure
|
||||
(cli/parse-args ["--name" "app"]
|
||||
{:require [:name :version]})
|
||||
;; Throws: Required option: :version
|
||||
```
|
||||
|
||||
#### Restricted Options
|
||||
|
||||
```clojure
|
||||
(cli/parse-args ["--verbose" "--debug"]
|
||||
{:restrict [:verbose]})
|
||||
;; Throws: Unknown option: :debug
|
||||
```
|
||||
|
||||
#### Custom Validators
|
||||
|
||||
```clojure
|
||||
(cli/parse-args ["--port" "0"]
|
||||
{:coerce {:port :long}
|
||||
:validate {:port pos?}})
|
||||
;; Throws: Invalid value for option :port: 0
|
||||
|
||||
;; With custom message
|
||||
(cli/parse-args ["--port" "-1"]
|
||||
{:coerce {:port :long}
|
||||
:validate {:port {:pred pos?
|
||||
:ex-msg (fn [{:keys [option value]}]
|
||||
(str option " must be positive, got: " value))}}})
|
||||
;; Throws: :port must be positive, got: -1
|
||||
```
|
||||
|
||||
### Default Values
|
||||
|
||||
Provide defaults via `:exec-args`:
|
||||
|
||||
```clojure
|
||||
(cli/parse-args ["--port" "9000"]
|
||||
{:coerce {:port :long}
|
||||
:exec-args {:port 8080 :host "localhost"}})
|
||||
;;=> {:opts {:port 9000 :host "localhost"}}
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
Custom error handler:
|
||||
|
||||
```clojure
|
||||
(defn error-handler [{:keys [type cause msg option]}]
|
||||
(when (= type :org.babashka/cli)
|
||||
(println "Error:" msg)
|
||||
(when option
|
||||
(println "Option:" option))
|
||||
(System/exit 1)))
|
||||
|
||||
(cli/parse-args ["--invalid"]
|
||||
{:restrict [:valid]
|
||||
:error-fn error-handler})
|
||||
```
|
||||
|
||||
Error causes:
|
||||
- `:restrict` - Unknown option
|
||||
- `:require` - Missing required option
|
||||
- `:validate` - Validation failed
|
||||
- `:coerce` - Type coercion failed
|
||||
|
||||
### Subcommand Dispatch
|
||||
|
||||
#### dispatch
|
||||
|
||||
Route execution based on subcommands:
|
||||
|
||||
```clojure
|
||||
(defn deploy [opts]
|
||||
(println "Deploying to" (:env opts)))
|
||||
|
||||
(defn rollback [opts]
|
||||
(println "Rolling back" (:version opts)))
|
||||
|
||||
(def table
|
||||
[{:cmds ["deploy"] :fn deploy :args->opts [:env]}
|
||||
{:cmds ["rollback"] :fn rollback :args->opts [:version]}
|
||||
{:cmds [] :fn (fn [_] (println "No command specified"))}])
|
||||
|
||||
(cli/dispatch table ["deploy" "production"])
|
||||
;; Prints: Deploying to production
|
||||
|
||||
(cli/dispatch table ["rollback" "v1.2.3"])
|
||||
;; Prints: Rolling back v1.2.3
|
||||
```
|
||||
|
||||
#### Nested Subcommands
|
||||
|
||||
```clojure
|
||||
(def table
|
||||
[{:cmds ["db" "migrate"] :fn db-migrate}
|
||||
{:cmds ["db" "rollback"] :fn db-rollback}
|
||||
{:cmds ["db"] :fn (fn [_] (println "db requires subcommand"))}])
|
||||
|
||||
(cli/dispatch table ["db" "migrate" "--env" "prod"])
|
||||
```
|
||||
|
||||
#### Dispatch Options
|
||||
|
||||
Pass options to parse-args:
|
||||
|
||||
```clojure
|
||||
(cli/dispatch table args
|
||||
{:coerce {:port :long}
|
||||
:exec-args {:host "localhost"}})
|
||||
```
|
||||
|
||||
The `:fn` receives enhanced parse-args result:
|
||||
- `:dispatch` - Matched command path
|
||||
- `:args` - Remaining unparsed arguments
|
||||
- `:opts` - Parsed options
|
||||
- `:cmds` - Subcommands
|
||||
|
||||
### Formatting & Help
|
||||
|
||||
#### format-opts
|
||||
|
||||
Generate help text from spec:
|
||||
|
||||
```clojure
|
||||
(def spec
|
||||
{:port {:desc "Port to listen on"
|
||||
:default 8080
|
||||
:coerce :long}
|
||||
:host {:desc "Host address"
|
||||
:default "localhost"
|
||||
:alias :h}
|
||||
:verbose {:desc "Enable verbose output"
|
||||
:alias :v}})
|
||||
|
||||
(println (cli/format-opts {:spec spec}))
|
||||
;; Output:
|
||||
;; --port Port to listen on (default: 8080)
|
||||
;; --host, -h Host address (default: localhost)
|
||||
;; --verbose, -v Enable verbose output
|
||||
```
|
||||
|
||||
With custom indent:
|
||||
|
||||
```clojure
|
||||
(cli/format-opts {:spec spec :indent 4})
|
||||
```
|
||||
|
||||
#### format-table
|
||||
|
||||
Format tabular data:
|
||||
|
||||
```clojure
|
||||
(cli/format-table
|
||||
{:rows [["Name" "Type" "Default"]
|
||||
["port" "long" "8080"]
|
||||
["host" "string" "localhost"]]
|
||||
:indent 2})
|
||||
```
|
||||
|
||||
#### spec->opts
|
||||
|
||||
Convert spec to parse options:
|
||||
|
||||
```clojure
|
||||
(def spec
|
||||
{:port {:ref "<port>"
|
||||
:desc "Server port"
|
||||
:coerce :long
|
||||
:default 8080}})
|
||||
|
||||
(cli/spec->opts spec)
|
||||
;;=> {:coerce {:port :long}}
|
||||
|
||||
(cli/spec->opts spec {:exec-args true})
|
||||
;;=> {:coerce {:port :long} :exec-args {:port 8080}}
|
||||
```
|
||||
|
||||
### Option Merging
|
||||
|
||||
#### merge-opts
|
||||
|
||||
Combine multiple option specifications:
|
||||
|
||||
```clojure
|
||||
(def base-opts
|
||||
{:coerce {:verbose :boolean}})
|
||||
|
||||
(def server-opts
|
||||
{:coerce {:port :long}
|
||||
:exec-args {:port 8080}})
|
||||
|
||||
(cli/merge-opts base-opts server-opts)
|
||||
;;=> {:coerce {:verbose :boolean :port :long}
|
||||
;; :exec-args {:port 8080}}
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### CLI Application Entry Point
|
||||
|
||||
```clojure
|
||||
#!/usr/bin/env bb
|
||||
|
||||
(ns my-app
|
||||
(:require [babashka.cli :as cli]))
|
||||
|
||||
(defn run [{:keys [port host verbose]}]
|
||||
(when verbose
|
||||
(println "Starting server on" host ":" port))
|
||||
;; ... server logic
|
||||
)
|
||||
|
||||
(def spec
|
||||
{:port {:desc "Port to listen on"
|
||||
:coerce :long
|
||||
:default 8080}
|
||||
:host {:desc "Host address"
|
||||
:default "localhost"}
|
||||
:verbose {:desc "Enable verbose output"
|
||||
:alias :v
|
||||
:coerce :boolean}})
|
||||
|
||||
(defn -main [& args]
|
||||
(cli/parse-args args
|
||||
{:spec spec
|
||||
:exec-args (:default spec)
|
||||
:error-fn (fn [{:keys [msg]}]
|
||||
(println msg)
|
||||
(println)
|
||||
(println "Usage: my-app [options]")
|
||||
(println (cli/format-opts {:spec spec}))
|
||||
(System/exit 1))}))
|
||||
|
||||
(when (= *file* (System/getProperty "babashka.file"))
|
||||
(apply -main *command-line-args*))
|
||||
```
|
||||
|
||||
### Subcommand CLI
|
||||
|
||||
```clojure
|
||||
#!/usr/bin/env bb
|
||||
|
||||
(ns my-cli
|
||||
(:require [babashka.cli :as cli]))
|
||||
|
||||
(defn build [{:keys [opts]}]
|
||||
(println "Building with options:" opts))
|
||||
|
||||
(defn test [{:keys [opts]}]
|
||||
(println "Running tests with options:" opts))
|
||||
|
||||
(defn help [_]
|
||||
(println "Commands: build, test"))
|
||||
|
||||
(def commands
|
||||
[{:cmds ["build"]
|
||||
:fn build
|
||||
:spec {:target {:coerce :keyword}
|
||||
:release {:coerce :boolean}}}
|
||||
{:cmds ["test"]
|
||||
:fn test
|
||||
:spec {:watch {:coerce :boolean}}}
|
||||
{:cmds []
|
||||
:fn help}])
|
||||
|
||||
(defn -main [& args]
|
||||
(cli/dispatch commands args))
|
||||
|
||||
(when (= *file* (System/getProperty "babashka.file"))
|
||||
(apply -main *command-line-args*))
|
||||
```
|
||||
|
||||
### Configuration File + CLI Override
|
||||
|
||||
```clojure
|
||||
(require '[clojure.edn :as edn])
|
||||
|
||||
(defn load-config [path]
|
||||
(when (.exists (io/file path))
|
||||
(edn/read-string (slurp path))))
|
||||
|
||||
(defn run [args]
|
||||
(let [file-config (load-config "config.edn")
|
||||
cli-opts (cli/parse-args args
|
||||
{:coerce {:port :long
|
||||
:workers :long}})
|
||||
final-config (merge file-config (:opts cli-opts))]
|
||||
;; Use final-config
|
||||
))
|
||||
```
|
||||
|
||||
### Babashka Task Integration
|
||||
|
||||
In `bb.edn`:
|
||||
|
||||
```clojure
|
||||
{:tasks
|
||||
{:requires ([babashka.cli :as cli])
|
||||
|
||||
test {:doc "Run tests"
|
||||
:task (let [opts (cli/parse-opts *command-line-args*
|
||||
{:coerce {:watch :boolean}})]
|
||||
(when (:watch opts)
|
||||
(println "Running in watch mode"))
|
||||
(shell "clojure -M:test"))}}}
|
||||
```
|
||||
|
||||
### Long Option Syntax Variations
|
||||
|
||||
```clojure
|
||||
;; All equivalent
|
||||
(cli/parse-opts ["--port" "8080"])
|
||||
(cli/parse-opts ["--port=8080"])
|
||||
(cli/parse-opts [":port" "8080"])
|
||||
|
||||
;; With coercion
|
||||
(cli/parse-opts ["--port=8080"] {:coerce {:port :long}})
|
||||
;;=> {:port 8080}
|
||||
```
|
||||
|
||||
### Repeated Options
|
||||
|
||||
```clojure
|
||||
;; Collect into vector
|
||||
(cli/parse-opts ["--include" "*.clj" "--include" "*.cljs"]
|
||||
{:coerce {:include []}})
|
||||
;;=> {:include ["*.clj" "*.cljs"]}
|
||||
|
||||
;; Count occurrences
|
||||
(defn inc-counter [m k]
|
||||
(update m k (fnil inc 0)))
|
||||
|
||||
(cli/parse-opts ["-v" "-v" "-v"]
|
||||
{:collect {:v inc-counter}})
|
||||
;;=> {:v 3}
|
||||
```
|
||||
|
||||
### Rest Arguments
|
||||
|
||||
Arguments after `--` are collected as `:rest-args`:
|
||||
|
||||
```clojure
|
||||
(cli/parse-args ["--port" "8080" "--" "arg1" "arg2"]
|
||||
{:coerce {:port :long}})
|
||||
;;=> {:opts {:port 8080}
|
||||
;; :rest-args ["arg1" "arg2"]}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Validation Failure Context
|
||||
|
||||
```clojure
|
||||
(defn validate-port [{:keys [value]}]
|
||||
(and (pos? value) (< value 65536)))
|
||||
|
||||
(cli/parse-args ["--port" "99999"]
|
||||
{:coerce {:port :long}
|
||||
:validate {:port {:pred validate-port
|
||||
:ex-msg (fn [{:keys [option value]}]
|
||||
(format "%s must be 1-65535, got %d"
|
||||
option value))}}})
|
||||
;; Throws: :port must be 1-65535, got 99999
|
||||
```
|
||||
|
||||
### Graceful Degradation
|
||||
|
||||
```clojure
|
||||
(defn safe-parse [args]
|
||||
(try
|
||||
(cli/parse-args args {:coerce {:port :long}})
|
||||
(catch Exception e
|
||||
{:error (ex-message e)
|
||||
:opts {}})))
|
||||
```
|
||||
|
||||
### Exit Code Handling
|
||||
|
||||
```clojure
|
||||
(defn -main [& args]
|
||||
(let [result (cli/parse-args args
|
||||
{:spec spec
|
||||
:error-fn (fn [{:keys [msg]}]
|
||||
(binding [*out* *err*]
|
||||
(println "Error:" msg))
|
||||
1)})]
|
||||
(if (number? result)
|
||||
(System/exit result)
|
||||
(do-work result))))
|
||||
```
|
||||
|
||||
## Use Cases
|
||||
|
||||
### Build Tool CLI
|
||||
|
||||
```clojure
|
||||
(def build-commands
|
||||
[{:cmds ["compile"]
|
||||
:fn compile-project
|
||||
:spec {:target {:coerce :keyword
|
||||
:desc "Compilation target"}
|
||||
:optimization {:coerce :keyword
|
||||
:desc "Optimization level"}}}
|
||||
{:cmds ["package"]
|
||||
:fn package-project
|
||||
:spec {:format {:coerce :keyword
|
||||
:desc "Package format"}}}])
|
||||
```
|
||||
|
||||
### Configuration Management
|
||||
|
||||
```clojure
|
||||
(defn read-env-config []
|
||||
(reduce-kv
|
||||
(fn [m k v]
|
||||
(if (str/starts-with? k "APP_")
|
||||
(assoc m (keyword (str/lower-case (subs k 4))) v)
|
||||
m))
|
||||
{}
|
||||
(System/getenv)))
|
||||
|
||||
(defn merged-config [args]
|
||||
(let [env-config (read-env-config)
|
||||
cli-config (:opts (cli/parse-args args))]
|
||||
(merge env-config cli-config)))
|
||||
```
|
||||
|
||||
### Testing Wrapper
|
||||
|
||||
```clojure
|
||||
(defn test-runner [{:keys [opts]}]
|
||||
(let [{:keys [namespace watch]} opts]
|
||||
(when watch
|
||||
(println "Starting test watcher..."))
|
||||
(apply clojure.test/run-tests
|
||||
(when namespace [(symbol namespace)]))))
|
||||
|
||||
(cli/dispatch
|
||||
[{:cmds ["test"]
|
||||
:fn test-runner
|
||||
:spec {:namespace {:desc "Specific namespace"}
|
||||
:watch {:coerce :boolean
|
||||
:desc "Watch mode"}}}]
|
||||
*command-line-args*)
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Minimize Parsing Overhead
|
||||
|
||||
For frequently called operations, parse once and pass options:
|
||||
|
||||
```clojure
|
||||
(defn process-files [opts files]
|
||||
(doseq [f files]
|
||||
(process-file f opts)))
|
||||
|
||||
(let [opts (cli/parse-args args)]
|
||||
(process-files (:opts opts) (:cmds opts)))
|
||||
```
|
||||
|
||||
### Coercion Functions
|
||||
|
||||
Custom coercion functions are called per-value:
|
||||
|
||||
```clojure
|
||||
;; Efficient: Use keywords for built-in types
|
||||
{:coerce {:port :long}}
|
||||
|
||||
;; Less efficient: Custom function for simple types
|
||||
{:coerce {:port #(Long/parseLong %)}}
|
||||
```
|
||||
|
||||
### Validation Overhead
|
||||
|
||||
Validators run after coercion. Use predicates wisely:
|
||||
|
||||
```clojure
|
||||
;; Good: Simple predicate
|
||||
{:validate {:port pos?}}
|
||||
|
||||
;; Avoid: Complex validation in predicate
|
||||
{:validate {:port (fn [p]
|
||||
(and (pos? p)
|
||||
(< p 65536)
|
||||
(not (contains? reserved-ports p))))}}
|
||||
```
|
||||
|
||||
## Platform Notes
|
||||
|
||||
### Babashka Integration
|
||||
|
||||
Since babashka 0.9.160, babashka.cli is built-in. Access via `bb -x`:
|
||||
|
||||
```bash
|
||||
bb -x my-ns/my-fn :port 8080 :verbose true
|
||||
```
|
||||
|
||||
### Clojure CLI Integration
|
||||
|
||||
Use with `-X` flag:
|
||||
|
||||
```bash
|
||||
clojure -X:my-alias my-ns/my-fn :port 8080
|
||||
```
|
||||
|
||||
Add metadata to functions for specs:
|
||||
|
||||
```clojure
|
||||
(defn ^{:org.babashka/cli {:coerce {:port :long}}}
|
||||
start-server [opts]
|
||||
(println "Starting on port" (:port opts)))
|
||||
```
|
||||
|
||||
### JVM vs Native
|
||||
|
||||
babashka.cli works identically on JVM Clojure and native Babashka with minimal performance differences in parsing itself.
|
||||
|
||||
### Cross-Platform Arguments
|
||||
|
||||
Quote handling varies by shell:
|
||||
|
||||
```bash
|
||||
# Unix shells
|
||||
script --name "My App"
|
||||
|
||||
# Windows cmd.exe
|
||||
script --name "My App"
|
||||
|
||||
# PowerShell
|
||||
script --name 'My App'
|
||||
```
|
||||
|
||||
Use positional args to avoid quoting complexity:
|
||||
|
||||
```bash
|
||||
script deploy production # Better than: script :env "production"
|
||||
```
|
||||
Reference in New Issue
Block a user