package xdge

  1. Overview
  2. Docs
package xdge
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Module Xdge.CmdSource

Sourcetype xdg_t = t

The type of the outer XDG context

Cmdliner integration for XDG directory configuration.

This module provides integration with the Cmdliner library, allowing XDG directories to be configured via command-line arguments while respecting the precedence of environment variables.

Sourcetype t

Type of XDG configuration gathered from command-line and environment.

This contains all XDG directory paths along with their sources, as determined by command-line arguments and environment variables.

Sourcetype dir = [
  1. | `Config
    (*

    User configuration files

    *)
  2. | `Cache
    (*

    User-specific cached data

    *)
  3. | `Data
    (*

    User-specific application data

    *)
  4. | `State
    (*

    User-specific state data (logs, history, etc.)

    *)
  5. | `Runtime
    (*

    User-specific runtime files (sockets, pipes, etc.)

    *)
]

XDG directory types for specifying which directories an application needs.

These allow applications to declare which XDG directories they use, enabling runtime systems to only provide the requested directories.

Sourceval term : string -> Eio.Fs.dir_ty Eio.Path.t -> ?dirs:dir list -> unit -> (xdg_t * t) Cmdliner.Term.t

term app_name fs ?dirs () creates a Cmdliner term for XDG directory configuration.

This function generates a Cmdliner term that handles XDG directory configuration through both command-line flags and environment variables, and directly returns the XDG context. Only command-line flags for the requested directories are generated.

  • parameter app_name

    The application name (used for environment variable prefixes)

  • parameter fs

    The Eio filesystem to use for path resolution

  • parameter dirs

    List of directories to include flags for (default: all directories)

Generated Command-line Flags: Only the flags for requested directories are generated:

  • --config-dir DIR: Override configuration directory (if `Config in dirs)
  • --data-dir DIR: Override data directory (if `Data in dirs)
  • --cache-dir DIR: Override cache directory (if `Cache in dirs)
  • --state-dir DIR: Override state directory (if `State in dirs)
  • --runtime-dir DIR: Override runtime directory (if `Runtime in dirs)

Environment Variable Precedence: For each directory type, the following precedence applies:

  1. Command-line flag (e.g., --config-dir) - if enabled
  2. Application-specific variable (e.g., MYAPP_CONFIG_DIR)
  3. XDG standard variable (e.g., XDG_CONFIG_HOME)
  4. Default value
Sourceval cache_term : string -> string Cmdliner.Term.t

cache_term app_name creates a Cmdliner term that provides just the cache directory path as a string, respecting XDG precedence.

This is a convenience function for applications that only need cache directory configuration. It returns the resolved cache directory path directly as a string, suitable for use in other Cmdliner terms.

  • parameter app_name

    The application name (used for environment variable prefixes)

Generated Command-line Flag:

  • --cache-dir DIR: Override cache directory

Environment Variable Precedence:

  1. Command-line flag (--cache-dir)
  2. Application-specific variable (e.g., MYAPP_CACHE_DIR)
  3. XDG standard variable (XDG_CACHE_HOME)
  4. Default value ($HOME/.cache/{app_name})
Sourceval env_docs : string -> string

env_docs app_name generates documentation for environment variables.

Returns a formatted string documenting all environment variables that affect XDG directory configuration for the given application. This is useful for generating man pages or help text.

  • parameter app_name

    The application name

  • returns

    A formatted documentation string

Included Information:

  • Configuration precedence rules
  • Application-specific environment variables
  • XDG standard environment variables
  • Default values for each directory type
Sourceval pp : Format.formatter -> t -> unit

pp ppf config pretty prints a Cmdliner configuration.

This function formats the configuration showing each directory path along with its source, which is helpful for debugging configuration issues or displaying the current configuration to users.

  • parameter ppf

    The formatter to print to

  • parameter config

    The configuration to print