NAME

Hash::Weighted::Categorize - Categorize weighted hashes using a Domain Specific Language

VERSION

version 0.002

SYNOPSIS

    # create a parser
    my $parser = Hash::Weighted::Categorize->new();

    # generate a scoring function
    my $score = $parser->parse( << 'CODE' );
    %OK > 90%, %CRIT < .1: OK;
    %CRIT > 50%: CRIT;
    %CRIT > 25%: WARN;
    UNKN;
    CODE

    # OK
    $status = $score->( { OK => 19, CRIT => 2 } );

    # WARN
    $status = $score->( { OK => 14, CRIT => 6, WARN => 1 } );

    # CRIT
    $status = $score->( { OK => 8, CRIT => 11, WARN => 1, UNKN => 1 } );

    # UNKN
    $status = $score->( { OK => 18, CRIT => 2, WARN => 1 } );

DESCRIPTION

Hash::Weighted::Categorize is a tool to easily create scoring functions (think monitoring) based on a simple mini-language. A Hash::Weighted::Categorize object is a parser for this mini-language, that will return coderefs implementing a scoring function written in this language.

METHODS

new()

Create a new Hash::Weighted::Categorize object.

parse( $code )

Parse the content of $code and return the corresponding code reference.

parse_to_source( $code )

Parse the content of $code and return the Perl source code for the code reference that would be returned by parse().

DOMAIN SPECIFIC LANGUAGE

The domain specific language parsed by Hash::Weighted::Categorize is intentionaly very simple. Simple statements consist of boolean expressions separated by commas (, meaning logical AND), and terminated by a colon (:) followed by the result to be returned if the condition is true.

In the following example:

    %OK > 90%, %CRIT < .1: OK;
    %CRIT > 50%: CRIT;
    %CRIT > 25%: WARN;
    UNKN;

OK, WARN, CRIT and UNKN are names. On the left-hand side of the :, they are interpreted in relation to the keys of the examined hash. A name by itself is interpreted as the count/weight of this element in the hash. When prefixed by a % sign, the ratio of this category compared to the total is used in the expression.

A literal number followed by a % sign is simply divided by 100.

The currently supported mathematical operators are: +, -, * and /.

The currently supported comparison operators are: <, <=, ==, !=, > and >=.

The mini-language supports the use of brace-delimited blocks, nested at an arbitrary depth, which allows to write complex expressions such as:

    %CRIT >= 10%: {
         %CRIT > 20% : CRIT;
         %OK   > 85% : OK;
         WARN;
    }
    WARN > 0 : WARN;
    OK;

which is equivalent to:

    %CRIT >= 10%, %CRIT > 20% : CRIT;
    %CRIT >= 10%, %OK   > 85% : OK;
    %CRIT >= 10%              : WARN;
    WARN > 0 : WARN;
    OK;

BUGS

Please report any bugs or feature requests on the bugtracker website http://rt.cpan.org/NoAuth/Bugs.html?Dist=Hash-Weighted-Categorize or by email to bug-hash-weighted-categorize@rt.cpan.org.

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

Philippe Bruhat (BooK) <book@cpan.org>

ACKNOWLEDGMENTS

This module was originally developed for Booking.com. With approval from Booking.com, this module was generalized and put on CPAN, for which the author would like to express his gratitude.

This module is the result of scratching my colleague Menno Blom's itch during a company-sponsored hackathon. Thanks to everyone involved.

The name of this module owes a lot to the module-authors mailing-list, and especially to Aristotle Pagaltzis. Thanks to everyone involved.

COPYRIGHT

Copyright 2013 Philippe Bruhat (BooK), all rights reserved.

LICENSE

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

cpanm Hash::Weighted::Categorize

perl -MCPAN -e shell
install Hash::Weighted::Categorize