/ 
Crypt-SecretBuffer-0.008
River stage zero No dependents
/ Crypt::SecretBuffer::INI

NAME

Crypt::SecretBuffer::INI - Parse INI format from a SecretBuffer

SYNOPSIS

use Crypt::SecretBuffer qw/ secret HEX /;
use Crypt::SecretBuffer::INI;

my $input= secret(<<END);
[database]
user=myapp
password=hunter2
[database.encryption]
aes_key=0123456789ABCDEF
[email]
smtp_auth=sldkdsjfldsjklfadsjkf
END

my $ini= Crypt::SecretBuffer::INI->new(
  section_delim => '.',
  field_config => [
    password  => { secret => 1 },
    smtp_auth => { secret => 1 },
    aes_key   => { secret => 1, encoding => HEX },
  ]
);
my $config= $ini->parse($input);
print Data::Dumper->new([$config])
  ->Terse(1)->Sortkeys(1)->Indent(2)->Dump;
#{
#  'database' => {
#    'encryption' => {
#      'aes_key' => bless( {}, 'Crypt::SecretBuffer' )
#    },
#    'password' => bless( {}, 'Crypt::SecretBuffer' ),
#    'user' => 'myapp'
#  },
#  'email' => {
#    'smtp_auth' => bless( {}, 'Crypt::SecretBuffer' )
#  }
#}

# Produce a file with secrets:
$out= secret;
$ini->render_sections($out, $header => \%fields);
$out->save_file($path);

DESCRIPTION

One of the challenges of trying to keep secrets hidden in a SecretBuffer is that they typically start inside of config files, and in parsing the config file to load them you leak them into the Perl interpreter's buffers.

This module lets you parse out the simple common "name=value\n" found in many config files, exposing the keys but selectively loading the value in a SecretBuffer.

CONSTRUCTORS

new

$ini= Crypt::SecretBuffer::INI->new(%attributes);

Pass key/value pairs of attributes to be initialized.

ATTRIBUTES

key_value_delim

The delimiter string (or character class) that separates keys from values. The default is '=' but another common option would be ':' or qr/[:=]/ to allow both.

bare_keys

Boolean. When enabled, a non-empty non-comment line that also lacks a "key_value_delim" will be treated as a single key having an undefined value. When not enabled, that situation is a parse error.

trim_chars

The character or character class that should be trimmed from both ends of all keys and values. The default is qr/[ \t]/. Note that '\r' and '\n' are implicitly trimmed by the line processing. Set this to undef if you want to perform your own trimming.

section_delim

This can be used to automatically tree-up your sections. If set, the "parse" function will treat the section headers as paths and build nested hashrefs instead of a flat array of sections. See examples in "parse".

comment_delim

The delimiter string (or character class) that indicates start of a comment line. The default is qr/[;#]/.

inline_comments

Boolean, whether to allow comments on the end of lines containing other directives/data, which also means your values can't contain the comment character.

field_config

This is an arrayref of rules that describe which flags should be applied to which type of keys. Each element is of the form:

{ key => $literal_or_pattern, flags => $flags },

or

{ section => $header_or_regex, rules => [
   ...
]}

As a convenience, that structure can be built from a shorter notation:

$literal_key     => $flags,
qr/$key_pattern/ => $flags,
$section_header => [
  ...
],
qr/$section_pattern/ => [
  ...
],
...

During a parse, rules are processed in order, and the first match wins.

METHODS

parse_next

%attrs= $self->parse_next($span);

Given a Crypt::SecretBuffer::Span (which has ->pos pointed at the next line of INI data) parse the next INI directive out of it. This can return one or more of:

comment => $comment_span,
section => $header_span,
key     => $key_span,
value   => $value_span,
error   => $parse_error_text,

The Span objects refer to a SecretBuffer, and you then have the option of loading them into Perl scalars or copying them to their own SecretBuffer objects.

parse

$tree= $ini->parse($buffer_or_span);

This is a convenient loop around "parse_next" which uses the specification in "field_config" to determine which keys are secret. If you defined section_delim, this returns a tree of configs where each section is a hashref located at the path from splitting its header. If section_delim is not defined, the result is an arrayref of section name and hashref pairs in the order they were found in the file.

This function dies on any parse errors.

VERSION

version 0.008

AUTHOR

Michael Conrad <mike@nrdvana.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2025 by Michael Conrad.

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