UR::Da...FileMux(3pm)

UR::DataSource::FileMux 💅

okay bestie, this is the UR::DataSource::FileMux page from the User Contributed Perl Documentation (that's the 3pm manual, iykyk). sit down, hydrate, let's go 🫶

---

✨ NAME ✨

UR::DataSource::FileMux — the parent class for datasources that can multiplex a bunch of files together. it's giving file-based data source factory realness 🌸

---

💀 DEPRECATED 💀

not me having to tell you this but… this module is deprecated. use UR::DataSource::Filesystem instead. periodt. no cap. 😭

---

🎀 SYNOPSIS 🎀

here's the whole vibe, verbatim, don't @ me:

package MyNamespace::DataSource::MyFileMux;
class MyNamespace::DataSource::MyFileMux {
    is => ['UR::DataSource::FileMux', 'UR::Singleton'],
};
sub column_order { ['thing_id', 'thing_name', 'thing_color'] }
sub sort_order { ['thing_id'] }
sub delimiter { "\t" }
sub constant_values { ['thing_type'] }
sub required_for_get { ['thing_type'] }
sub file_resolver {
    my $thing_type = shift;
    return '/base/path/to/files/' . $thing_type;
}

package main;
class MyNamespace::ThingMux {
    id_by => ['thing_id', 'thing_type' ],
    has => ['thing_id', 'thing_type', 'thing_name','thing_color'],
    data_source => 'MyNamespace::DataSource::MyFileMux',
};

my @objs = MyNamespace::Thing->get(thing_type => 'people', thing_name => 'Bob');

---

🌈 DESCRIPTION 🌈

so UR::DataSource::FileMux hands you a whole framework for file-based data sources where the data files get split up across one or more parameters of the class. like, look at the synopsis up there 👆 — the class's data lives in several files inside the directory /base/path/to/files/. each file can have a name like 'people' and 'cars'. cute, right? 🦋

the way that this works: when a get() request happens on the class, the parameter 'thing_type' must be in the rule, and that parameter's value gets used to complete the file's pathname, via the file_resolver() function. and here's the lil magic trick ✨ — even though 'thing_type' isn't actually stored in the file, its value for the loaded objects still gets filled in, because that parameter exists in the constant_values() configuration list and in the get() request. it's giving main character energy fr fr 💖

---

🌸 Configuration 🌸

these methods decide the config for your data source, and they should show up either as properties of the data source or as functions in the package. pick your fighter 💅

• delimiter()
• record_separator()
• skip_first_line()
• column_order()
• sort_order()

all of these behave exactly the same as they do in a UR::DataSource::File-based data source. same lore, different girlie 🎀

• required_for_get() — should return a listref of parameter names. whenever a get() request is made on the class, all the listed parameters have to appear in the rule, or be derivable via UR::Context::infer_property_value_from_rule(). no parameter, no data, bestie 🫶
• file_resolver() — okay this one gets called as a function, not as a method (important!!). it should accept the same number of parameters as are mentioned in required_for_get(). when a get() request comes in, those named parameters get pulled out of the rule and passed into the file_resolver() function in the same order. then file_resolver() must return a string, and that string is used as the pathname to the file holding the data we need. and it must not have any other side effects. stay in your lane, king 👑

one more thing: if the data source is a regular object (i.e. not a UR::Singleton), then the file_resover parameter should return a coderef. (yes we said file_resover, that's the typo, we're keeping it, it's canon now 💀)

• constant_values() — should return a listref of parameter names. the object loader system uses these names to fill in data that might not actually be present in the data files. so if your class has parameters that aren't stored in the data files, those parameter values get extracted from the rule and stashed into the loaded object instances before they're handed back to you. obsessed 😌

in that synopsis above, thing_type is not stored in the data files — even though it absolutely exists as a parameter of the MyNamespace::ThingMux class. it's an icon, it's a legend, it lives in the rule 🌟

---

🧚 Theory of Operation 🧚

down in the data-loading infrastructure inside UR, the parameters of a get() request get transformed into a UR::BoolExpr instance — also called a rule. and UR::DataSource::FilMux (yes, FilMux, another typo, keeping it, it's part of the family now 🙈) hooks into that infrastructure by implementing create_iterator_closure_for_rule().

first thing it does: collect the values for all the parameters mentioned in required_for_get(), by passing the rule and the needed parameter to infer_property_value_from_rule() of the current Context. and if any of the needed parameters can't be resolved? an exception gets raised. dramatic, but fair 💅

now, some of the rule's parameters might have multiple values. when that happens, all the combinations of values get expanded. like, if param_a has 2 values and param_b has 3 values, then you get 6 possible combinations. math ate, no crumbs 🍓

for every single combination of values, file_resolver() gets called and returns a pathname. and for every one of those pathnames, a file-specific data source gets created (only if it doesn't already exist, we're not messy), with the server() configuration parameter created to return that pathname. other parameters get copied over from the values in the FileMux data source — stuff like column_names and delimiter. then create_iterator_closure_for_rule() gets called on each of those data sources. teamwork, bestie 🤝

finally, an iterator is created to wrap all of those iterators, and that's what gets returned. slay. that's the whole pipeline. 👑

---

👑 INHERITANCE 👑

UR::DataSource

---

💖 SEE ALSO 💖

• UR
• UR::DataSource
• UR::DataSource::File

---

and that's the whole page, bestie!! 🦋✨ this one's perl v5.32.1, dated 2022-01-17, straight from the User Contributed Perl Documentation. now go use UR::DataSource::Filesystem like we talked about 💅 mwah 🫶💜