/ 
Sieve-Generator-0.001
/ Sieve::Generator::Sugar

NAME

Sieve::Generator::Sugar - constructor functions for building Sieve generator objects

VERSION

version 0.001

SYNOPSIS

use Sieve::Generator::Sugar '-all';

my $script = sieve(
  command('require', qstr([ qw(fileinto imap4flags) ])),
  blank(),
  ifelse(
    header_exists('X-Spam'),
    block(
      command('addflag', qstr('$Junk')),
      command('fileinto', qstr('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, @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.

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 ...

fourpart

my $test = fourpart($identifier, $tag, $arg1, $arg2);

This function creates a Sieve::Generator::Text::Terms representing a four-part Sieve test of the form identifier :tag arg1 arg2. $identifier and $tag are used as-is (with : prepended to $tag); $arg1 and $arg2 are each quoted automatically, with array references becoming Sieve string lists and plain scalars becoming quoted strings.

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.

header_exists

my $test = header_exists($header);

This function creates an RFC 5228 exists test that is true if the named header field is present in the message. The $header is automatically quoted as a Sieve string.

not_header_exists

my $test = not_header_exists($header);

This function creates a not exists test that is true if the named header field is absent from the message. The $header is automatically quoted as a Sieve string.

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.

string_test

my $test = string_test($comparator, $key, $value);

This function creates an RFC 5229 string test using the given comparator tag (e.g. is, contains, matches). The $key and $value should be objects doing Sieve::Generator::Text, typically produced by "qstr".

not_string_test

my $test = not_string_test($comparator, $key, $value);

This function creates the negation of an RFC 5229 string test. It accepts the same arguments as "string_test".

size

my $test = size($comparator, $value);

This function creates an RFC 5228 size test using the given comparator (over or under) and size value (e.g. 100K). The value is not quoted and is passed through as-is.

bool

my $test = bool($value);

This function returns a Terms representing a literal true or false depending on the truthiness of $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.