NAME
Sieve::Generator::Sugar - constructor functions for building Sieve generator objects
VERSION
version 0.002
SYNOPSIS
use Sieve::Generator::Sugar '-all';
my $script = sieve(
command('require', [ qw(fileinto imap4flags) ]),
blank(),
ifelse(
header_exists('X-Spam'),
block(
command('addflag', '$Junk'),
command('fileinto', 'Spam'),
),
),
);
print $script->as_sieve;DESCRIPTION
This module exports constructor functions for building Sieve::Generator object trees. All functions can be imported at once with the -all tag.
Because many of the function names (block, size, terms, and so on) are common words that may clash with existing code, Sub::Exporter allows all imported symbols to be given a prefix:
use Sieve::Generator::Sugar -all => { -prefix => 'sv_' };With that import, each function is available under its prefixed name, e.g. sv_sieve, sv_ifelse, sv_block, and so on.
PERL VERSION
This module is shipped with no promise about what version of perl it will require in the future. In practice, this tends to mean "you need a perl from the last three years," but you can't rely on that. If a new version of perl ship, this software may begin to require it for any reason, and there is no promise that patches will be accepted to lower the minimum required perl.
FUNCTIONS
comment
my $comment = comment($text);
my $comment = comment($text, { hashes => 2 });This function creates a Sieve::Generator::Lines::Comment with the given content. The content may be a plain string or an object doing Sieve::Generator::Text. The optional second argument is a hashref; its hashes key controls how many # characters prefix each line, defaulting to one.
command
my $cmd = command($identifier, (\%tagged?), @args);This function creates a Sieve::Generator::Lines::Command with the given identifier and arguments. Arguments may be plain strings or objects doing Sieve::Generator::Text. The command renders as a semicolon-terminated Sieve statement.
test
my $test = test($identifier, (\%tagged?), @args);This function creates a Sieve::Generator::Lines::Command with the given identifier and arguments -- and semicolon-at-the-end turned off. In the future, this might produce a distinct object, but for now, and really in Sieve, commands and tests are nearly the same thing.
set
my $cmd = set($variable, $value);This function creates a Sieve::Generator::Lines::Command for the Sieve set command (RFC 5229). Both $variable and $value are automatically quoted as Sieve strings.
ifelse
my $if = ifelse($condition, $block);
my $if = ifelse($cond, $if_block, [ $condN, $elsif_blockN ] ..., $else_block);This function creates a Sieve::Generator::Lines::IfElse. The first two arguments are the condition and the block to execute when it is true. Additional condition/block pairs render as elsif clauses. If the total number of trailing arguments is odd, the final argument is used as the plain else block.
blank
my $blank = blank();This function creates an empty Sieve::Generator::Lines::Document. It is typically used to insert a blank line between sections of a Sieve script.
sieve
my $doc = sieve(@things);This function creates a Sieve::Generator::Lines::Document from the given @things. The document is the top-level container for a Sieve script; its as_sieve method renders the full script as a string.
block
my $block = block(@things);This function creates a Sieve::Generator::Lines::Block containing the given @things. A block renders as a brace-delimited, indented sequence of statements, as used in Sieve if/elsif/else constructs.
allof
my $test = allof(@tests);This function creates a Sieve::Generator::Lines::Junction that renders as a Sieve allof(...) test, which is true only when all of the given tests are true.
anyof
my $test = anyof(@tests);This function creates a Sieve::Generator::Lines::Junction that renders as a Sieve anyof(...) test, which is true when any of the given tests is true.
noneof
my $test = noneof(@tests);This function creates a Sieve::Generator::Lines::Junction that renders as a Sieve not anyof(...) test, which is true only when none of the given tests are true.
terms
my $terms = terms(@terms);This function creates a Sieve::Generator::Text::Terms from the given @terms. Each term may be a plain string or an object doing Sieve::Generator::Text; all terms are joined with single spaces when rendered. This is the general-purpose constructor for Sieve test expressions and argument sequences.
heredoc
my $hd = heredoc($text);This function creates a Sieve::Generator::Lines::Heredoc containing the given $text. The text renders using the Sieve text:/. multiline string syntax. Any line beginning with . is automatically escaped to ...
qstr
my $q = qstr($string);
my @qs = qstr(@strings);
my $list = qstr(\@strings);This function creates Sieve string objects. A plain scalar produces a Sieve::Generator::Text::Qstr that renders as a quoted Sieve string. An array reference produces a Sieve::Generator::Text::QstrList that renders as a bracketed Sieve string list. When given a list of arguments, it maps over each and returns a corresponding list of objects.
hasflag
my $test = hasflag($flag);This function creates an RFC 5232 hasflag test that is true if the message has the given flag set. The $flag is automatically quoted as a Sieve string.
bool
my $test = bool($value);This function returns a Terms representing a literal true or false depending on the truthiness of $value.
var_eq
my $test = var_eq($var, $value);This produces a string "is" test checking that the given variable name equals the given value, by producing something like string :is "${$var}" "$value".
var_ne
my $test = var_ne($var, $value);This produces an inverted string "is" test checking that the given variable name equals the given value, by producing something like not string :is "${$var}" "$value".
AUTHOR
Ricardo Signes <rjbs@semiotic.systems>
COPYRIGHT AND LICENSE
This software is copyright (c) 2026 by Ricardo SIGNES.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.