/ 
Getopt-Pad-0.05
/ Getopt::Pad::Config::Format

NAME

Getopt::Pad::Config::Format - Base class of config file formats, and how to add one

SYNOPSIS

use v5.26;
use Object::Pad;
use Getopt::Pad;
use Getopt::Pad::Config::Format;

class My::Format::Toml :isa(Getopt::Pad::Config::Format) {
    use TOML::Tiny ();

    use constant NAMES => ['toml'];

    method parse($text) {
        return TOML::Tiny::from_toml($text);
    }

    # Optional: enables --create-default-config for this format.
    method dump($data) {
        return TOML::Tiny::to_toml($data) . "\n";
    }
}

Getopt::Pad::Config::Format::registerFormat('My::Format::Toml');

my $opt = GetOptions(
    options => {
        'log-level' => { type => 'string', default => 'info' },
    },
    config => { format => 'toml', paths => ['~/.tool.toml'] },
);

DESCRIPTION

A format translates one config file syntax, such as YAML or JSON, between text and Perl data. Getopt::Pad comes with the formats yaml (also yml, see Getopt::Pad::Config::Format::Yaml) and json (see Getopt::Pad::Config::Format::Json). Every format is a subclass of Getopt::Pad::Config::Format, including the ones you write yourself.

A format only translates. Getopt::Pad finds, reads and writes the files itself, always as UTF-8, and checks the data a format returns. How config files are used is described in "CONFIG FILES" in Getopt::Pad.

To add a format:

  1. Write an Object::Pad class that inherits from Getopt::Pad::Config::Format.

  2. Give it a NAMES constant and a parse method, and optionally a dump method (see "THE FORMAT CONTRACT").

  3. Register it with "registerFormat" before the first GetOptions call whose config block uses one of its names.

THE FORMAT CONTRACT

NAMES

use constant NAMES => ['toml'];

Required. A constant that returns an arrayref of the names the format answers to in the format key of the config block. Names are matched case-insensitively. A name that another class has already registered, built-in or not, cannot be taken over: "registerFormat" dies.

parse

method parse($text) { return TOML::Tiny::from_toml($text) }

Required. Receives the complete content of one config file as a Perl character string (already decoded from UTF-8) and returns the data as a hashref. The format does not open files and does not deal with encodings.

The hashref has the layout described in "File layout" in Getopt::Pad:

{
    Options  => { 'log-level' => 'debug' },          # group => { option => value }
    Target   => { owner => 'dave' },
    commands => {                                   # command sections
        document => { Options => { notes => '/srv/docs/notes.txt' } },
    },
}

Values are plain scalars, arrayrefs (for multiple and objectlist options) and hashrefs (for hash and objectlist options). Getopt::Pad checks the structure and every value, so parse does not need to. Booleans may be returned as 1 and 0 or as boolean objects such as JSON::PP::Boolean; an undefined value is reported to the user as no value given.

When the text cannot be parsed, parse dies. Getopt::Pad reports the message to the user as a config error that names the file, for example ERROR: config file '~/.tool.toml': toml parse error at line 3: .... A trailing at FILE line N. is removed from the message. If the text parses to something other than a hashref, for example an empty document, that is reported as config file 'PATH' must contain a mapping of group names.

dump

method dump($data) { return TOML::Tiny::to_toml($data) . "\n" }

Optional. Receives a hashref in the same layout as parse returns and returns it serialized as a Perl character string; Getopt::Pad encodes it as UTF-8 and writes the file. --create-default-config uses it. Without dump, --create-default-config fails with the user error config format 'NAME' cannot write config files.

When dump dies, no file is created, and the exception propagates out of GetOptions unchanged.

FUNCTIONS

registerFormat

Getopt::Pad::Config::Format::registerFormat('My::Format::Toml');

Registers a format class under the names in its "NAMES" constant, for all specs in the program. The argument is the class name. If the class has no NAMES method yet, which usually means that its module is not loaded, its module file is loaded first (for example My/Format/Toml.pm from @INC).

It dies when a name is already registered by another class, with Getopt::Pad: config format name 'NAME' is already registered by CLASS, and when the class has no NAMES constant. Registering the same class again does nothing. The function is not exported; call it with its full name.

EXAMPLES

The distribution's examples/05-custom-format.pl is a runnable version of the TOML format from the "SYNOPSIS". Unlike the synopsis, which loads TOML::Tiny with use, it loads the module only when a TOML file is actually read or written, so the program also runs without TOML::Tiny as long as no TOML file is used:

method parse($text) {
    try { require TOML::Tiny }
    catch ($error) { croak "config format 'toml' requires the TOML::Tiny module" }

    return TOML::Tiny::from_toml($text);
}

The built-in formats are short and can serve as examples as well: Getopt::Pad::Config::Format::Json and Getopt::Pad::Config::Format::Yaml.

SEE ALSO

"CONFIG FILES" in Getopt::Pad, Getopt::Pad::Type (the other extension point), Object::Pad

AUTHOR

davenonymous <perl@davenonymous.com>

COPYRIGHT AND LICENSE

Copyright 2026 davenonymous

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.