NAME
Data::Sah::Coerce - Coercion rules for Data::Sah
VERSION
This document describes version 0.013 of Data::Sah::Coerce (from Perl distribution Data-Sah-Coerce), released on 2016-05-25.
SYNOPSIS
use Data::Sah::Coerce qw(gen_coercer);
# a utility routine: gen_coercer
my $c = gen_coercer(
type => 'date',
coerce_to => 'DateTime',
coerce_rules => ['str_alami'], # explicitly enable a rule, etc
# return_type => 'str+val', # default is 'val'
);
my $val = $c->(123); # unchanged, 123
my $val = $c->(1463307881); # becomes a DateTime object
my $val = $c->("2016-05-15"); # becomes a DateTime object
my $val = $c->("2016foo"); # unchanged, "2016foo"
DESCRIPTION
This distribution contains a standard set of coercion rules for Data::Sah. It is separated from the Data-Sah
distribution and can be used independently.
A coercion rule is put in Data::Sah::Coerce::$COMPILER::$TARGET_TYPE::$SOURCE_TYPE_AND_EXTRA_DESCRIPTION
module, for example: Data::Sah::Coerce::perl::date::float_epoch for converting date from integer (Unix epoch) or Data::Sah::Coerce::perl::date::str_iso8601 for converting date from ISO8601 strings like "2016-05-15".
The module must contain meta
subroutine which must return a hashref that has the following keys (*
marks that the key is required):
v* => int (default: 1)
Metadata specification version. Currently at 2 (bumped from 1 to exclude old module names).
enable_by_default* => bool
Whether the rule should be used by default. Some rules might be useful in certain situations only and can set this key's value to 0.
To explicitly enable a disabled-by-default rule or explicitly disable an enabled-by-default rule, a Sah schema can set the attribute
x.coerce_rules
orx.perl.coerce_rules
to something like["!str_iso8601", "str_alami"]
(this means to exclude thestr_iso8601
rule but enable thestr_alami
rule.might_die => bool (default: 0)
Whether the rule will generate code that might die (e.g. does not trap failure in a conversion process). An example of a rule like this is coercing from string in the form of "YYYY-MM-DD" to a DateTime object. The rule might match any string in the form of
/\A(\d{4})-(\d{2})-(\d{2})\z/
and feed it toDateTime->new
, without checking of a valid date, so the latter might die.An example of rule that "might not die" is coercing from a comma-separated string into array. This process should not die unless under extraordinary condition (e.g. out of memory).
For a rule that might die, the program/library that uses the rule module might add an eval block around the expr_coerce code that is generated by the rule module.
prio => int (0-100, default: 50)
This is to regulate the ordering of rules. The higher the number, the lower the priority (meaning the rule will be put further back). Rules that are computationally expensive and/or matches more broadly in general should be put further back (lower priority, higher number).
precludes => array of (str|re)
List the other rules or rule patterns that are precluded by this rule. Rules that are pure alternatives to one another (e.g. date coercien rules str_alami vs str_alami both parse natural language date string; there is little to none usefulness in using both; besides, both rules match all string and dies when failing to parse the string. So in
str_natural
rule, you might find this metadata:precludes => [qr/\Astr_alami(_.+)?\z/]
and in
str_alami
rule you might find this metadata:precludes => [qr/\Astr_alami(_.+)?\z/, 'str_natural']
Note that the
str_alami
rule also precludes otherstr_alami_*
rules (likestr_alami_en
andstr_alami_id
).Also note that rules which are specifically requested to be used (e.g. using
x.perl.coerce_rules
attribute in Sah schema) will still be precluded.
The module must also contain coerce
subroutine which must generate the code for coercion. The subroutine must accept a hash of arguments (*
indicates required arguments):
data_term => str
coerce_to => str
Some Sah types are "abstract" and can be represented using a choice of several actual types in the target programming language. For example, "date" can be represented in Perl as an integer (Unix epoch value), or a DateTime object, or a Time::Moment object.
Not all target Sah types will need this argument.
The coerce
subroutine must return a hashref with the following keys (*
indicates required keys):
expr_match => str
Expression in the target language to test whether the data can be coerced. For example, in
Data::Sah::Coerce::perl::date::float_epoch
, only integers ranging from 10^8 to 2^31 are converted into date. Non-integers or integers outside this range are not coerced.expr_coerce => str
Expression in the target language to actually convert data to the target type.
modules => hash
A list of modules required by the expressions.
Basically, the coerce
subroutine must generates a code that accepts a non-undef data and must convert this data to the desired type/format under the right condition. The code to match the right condition must be put in expr_match
and the code to convert data must be put in expr_coerce
.
Program/library that uses Data::Sah::Coerce can collect rules from the rule modules then compose them into the final code, something like (in pseudocode):
if (data is undef) {
return undef;
} elsif (data matches expr-match-from-rule1) {
return expr-coerce-from-rule1;
} elsif (data matches expr-match-from-rule2) {
return expr-coerce-from-rule1;
...
} else {
# does not match any expr-match
return original data;
}
VARIABLES
$Log_Coercer_Code => bool (default: from ENV or 0)
If set to true, will log the generated coercer code (currently using Log::Any at trace level). To see the log message, e.g. to the screen, you can use something like:
% TRACE=1 perl -MLog::Any::Adapter=Screen -MData::Sah::Coerce=gen_coercer \
-E'my $c = gen_coercer(...)'
FUNCTIONS
gen_coercer() -> any
Generate coercer code.
This is mostly for testing. Normally the coercion rules will be used from Data::Sah
.
This function is not exported by default, but exportable.
No arguments.
Return value: (any)
ENVIRONMENT
LOG_SAH_COERCER_CODE => bool
Set default for $Log_Coercer_Code
.
HOMEPAGE
Please visit the project's homepage at https://metacpan.org/release/Data-Sah-Coerce.
SOURCE
Source repository is at https://github.com/perlancar/perl-Data-Sah-Coerce.
BUGS
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Data-Sah-Coerce
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
AUTHOR
perlancar <perlancar@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2016 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.