···
as determined by command-line arguments and environment variables. *)
364
-
(** [term app_name fs] creates a Cmdliner term for XDG directory configuration.
366
-
This function generates a Cmdliner term that handles all XDG directory
364
+
(** [term app_name fs ?config ?data ?cache ?state ?runtime ()] creates a
365
+
Cmdliner term for XDG directory configuration.
367
+
This function generates a Cmdliner term that handles XDG directory
configuration through both command-line flags and environment variables,
368
-
and directly returns the XDG context.
369
+
and directly returns the XDG context. Individual directory flags can be
370
+
disabled by passing [false] for the corresponding optional parameter.
@param app_name The application name (used for environment variable prefixes)
@param fs The Eio filesystem to use for path resolution
374
+
@param config Include [--config-dir] flag (default: true)
375
+
@param data Include [--data-dir] flag (default: true)
376
+
@param cache Include [--cache-dir] flag (default: true)
377
+
@param state Include [--state-dir] flag (default: true)
378
+
@param runtime Include [--runtime-dir] flag (default: true)
{b Generated Command-line Flags:}
374
-
- [--config-dir DIR]: Override configuration directory
375
-
- [--data-dir DIR]: Override data directory
376
-
- [--cache-dir DIR]: Override cache directory
377
-
- [--state-dir DIR]: Override state directory
378
-
- [--runtime-dir DIR]: Override runtime directory
381
+
Only the flags for enabled directories are generated:
382
+
- [--config-dir DIR]: Override configuration directory (if [config=true])
383
+
- [--data-dir DIR]: Override data directory (if [data=true])
384
+
- [--cache-dir DIR]: Override cache directory (if [cache=true])
385
+
- [--state-dir DIR]: Override state directory (if [state=true])
386
+
- [--runtime-dir DIR]: Override runtime directory (if [runtime=true])
{b Environment Variable Precedence:}
For each directory type, the following precedence applies:
382
-
+ Command-line flag (e.g., [--config-dir])
390
+
+ Command-line flag (e.g., [--config-dir]) - if enabled
+ Application-specific variable (e.g., [MYAPP_CONFIG_DIR])
+ XDG standard variable (e.g., [XDG_CONFIG_HOME])
395
+
{b Example - All directories:}
390
-
let main (xdg, _config) =
391
-
(* use xdg directly *)
393
-
let xdg_term = Cmd.term "myapp" env#fs in
398
+
let xdg_term = Cmd.term "myapp" env#fs () in
399
+
let main_term = Term.(const main $ xdg_term $ other_args) in
403
+
{b Example - Only cache directory:}
405
+
let open Cmdliner in
406
+
let xdg_term = Cmd.term "myapp" env#fs
407
+
~config:false ~data:false ~state:false ~runtime:false () in
let main_term = Term.(const main $ xdg_term $ other_args) in
397
-
val term : string -> Eio.Fs.dir_ty Eio.Path.t -> (xdg_t * t) Cmdliner.Term.t
411
+
val term : string -> Eio.Fs.dir_ty Eio.Path.t ->
412
+
?config:bool -> ?data:bool -> ?cache:bool -> ?state:bool -> ?runtime:bool ->
413
+
unit -> (xdg_t * t) Cmdliner.Term.t
415
+
(** [cache_term app_name] creates a Cmdliner term that provides just the cache
416
+
directory path as a string, respecting XDG precedence.
418
+
This is a convenience function for applications that only need cache
419
+
directory configuration. It returns the resolved cache directory path
420
+
directly as a string, suitable for use in other Cmdliner terms.
422
+
@param app_name The application name (used for environment variable prefixes)
424
+
{b Generated Command-line Flag:}
425
+
- [--cache-dir DIR]: Override cache directory
427
+
{b Environment Variable Precedence:}
428
+
+ Command-line flag ([--cache-dir])
429
+
+ Application-specific variable (e.g., [MYAPP_CACHE_DIR])
430
+
+ XDG standard variable ([XDG_CACHE_HOME])
431
+
+ Default value ([$HOME/.cache/{app_name}])
435
+
let cache_dir_term = Xdge.Cmd.cache_term "myapp" in
436
+
let main cache_dir other_args =
437
+
(* use cache_dir as a string path *)
439
+
let main_term = Term.(const main $ cache_dir_term $ other_args) in
441
+
val cache_term : string -> string Cmdliner.Term.t
(** [env_docs app_name] generates documentation for environment variables.
anil.recoil.org