The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
OP-0.320
++
/ OP::Subtype

NAME

OP::Subtype - Subtype rules for OP::Type instances

DESCRIPTION

Subtypes are optional components which may modify the parameters of an OP::Type. Subtypes are sent as arguments when calling OP::Type constructors.

When you see something like:

  foo => OP::Str->assert(
    subtype(
      optional => true
    )
  )

"OP::Str->assert()" was the Type constructor, and "optional" was part of the Subtype specification. "foo" was name of the instance variable and database table column which was asserted.

The class variable %OP::Type::RULES is walked at package load time, and the necessary rule subclasses are created dynamically.

SCHEMA ADVISEMENT

Many of these rules affect database schema attributes-- meaning if you change them after the table already exists, the table will need to be administratively ALTERed (or moved aside to a new name, re-created, and migrated). A class's table is created when its package is loaded for the first time.

Schema updates should be performed using carefully reviewed commands. Always back up the current table before executing an ALTER.

SUBTYPE ARGS

Instance variable assertions may be modified by providing the following arguments to subtype():

columnType => $colType

Override a database column type, eg "VARCHAR(128)".

default => $value

Set the default value for a given instance variable and database table column.

Unless optional() is given, the default value must also be included as an allowed value.

min => $num

Specifies the minimum allowed numeric value for a given instance variable.

minSize => $num

Specifies the minimum length or scalar size for a given instance variable.

max => $num

Specifies the maximum allowed numeric value for a given instance variable.

maxSize => $num

Specifies the maximum length or scalar size for a given instance variable.

optional => true

Permit a NULL (undef) value for a given instance variable.

regex => qr/.../

Specifies an optional regular expression which the value of the given instance variable must match.

size => $num

Specify that values must always be of a fixed size. The "size" is the value obtained through the built-in function length() (string length) for Scalars, scalar(...) (element count) for Arrays, and scalar keys() (key count) for Hashes.

sqlValue => $str, sqlInsertValue => $str, sqlUpdateValue => $str

Override an asserted attribute's "insert" value when writing to a SQL database. This is useful if deriving a new value from existing table values at insertion time.

::sqlInsertValue and ::sqlUpdateValue override any provided value for ::sqlValue, but only on INSERT and UPDATE statements, respectively.

  create "OP::Example" => {
    foo => OP::Int->assert(...,
      subtype(
        sqlValue => "(coalesce(max(foo),-1)+1)",
      )
    ),

    # ...
  };

unique => true

Specify UNIQUE database table columns.

  create "OP::Example" => {
    #
    # Your must either specify true or false...
    #
    foo => OP::Str->assert(...,
      subtype(
        unique => true
      )
    ),

    #
    # ... or specify a name for "joined" combinatory keys,
    # as used in statement UNIQUE KEY ("foo","bar")
    #
    # To join with more than one key, provide an array reference
    # of key names.
    #
    # For example, to make sure bar+foo is always unique:
    #
    bar => OP::Str->assert(...,
      subtype(
        unique => "foo"
      )
    ),

    # ...
  };

uom => $str

Specify an attribute's unit of measurement label.

PUBLIC INSTANCE METHODS

  • $self->value()

    Return the scalar value which was provided to self's constructor.

SEE ALSO

OP::Type

This file is part of OP.