NAME

YAML::yq::Helper - Wrapper for yq for various common tasks so YAML files can be manipulated in a manner to preserve comments and version header.

VERSION

Version 0.2.0

SYNOPSIS

use YAML::yq::Helper;

my $yq = YAML::yq::Helper->new(file='/etc/suricata/suricata-ids.yaml');

$yq->set_array(var=>'rule-files', vals=>['suricata.rules','custom.rules'])

METHODS

new

Inits the object and check if a version header is present for use with the ensure method.

Will make sure the file specified exists, is a file, is readable, and is writable. Otherwise it will die.

Will also die if yq is not in the path.

- file :: The YAML file to operate on.

clear_array

Clears the entries in a array, but does not delete the array.

Will die if called on a item that is not a array.

- var :: Variable to check. If not matching /^\./,
         a period will be prepended.

$yq->clear_array(var=>'rule-files');

clear_hash

Clears the entries in a hash, but does not delete the hash.

Will die if called on a item that is not a hash.

- var :: Variable to check. If not matching /^\./,
         a period will be prepended.

$yq->clear_hash(var=>'rule-files');

create_array

Creates a empty array. Unlike set_array, vals is optional.

Will die if it already exists.

- var :: Variable to operate on. If not matching /^\./,
         a period will be prepended.

- vals :: Array of values to set the array to.

$yq->create_array(var=>'rule-files');

create_hash

Creates a empty hash.

Will die if it already exists.

- var :: Variable to operate on. If not matching /^\./,
         a period will be prepended.

$yq->clear_hash(var=>'rule-files');

dedup_array

Dedup the specified array.

Will die if called on a item that is not a array or the array does not exist.

- var :: Variable to check. If not matching /^\./,
         a period will be prepended.

$yq->dedup_array(var=>'rule-files');

delete

Deletes an variable. If it is already undef, it will just return.

- var :: Variable to check. If not matching /^\./,
         a period will be prepended.

$yq->delete_array(var=>'rule-files');

delete_array

Deletes an array. If it is already undef, it will just return.

Will die if called on a item that is not a array.

- var :: Variable to check. If not matching /^\./,
         a period will be prepended.

$yq->delete_array(var=>'rule-files');

delete_hash

Deletes an hash. If it is already undef, it will just return.

Will die if called on a item that is not a hash.

- var :: Variable to check. If not matching /^\./,
         a period will be prepended.

$yq->delete_hash(var=>'vars');

ensure

Makes sure that the YAML file has the version at the top.

If the file none originally, no action will be taken unless force=>1 is also set for this. At which point it will it to 1.1.

$yq->ensure;
$yq->ensure(force=>1);

is_array

Checks if the specified variable in a array.

- var :: Variable to check. If not matching /^\./,
         a period will be prepended.

if ( $yq->is_array(var=>'rule-files') ){
    print "array...\n:";
}

is_array_clear

Checks if a array is clear or not.

- var :: Variable to check. If not matching /^\./,
         a period will be prepended.

if ( $yq->is_array_clear(var=>'rule-files') ){
    print "clear...\n:";
}

is_defined

Checks if the specified variable is defined or not.

Will die if called on a item that is not a array.

- var :: Variable to check. If not matching /^\./,
         a period will be prepended.

if ( $yq->is_defined('vars.address-groups') ){
    print "defined...\n:";
}

is_hash

Checks if the specified variable in a hash.

Will die if called on a item that is not a array.

- var :: Variable to check. If not matching /^\./,
         a period will be prepended.

if ( $yq->is_hash('vars.address-groups') ){
    print "hash...\n:";
}

is_hash_clear

Checks if a hash is clear or not.

Will die if called on a item that is not a hash.

- var :: Variable to check. If not matching /^\./,
         a period will be prepended.

if ( ! $yq->is_hash_clear(var=>'vars') ){
    print "not clear...\n:";
}

merge_yaml

Murges the specified YAML into the current YAML.

- yaml :: The YAML to merge into into the current one.
        This value may not match /[\'\"]/.
    - Default :: undef

- merge_mode :: Merge mode to use.
    - Default :: deeply

$yq->merge_yaml(yaml=>'./some_other_file.yaml');

The merge modes are as below.

- deeply :: Deeply merge arrays.
    - yq :: '. *d load("file2.yml")'

- replace :: Replace arrays.
    - yq :: '. *= load("file2.yml")'

- append :: Append arrays.
    - yq :: '. *+ load("file2.yml")'

- existing :: Only merge existing fields.
    - yq :: '. *? load("file2.yml")'

- new :: Only merge new fields.
    - yq :: '. *n load("file2.yml")'

push_array

Pushes the passed array onto the specified array.

Will die if called on a item that is not a array or the array does not exist.

- var :: Variable to check. If not matching /^\./,
         a period will be prepended.

- vals :: Array of values to set the array to.

$yq->push_array(var=>'rule-files',vals=>\@new_rules_files);

set_array

Creates an array and sets it to the values.

If the array is already defined, it will clear it and set the values to those specified.

Will die if called on a item that is not a array.

- var :: Variable to check. If not matching /^\./,
         a period will be prepended.

- vals :: Array of values to set the array to.

$yq->set_array(var=>'rule-files',vals=>\@vals);

set_hash

Creates an hash and sets it to the values.

If the hash is already defined, it will clear it and set the values to those specified.

Will die if called on a item that is not a array.

- var :: Variable to check. If not matching /^\./,
         a period will be prepended.

- hash :: A hash to use for generating the hash to be
          added. Any undef value will be set to null.

$yq->set_hash(var=>'vars',hash=>{a=>33,bar=>undef});

set_in_array

Ensures the values specified exist at any point in the array.

Will create the array if it does not already exist.

Will die if called on a item that is not a array.

- var :: Variable to check. If not matching /^\./,
         a period will be prepended.

- vals :: Array of values to set the array to.

- dedup :: If it should deduplicate the existing items
           in the array or not.
  Default :: 1

$yq->set_in_array(var=>'rule-files',vals=>\@vals);

yaml_diff

This returns a diff between both YAMLs.

The two YAMLs are are copied to the a temp dir.

- yaml :: The YAML use for the new side of the diff.
    - Default :: undef

AUTHOR

Zane C. Bowers-Hadley, <vvelox at vvelox.net>

BUGS

Please report any bugs or feature requests to bug-yaml-yq-helper at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=YAML-yq-Helper. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc YAML::yq::Helper

You can also look for information at:

• RT: CPAN's request tracker (report bugs here)

  https://rt.cpan.org/NoAuth/Bugs.html?Dist=YAML-yq-Helper

• Search CPAN

  https://metacpan.org/release/YAML-yq-Helper

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

This software is Copyright (c) 2022 by Zane C. Bowers-Hadley.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)

cpanm YAML::yq::Helper

perl -MCPAN -e shell
install YAML::yq::Helper