UR::Object::Type(3pm)

okay bestie, buckle up 💖 this is the manual page for UR::Object::Type(3pm) from the User Contributed Perl Documentation — and it's a long one, so we're doing it in parts. Part 1 starts now. No skipping, no skimming, we're reading the whole thing like the main characters we are. 👑

---

✨ NAME ✨

UR::Object::Type — a meta-class for any class or primitive type 🦋

---

✨ SYNOPSIS ✨

use UR;

class MyClass {
    is => ['ParentClass1', 'ParentClass2'],
    id_by => [
        id_prop1    => { is => 'Integer' },
        id_prop2    => { is => 'String' },
    ],
    has => [
        property_a  => { is => 'String' }
        property_b  => { is => 'Integer', 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->...

so basically you write a class, you grab its meta with __meta__, and then you can interrogate it about its parents and properties like the nosy queen you are 💅

---

✨ DESCRIPTION ✨

UR::Object::Type implements the class behind the central metadata in the UR class framework. It's literally the class behind the classes. It's got methods for introspection and manipulation of all that related class data. 🔍

A UR::Object::Type object describes UR::Object, and also describes every single subclass of UR::Object. Every one. All of them. No cap.

---

✨ INHERITANCE ✨

okay this part is so iconic, pay attention 🎀

In addition to describing UR::Object and each of its subclasses, UR::Object::Type is _itself_ a subclass of UR::Object. Meaning: the exact same query APIs you use for regular objects? You can use them on meta objects too. Same energy, different target. ✨

   UR::Object  -> has-meta -> UR::Object::Type
          A                         |
          \                        /
           \-----<- is-a  <-------/

And it gets better, bestie. Further, new classes which generate a new UR::Objec::Type, also generate a new subclass for the meta-class. So every new class can have its own private meta methods (ala Ruby). 🫶

Which means: extensions to a meta-class apply to the meta-class of its derivatives. The vibes cascade. 🌈

     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
        |                          |     /-----------------\
        V                          V     V                 |
   UR::Object   has-meta ->   UR::Object::Type   has-meta -/
          A                      is-a
          |                        |
           \______________________/

look at that little loop at the end — UR::Object::Type has-meta's itself. it's giving ouroboros, it's giving self-aware. 😭💖

---

✨ CONSTRUCTORS ✨

💫 class

class MyClass1 {};

class MyClass2 { is => 'MyClass1' };

class MyClass3 {
    is => ['Parent1','Parent2'],
    is_abstract => 1,
    is_transient => 1,
    has => [ qw/p1 p2 p3/ ],
    doc => 'woo hoo!'
};

okay plot twist 🌸 the primary constructor is not a method on this class at all. UR catches class SOMENAME { ... } and calls define() with the parameters. Sneaky. Elegant. Iconic.

💫 define

my $class_obj = UR::Object::Type->define(
                    class_name => 'MyClass',
                    ...
                );

Register a class with the system. Register it. Put it in the system. The given class_name must be unique within the application — no duplicates, bestie, we don't do that here. 🚫

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. So much happening behind the scenes, honestly slay. ✨

See the UR::Object::Type::Initializer documentation for more information about the parameters define() accepts. 👀

💫 create

my $class_obj = UR::Object::Type->create(
                    class_name => 'Namespace::MyClass',
                    ...
                );

Create a brand new class within an already existing UR namespace. create() takes all the same parameters as define().

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. it literally writes a module for you 🧚

heads up though: applications will not normally use create(). So like, don't just casually reach for it, okay? 🙈

---

okay that's part 1 bestie — the rest is coming, don't go anywhere 💖

✨ PROPERTIES ✨

Okay bestie, here's the tea: every single property has a method with the same name as that property. That's just how this works. 💅

---

🌸 External API 🌸

💖 class_name

$name = $class_obj->class_name

The name of the class. Class names are unique within a UR namespace and an application.

This is symmetrical with $class_obj = $name->__meta__. ✨

🦋 properties

@all = $class_obj->properties();

@some = $class_obj->properties(
    'is                    => ['Text','Number']
    'doc like'             => '%important%',
    'property_name like'   => 'someprefix_%',
);

Access the related property meta-objects for all the properties of this class. It includes the properties of any parent classes that are inherited by this class, no gatekeeping here. 💫

See UR::Object::Property for the details, iykyk.

🎀 property

$property_meta = $class_obj->property('someproperty');

The singular version of the one above, bestie. A single argument, as usual, is treated as the remainder of the ID, and will select a property by name.

🌈 namespace

$namespace_name = $class_obj->namespace

Returns the name of the class's UR namespace. 🫶

🌸 doc

$doc = $class_obj->doc

A place to put general class-specific notes. It's giving notes app. 📝

⭐ data_source_id

$ds_id = $class_obj->data_source_id

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.

🧚 table_name

$table_name = $class_object->table_name

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.

At a basic level, it is a storage directive interpreted by the data source, and may or may not be related to a storage table at that level. 🤷♀️

💅 is_abstract

$bool = $class_obj->is_abstract

A flag indicating if this is an abstract class. Abstract classes cannot have instances, but can be inherited by other classes. No instances for you, sorry queen. 👑

🔥 is_final

$bool = $class_obj->is_final

A flag indicating if this class cannot have subclasses. Periodt, no descendants.

🎀 is_singleton

$bool = $class_obj->is_singleton

A flag indicating whether this is a singleton class. If true, the class will inherit from UR::Singleton. Main character energy, only one of them. ⭐

💜 is_transactional

$bool = $class_obj->is_transactional

A flag indicating whether changes to this class's instances will be tracked. Non-transactional objects do not change when an in-memory transaction rolls back.

It is similar to the is_transient meta-property, which does the same for an individual property.

---

💜 Internal API 💜

These methods return data about how this class relates to other classes. Family tree lore, basically. 🌳

🌙 namespace_meta

$ns_meta = $class_obj->namespace_meta

Returns the UR::Namespace object with the class's namespace name.

🦋 parent_class_names

@names = $class_obj->parent_class_names

Returns a list of the immediate parent classes.

🌸 parent_class_metas

@class_objs = $class_obj->parent_class_metas

Returns a list of the class objects (UR::Object::Type instances) of the immediate parent classes.

✨ ancestry_class_names

@names = $class_obj->ancestry_class_names

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. Messy family, we love it. 💀

🧚 ancestry_class_metas

@class_objs = $class_obj->ancestry_class_metas

Returns a list of the class objects for each inherited class.

🎀 direct_property_names

@names = $class_obj->direct_property_names

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. Only the homegrown ones. 🏡

💖 direct_property_metas

@property_objs = $class_obj->direct_property_metas

Returns a list of the UR::Object::Property objects for each direct property name.

🌈 ancestry_property_names

@names = $class_obj->ancestry_property_names

Returns a list of property names of the parent classes and their inheritance hierarchy. The list may include duplicates if a property is overridden somewhere in the hierarchy.

🫶 ancestry_property_metas

@property_objs = $class_obj->ancestry_property_metas;

Returns a list of the UR::Object::Property objects for each ancestry property name.

⭐ all_property_names

Returns a list of property names of the given class and its inheritance hierarchy. The list may include duplicates if a property is overridden somewhere in the hierarchy.

💅 all_property_metas

@property_objs = $class_obj->all_property_metas;

Returns a list of the UR::Object::Property objects for each name returned by all_property_names.

🔥 direct_id_property_names

@names = $class_obj->direct_id_property_names

Returns a list of the property names designated as "id" properties in the class definition.

🎀 direct_id_property_metas

@property_objs = $class_obj->direct_id_property_metas

Returns a list of the UR::Object::Property objects for each id property name.

💜 ancestry_id_property_names

🌸 ancestry_id_property_metas

🦋 all_id_property_names

✨ all_id_property_metas

@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;

Returns the property names or UR::Object::Property objects for either the parent classes and their inheritance hierarchy, or for the given class and all of its inheritance hierarchy. The lists may include duplicates if properties are overridden somewhere in the hierarchy.

🌙 unique_property_set_hashref

$constraints = $class_obj->unique_property_set_hashref

Return a hashref describing the unique constraints on the given class. The keys of $constraint are constraint names, and the values are listrefs of property names that make up the unique constraint.

💖 add_unique_constraint

$class_obj->add_unique_constraint($constraint_name, @property_name_list)

Add a unique constraint to the given class. It is an exception if the given $constraint_name already exists as a constraint on this class or its parent classes. 👀

🎀 remove_unique_constraint

$class_obj->remove_unique_constraint($constraint_name)

Remove a unique constraint from the given class. It is an exception if the given constraint name does not exist.

🧚 ancestry_table_names

🌈 all_table_names

@names = $class_obj->ancestry_table_names

Returns a list of table names in the class's inheritance hierarchy.

⭐ 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.

💅 direct_id_column_names

Returns a list of ID column names for each direct property meta.

🦋 direct_columnless_property_names

🌸 direct_columnless_property_metas

🔥 ancestry_columnless_property_names

💜 ancestry_columnless_property_metas

✨ all_columnless_property_names

🎀 all_columnless_property_metas

Return lists of property meta objects and their names for properties that have no column name.

✨ METHODS ✨

💅 property_meta_for_name

$property_obj = $class_obj->property_meta_for_name($property_name);

Okay so bestie, this one hands you back the UR::Object::Property object that lives somewhere in your class's inheritance hierarchy and answers to that name. 🫶

And here's the tea: if that property name got overridden somewhere along the way up the family tree, you get the property object that's the most specific to your class. Most specific wins, always. 👑

---

🧚 id_property_sorter

$subref = $class_obj->id_property_sorter;
@sorted_objs = sort $subref @unsorted_objs;

Returns a subroutine reference you can straight-up hand to sort to sort object instances of the class. ✨

She's built different, fr fr — this subref handles classes with multiple ID properties, and it doesn't even flinch at a mix of numeric and non-numeric data and data types. Versatile queen. 💅

---

🎀 autogenerate_new_object_id

This method gets called whenever new objects of the given class are created through ClassName->create(), and not all of their ID properties were specified. 🫣

UR::Object::Type ships with an implementation that's used by default, but other classes can override it if they need some special handling. Do your own thing, iykyk. 💖

---

🦋 singular_accessor_name_for_is_many_accessor

$property_name = $class_obj->singular_accessor_name_for_is_many_accessor($is_many_name);

For is_many properties, this gives you back the name of the singular accessor. Usually it's just the singular version of the plural, is_many property's name. 🌸

The singular accessor takes key/value pairs as arguments, and those get used to filter the results of the is_many accessor. Like, for example? The singular for the 'cars' accessor is 'car'. Cute, right?

Returns a false value if the given property name doesn't exist or isn't is_many. 🙈

---

🌈 iterator_accessor_name_for_is_many_accessor

$iter_name = $class_obj->iterator_accessor_name_for_is_many_accessor($is_many_name);

Returns the accessor name you use to get the UR::Object::Iterator that corresponds with the is_many accessor. 🌀

For example, the iterator for the 'cars' accessor is 'car_iterator'.

Returns a false value if the given property name doesn't exist or isn't is_many. 💀

---

🍓 set_accessor_name_for_is_many_accessor

$set_name = $class_obj->set_accessor_name_for_is_many_accessor($is_many_name);

Returns the accessor name used to get the UR::Object::Set that corresponds with the is_many accessor. 🎁

For example, the set for the 'cars' accessor is 'car_set'.

Returns a false value if the given property name doesn't exist or isn't is_many. 😭

---

💜 rule_accessor_name_for_is_many_accessor

$rule_name = $class_obj->rule_accessor_name_for_is_many_accessor($is_many_name);

Returns the accessor name used to get the UR::BoolExpr that corresponds with the is_many accessor. 🧠

For example, the rule for the 'cars' accessor is '__car_rule'. (Yes, with the double underscore. She's shy. 🙈)

Returns a false value if the given property name doesn't exist or isn't is_many.

---

⭐ arrayref_accessor_name_for_is_many_accessor

$arrayref_name = $class_obj->arrayref_accessor_name_for_is_many_accessor($is_many_name);

Returns the accessor name used to get the arrayref of objects that corresponds with the is_many accessor. 📚

For example, the arrayref for the 'cars' accessor is 'car_arrayref'.

Returns a false value if the given property name doesn't exist or isn't is_many. 💅

---

🔥 adder_name_for_is_many_accessor

$adder_name = $class_obj->adder_name_for_is_many_accessor($is_many_name);

Returns the method name used to get the adder method that corresponds with the is_many accessor. ➕

For example, the adder for the 'cars' accessor is 'add_car'.

Returns a false value if the given property name doesn't exist or isn't is_many. 🫶

---

🌸 remover_name_for_is_many_accessor

$remover_name = $class_obj->remover_name_for_is_many_accessor($is_many_name);

Returns the method name used to get the remover method that corresponds with the is_many accessor. ➖

For example, the adder for the 'cars' accessor is 'remove_car'.

Returns a false value if the given property name doesn't exist or isn't is_many. (And yeah, the original says "adder" in that example line — we keep it real and keep it exact, bestie. 😌)

---

👑 SEE ALSO 👑

Go read these, they're the whole friend group:

• UR::Object::Property
• UR::Object::Iterator
• UR::Object::Set
• UR::BoolExpr

---

And that's the whole page, bestie!! 🎉 You just read the perl v5.32.1 build of this doc, dated 2022-01-17, and honestly? Ate. No crumbs. 💅✨ Go forth and slay your objects. 💖