/ 
File-SOPS-0.003
/ File::SOPS::Comment

NAME

File::SOPS::Comment - the leaf a sops comment becomes -- not a value, and not a string

VERSION

version 0.003

SYNOPSIS

use File::SOPS::Comment;

my $comment = File::SOPS::Comment->new(text => ' a comment');
$comment->text;   # => ' a comment'

# A comment in a list is what a decrypted document hands back
my $data = File::SOPS->decrypt(
    encrypted  => $yaml,
    identities => [$identity],
);
# $data->{list}[0] is a File::SOPS::Comment, $data->{list}[1] a string

DESCRIPTION

File::SOPS::Comment is the Perl representation of SOPS's type:comment: a leaf that is not a value. sops attaches a comment to the node that follows it, and where that node is a sequence entry it has nowhere to put a comment line, so it writes the comment as a sequence entry of its own:

list:
    - ENC[AES256_GCM,...,type:comment]
    - ENC[AES256_GCM,...,type:str]

This class is what such an entry becomes on the way in, and what produces one on the way out. It holds the comment's text and nothing else.

It is an object rather than a string on purpose, and it is the same move type:bool makes with JSON::PP::Boolean: a wire type that is not a string gets a Perl value that cannot be mistaken for one. Read as a string, a comment is an extra element in the caller's list that the file does not contain, and a decrypt plus encrypt cycle makes it permanent with every party reporting success -- which is the defect (k108) this class exists to close.

There is deliberately no overloaded stringification: a comment that compares equal to a string is how one became a value in the first place. "text" is the way to the text.

Callers do not have to load this module to receive one -- File::SOPS::Encrypted loads it, and the dependency runs only that way. Load it to build one.

See docs/adr/0041.

new

my $comment = File::SOPS::Comment->new(text => ' a comment');

Builds a comment leaf from its text, which is everything sops puts after the #, leading space included. The text is a character string and is encoded on the way to the wire like every other string (docs/adr/0003); Perl's UTF-8 flag is not consulted here or there.

Croaks on the three inputs that are not a comment: a missing text, a reference, and an empty string. The last one is not a strictness of this distribution's own -- measured against sops 3.13.3, a bare # above a sequence entry is written as an unencrypted empty string element (- "") and no comment leaf at all, so type:comment never carries an empty plaintext and AES-GCM has no ciphertext for one either.

text

$comment->text;   # => ' a comment'

The comment's text, verbatim, as a character string. This is the only way to it: the class deliberately does not overload stringification.

SEE ALSO

  • File::SOPS::Encrypted - the type ladder that produces this class and the conversion that writes it

  • File::SOPS - the tree a decrypted document hands back, and where a comment may sit in one

  • docs/adr/0041 - why a comment is a leaf of its own, measured against sops 3.13.3

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.