.\" 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::File 3pm"
.TH UR::DataSource::File 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::File \- Parent class for file\-based data sources
.SH "DEPRECATED"
.IX Header "DEPRECATED"
This module is deprecated.  Use UR::DataSource::Filesystem instead.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 8
\&  package MyNamespace::DataSource::MyFile;
\&  class MyNamespace::DataSource::MyFile {
\&      is => [\*(AqUR::DataSource::File\*(Aq, \*(AqUR::Singleton\*(Aq],
\&  };
\&  sub server { \*(Aq/path/to/file\*(Aq }
\&  sub delimiter { "\et" }
\&  sub column_order { [\*(Aqthing_id\*(Aq, \*(Aqthing_name\*(Aq, \*(Aqthing_color\*(Aq ] }
\&  sub sort_order { [\*(Aqthing_id\*(Aq] }
\&
\&  package main;
\&  class MyNamespace::Thing {
\&      id_by => \*(Aqthing_id\*(Aq,
\&      has => [ \*(Aqthing_id\*(Aq, \*(Aqthing_name\*(Aq, \*(Aqthing_color\*(Aq ],
\&      data_source => \*(AqMyNamespace::DataSource::MyFile\*(Aq,
\&  }
\&  my @objs = MyNamespace::Thing\->get(thing_name => \*(AqBob\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Classes which wish to retrieve their data from a regular file can use a UR::DataSource::File\-based
data source.  The modules implementing these data sources live under the DataSource subdirectory
of the application's Namespace, by convention.  Besides defining a class for your data source
inheriting from UR::DataSource::File, it should have the following methods, either as properties
or functions in the package.
.SS "Configuration"
.IX Subsection "Configuration"
These methods determine the configuration for your data source.
.IP "\fBserver()\fR" 4
.IX Item "server()"
\&\fBserver()\fR should return a string representing the pathname of the file where the data is stored.
.IP "\fBfile_list()\fR" 4
.IX Item "file_list()"
The \fBfile_list()\fR method should return a listref of pathnames to one or more identical files
where data is stored.   Use \fBfile_list()\fR instead of \fBserver()\fR when you want to load-balance several \s-1NFS\s0
servers, for example.
.Sp
You must have either \fBserver()\fR or \fBfile_list()\fR in your module, but not both.  The existence of \fBserver()\fR
takes precedence over \fBfile_list()\fR.
.IP "\fBdelimiter()\fR" 4
.IX Item "delimiter()"
\&\fBdelimiter()\fR should return a string representing how the fields in each record are split into
columns.  This string is interpreted as a regex internally.  The default delimiter is \*(L"\es*,\es*\*(R"
meaning that the file is separated by commas.
.IP "\fBrecord_separator()\fR" 4
.IX Item "record_separator()"
\&\fBrecord_separator()\fR should return a string that gets stored in $/ before \fBgetline()\fR is called on the
file's filehandle.  The default \fBrecord_separator()\fR is \*(L"\en\*(R" meaning that the file's records are 
separated by newlines.
.IP "\fBskip_first_line()\fR" 4
.IX Item "skip_first_line()"
\&\fBskip_first_line()\fR should return a boolean value.  If true, the first line of the file is ignored, for
example if the first line defines the columns in the file.
.IP "\fBcolumn_order()\fR" 4
.IX Item "column_order()"
\&\fBcolumn_order()\fR should return a listref of column names in the file.  column_order is required; there
is no default.
.IP "\fBsort_order()\fR" 4
.IX Item "sort_order()"
If the data file is sorted in some way, \fBsort_order()\fR should return a listref of column names (which must
exist in \fBcolumn_order()\fR) by which the file is sorted.  This gives the system a hint about how the file
is structured, and is able to make shortcuts when reading the file to speed up data access.  The default
is to assume the file is not sorted.
.SH "INHERITANCE"
.IX Header "INHERITANCE"
.Vb 1
\&  UR::DataSource
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1UR,\s0 UR::DataSource