NAME

Data::Sah::Compiler::BaseCompiler - Base class for Sah compilers (Data::Sah::Compiler::*)

VERSION

version 0.04

ATTRIBUTES

main => OBJ

Reference to the main Data::Sah object.

METHODS

new() => OBJ

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

Compile schema into target language.

Arguments (subclass may introduce others):

• inputs => ARRAYREF

  A list of inputs. Each input is a hashref with the following keys: schema, normalized (bool, set to true if input schema is already normalized to skip normalization step). Subclasses may require/recognize additional keys (for example, ProgBase compilers recognize data_term to customize variable to get data from).

About compilation data ($cd): During compilation, compile() will call various hooks (listed below). The hooks will be passed compilation data ($cd) which is a hashref containing various compilation state and result. Compilation state is written to this hashref instead of on the object's attributes to make it easy to do recursive compilation (compilation of subschemas).

These keys (subclasses may add more data): args (arguments given to compile()), compiler (the compiler object), result, input (current input), schema (current schema we're compiling), ctbl (clauses table, see explanation below), lang (current language), clause (current clause), th (current type handler), cres (result of clause handler), prefilters (an array of containing names of current prefilters), postfilters (an array containing names of postfilters), th_map (a hashref containing mapping of fully-qualified type names like int and its Data::Sah::Compiler::*::TH::* type handler object (or array, normalized schema), fsh_map (a hashref containing mapping of function set name like core and its Data::Sah::Compiler::*::FSH::* handler object).

About clauses table (ctbl): A single hashref containing all the clauses to be processed, parsed from schema's (normalized and merged) clause sets. Clause table is easier to use by the handlers. Each hash key is clause name, stripped from all attributes, in the form of NAME (e.g. 'min') or NAME#INDEX if there are more than one clause of the same name (e.g. 'min#1', 'min#2' and so on).

Each hash value is called a clause record (crec) which is a hashref: {name=>..., value=>...., 'value='=>..., attrs=>{...}, order=>..., cset_idx=>..., cset=>...]. 'name' is the clause name (no attributes, or #INDEX suffixes), 'value' is the clause value ('value=' is set instead if clause value is an expression), 'attrs' is a hashref containing attribute names and values (attribute names can contain '=' suffix if its value is an expression), 'order' is the processing order (1, 2, 3, ...), 'cset_idx' is the index to the original clause sets arrayref, 'cset' is reference to the original clause set.

Return value. Compilation data will be returned. Compilation data should have these keys: result (the final compilation result, usually a string like Perl code or human text). There could be other metadata which are compiler-specific (see respective compiler for more information).

Hooks. By default this base compiler does not define any hooks; subclasses can define hooks to implement their compilation process. Each hook will be passed compilation data, and should modify or set the compilation data as needed. The hooks that compile() will call at various points, in calling order, are:

• $c->before_compile($cd)

  Called once at the beginning of compilation.

  If hook sets $cd->{SKIP_ALL_INPUTS} to true then the whole compilation process will end (after_compile() will not even be called).

• $c->before_input($cd)

  Called at the start of processing each input.

  If hook sets $cd->{SKIP_THIS_INPUT} to true then compilation for the current input ends and compilation moves on to the next input. This can be used, for example, to skip recompiling a schema that has been compiled before.

• $c->before_all_clauses($cd)

  Called before calling handler for any clauses.

• $c->before_clause($cd)

  Called for each clause, before calling the actual clause handler ($th->clause_NAME() or $th->clause).

  If hook sets $cd->{SKIP_THIS_CLAUSE} to true then compilation for the clause will be skipped (including calling clause_NAME() and after_clause()). If $cd->{SKIP_REMAINING_CLAUSES} is set to true then compilation for the rest of the schema's clauses will be skipped (including current clause's clause_NAME() and after_clause()).

• $th->before_clause($cd)

  After compiler's before_clause() is called, type handler's before_clause() will also be called if available (note that this method is called on the compiler's type handler class, not the compiler class itself.)

  Input and output interpretation is the same as compiler's before_clause().

• $th->clause_NAME($cd)

  Note that this method is called on the compiler's type handler class, not the compiler class itself. NAME is the name of the clause.

  If hook sets $cd->{SKIP_REMAINING_CLAUSES} to true then compilation for the rest of the clauses to be skipped (including current clause's after_clause()).

• $th->after_clause($cd)

  Note that this method is called on the compiler's type handler class, not the compiler class itself. Called for each clause, after calling the actual clause handler ($th->clause_NAME()).

  If hook sets $cd->{SKIP_REMAINING_CLAUSES} to true then compilation for the rest of the clauses to be skipped.

• $c->after_clause($cd)

  Called for each clause, after calling the actual clause handler ($th->clause_NAME()).

  Output interpretation is the same as $th->after_clause().

• $c->after_all_clauses($cd)

  Called after all clauses have been compiled.

• $c->after_input($cd)

  Called for each input after compiling finishes.

  If hook sets $cd->{SKIP_REMAINING_INPUTS} to true then remaining inputs will be skipped.

• $c->after_compile($cd)

  Called at the very end before compiling process end.

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.