/ 
Data-Sah-0.02
River stage three • 442 direct dependents • 699 total dependents
/ Data::Sah::Compiler::Base

NAME

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

VERSION

version 0.02

ATTRIBUTES

main => OBJ

Reference to the main Sah module.

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. Subclasses may require/recognize additional keys (for example, ProgBase compilers recognize data_term to customize variable to get data from).

Return. Compiler should return a hash containing at least these keys: result (the final compilation result, usually a string like Perl code or human text). Hash can contain other metadata which are compiler-specific.

Hooks. compile() will at various points call other methods (hooks) which must be supplied/added by the subclass (or by the compiler's type handler). These hooks will be called with hash arguments and expected to return a hashref. One of the arguments that will always be passed is cdata, compilation data, which is a used to store the compilation state and result. It is passed around instead of put as an attribute to simplify inner compilation (i.e. a hook invokes another compile()).

These hooks, in calling order, are:

  • $c->before_compile(args=>\%args, outer_cdata=>$d) => HASHREF

    Called once at the beginning of compilation. The base class initializes a relatively empty compilation data and return it.

    Arguments: args (arguments given to compile()), outer_cdata can be set if this compilation is for a subschema. This compilation data will then be based on outer_cdata instead of empty.

    Return value: If key SKIP_ALL_INPUTS is set to true then the whole compilation process will end (after_compile() will not even be called). The return hashref value MUST also return cdata, as it will be passed around to the remaining hooks.

    About compilation data (cdata): it store schema compilation state, or other compilation data (like result). Should be a hashref containing 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), ct (clauses table, see explanation below), lang (current language), clause (current clause), th (current type handler), clause_res (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 a hash form, 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 (sometimes abbreviated as ct): A single hashref containing all the clauses to be processed, parsed from schema's clause_sets (which is an array of hashrefs). It is easier to use by the handlers. Each hash key is clause name, stripped from all prefixes and 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 which is a hashref: {name=>..., value=>...., attrs=>{...}, order=>..., cs_idx=>..., cs=>...]. 'name' is the clause name (no prefixes, attributes, or #INDEX suffixes), 'value' is the clause value, 'attrs' is a hashref containing attribute names and values, 'order' is the processing order (1, 2, 3, ...), 'cs_idx' is the index to the original clause_sets arrayref, 'cs' is reference to the original clause set.

  • $c->before_input(cdata=>$cdata) => HASHREF

    Called at the start of processing each input. Base compiler uses this to set/reset schema, ct, and the rest of schema data in cdata.

    Arguments: cdata.

    Return value: If SKIP_THIS_INPUT is set 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_schema(cdata=>$cdata) => HASHREF

    Called at the start of processing each schema. At this stage, the normalized schema is available at $cdata->{schema}. The base compiler uses this hook to save $cdata->{th_table_before_def} which is type table before being modified by any subschema definition.

    Arguments: cdata.

    Return value: If SKIP_THIS_SCHEMA is set to true then compilation for the current schema and compilation directly move on to after_input(). This can be used, for example, to skip recompiling a schema that has been compiled before.

  • $c->def(cdata=>$d, name=>$name, def=>$def, optional=>1|0) => HASHREF

    Called for each subschema definition.

    Arguments: cdata, name (definition name), def (the definition), optional (boolean will be set to true if the definition is an optional one, e.g. {def => {'?email' => ...}, ...}).

  • $c->before_all_clauses(cdata=>$d) => HASHREF

    Called before calling handler for any clauses.

  • $c->before_clause(cdata=>$d) => HASHREF

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

    Return value: If SKIP_THIS_CLAUSE is set to true then compilation for the clause will be skipped (including calling clause_NAME() and after_clause()). If 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(cdata=>$d) => HASHREF

    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(cdata=>$d) => HASHREF

    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.

    Return value: If SKIP_REMAINING_CLAUSES if set to true then compilation for the rest of the clauses to be skipped (including current clause's after_clause()).

  • $th->after_clause(cdata=>$d) => HASHREF

    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()).

    Return value: If SKIP_REMAINING_CLAUSES is set to true then compilation for the rest of the clauses to be skipped.

  • $c->after_clause(cdata=>$d) => HASHREF

    Called for each clause, after calling the actual clause handler ($th->clause_NAME()). $res is result return by clause_NAME(). th is reference to type handler object.

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

  • $c->after_all_clauses(cdata=>$d) => HASHREF

    Called after all clause have been compiled.

  • $c->after_input(cdata=>$d) => HASHREF

    Called for each input after compiling finishes.

    Return hashref which can contain this key: SKIP_REMAINING_INPUTS which if set to true will skip remaining inputs.

  • $c->after_compile(cdata=>$d) => HASHREF

    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.