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

VERSION
    This document describes version 0.024 of Data::Sah::Filter (from Perl
    distribution Data-Sah-Filter), released on 2024-01-17.

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"

    Another example:

     my $c = gen_filter(
         filter_names       => [ ['Str::remove_comment' => {style=>'shell'}] ],
         #filter_names      => ['Str::remove_comment=style,shell'], # same as above
     );

DESCRIPTION
    This distribution contains a standard set of filter rules for Data::Sah
    (to be used in "prefilters" and "postfilters" clauses). 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 (in "expr_filter")
    in the target language (e.g. Perl, JavaScript, or others) to convert one
    data to another. Multiple filter rules can be combined to form the final
    filtering code. This code can be used by "Data::Sah" when generating
    validator code from Sah schema, or can be used directly. Some projects
    which use filtering rules directly include: App::orgadb (which lets
    users specify filters from the command-line).

  meta()
    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.

    *   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 error message string should be set to
        undefined value.

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

    *   args => hash

        List of arguments that this filter accepts, in the form of hash
        where hash keys are argument names and hash values are argument
        specifications. Argument specification is a DefHash similar to
        argument specification for functions in Rinci::function
        specification.

  filter()
    The filter rule module must also contain "filter" subroutine which must
    generate the code for filtering. The subroutine must accept a hash of
    arguments and will be passed these:

    *   data_term => str

    *   args => hash

        The arguments for the filter. Hash keys will contain the argument
        names, while hash values will contain the argument's values.

    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, where hash keys are
        module names and hash values are modules' minimum versions.

    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;
     }

  Filter modules included in this distribution
    1. Data::Sah::Filter::js::Str::downcase
    2. Data::Sah::Filter::js::Str::lc
    3. Data::Sah::Filter::js::Str::lcfirst
    4. Data::Sah::Filter::js::Str::lowercase
    5. Data::Sah::Filter::js::Str::ltrim
    6. Data::Sah::Filter::js::Str::rtrim
    7. Data::Sah::Filter::js::Str::trim
    8. Data::Sah::Filter::js::Str::uc
    9. Data::Sah::Filter::js::Str::ucfirst
    10. Data::Sah::Filter::js::Str::upcase
    11. Data::Sah::Filter::js::Str::uppercase
    12. Data::Sah::Filter::perl::Array::check_uniq
    13. Data::Sah::Filter::perl::Array::check_uniqnum
    14. Data::Sah::Filter::perl::Array::check_uniqstr
    15. Data::Sah::Filter::perl::Array::remove_undef
    16. Data::Sah::Filter::perl::Array::uniq
    17. Data::Sah::Filter::perl::Array::uniqnum
    18. Data::Sah::Filter::perl::Array::uniqstr
    19. Data::Sah::Filter::perl::Float::ceil
    20. Data::Sah::Filter::perl::Float::check_has_fraction
    21. Data::Sah::Filter::perl::Float::check_int
    22. Data::Sah::Filter::perl::Float::floor
    23. Data::Sah::Filter::perl::Float::round
    24. Data::Sah::Filter::perl::Str::check
    25. Data::Sah::Filter::perl::Str::check_lowercase
    26. Data::Sah::Filter::perl::Str::check_oneline
    27. Data::Sah::Filter::perl::Str::check_uppercase
    28. Data::Sah::Filter::perl::Str::downcase
    29. Data::Sah::Filter::perl::Str::ensure_trailing_newline
    30. Data::Sah::Filter::perl::Str::lc
    31. Data::Sah::Filter::perl::Str::lcfirst
    32. Data::Sah::Filter::perl::Str::lowercase
    33. Data::Sah::Filter::perl::Str::ltrim
    34. Data::Sah::Filter::perl::Str::oneline
    35. Data::Sah::Filter::perl::Str::remove_comment
    36. Data::Sah::Filter::perl::Str::remove_non_latin_alphanum
    37. Data::Sah::Filter::perl::Str::remove_nondigit
    38. Data::Sah::Filter::perl::Str::remove_whitespace
    39. Data::Sah::Filter::perl::Str::replace_map
    40. Data::Sah::Filter::perl::Str::rtrim
    41. Data::Sah::Filter::perl::Str::trim
    42. Data::Sah::Filter::perl::Str::try_center
    43. Data::Sah::Filter::perl::Str::uc
    44. Data::Sah::Filter::perl::Str::ucfirst
    45. Data::Sah::Filter::perl::Str::underscore_non_latin_alphanum
    46. Data::Sah::Filter::perl::Str::underscore_non_latin_alphanums
    47. Data::Sah::Filter::perl::Str::upcase
    48. Data::Sah::Filter::perl::Str::uppercase
    49. Data::Sah::Filter::perl::Str::wrap

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

        (No description)

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

        (No description)

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

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>

CONTRIBUTING
    To contribute, you can send patches by email/via RT, or send pull
    requests on GitHub.

    Most of the time, you don't need to build the distribution yourself. You
    can simply modify the code, then test via:

     % prove -l

    If you want to build the distribution (e.g. to try to install it locally
    on your system), you can install Dist::Zilla,
    Dist::Zilla::PluginBundle::Author::PERLANCAR,
    Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two
    other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps
    required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE
    This software is copyright (c) 2024, 2023, 2022, 2020 by perlancar
    <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.

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.