.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "UR::Object::Type::Initializer 3pm"
.TH UR::Object::Type::Initializer 3pm "2019-01-02" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
UR::Object::Type::Initializer \- Class definition syntax
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&  UR::Object::Type\->define(
\&      class_name => \*(AqNamespace::MyClass\*(Aq,
\&      id_by => \*(Aqmy_class_id\*(Aq,
\&      has => [\*(Aqprop_a\*(Aq, \*(Aqprop_b\*(Aq]
\&  );
\&
\&  UR::Object::Type\->define(
\&      class_name => \*(AqNamespace::MyChildClass\*(Aq,
\&      is => \*(AqNamespace::MyClass\*(Aq,
\&      has => [
\&          \*(Aqgreeting\*(Aq => { is => \*(AqString\*(Aq, is_optional => 0,
\&                          valid_values => ["hello","good morning","good evening"],
\&                          default_value => \*(Aqhello\*(Aq },
\&      ],
\&  );
\&
\&  UR::Object::Type\->define(
\&      class_name => \*(AqNamespace::Helper\*(Aq,
\&      id_by => \*(Aqhelper_id\*(Aq,
\&      has => [
\&          \*(Aqmy_class_id\*(Aq => { is => \*(AqString\*(Aq, is_optional => 0 },
\&          \*(Aqmy_class\*(Aq    => { is => \*(AqNamespace::MyClass\*(Aq, id_by => \*(Aqmy_class_id\*(Aq },
\&          \*(Aqmy_class_a\*(Aq  => { via => \*(Aqmy_class\*(Aq, to => \*(Aqprop_a\*(Aq },
\&      ],
\&      has_optional => [
\&          \*(Aqother_attribute\*(Aq => { is => \*(AqInteger\*(Aq }
\&      ],
\&      data_source => \*(AqNamespace::DataSource::DB\*(Aq,
\&      table_name  => \*(AqHELPERS\*(Aq,
\&  );
\&
\&  UR::Object::Type\->define(
\&      class_name => \*(AqNamespace::Users\*(Aq,
\&      id_by => [\*(Aquid\*(Aq],
\&      has => [ \*(Aqlogin\*(Aq,\*(Aqpasswd\*(Aq,\*(Aqgid\*(Aq,\*(Aqname\*(Aq,\*(Aqhome\*(Aq,\*(Aqshell\*(Aq],
\&      data_source => {
\&          is => \*(AqUR::DataSource::File\*(Aq,
\&          file => \*(Aq/etc/passwd\*(Aq,
\&          column_order => [\*(Aqlogin\*(Aq,\*(Aqpasswd\*(Aq,\*(Aquid\*(Aq,\*(Aqgid\*(Aq,\*(Aqname\*(Aq,\*(Aqhome\*(Aq,\*(Aqshell\*(Aq,
\&          skip_first_line => 0,
\&          delimiter => \*(Aq:\*(Aq
\&      },
\&      id_generator => \*(Aq\-uuid\*(Aq,
\&  );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Defining a \s-1UR\s0 class is like drawing up a blueprint of what a particular kind
of object will look like. That blueprint includes the properties these
objects will have, what other classes the new class inherits from, and where
the source data comes from such as a database or file.
.SS "The Simplest Class"
.IX Subsection "The Simplest Class"
The simplest class definition would look like this:
.PP
.Vb 2
\&  use UR;
\&  class Thing {};
.Ve
.PP
You can create an instance of this class like this:
.PP
.Vb 1
\&  my $thing_object = Thing\->create();
.Ve
.PP
Instances of this class have no properties, no backing storage location, and
no inheritance.
.PP
Actually, none of those statements are fully true, but we'll come back to
that later...
.SS "A Little Background"
.IX Subsection "A Little Background"
After using \s-1UR,\s0 or another class that inherits from UR::Namespace, the above
\&\*(L"class\*(R" syntax above can be used to define a class.
.PP
The equivalent, more plain-Perl way to define a class is like this:
.PP
.Vb 4
\&  UR::Object::Type\->define(
\&     class_name => \*(AqThing\*(Aq,
\&     # the remainder of the class definition would go here, if there were any
\&  );
.Ve
.PP
Classes become instances of another class called UR::Object::Type. It has
a property called class_name that contains the package that instances of
these objects are blessed into. Class properties are also instances of a
class called UR::Object::Property, and those properties have properties
(also UR::Object::Properties) that describe it, such as the type of data it
holds, and its length. In fact, all the metadata about classes, properties,
relationships, inheritance, data sources and contexts are available as
instances of metadata classes. You can get information about any class
currently available from the command line with the command
.PP
.Vb 1
\&  ur show properties Thing
.Ve
.PP
with the caveat that \*(L"currently available\*(R" means you need to be under a
namespace directory that contains the class you're describing.
.SS "Making Something Useful"
.IX Subsection "Making Something Useful"
.Vb 5
\&  class Vehicle {
\&      id_by => \*(Aqserial_number\*(Aq,
\&      has => [\*(Aqcolor\*(Aq, \*(Aqweight\*(Aq],
\&      has_optional => [\*(Aqlicense_plate\*(Aq],
\&  };
.Ve
.PP
Here we have a basic class definition for a thing we're calling a Vehicle.
It has 4 properties: serial_number, color, weight and license_plate. Three
of these properties are required, meaning that when you create one, you must
give a value for those properties; it is similar to a '\s-1NOT NULL\s0' constraint
on a database column. The serial_number property is an \s-1ID\s0 property of the
class, meaning that no two instances (objects) of that class can exist with
the same serial_number; it is similar to having a \s-1UNIQUE\s0 index on that
column (or columns) in a database. Not all vehicles have license plates, so
it is optional.
.PP
After that, you've effectively created five object instances. One
UR::Object::Type identified by its class_name being 'Vehicle', and four
UR::Object::Property objects identified by the pairs of class_name and
property_name. For these four properties, class_name is always 'Vehicle'
and property name is one each of serial_number, color, weight and
license_plate.
.PP
Objects always have one property that is called 'id'. If you have only one
property in the id_by section, then the 'id' property is effectively an alias
for it. If you have several id_by properties, then the 'id' property becomes
an amalgamation of the directly named id properties such that no two objects
of that class will have the same 'id'. If there are no id_by properties
given (including MyClass above that doesn't have _any_ properties), then an
implicit 'id' property will get created.  Instances of that class will have
an 'id' generated internally by an algorithm.  Finally, if the class has
more than one \s-1ID\s0 property, none of them may be called 'id', since that name
will be reserved for the amalgamated-value property.
.PP
You can control how IDs get autogenerated with the class' id_generator
metadata.  For classes that save their results in a relational database, it
will get new IDs from a sequence (or some equivalent mechanism for databases
that do not support sequences) based on the class' table name.  If you want
to force the system to use some specific sequence, for example if many
classes should use the same sequence generator, then put the name of this
sequence in.
.PP
If the id_generator begins with a dash (\-), it indicates a method should
be called to generate a new \s-1ID.\s0  For example, if the name is \*(L"\-uuid\*(R", then the
system will call the internal method
\&\f(CW\*(C`$class_meta\-\*(C'\fRautogenerate_new_object_id_uuid>. nd will make object IDs as hex
string UUIDs.  The default value is '\-urinternal' which makes an \s-1ID\s0 string
composed of the hostname, process \s-1ID,\s0 the time the program was started and 
an increasing integer.  If id_generator is a subroutine reference, then the
sub will be called with the class metaobject and creation BoolExpr passed as
parameters.
.PP
You'll find that the parser for class definitions is pretty accepting about
the kinds of data structures it will take. The first thing after class is
used as a string to name the class. The second thing is a hashref
containing key/value pairs. If the value part of the pair is a single
string, as the id_by is in the Vehicle class definition, then one property
is created. If the value portion is an arrayref, then each member of the
array creates an additional property.
.SS "Filling in the Details"
.IX Subsection "Filling in the Details"
That same class definition can be made this way:
.PP
.Vb 10
\&  class Vehicle {
\&      id_by => [
\&          serial_number => { is => \*(AqString\*(Aq, len => 25 },
\&      ],
\&      has => [
\&          color => { is => \*(AqString\*(Aq },
\&          weight => { is => \*(AqNumber\*(Aq },
\&          license_plate => { is => \*(AqString\*(Aq, len => 8, is_optional => 1 },
\&      ],
\&  };
.Ve
.PP
Here we've more explicitly defined the class' properties by giving them a
type. serial_number and license_number are given a maximum length, and
license_number is declared as optional. Note that having a 'has_optional'
section is the same as explicitly putting 'is_optional => 1' for all those
properties. The same shortcut is supported for the other boolean properties
of UR::Object::Property, such as is_transient, is_mutable, is_abstract, etc.
.PP
The type system is pretty lax in that there's nothing stopping you from
using the method for the property to assign a string into a property
declared 'Number'.  Type, length, is_optional constraints are checked by
calling \f(CW\*(C`_\|_errors_\|_()\*(C'\fR on the object, and indirectly when data is committed
back to its data source.
.SS "Inheritance"
.IX Subsection "Inheritance"
.Vb 8
\&  class Car {
\&      is => \*(AqVehicle\*(Aq,
\&      has => [
\&          passenger_count   => { is => \*(AqInteger\*(Aq, default_value => 0 },
\&          transmission_type => { is => \*(AqString\*(Aq,
\&                                 valid_values => [\*(Aqmanual\*(Aq,\*(Aqautomatic\*(Aq,\*(Aqcvt\*(Aq] },
\&      ],
\&  };
\&
\&  my $car = Car\->create(color => \*(Aqblue\*(Aq,
\&                        serial_number => \*(Aqabc123\*(Aq,
\&                        transmission_type => \*(Aqmanual\*(Aq);
.Ve
.PP
Here we define another class called Car. It inherits from Vehicle, meaning
that all the properties that apply to Vehicle instances also apply to Car
instances. In addition, Car instances have two new properties.
passenger_count has a default value of 0, and transmission_type is
constrained to three possible values.
.SS "More class properties"
.IX Subsection "More class properties"
Besides property definitions, there are other things that can be specified
in a class definition.
.IP "is" 4
.IX Item "is"
Used to name the parent class(es). Single inheritance can be specified by
just listing the name of the parent class as a string. Multiple inheritance
is specified by an arrayref containing the parent class names.  If no 'is'
is listed, then the class will inherit from 'UR::Entity'
.IP "doc" 4
.IX Item "doc"
A single string to list some short, useful documentation about the class.
.IP "data_source" 4
.IX Item "data_source"
A string to list the data source \s-1ID.\s0 For classes with no data_source,
the only objects \fBget()\fR can return are those that had previously been
instantiated with \fBcreate()\fR or \fBdefine()\fR earlier in the program, and they do
not get saved anywhere during a \fBcommit()\fR. They do, however, exist in the
object cache during the program's execution.
.Sp
data_source can also be a hashref to define a data source in line with
the class definition.  See below for more information about
\&\*(L"Inline Data Sources\*(R".
.IP "table_name" 4
.IX Item "table_name"
When the class' data source is some kind of database, \f(CW\*(C`table_name\*(C'\fR Specifies
the name of the table where this class' data is stored to.
.IP "select_hint" 4
.IX Item "select_hint"
Some relational databases use hints as a way of telling the query optimizer
to behave differently than usual.  These hints are specified inside comments
like this:
    /* the hint */
If the class is the primary class of a query, and it has a hint, then the hint
will appear after the word 'select' in the \s-1SQL.\s0
.IP "join_hint" 4
.IX Item "join_hint"
If the class is part of a query where it is joined, then its hint will be
added to the hints already part of the query.  The primary table's hint will
be first, followed by the joined class' hints in the order they are joined.
All the hints are separated by a single space.
.IP "is_abstract" 4
.IX Item "is_abstract"
A flag indicating that no instances of this class may be instantiated,
instead it is used as a parent of other classes.
.IP "sub_classification_method_name" 4
.IX Item "sub_classification_method_name"
Holds the name of a method that is called whenever new instances of the
class are loaded from a data source. This method will be called with two
arguments: the name of the class the \fBget()\fR was called on, and the object
instance being loaded. The method should return the complete name of a
subclass the object should be blessed into.
.IP "sub_classification_property_name" 4
.IX Item "sub_classification_property_name"
Works like 'sub_classification_method_name', except that the value of the
property is directly used to subclass the loaded object.
.SS "Properties properties"
.IX Subsection "Properties properties"
\&\f(CW\*(C`ur show properties UR::Object::Property\*(C'\fR will print out an exhaustive list of all
the properties of a Class Property. A class' properties are declared in the 'id_by'
or one of the 'has' sections.  Some of the more important ones:
.IP "class_name" 4
.IX Item "class_name"
The name of the class this property belongs to.
.IP "property_name" 4
.IX Item "property_name"
The name of the property. 'property_name' and 'class_name' do not actually
appear in the hashref that defines the property inside a class definition,
though they are properties of UR::Object::Property instances.
.IP "is" 4
.IX Item "is"
Specifies the data type of this property. Basic types include 'String',
\&'Integer', 'Float'.  Relationships between classes are defined by having the
name of another class here. See the Relationships section of
UR::Manual::Cookbook for more information.
.Sp
Object properties do not normally hold Perl references to other objects, but you
may use '\s-1ARRAY\s0' or '\s-1HASH\s0' here to indicate that the object will store the
reference directly.  Note that these properties are not usually saveable to
outside data sources.
.IP "data_type" 4
.IX Item "data_type"
A synonym for 'is'
.IP "len" 4
.IX Item "len"
Specifies the maximum length of the data, usually in bytes.
.IP "doc" 4
.IX Item "doc"
A space for useful documentation about the property
.IP "default_value" 4
.IX Item "default_value"
The value a property will have if it is not specified when the object is
created.  If used on a property that is 'via' another property (see the
Indirect Properties section below), it can trigger creation of a referent
object.
.IP "calculated_default" 4
.IX Item "calculated_default"
A name of an instance method or a code ref to be used to resolve a default
value during object creation.  The instance method will be called immediately
after \s-1UR\s0 creates the initial entity so the method will have access to other
parameters used during creation.
.Sp
Specifying \f(CW\*(C`calculated_default > 1\*(C'\fR is equivalent to,
.Sp
.Vb 1
\&  calculated_default => \*(Aq_\|_default_\*(Aq . $prop_name . \*(Aq_\|_\*(Aq
.Ve
.Sp
and is meant to establish a naming convention without requiring it.
.IP "is_mutable" 4
.IX Item "is_mutable"
A flag indicating that this property can be changed. It is the default state
of a property.  Set this to 0 in the property definition if the property is
not changeable after the object is created.
.IP "is_constant" 4
.IX Item "is_constant"
A flag indicating that the value of this property may not be changed after
the object is created. It is a synonym for having is mutable = 0
.IP "is_many" 4
.IX Item "is_many"
Indicates that this returns a list of values.  Usually used with
reverse_as properties.
.IP "is_optional" 4
.IX Item "is_optional"
Indicates that this property can hold the value undef.
.PP
\fICalculated Properties\fR
.IX Subsection "Calculated Properties"
.IP "is_calculated" 4
.IX Item "is_calculated"
A flag indicating that the value of this property is determined from a
function.
.IP "calculate_from" 4
.IX Item "calculate_from"
A listref of other property names used by the calculation
.IP "calculate" 4
.IX Item "calculate"
A specification for how the property is to be calculated in Perl.
.RS 4
.IP "\(bu" 6
if the value is a coderef, it will be called when that property is accessed,
and the first argument will be the object instance being acted on.
.IP "\(bu" 6
the value may be a string containing Perl code that is eval-ed when the
accessor is called. The Perl code can refer to \f(CW$self\fR, which will hold
the correct object instance during execution of that code. Any properties
listed in the 'calculate_from' list will also be initialized
.IP "\(bu" 6
The special value 'sum' means that the values of all the properties in the
calculate_from list are added together and returned
.RE
.RS 4
.Sp
Any property can be effectively turned into a calculated property by defining
a method with the same name as the property.
.RE
.PP
\fIDatabase-backed properties\fR
.IX Subsection "Database-backed properties"
.IP "column_name" 4
.IX Item "column_name"
For classes whose data is stored in a database table (meaning the class has
a data_source), the column_name holds the name of the database column in its
table. In the default case, the column_name is the same as the 'property_name'.
.IP "calc_sql" 4
.IX Item "calc_sql"
Specifies that this property is calculated, and its value is a string
containing \s-1SQL\s0 code inserted into that property's \*(L"column\*(R" in the \s-1SELECT\s0
clause
.SS "Relation Properties"
.IX Subsection "Relation Properties"
Some properties are not used to hold actual data, but instead describe some
kind of relationship between two classes.  For example:
.PP
.Vb 12
\&  class Person {
\&      id_by => \*(Aqperson_id\*(Aq,
\&      has => [\*(Aqname\*(Aq],
\&  };
\&  class Thing {
\&      id_by => \*(Aqthing_id\*(Aq,
\&      has => [
\&          owner => { is => \*(AqPerson\*(Aq, id_by => \*(Aqowner_id\*(Aq },
\&      ],
\&  };
\&  $person = Person\->create(person_id => 1, name => \*(AqBob\*(Aq);
\&  $thing = Thing\->create(thing_id => 2, owner_id => 1);
.Ve
.PP
Here, Thing has a property called \f(CW\*(C`owner\*(C'\fR.  It implicitly defines a property
called \f(CW\*(C`owner_id\*(C'\fR.  \f(CW\*(C`owner\*(C'\fR becomes a read-only property that returns an
object of type Person by using the object's value for the \f(CW\*(C`owner_id\*(C'\fR
property, and looking up a Person object where its \s-1ID\s0 matches.  In the above
case, \f(CW\*(C`$thing\->owner\*(C'\fR will return the same object that \f(CW$person\fR
contains.
.PP
Indirect properties can also link classes with multiple \s-1ID\s0 properties.
.PP
.Vb 11
\&  class City {
\&      id_by => [\*(Aqname\*(Aq, \*(Aqstate\*(Aq]
\&  };
\&  class Location {
\&      has => [
\&         city    => { is => \*(AqString\*(Aq },
\&         state   => { is => \*(AqString\*(Aq },
\&         cityobj => { is => \*(AqCity\*(Aq,
\&                      id_by => [\*(Aqcity\*(Aq, \*(Aqstate\*(Aq ] },
\&      ],
\&  };
.Ve
.PP
Note that the order the properties are linked must match in the relationship
property's \f(CW\*(C`id_by\*(C'\fR and the related class's \f(CW\*(C`id_by\*(C'\fR
.SS "Reverse Relationships"
.IX Subsection "Reverse Relationships"
When one class has a relation property to another, the target class can also
define the converse relationship.  In this case, OtherClass is the same
as the first \*(L"Relation Properties\*(R" example where the relationship from
OtherClass to MyClass, but we also define the relationship in the other
direction, from MyClass to OtherClass.
.PP
Many Things can point back to the same Person.
.PP
.Vb 10
\&  class Person {
\&      id_by => \*(Aqperson_id\*(Aq,
\&      has => [\*(Aqname\*(Aq],
\&      has_many => [
\&          things => { is => \*(AqThing\*(Aq, reverse_as => \*(Aqowner\*(Aq },
\&      ]
\&  };
\&  class Thing {
\&      id_by => \*(Aqthing_id\*(Aq,
\&      has => [
\&          owner => { is => \*(AqPerson\*(Aq, id_by => \*(Aqowner_id\*(Aq },
\&      ],
\&  };
.Ve
.PP
Note that the value for \f(CW\*(C`reverse_as\*(C'\fR needs to be the name of the relation
property in the related class that would point back to \*(L"me\*(R".  Yes, it's a bit
obtuse, but it's the best we have for now.
.SS "Indirect Properties"
.IX Subsection "Indirect Properties"
When the property of a related object has meaning to another object, that
relationship can be defined through an indirect property.  Things already
have owners, but it is also useful to know a Thing's owner's name.
.PP
.Vb 9
\&  class Thing {
\&      id_by => \*(Aqthing_id\*(Aq,
\&      has => [
\&          owner => { is => \*(AqPerson\*(Aq, id_by => \*(Aqowner_id\*(Aq },
\&          owner_name => { via => \*(Aqowner\*(Aq, to => \*(Aqname\*(Aq, default_value => \*(AqNo one\*(Aq },
\&      ],
\&  };
\&  $name = $thing\->owner_name();
\&  $name eq $person\->name;  # evaluates to true
.Ve
.PP
The values of indirect properties are not stored in the object.  When the
property's method is called, it looks up the related object through the
accessor named in \f(CW\*(C`via\*(C'\fR, and on that result, returns whatever the method
named in \f(CW\*(C`to\*(C'\fR returns.
.PP
If one of these Thing objects is created by calling Thing\->\fBcreate()\fR, and 
no value is specified for owner_id, owner or owner_name, then the system will
find a Person object where its 'name' is 'No one' and assign the Thing's 
owner_id to point to that Person.  If no matching Person is found, it will
first create one with the name 'No one'.
.SS "Alias Properties"
.IX Subsection "Alias Properties"
Sometimes it's useful to have a property that is an alias for another
property, perhaps as a refactoring tool or to make the \s-1API\s0 clearer.  The is
accomilished by defining an indirect property where the 'via' is _\|_self_\|_.
.PP
.Vb 7
\&  class Thing {
\&      id_by => \*(Aqthing_id\*(Aq,
\&      has => [
\&          owner => { is => \*(AqPerson\*(Aq, id_by => \*(Aqowner_id\*(Aq },
\&          titleholder => { via => \*(Aq_\|_self_\|_\*(Aq, to => \*(Aqowner\*(Aq },
\&      ]
\&  };
.Ve
.PP
In this case, 'titleholder' is an alias for the 'owner' property.  titleholder
can be called as a method any place owner is a valid method call.  BoolExprs
may refer to titleholder, but any such references will be rewrittn to 'owner'
when they are normalized.
.SS "Subclassing Members of an Abstract Class"
.IX Subsection "Subclassing Members of an Abstract Class"
In some cases, objects may be loaded using a parent class, but all the
objects are binned into some other subclass.
.PP
.Vb 10
\&  class Widget {
\&      has => [
\&          manufacturer => { is => \*(AqString\*(Aq,
\&                            valid_values => [\*(AqCoolCo\*(Aq,\*(AqVectornox\*(Aq] },
\&      ],
\&      is_abstract => 1,
\&      sub_classification_method_name => \*(Aqsubclasser\*(Aq,
\&  };
\&  sub Widget::subclasser {
\&      my($class,$pending_object) = @_;
\&      my $subclass = \*(AqWidget::\*(Aq . $pending_object\->manufacturer;
\&      return $subclass;
\&  }
\&
\&  class Widget::CoolCo {
\&      is => \*(AqWidget\*(Aq,
\&      has => \*(Aqserial_number\*(Aq,
\&  };
\&  class Widget::Vextornox {
\&      is => \*(AqWidget\*(Aq,
\&      has => \*(Aqseries_string\*(Aq,
\&  }
\&          
\&  my $cool_widget = Widget\->create(manufacturer => \*(AqCoolCo\*(Aq);
\&  $cool_widget\->isa(\*(AqWidget::CoolCo\*(Aq); # evaluates to true
\&  $cool_widget\->serial_number(12345);  # works
\&  $cool_widget\->series_srting();       # dies
.Ve
.PP
In the class definition for the parent class, Widget, it is marked as being
an abstract class, and the sub_classification_method_name specifies the name
of a method to call whenever a new Widget object is created or loaded.  That
method is passed the pre-subclassed object and must return the fully
qualified subclass name the object really belongs in.  All the objects
returned to the caller will be blessed into the appropriate subclass.
.PP
Alternatively, a property can be designated to hold the fully qualified
subclass name.
.PP
.Vb 9
\&  class Widget {
\&      has => [
\&          subclass_name => { is => \*(AqString\*(Aq,
\&                             valid_values => [\*(AqWidget::CoolCo\*(Aq,
\&                                              \*(AqWidget::Vectornox\*(Aq] },
\&      ],
\&      is_abstract => 1,
\&      subclassify_by => \*(Aqsubclass_name\*(Aq,
\&  }
\&
\&  my $cool_widget = Widget\->create(subclass_name => \*(AqWidget::CoolCo\*(Aq);
\&  $cool_widget = Widget::CoolCo\->create();  # subclass_name is automatically "Widget::CoolCo"
.Ve
.PP
These subclass names will be saved to the data source if the class has a data
source.  Also, when objects of the base class are retrieved with \fBget()\fR, the
results will be automatically put in the appropriate child class.
.SS "Inline Data Sources"
.IX Subsection "Inline Data Sources"
If the data_source of a class definition is a hashref instead of a simple
string, that defines an in-line data source.  The only required item in that
hashref is \f(CW\*(C`is\*(C'\fR, which declares what class this data source will be created
from, such as \*(L"UR::DataSource::Oracle\*(R" or \*(L"UR::DataSource::File\*(R".  From
there, each type of data source will have its own requirements for what is
allowed in an inline definition.
.PP
For UR::DataSource::RDBMS\-derived data sources, it accepts these keys
corresponding to the properties of the same name:
.PP
.Vb 1
\&  server, user, auth, owner
.Ve
.PP
For UR::DataSource::File data sources:
.PP
.Vb 2
\&  server, file_list, column_order, sort_order, skip_first_line,
\&  delimiter, record_separator
.Ve
.PP
In addition, file is a synonym for server.
.PP
For UR::DataSource::FileMux data sources:
.PP
.Vb 2
\&  column_order, sort_order, skip_first_line, delimiter, 
\&  record_separator, required_for_get, constant_values, file_resolver
.Ve
.PP
In addition, resolve_path_with can replace \f(CW\*(C`file_resolver\*(C'\fR and accepts
several formats:
.IP "subref" 4
.IX Item "subref"
A reference to a subroutine.  In this case, \f(CW\*(C`resolve_path_with\*(C'\fR is a
synonym for \f(CW\*(C`file_resolver\*(C'\fR.
.ie n .IP "[ $subref, param1, param2, ..., paramn ]" 4
.el .IP "[ \f(CW$subref\fR, param1, param2, ..., paramn ]" 4
.IX Item "[ $subref, param1, param2, ..., paramn ]"
The subref will be called to resolve the path.  Its arguments will be taken
from the values in the rule from properties mentioned.
.ie n .IP "[ $format, param1, param2, ..., paramn ]" 4
.el .IP "[ \f(CW$format\fR, param1, param2, ..., paramn ]" 4
.IX Item "[ $format, param1, param2, ..., paramn ]"
\&\f(CW$format\fR will be interpreted as an \fBsprintf()\fR format.  The placeholders in the 
format will be filled in from the values in the rule from properties
mentioned.
.PP
Finally, \f(CW\*(C`base_path\*(C'\fR and \f(CW\*(C`resolve_path_with\*(C'\fR can be used together.  In
this case, resolve_path_with is a listref of property names, base_path 
is a string specifying the first part of the pathname.  The final path
is created by joining the base_path and all the property's values together
with '/', as in
  join('/', \f(CW$base_path\fR, param1, param2, ..., paramn )
.SH "SEE ALSO"
.IX Header "SEE ALSO"
UR::Object::Type, UR::Object::Property, UR::Manual::Cookbook