DBIx::Renderer::Base - base class for DBI renderers

NAME

DBIx::Renderer::Base - base class for DBI renderers

SYNOPSIS

  package DBIx::Renderer::MyRenderer;
  use base 'DBIx::Renderer::Base;

DESCRIPTION

This base class for DBI renderers defines some general mechanisms that might be of use to actual renderers. It's not required that a specific renderer subclasses this class, but it does need to support the renderer API (which hasn't been formalized).

METHODS

new

Constructs the renderer object and returns it.

_init

Object initialization. Does nothing in this class, but is called by new(), so subclasses can override this method.

create_index($indexname, $tablename, @fields)

Returns the SQL necessary to create an index called $indexname on table $tablename for the specified fields. An example might be

        CREATE INDEX product_idx ON product (title);

create_table($tablename, $tabledef)

Returns the SQL necessary to create a table called $tablename using field definitions given in the array reference $tabledef. Each field definition is a hash with the fieldname being the key and the field specification being the value. The field specification, in turn, is a reference to an array consisting of attributes. The attributes are themselves hashes with the key being the attribute name (e.g., 'int4', 'bool', 'index', 'unique') and the value being the attribute parameters (e.g. the size of varchar fields, or an id for grouping index fields).

Instead of saying ``hashes'', I should really say key-value pairs, since they are stored in a list. But they are interpreted as hashes.

All this sounds a bit abstract, so maybe looking at that data structure helps. This has been produced with Data::Dumper but rolled into hashes and lined up to make it more obvious what's going on.

    use DBIx::Renderer ':all';

    # mandatory name
    use constant TYPE_MANDNAME => ( VARCHAR(255), NOTNULL );

    my $struct = [
            product => [
                    id         => { TYPE_ID },
                    name       => { TYPE_MANDNAME, INDEX },
                    short_desc => { TEXT },
                    long_desc  => { TEXT },
                    image      => { VARCHAR(255) },
                ],
    ];

constructs a structure looking like this:

    product => [
      id => {
          'NOTNULL' => 1,
          'type'    => 'INT4',
          'PK'      => 1
        },
      name => {
          'NOTNULL' => 1,
          'size'    => 255,
          'INDEX'   => 1,
          'type'    => 'VARCHAR'
        },
      short_desc => {
          'type'    => 'TEXT'
        },
      long_desc => {
          'type'    => 'TEXT'
        },
      image => {
          'size'    => 255,
          'type'    => 'VARCHAR'
        }
    ];

create_schema($schema)

Constructs all SQL commands necessary to create the specified database schema. $schema is an array reference consisting of table definitions as shown above. The method then calls create_table and create_index to generate the SQL and returns the string.

get_type_name($coldef)

Helper method that returns this SQL version's name for the type specified in the column definition.

find_fields($tabledef, $wanted)

Helper method that searches the given table definition for fields whose definition have the $wanted attribute. For example, to find all primary key fields of a table, use

        @pk_fields = $self->find_fields($tabledef, 'PK');

get_pk_fields($tabledef)

Helper method that returns a list of primary key fields for the given table definition.

get_index_fields($tabledef)

Helper method that returns a list of indexed fields for the given table definition.

get_attr_names($coldef)

Returns the SQL corresponding to a field's specification.

For example, the following field definition

      name => {
          'size'  => 255,
          'type'  => 'VARCHAR'
          'UNIQUE'=> 1,
        }

might return

        VARCHAR(255) UNIQUE

get_attr($coldef)

Return a field's attributes by scanning the $coldef for attributes as defined in DBIx::Renderer::Constants. The term 'attributes' is used here to mean things like 'NOTNULL', 'UNIQUE', 'DEFAULT', but not data types or whether the field is a primary key or indexed.

get_const_name($const, @args)

This method takes a constant as defined in DBIx::Renderer::Constants and an optional list of arguments (e.g., a varchar has the size as its argument) and returns the appropriate name for this SQL version. The default method implemented in this class, for example, returns 'VARCHAR(255)' when called as get_const_name('VARCHAR', 255). Other SQL dialects may have a different name for it.

expand($l)

Helper function (not a method) that takes a scalar and recursively expands array references to create a flat array reference, which it returns. If the scalar isn't an array reference to begin with, it just returns the scalar.

This function is useful for constructing the structures mentioned above, since you can combine attributes by creating an array reference containing them, but then inserting this combination into a surrounding definition creates nested array references, so we use this function to flatten them. Check the source for details.

BUGS

None known so far. If you find any bugs or oddities, please do inform the author.

AUTHOR

Marcel Grünauer <marcel@codewerk.com>

COPYRIGHT

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