NAME
Data::Sah::Filter - Filtering for Data::Sah
VERSION
This document describes version 0.001 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) -> anyGenerate 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
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.