/ 
File-SOPS-0.003
/ File::SOPS::Format::ENV::Ordered

NAME

File::SOPS::Format::ENV::Ordered - the tied hash that keeps a flat format's parse in document order

VERSION

version 0.003

SYNOPSIS

use File::SOPS::Format::ENV::Ordered;

my %doc;
tie %doc, 'File::SOPS::Format::ENV::Ordered';

$doc{PORT} = undef;
$doc{HOST} = undef;

my @keys = keys %doc;   # => ('PORT', 'HOST'), the order they were stored

DESCRIPTION

A hash whose keys iterate in the order they were first stored, tied rather than blessed: it is used through tie and never through a constructor.

It exists for one job. MAC verification walks the document in document order, and a handler supplies that order by returning a tree of the same shape as its own parse whose mappings iterate the way the file reads (docs/adr/0036). YAML and JSON get theirs from a second parser; the flat formats have none to get it from, so their order lives in the hash itself. Condition 2 of that contract calls this a tied hash and nothing else, because File::SOPS's walk reads the order with keys -- a handler that returns a plain hash hands it Perl's randomised iteration order, and the document then fails verification with an error that names the MAC and nothing else.

Both flat handlers tie to it: "parse_in_document_order" in File::SOPS::Format::ENV for a dotenv document, and "parse_in_document_order" in File::SOPS::Format::INI for an ini one, which ties a second hash per section.

Two things follow from what the order reader is for, and both make this class smaller than an ordered hash would otherwise have to be:

  • The values are never read, only the shape, so the handlers store undef in every slot. Nothing that goes into one of these hashes reaches the digest as data.

  • It is not a general-purpose ordered hash and is not offered as one. Tie::IxHash is not a prerequisite of this distribution and YAML::PP's YAML::PP::Preserve::Hash is not separately loadable, which is why this is here at all rather than a dependency.

THE TIE INTERFACE

STORE appends a key to the order the first time it is stored and leaves the order alone when an existing key is overwritten; FIRSTKEY and NEXTKEY iterate that order; FETCH, EXISTS, DELETE, CLEAR and SCALAR do what their names say. The handlers exercise only STORE, FETCH, EXISTS and the iteration pair -- the rest are implemented so that a later caller does not meet a hash that silently drops half of what a hash does.

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-file-sops/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

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