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 or x.perl.coerce_rules to something like ["!str_iso8601", "str_alami"] (this means to exclude the str_iso8601 rule but enable the str_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 to DateTime->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 other str_alami_* rules (like str_alami_en and str_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(...)' ENVIRONMENT LOG_SAH_COERCER_CODE => bool Set default for $Log_Coercer_Code. SEE ALSO Data::Sah Data::Sah::CoerceJS