.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" 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 turned on, 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 3pm" .TH UR::Object::Type 3pm "2014-07-04" "perl v5.18.2" "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 \- a meta\-class for any class or primitive type .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use UR; \& \& class MyClass { \& is => [\*(AqParentClass1\*(Aq, \*(AqParentClass2\*(Aq], \& id_by => [ \& id_prop1 => { is => \*(AqInteger\*(Aq }, \& id_prop2 => { is => \*(AqString\*(Aq }, \& ], \& has => [ \& property_a => { is => \*(AqString\*(Aq } \& property_b => { is => \*(AqInteger\*(Aq, is_optional => 1 }, \& ], \& }; \& \& my $meta = MyClass\->_\|_meta_\|_; \& \& my @parent_class_metas = $meta\->parents(); \& # 2 meta objects, see UR::Object::Property \& \& my @property_meta = $meta\->properties(); \& # N properties (4, +1 from UR::Object, +? from ParentClass1 and ParentClass2) \& \& $meta\->is_abstract; \& \& $meta\->... .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" UR::Object::Type implements the class behind the central metadata in the \s-1UR\s0 class framework. It contains methods for introspection and manipulation of related class data. .PP A UR::Object::Type object describes UR::Object, and also every subclass of UR::Object. .SH "INHERITANCE" .IX Header "INHERITANCE" Each sub-class of UR::Object has a single UR::Object::Type object describing the class. The UR::Object class itself also has a UR::Object::Type object describing the base class of the system. .PP In addition to describing UR::Object an each of its subclasses, UR::Object::Type is _itself_ a subclass of UR::Object. This means that the same query APIs used for regular objects can be used for meta objects. /\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\e V | UR::Object \-> has-meta \-> UR::Object::Type \-\-> has-meta >\-\-/ A | \e / \e\-\-\-\-\-<\- is-a <\-\-\-\-\-\-\-/ .PP Further, new classes which generate a new UR::Object::Type, also generate a private subclass for the meta-class. This means that each new class can have private meta methods, (ala Ruby). .PP This also means that extensions to a meta-class, apply to the meta-class of its derivatives. .PP .Vb 3 \& Regular Meta\-Class \& Entity Singleton \& \-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\- \& \& Greyhound has\-meta \-> Greyhound::Type \& | | \& V V \& is\-a is\-a \& | | \& V V \& Dog has\-meta \-> Dog::Type \& | | \& V V \& is\-a is\-a \& | | \& V V \& Animal has\-meta \-> Animal::Type \& | | \& V V \& is\-a is\-a \& | | /\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\e \& V V V | \& UR::Object has\-meta \-> UR::Object::Type has\-meta \-/ \& A is\-a \& | | \& \e_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_/ .Ve .SH "CONSTRUCTORS" .IX Header "CONSTRUCTORS" .ie n .IP """class""" 4 .el .IP "``class''" 4 .IX Item "class" .Vb 1 \& class MyClass1 {}; \& \& class MyClass2 { is => \*(AqMyClass1\*(Aq }; \& \& class MyClass3 { \& is => [\*(AqParent1\*(Aq,\*(AqParent2\*(Aq], \& is_abstract => 1, \& is_transient => 1, \& has => [ qw/p1 p2 p3/ ], \& doc => \*(Aqwoo hoo!\*(Aq \& }; .Ve .Sp The primary constructor is not a method on this class at all. \&\s-1UR\s0 catches \*(L"class \s-1SOMENAME\s0 { ... }\*(R" and calls \fIdefine()\fR with the parameters. .IP "define" 4 .IX Item "define" .Vb 4 \& my $class_obj = UR::Object::Type\->define( \& class_name => \*(AqMyClass\*(Aq, \& ... \& ); .Ve .Sp Register a class with the system. The given class_name must be unique within the application. As a side effect, a new Perl namespace will be created for the class's name, and methods will be injected into that namespace for any of the class properties. Other types of metadata objects will get created to manage the properties and relationships to other classes. See the UR::Object::Type::Initializer documentation for more information about the parameters \f(CW\*(C`define()\*(C'\fR accepts. .IP "create" 4 .IX Item "create" .Vb 4 \& my $class_obj = UR::Object::Type\->create( \& class_name => \*(AqNamespace::MyClass\*(Aq, \& ... \& ); .Ve .Sp Create a brand new class within an already existing \s-1UR\s0 namespace. \&\f(CW\*(C`create()\*(C'\fR takes all the same parameters as \f(CW\*(C`define()\*(C'\fR. Another side effect of create is that when the application commits its Context, a new Perl module will be created to implement the class, complete with a class definition. .Sp Applications will not normally use \fIcreate()\fR. .SH "PROPERTIES" .IX Header "PROPERTIES" Each property has a method of the same name .SS "External \s-1API \s0" .IX Subsection "External API " .IP "class_name" 4 .IX Item "class_name" .Vb 1 \& $name = $class_obj\->class_name .Ve .Sp The full name of the class. This is symmetrical with \f(CW$class_obj\fR = \f(CW$name\fR\->_\|_meta_\|_. .IP "properties" 4 .IX Item "properties" .Vb 1 \& @all = $class_obj\->properties(); \& \& @some = $class_obj\->properties( \& \*(Aqis => [\*(AqText\*(Aq,\*(AqNumber\*(Aq] \& \*(Aqdoc like\*(Aq => \*(Aq%important%\*(Aq, \& \*(Aqproperty_name like\*(Aq => \*(Aqsomeprefix_%\*(Aq, \& ); .Ve .Sp Access the related property meta-objects for all properties of this class. It includes the properties of any parent classes which are inherited by this class. .Sp See UR::Object::Property for details. .IP "id_properties" 4 .IX Item "id_properties" .Vb 1 \& @all_id = $class_obj\->id_properties(); \& \& @some = $class_obj\->properties( \& \*(Aqis => [\*(AqText\*(Aq,\*(AqNumber\*(Aq] \& \*(Aqdoc like\*(Aq => \*(Aq%important%\*(Aq, \& \*(Aqproperty_name like\*(Aq => \*(Aqsomeprefix_%\*(Aq, \& ); .Ve .Sp Like \fIproperties()\fR, but only returns \s-1ID\s0 property metadata. .IP "property" 4 .IX Item "property" .Vb 1 \& $property_meta = $class_obj\->property(\*(Aqsomeproperty\*(Aq); .Ve .Sp The singular version of the above. A single argument, as usual, is treated as the remainder of the \s-1ID,\s0 and will select a property by name. .IP "property_names" 4 .IX Item "property_names" .Vb 1 \& @names = $class_obj\->property_names; .Ve .Sp Returns a list of all properties belonging to the class, directly or through inheritance. .IP "namespace" 4 .IX Item "namespace" .Vb 1 \& $namespace_name = $class_obj\->namespace .Ve .Sp Returns the name of the class's \s-1UR\s0 namespace. .IP "doc" 4 .IX Item "doc" .Vb 1 \& $doc = $class_obj\->doc .Ve .Sp A place to put general class-specific notes. .IP "data_source_id" 4 .IX Item "data_source_id" .Vb 1 \& $ds_id = $class_obj\->data_source_id .Ve .Sp The name of the external data source behind this class. Classes without data sources cannot be saved and exist only during the life of the application. data_source_id will resolve to an UR::DataSource id. .IP "table_name" 4 .IX Item "table_name" .Vb 1 \& $table_name = $class_object\->table_name .Ve .Sp For classes with data sources, this is the name of the table within that data source. This is usually a table in a relational database. .Sp At a basic level, it is a storage directive interpreted by the data_source, and may or may not related to a storage table at that level. .IP "is_abstract" 4 .IX Item "is_abstract" .Vb 1 \& $bool = $class_obj\->is_abstract .Ve .Sp A flag indicating if this is an abstract class. Abstract classes cannot have instances, but can be inherited by other classes. .IP "is_final" 4 .IX Item "is_final" .Vb 1 \& $bool = $class_obj\->is_final .Ve .Sp A flag indicating if this class cannot have subclasses. .IP "is_singleton" 4 .IX Item "is_singleton" .Vb 1 \& $bool = $class_obj\->is_singleton .Ve .Sp A flag indicating whether this is a singleton class. If true, the class will inherit from UR::Singleton. .IP "is_transactional" 4 .IX Item "is_transactional" .Vb 1 \& $bool = $class_obj\->is_transactional .Ve .Sp A flag indicating whether changes to this class's instances will be tracked. Non-transactional objecs do not change when an in-memory transaction rolls back. .Sp It is similar to the is_transient meta-property, which does the same for an individual property. .SS "Internal \s-1API \s0" .IX Subsection "Internal API " These methods return data about how this class relates to other classes. .IP "namespace_meta" 4 .IX Item "namespace_meta" .Vb 1 \& $ns_meta = $class_obj\->namespace_meta .Ve .Sp Returns the UR::Namespace object with the class's namespace name. .IP "parent_class_names" 4 .IX Item "parent_class_names" .Vb 1 \& @names = $class_obj\->parent_class_names .Ve .Sp Returns a list of the immediate parent classes. .IP "parent_class_metas" 4 .IX Item "parent_class_metas" .Vb 1 \& @class_objs = $class_obj\->parent_class_metas .Ve .Sp Returns a list of the class objects (UR::Object::Type instances) of the immediate parent classes .IP "ancestry_class_names" 4 .IX Item "ancestry_class_names" .Vb 1 \& @names = $class_obj\->ancestry_class_names .Ve .Sp Returns a list of all the class names this class inherits from, directly or indirectly. This list may have duplicate names if there is multiple inheritance in the family tree. .IP "ancestry_class_metas" 4 .IX Item "ancestry_class_metas" .Vb 1 \& @class_objs = $class_obj\->ancestry_class_metas .Ve .Sp Returns a list of the class objects for each inherited class. .IP "direct_property_names" 4 .IX Item "direct_property_names" .Vb 1 \& @names = $class_obj\->direct_property_names .Ve .Sp Returns a list of the property names defined within this class. This list will not include the names of any properties inherited from parent classes unless they have been overridden. .IP "direct_property_metas" 4 .IX Item "direct_property_metas" .Vb 1 \& @property_objs = $class_obj\->direct_property_metas .Ve .Sp Returns a list of the UR::Object::Property objects for each direct property name. .IP "ancestry_property_names" 4 .IX Item "ancestry_property_names" .Vb 1 \& @names = $class_obj\->ancestry_property_names .Ve .Sp Returns a list of property names of the parent classes and their inheritance heirarchy. The list may include duplicates if a property is overridden somewhere in the heirarchy. .IP "ancestry_property_metas" 4 .IX Item "ancestry_property_metas" .Vb 1 \& @property_objs = $class_obj\->ancestry_property_metas; .Ve .Sp Returns a list of the UR::Object::Property objects for each ancestry property name. .IP "all_property_names" 4 .IX Item "all_property_names" Returns a list of property names of the given class and its inheritance heirarchy. The list may include duplicates if a property is overridden somewhere in the heirarchy. .IP "all_property_metas" 4 .IX Item "all_property_metas" .Vb 1 \& @property_objs = $class_obj\->all_property_metas; .Ve .Sp Returns a list of the UR::Object::Property objects for each name returned by all_property_names. .IP "direct_id_property_names" 4 .IX Item "direct_id_property_names" .Vb 1 \& @names = $class_obj\->direct_id_property_names .Ve .Sp Returns a list of the property names designated as \*(L"id\*(R" properties in the class definition. .IP "direct_id_property_metas" 4 .IX Item "direct_id_property_metas" .Vb 1 \& @property_objs = $class_obj\->direct_id_property_metas .Ve .Sp Returns a list of the UR::Object::Property objects for each id property name. .IP "ancestry_id_property_names" 4 .IX Item "ancestry_id_property_names" .PD 0 .IP "ancestry_id_property_metas" 4 .IX Item "ancestry_id_property_metas" .IP "all_id_property_names" 4 .IX Item "all_id_property_names" .IP "all_id_property_metas" 4 .IX Item "all_id_property_metas" .PD .Vb 4 \& @names = $class_obj\->ancestry_id_property_names; \& @property_objs = $class_obj\->ancestry_id_property_metas; \& @names = $class_obj\->all_id_property_names; \& @property_objs = $class_obj\->all_id_property_metas; .Ve .Sp Returns the property names or UR::Object::Property objects for either the parent classes and their inheritance heirarchy, or for the given class and all of its inheritance heirarchy. The lists may include duplicates if properties are overridden somewhere in the heirarchy. .IP "unique_property_set_hashref" 4 .IX Item "unique_property_set_hashref" .Vb 1 \& $constraints = $class_obj\->unique_property_set_hashref .Ve .Sp Return a hashref describing the unique constraints on the given class. The keys of \f(CW$constraint\fR are constraint names, and the values are listrefs of property names that make up the unique constraint. .IP "add_unique_constraint" 4 .IX Item "add_unique_constraint" .Vb 1 \& $class_obj\->add_unique_constraint($constraint_name, @property_name_list) .Ve .Sp Add a unique constraint to the given class. It is an exception if the given \f(CW$constraint_name\fR already exists as a constraint on this class or its parent classes. .IP "remove_unique_constraint" 4 .IX Item "remove_unique_constraint" .Vb 1 \& $class_obj\->remove_unique_constraint($constraint_name) .Ve .Sp Remove a unique constraint from the given class. It is an exception if the given constraint name does not exist. .IP "ancestry_table_names" 4 .IX Item "ancestry_table_names" .PD 0 .IP "all_table_names" 4 .IX Item "all_table_names" .PD .Vb 1 \& @names = $class_obj\->ancestry_table_names .Ve .Sp Returns a list of table names in the class's inheritance heirarchy. .IP "direct_column_names" 4 .IX Item "direct_column_names" Returns a list of column names for each direct property meta. Classes with data sources and table names will have properties with column names. .IP "direct_id_column_names" 4 .IX Item "direct_id_column_names" Returns a list of \s-1ID\s0 column names for each direct property meta. .IP "direct_columnless_property_names" 4 .IX Item "direct_columnless_property_names" .PD 0 .IP "direct_columnless_property_metas" 4 .IX Item "direct_columnless_property_metas" .IP "ancestry_columnless_property_names" 4 .IX Item "ancestry_columnless_property_names" .IP "ancestry_columnless_property_metas" 4 .IX Item "ancestry_columnless_property_metas" .IP "all_columnless_property_names" 4 .IX Item "all_columnless_property_names" .IP "all_columnless_property_metas" 4 .IX Item "all_columnless_property_metas" .PD Return lists of property meta objects and their names for properties that have no column name. .SH "METHODS" .IX Header "METHODS" .IP "property_meta_for_name" 4 .IX Item "property_meta_for_name" .Vb 1 \& $property_obj = $class_obj\->property_meta_for_name($property_name); .Ve .Sp Return the UR::Object::Property object in the class's inheritance hierarchy with the given name. If the property name has been overridden somewhere in the hierarchy, then it will return the property object most specific to the class. .IP "id_property_sorter" 4 .IX Item "id_property_sorter" .Vb 2 \& $subref = $class_obj\->id_property_sorter; \& @sorted_objs = sort $subref @unsorted_objs; .Ve .Sp Returns a subroutine reference that can be used to sort object instances of the class. The subref is able to handle classes with multiple \s-1ID \s0 properties, and mixes of numeric and non-numeric data and data types. .IP "autogenerate_new_object_id" 4 .IX Item "autogenerate_new_object_id" This method is called whenever new objects of the given class are created through \f(CW\*(C`ClassName\->create()\*(C'\fR, and not all of their \s-1ID\s0 properties were specified. UR::Object::Type has an implementation used by default, but other classes can override this if they need special handling. .SH "SEE ALSO" .IX Header "SEE ALSO" UR::Object::Property