.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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
.\" ========================================================================
.\"
.IX Title "Rose::DB::Registry 3pm"
.TH Rose::DB::Registry 3pm "2023-03-04" "perl v5.36.0" "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"
Rose::DB::Registry \- Data source registry.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Rose::DB::Registry;
\&
\&  $registry = Rose::DB::Registry\->new;
\&
\&  $registry\->add_entry(
\&    domain   => \*(Aqdevelopment\*(Aq,
\&    type     => \*(Aqmain\*(Aq,
\&    driver   => \*(AqPg\*(Aq,
\&    database => \*(Aqdev_db\*(Aq,
\&    host     => \*(Aqlocalhost\*(Aq,
\&    username => \*(Aqdevuser\*(Aq,
\&    password => \*(Aqmysecret\*(Aq,
\&    server_time_zone => \*(AqUTC\*(Aq);
\&
\&  $entry = Rose::DB::Registry::Entry\->new(
\&    domain   => \*(Aqproduction\*(Aq,
\&    type     => \*(Aqmain\*(Aq,
\&    driver   => \*(AqPg\*(Aq,
\&    database => \*(Aqbig_db\*(Aq,
\&    host     => \*(Aqdbserver.acme.com\*(Aq,
\&    username => \*(Aqdbadmin\*(Aq,
\&    password => \*(Aqprodsecret\*(Aq,
\&    server_time_zone => \*(AqUTC\*(Aq);
\&
\&  $registry\->add_entry($entry);
\&
\&  $entry = $registry\->entry(domain => \*(Aqdevelopment\*(Aq, type => \*(Aqmain\*(Aq);
\&
\&  $registry\->entry_exists(domain => \*(Aqfoo\*(Aq, type => \*(Aqbar\*(Aq); # false
\&
\&  $registry\->delete_entry(domain => \*(Aqdevelopment\*(Aq, type => \*(Aqmain\*(Aq);
\&
\&  ...
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Rose::DB::Registry objects manage information about Rose::DB data sources.  Each data source has a corresponding Rose::DB::Registry::Entry object that contains its information.  The registry entries are organized in a two-level namespace based on a \*(L"domain\*(R" and a \*(L"type.\*(R"  See the Rose::DB documentation for more information on data source domains and types.
.PP
Rose::DB::Registry inherits from, and follows the conventions of, Rose::Object.  See the Rose::Object documentation for more information.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.IP "\fBnew \s-1PARAMS\s0\fR" 4
.IX Item "new PARAMS"
Constructs a Rose::DB::Registry object based on \s-1PARAMS,\s0 where \s-1PARAMS\s0 are
name/value pairs.  Any object method is a valid parameter name.
.SH "OBJECT METHODS"
.IX Header "OBJECT METHODS"
.IP "\fBadd_entries \s-1ENTRY1\s0 [, \s-1ENTRY2, ...\s0]\fR" 4
.IX Item "add_entries ENTRY1 [, ENTRY2, ...]"
Add registry entries.  Each \s-1ENTRY\s0 must be either a Rose::DB::Registry::Entry\-derived object or  reference to a hash of name/value pairs.  The name/value pairs must be valid arguments for Rose::DB::Registry::Entry's constructor.
.Sp
Each \s-1ENTRY\s0 must have a defined domain and type, either in the Rose::DB::Registry::Entry\-derived object or in the name/value pairs.  A fatal error will occur if these values are not defined.
.Sp
If a registry entry for the specified domain and type already exists, then the new entry will overwrite it.  If you want to know beforehand whether or not an entry exists under a specific domain and type, use the entry_exists method.
.Sp
Returns a list (in list context) or reference to an array (in scalar context) of Rose::DB::Registry::Entry objects added.
.IP "\fBadd_entry \s-1ENTRY\s0\fR" 4
.IX Item "add_entry ENTRY"
Add a registry entry.  \s-1ENTRY\s0 must be either a Rose::DB::Registry::Entry\-derived object or a list of name/value pairs.  The name/value pairs must be valid arguments for Rose::DB::Registry::Entry's constructor.
.Sp
The \s-1ENTRY\s0 must have a defined domain and type, either in the Rose::DB::Registry::Entry\-derived object or in the name/value pairs.  A fatal error will occur if these values are not defined.
.Sp
If a registry entry for the specified domain and type already exists, then the new entry will overwrite it.  If you want to know beforehand whether or not an entry exists under a specific domain and type, use the entry_exists method.
.Sp
Returns the Rose::DB::Registry::Entry object added.
.IP "\fBdump\fR" 4
.IX Item "dump"
Returns a reference to a hash containing information about all registered data sources.  The hash is structured like this:
.Sp
.Vb 12
\&    {
\&      domain1 =>
\&      {
\&        type1 =>
\&        {
\&          # Rose::DB::Registry::Entry attributes
\&          # generated by its dump() method
\&          driver   => ...,
\&          database => ...,
\&          host     => ...,
\&          ...
\&        },
\&
\&        type2 =>
\&        {
\&          ...
\&        },
\&        ...
\&      },
\&
\&      domain2 =>
\&      {
\&        ...
\&      },
\&
\&      ...
\&    }
.Ve
.Sp
All the registry entry attribute values are copies, not the actual values.
.IP "\fBdelete_domain \s-1DOMAIN\s0\fR" 4
.IX Item "delete_domain DOMAIN"
Delete an entire domain, including all the registry entries under that domain.
.IP "\fBdelete_entry \s-1PARAMS\s0\fR" 4
.IX Item "delete_entry PARAMS"
Delete the registry entry specified by \s-1PARAMS,\s0 where \s-1PARAMS\s0 must be name/value pairs with defined values for \f(CW\*(C`domain\*(C'\fR and \f(CW\*(C`type\*(C'\fR.  A fatal error will occur if either one is missing or undefined.
.Sp
If the specified entry does not exist, undef is returned.  Otherwise, the deleted entry is returned.
.IP "\fBentry \s-1PARAMS\s0\fR" 4
.IX Item "entry PARAMS"
Get the registry entry specified by \s-1PARAMS,\s0 where \s-1PARAMS\s0 must be name/value pairs with defined values for \f(CW\*(C`domain\*(C'\fR and \f(CW\*(C`type\*(C'\fR.  A fatal error will occur if either one is missing or undefined.  If the specified entry does not exist, undef is returned.
.IP "\fBentry_exists \s-1PARAMS\s0\fR" 4
.IX Item "entry_exists PARAMS"
Returns true if the registry entry specified by \s-1PARAMS\s0 exists, false otherwise.  \s-1PARAMS\s0 must be name/value pairs with defined values for \f(CW\*(C`domain\*(C'\fR and \f(CW\*(C`type\*(C'\fR.  A fatal error will occur if either one is missing or undefined.
.IP "\fBregistered_types \s-1DOMAIN\s0\fR" 4
.IX Item "registered_types DOMAIN"
Returns a list (in list context) or reference to an array (in scalar context) of the names of all registered types under the domain named \s-1DOMAIN.\s0
.IP "\fBregistered_domains\fR" 4
.IX Item "registered_domains"
Returns a list (in list context) or reference to an array (in scalar context) of the names of all registered domains.
.SH "AUTHOR"
.IX Header "AUTHOR"
John C. Siracusa (siracusa@gmail.com)
.SH "LICENSE"
.IX Header "LICENSE"
Copyright (c) 2010 by John C. Siracusa.  All rights reserved.  This program is
free software; you can redistribute it and/or modify it under the same terms
as Perl itself.