NAME

    Data::Annotation - Analyze data iptables-like

VERSION

    This document describes Data::Annotation version 0.004.

SYNOPSIS

       use Data::Annotation;
    
       my %definition = (...);
       my $da = Data::Annotation->new(\%definition);
    
       my %data = (...);
       my $annotation = $da->evaluate(\%data);

DESCRIPTION

    Generic framework for defining iptables-like chains of rules, apply
    them on data and get back an overall annotation about it. This
    annotation can be whatever, e.g. strings accept and reject (following
    the spirit of iptables) or more complicated stuff like data structures
    describing whatever has been analyzed.

    The definition is a hash with the following high-level structure:

       my %da_def = (
          chains:     => \%hash_of_chains,
          default     => 'some annotation',
          description => 'string...',
          'condition-parse-context' => \%hash_of_configurations,
       );

    This high level is much like a table in iptables, containing a number
    of chains below. default represents the default annotation if none of
    the chains provides any result back, much like the POLICY in a table in
    iptables. The parse_context provides some more kick for generating a
    function but it's totally optional, much like the description.

    A chain has the following structure:

       my %chain = (
          rules       => \@rules,
          description => 'string...',
          'condition-parse-context' => \%hash_of_configurations,
       );

    A chain is a sequence of rules, which will be analyzed in order, much
    like what happens in iptables.

    A rule has the following structure:

       my %rule = (
          condition => <expression/expression-definition/plain-scalar>,
          return    => <call/goto/whatever else>
          description => 'string...',
          'condition-parse-context' => \%hash_of_configurations,
       );

    When a rule is evaluated, the condition is checked first. It can be a
    plain scalar, in which case it's considered a boolean value, or a hash
    definition, which will be inflated via Data::Annotation::Expression, or
    a sub reference that accepts a runtime context that most of the time
    will be a hash reference of sort.

    If the condition gives a true value, the return value is provided back
    as the result of the rule and. This result can be almost anything:

      * if it's a hash reference, it should only contain one single
      key/value pair, with allowed keys:

	* call: call another chain (name from value) from the beginning
	like it were a single rule. If the called chain does not provide a
	result, continue processing the current chain from the following
	rule.

	* goto: stop processing the current chain and move on to the start
	of another chain (name provided as value).

	* result: value is the result for the whole annotation (i.e. it
	will exit the rule, the chain and the annotation evaluations).

      * anything else is taken at face value and used as the result above.

    A result can be anything, even a hash reference (provided it's wrapped
    into another hash reference with key result). In the most basic case,
    it will be a bunch of labels, e.g. accept or reject, but it can also be
    something more sophisticated like a list of characteristics or a whole
    complex data structure.

    Full definition example:

      description: some policy of sort
      default: reject
      default-chain: foo
      chains:
        foo:
          description: an example chain
          rules:
            - return: accept
              condition:
                eq: [ '.from', '=foobar@example.com' ]
        bar:
          rules:
            - return: accept
              condition:
                '=~': [ '.to', '=(?mxs:\A barbaz)' ]

INTERFACE

 Constructor

  new

       my $da1 = Data::Annotation->new(%definition); # OR
       my $da2 = Data::Annotation->new(\%definition);

    Constructor. See "DESCRIPTION" for the format of the definition.

 Accessors

  chains

       my $href = $da->chains;

    A hash reference of chains, indexed by name. This name is the same that
    can be used by rules in results like {name => ...} and { goto => ... }.

  default_chain

       my $chain_name = $da->default_chain;

    The default chain to use if an "evaluate" call is done on a chain that
    is not known.

  default_retval

       my $retval = $da->default_retval;

    The default result (annotation) value returned when none of the rules
    that are checked as part of a call to "evaluate" provides anything
    meaningful back.

    Initialized by key default in the constructor.

  description

       my $text = $da->description;

    An optional description for the Data::Annotation definition. It will be
    useful for you in a couple of months, after you forgot everything about
    it.

  parse_context

       my $ctx = $da->parse_context;

    Whatever was passed as argument condition-parse-context, which can help
    set the stage for condition parsing. This should not be generally
    needed, but still. See Data::Annotation::Expression for more details.

 Methods

  chains_list

    Get the sorted list of chains (as strings).

  evaluate

       my $result = $da->evaluate($chain_name, $data);

    Evaluate the annotation for some $data, starting at chain named
    $chain_name.

  has_chain_for

       my $bool = $da->has_chain_for($chain_name);

    Check if there is a chain definition whose name is $chain_nameo

  inflate_chains

       $da->inflate_chains;

    Make sure all input chain definitions are inflated, i.e. turned into
    "Data::Annotation::Chain" objects. This makes sure the definitions
    parse correctly.

  overlay_cloak

       my $overlay = $da->overlay_cloak($data, %opts);

    Shorthand to the constructor for "Data::Annotation::Overlay", passing
    $data as the under option and then the rest of %opts:

BUGS AND LIMITATIONS

    Minimul perl version 5.24.

    Report bugs through Codeberg (patches welcome) at
    https://codeberg.org/polettix/Data-Annotation.

AUTHOR

    Flavio Poletti <flavio@polettix.it>

COPYRIGHT AND LICENSE

    Copyright 2024 by Flavio Poletti <flavio@polettix.it>

    Licensed under the Apache License, Version 2.0 (the "License"); you may
    not use this file except in compliance with the License. You may obtain
    a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
    implied. See the License for the specific language governing
    permissions and limitations under the License.

    Just to be clear: apache-2.0