.\" 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::DataSource::FileMux 3pm"
.TH UR::DataSource::FileMux 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::DataSource::FileMux \- Parent class for datasources which can multiplex many files together
.SH "DEPRECATED"
.IX Header "DEPRECATED"
This module is deprecated.  Use UR::DataSource::Filesystem instead.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\&  package MyNamespace::DataSource::MyFileMux;
\&  class MyNamespace::DataSource::MyFileMux {
\&      is => [\*(AqUR::DataSource::FileMux\*(Aq, \*(AqUR::Singleton\*(Aq],
\&  };
\&  sub column_order { [\*(Aqthing_id\*(Aq, \*(Aqthing_name\*(Aq, \*(Aqthing_color\*(Aq] }
\&  sub sort_order { [\*(Aqthing_id\*(Aq] }
\&  sub delimiter { "\et" }
\&  sub constant_values { [\*(Aqthing_type\*(Aq] }
\&  sub required_for_get { [\*(Aqthing_type\*(Aq] }
\&  sub file_resolver {
\&      my $thing_type = shift;
\&      return \*(Aq/base/path/to/files/\*(Aq . $thing_type;
\&  }
\&
\&  package main;
\&  class MyNamespace::ThingMux {
\&      id_by => [\*(Aqthing_id\*(Aq, \*(Aqthing_type\*(Aq ],
\&      has => [\*(Aqthing_id\*(Aq, \*(Aqthing_type\*(Aq, \*(Aqthing_name\*(Aq,\*(Aqthing_color\*(Aq],
\&      data_source => \*(AqMyNamespace::DataSource::MyFileMux\*(Aq,
\&  };
\&
\&  my @objs = MyNamespace::Thing\->get(thing_type => \*(Aqpeople\*(Aq, thing_name => \*(AqBob\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
UR::DataSource::FileMux provides a framework for file-based data sources where the
data files are split up between one or more parameters of the class.  For example,
in the synopsis above, the data for the class is stored in several files in the
directory /base/path/to/files/.  Each file may have a name such as 'people' and 'cars'.
.PP
When a \fBget()\fR request is made on the class, the parameter 'thing_type' must be present
in the rule, and the value of that parameter is used to complete the file's pathname,
via the \fBfile_resolver()\fR function.  Note that even though the 'thing_type' parameter
is not actually stored in the file, its value for the loaded objects gets filled in
because that parameter exists in the \fBconstant_values()\fR configuration list, and in
the \fBget()\fR request.
.SS "Configuration"
.IX Subsection "Configuration"
These methods determine the configuration for your data source and should appear as
properties of the data source or as functions in the package.
.IP "\fBdelimiter()\fR" 4
.IX Item "delimiter()"
.PD 0
.IP "\fBrecord_separator()\fR" 4
.IX Item "record_separator()"
.IP "\fBskip_first_line()\fR" 4
.IX Item "skip_first_line()"
.IP "\fBcolumn_order()\fR" 4
.IX Item "column_order()"
.IP "\fBsort_order()\fR" 4
.IX Item "sort_order()"
.PD
These configuration items behave the same as in a UR::DataSource::File\-based data source.
.IP "\fBrequired_for_get()\fR" 4
.IX Item "required_for_get()"
\&\fBrequired_for_get()\fR should return a listref of parameter names.  Whenever a \fBget()\fR request is
made on the class, the listed parameters must appear in the rule, or be derivable via
\&\fBUR::Context::infer_property_value_from_rule()\fR.
.IP "\fBfile_resolver()\fR" 4
.IX Item "file_resolver()"
\&\fBfile_resolver()\fR is called as a function (not a method).  It should accept the same number
of parameters as are mentioned in \fBrequired_for_get()\fR.  When a \fBget()\fR request is made,
those named parameters are extracted from the rule and passed in to the \fBfile_resolver()\fR
function in the same order.  \fBfile_resolver()\fR must return a string that is used as the
pathname to the file that contains the needed data.  The function must not have any
other side effects.
.Sp
In the case where the data source is a regular object (not a UR::Singleton'), then 
the file_resover parameter should return a coderef.
.IP "\fBconstant_values()\fR" 4
.IX Item "constant_values()"
\&\fBconstant_values()\fR should return a listref of parameter names.  These parameter names are used by
the object loader system to fill in data that may not be present in the data files.  If the
class has parameters that are not actually stored in the data files, then the parameter
values are extracted from the rule and stored in the loaded object instances before being
returned to the user.
.Sp
In the synopsis above, thing_type is not stored in the data files, even though it exists
as a parameter of the MyNamespace::ThingMux class.
.SS "Theory of Operation"
.IX Subsection "Theory of Operation"
As part of the data-loading infrastructure inside \s-1UR,\s0 the parameters in a \fBget()\fR 
request are transformed into a UR::BoolExpr instance, also called a rule.  
UR::DataSource::FilMux hooks into that infrastructure by implementing
\&\fBcreate_iterator_closure_for_rule()\fR.  It first collects the values for all the
parameters mentioned in \fBrequired_for_get()\fR by passing the rule and needed
parameter to \fBinfer_property_value_from_rule()\fR of the current Context.  If any
of the needed parameters is not resolvable, an exception is raised.
.PP
Some of the rule's parameters may have multiple values.  In those cases, all the 
combinations of values are expanded.  For example of param_a has 2 values, and
param_b has 3 values, then there are 6 possible combinations.
.PP
For each combination of values, the \fBfile_resolver()\fR function is called and 
returns a pathname.  For each pathname, a file-specific data source is created
(if it does not already exist), the \fBserver()\fR configuration parameter created
to return that pathname.  Other parameters are copied from the values in the
FileMux data source, such as column_names and delimiter.
\&\fBcreate_iterator_closure_for_rule()\fR is called on each of those data sources.
.PP
Finally, an iterator is created to wrap all of those iterators, and is returned.
.SH "INHERITANCE"
.IX Header "INHERITANCE"
UR::DataSource
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1UR,\s0 UR::DataSource, UR::DataSource::File