SYNOPSIS

     use Data::Sah::Coerce qw(gen_coercer);
    
     # a utility routine: gen_coercer
     my $c = gen_coercer(
         type               => 'date',
         coerce_to          => 'DateTime',
         # coerce_from      => [qw/str_alami/],   # explicitly enable some rules
         # dont_coerce_from => [qw/str_iso8601/], # explicitly disable some rules
     );
    
     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::$LANG::$TARGET_TYPE::$SOURCE_TYPE_AND_EXTRA_DESCRIPTION
    module, for example: Data::Sah::Coerce::perl::date::int_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):

      * 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, a Sah schema can
      specify an attribute x.coerce_from or x.perl.coerce_from, etc to an
      array of coercion rule names to enable explicitly (e.g. ["int_epoch",
      "str_8601"]. On the other hand, to explicitly disable an
      enabled-by-default rule, one can use the x.dont_coerce_from (or
      x.perl.dont_coerce_from, etc).

    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::int_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.

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

