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

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

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):

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

