NAME Data::Sah::Filter - Filtering for Data::Sah VERSION This document describes version 0.009 of Data::Sah::Filter (from Perl distribution Data-Sah-Filter), released on 2022-07-04. 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 error message 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 . SOURCE Source repository is at . 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) but is simpler and composited differently to form the final filtering code. Mainly, input data will be passed to all filtering expressions. AUTHOR perlancar 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, and sometimes one or two other Dist::Zilla plugin and/or Pod::Weaver::Plugin. Any additional steps required beyond that are considered a bug and can be reported to me. COPYRIGHT AND LICENSE This software is copyright (c) 2022, 2020 by perlancar . 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 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.