Data::Sah::Filter - Filtering for Data::Sah
This document describes version 0.022 of Data::Sah::Filter (from Perl distribution Data-Sah-Filter), released on 2023-08-16.
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"
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.
prefilters
postfilters
Data-Sah
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.
Data::Sah::Filter::$COMPILER::$CATEGORY:$DESCRIPTION
Basically, a filter rule will provide a Perl expression (expr_filter) 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).
expr_filter
Data::Sah
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):
meta
*
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.
filter()
(error_msg, data)
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.
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:
filter
data_term => str
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; }
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(...)'
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")
Return value: (any)
Set default for $Log_Filter_Code.
$Log_Filter_Code
Please visit the project's homepage at https://metacpan.org/release/Data-Sah-Filter.
Source repository is at https://github.com/perlancar/perl-Data-Sah-Filter.
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.
perlancar <perlancar@cpan.org>
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.
This software is copyright (c) 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.
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.
To install Data::Sah::Filter, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Data::Sah::Filter
CPAN shell
perl -MCPAN -e shell install Data::Sah::Filter
For more information on module installation, please visit the detailed CPAN module installation guide.