NAME

Data::Sah::Compiler::Prog - Base class for programming language compilers

VERSION

version 0.07

SYNOPSIS

DESCRIPTION

This class is derived from Data::Sah::Compiler. It is used as base class for compilers which compile schemas into code (usually a validator) in programming language targets, like Data::Sah::Compiler::perl and Data::Sah::Compiler::js. The generated validator code by the compiler will be able to validate data according to the source schema, usually without requiring Data::Sah anymore.

Aside from Perl and JavaScript, this base class is also suitable for generating validators in other procedural languages, like PHP, Python, and Ruby. See CPAN if compilers for those languages exist.

Compilers using this base class are usually flexible in the kind of code they produce:

• configurable validator return type

  Can generate validator that returns a simple bool result, str, or full data structure.

• configurable data term

  For flexibility in combining the validator code with other code, e.g. in sub wrapper (one such application is in Perinci::Sub::Wrapper).

Planned future features include:

• generating other kinds of code (aside from validators)

  Perhaps data compliance measurer, data transformer, or whatever.

ATTRIBUTES

These usually need not be set/changed by users.

comment_style => STR

Specify how comments are written in the target language. Either 'cpp' (// comment), 'shell' (# comment), 'c' (/* comment */), or 'ini' (; comment). Each programming language subclass will set this, for example, the perl compiler sets this to 'shell' while js sets this to 'cpp'.

METHODS

new() => OBJ

$c->compile(%args) => RESULT

Aside from BaseCompiler's arguments, this class supports these arguments (suffix * denotes required argument):

• data_term => STR

  A variable name or an expression in the target language that contains the data, defaults to var_sigil + name if not specified.

• data_term_is_lvalue => BOOL (default: 1)

  Whether data_term can be assigned to.

• err_term => STR

  A variable name or lvalue expression to store error message(s), defaults to var_sigil + err_NAME (e.g. $err_data in the Perl compiler).

• var_prefix => STR (default: _sahv_)

  Prefix for variables declared by generated code.

• sub_prefix => STR (default: _sahs_)

  Prefix for subroutines declared by generated code.

• code_type => STR (default: validator)

  The kind of code to generate. For now the only valid (and default) value is 'validator'. Compiler can perhaps generate other kinds of code in the future.

• return_type => STR (default: bool)

  Specify what kind of return value the generated code should produce. Either bool, str, or full.

  bool means generated validator code should just return true/false depending on whether validation succeeds/fails.

  str means validation should return an error message string (the first one encountered) if validation fails and an empty string/undef if validation succeeds.

  full means validation should return a full data structure. From this structure you can check whether validation succeeds, retrieve all the collected errors/warnings, etc.

• debug => BOOL (default: 0)

  This is a general debugging option which should turn on all debugging-related options, e.g. produce more comments in the generated code, etc. Each compiler might have more specific debugging options.

• debug_log => BOOL (default: 0)

  Whether to add logging to generated code.

Compilation data

This subclass adds the following compilation data ($cd).

Keys which contain compilation state:

• data_term => ARRAY

  Input data term. Set to $cd->{args}{data_term} or a temporary variable (if $cd->{args}{data_term_is_lvalue} is false). Hooks should use this instead of $cd->{args}{data_term} directly, because aside from the aforementioned temporary variable, data term can also change, for example if default.temp or prefilters.temp attribute is set, where generated code will operate on another temporary variable to avoid modifying the original data. Or when .input attribute is set, where generated code will operate on variable other than data.

Keys which contain compilation result:

• modules => ARRAY

  List of module names that are required by the code, e.g. ["Scalar::Utils", "List::Util"]).

• subs => ARRAY

  Contains pairs of subroutine names and definition code string, e.g. [ [_sahs_zero => 'sub _sahs_zero { $_[0] == 0 }'], [_sahs_nonzero => 'sub _sah_s_nonzero { $_[0] != 0 }'] ]. For flexibility, you'll need to do this bit of arranging yourself to get the final usable code you can compile in your chosen programming language.

• vars => ARRAY ?

$c->comment($cd, @arg)

Append a comment line to $cd->{result}. Used by compiler; users normally do not need this. Example:

 $c->comment($cd, 'this is a comment', ', ', 'and this one too');

When comment_style is shell this line will be added:

 # this is a comment, and this one too

AUTHOR

Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Steven Haryanto.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Data::Sah

perl -MCPAN -e shell
install Data::Sah