NAME
    Data::Sah::Filter - Filtering for Data::Sah

VERSION
    This document describes version 0.004 of Data::Sah::Filter (from Perl
    distribution Data-Sah-Filter), released on 2020-02-11.

SYNOPSIS
     use Data::Sah::Filter qw(gen_filter);

     # a utility routine: gen_filter
     my $c = gen_filter(
         filter_names       => ['Str::ltrim', 'Str::rtrim'],
     );

     my $val = $c->("foo");        # unchanged, "foo"
     my $val = $c->(" foo ");      # "foo"

DESCRIPTION
    This distribution contains a standard set of filter rules for Data::Sah
    (to be used in "prefilters" and "postfilter" cause). It is separated
    from the "Data-Sah" distribution and can be used independently.

    A filter rule is put in
    "Data::Sah::Filter::$COMPILER::$CATEGORY:$DESCRIPTION" module, for
    example: Data::Sah::Filter::perl::Str::trim for trimming whitespace at
    the beginning and end of string.

    Basically, a filter rule will provide an expression ("expr_filter") to
    convert data to another. Multiple filter rules will be combined to form
    the final filtering code.

    The filter rule module must contain "meta" subroutine which must return
    a hashref (DefHash) that has the following keys ("*" marks that the key
    is required):

    *   v* => int (default: 1)

        Metadata specification version. From DefHash. Currently at 1.

    *   summary => str

        From DefHash.

    The filter rule module must also contain "filter" subroutine which must
    generate the code for filtering. The subroutine must accept a hash of
    arguments ("*" indicates required arguments):

    *   data_term => str

    The "filter" subroutine must return a hashref with the following keys
    ("*" indicates required keys):

    *   might_fail => bool

        Whether coercion might fail, e.g. because of invalid input. If set
        to 1, "expr_filter" key that the "filter()" routine returns must be
        an expression that returns an array (envelope) of "(error_msg,
        data)" instead of just filtered data. Error message should be a
        string that is set when filtering fails and explains why. Otherwise,
        if filtering succeeds, the string should be set to undefined value.

        This is used for filtering rules that act as a data checker.

    *   expr_filter => str

        Expression in the target language to actually convert data.

    *   modules => hash

        A list of modules required by the expression.

    Basically, the "filter" subroutine must generate a code that accepts a
    non-undef data and must convert this data to the desired value.

    Program/library that uses Data::Sah::Filter can collect rules from the
    rule modules then compose them into the final code, something like (in
    pseudo-Perl code):

     if (!defined $data) {
       return undef;
     } else {
       $data = expr-filter-from-rule1($data);
       $data = expr-filter-from-rule2($data);
       ...
       return $data;
     }

VARIABLES
  $Log_Filter_Code => bool (default: from ENV or 0)
    If set to true, will log the generated filter code (currently using
    Log::ger at trace level). To see the log message, e.g. to the screen,
    you can use something like:

     % TRACE=1 perl -MLog::ger::LevelFromEnv -MLog::ger::Output=Screen \
         -MData::Sah::Filter=gen_filter -E'my $c = gen_filter(...)'

FUNCTIONS
  gen_filter
    Usage:

     gen_filter(%args) -> any

    Generate filter code.

    This is mostly for testing. Normally the filter rules will be used from
    Data::Sah.

    This function is not exported by default, but exportable.

    Arguments ('*' denotes required arguments):

    *   filter_names* => *array[str]*

    *   return_type => *str* (default: "val")

    Return value: (any)

ENVIRONMENT
  LOG_SAH_FILTER_CODE => bool
    Set default for $Log_Filter_Code.

HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/Data-Sah-Filter>.

SOURCE
    Source repository is at
    <https://github.com/perlancar/perl-Data-Sah-Filter>.

BUGS
    Please report any bugs or feature requests on the bugtracker website
    <https://rt.cpan.org/Public/Dist/Display.html?Name=Data-Sah-Filter>

    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.

SEE ALSO
    Data::Sah

    Data::Sah::FilterJS

    App::SahUtils, including filter-with-sah to conveniently test filter
    from the command-line.

    Data::Sah::Coerce. Filtering works very similarly to coercion in the
    Data::Sah framework (see l<Data::Sah::Coerce>) but is simpler and
    composited differently to form the final filtering code. Mainly, input
    data will be passed to all filtering expressions.

AUTHOR
    perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2020 by perlancar@cpan.org.

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

