genders/package/usr/share/man/man3/Genders.3pm

.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" 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 "Genders 3"
.TH Genders 3 "2013-08-02" "perl v5.10.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"
Genders \- Perl library for querying a genders file
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Genders;
\&
\& $Genders::GENDERS_DEFAULT_FILE;
\&
\& $obj = Genders\->new([$filename])
\&
\& $obj\->debug($num)
\&
\& $obj\->getnodename()
\& $obj\->getnodes([$attr, [$val]])
\& $obj\->getattr([$node])
\& $obj\->getattr_all()
\& $obj\->getattrval($attr, [$node])
\&
\& $obj\->testattr($attr, [$node])
\& $obj\->testattrval($attr, $val, [$node])
\&
\& $obj\->isnode([$node])
\& $obj\->isattr($attr)
\& $obj\->isattrval($attr, $val)
\&
\& $obj\->index_attrvals($attr)
\&
\& $obj\->query($query)
\& $obj\->testquery($query, [$node])
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This package provides a perl interface for querying a genders file.
.IP "\fBGenders\->new([$filename])\fR" 4
.IX Item "Genders->new([$filename])"
Creates a Genders object and load genders data from the specified
file.  If the genders file is not specified, the default genders file
will be used.  Returns undef if file cannot be read.
.ie n .IP "\fB\fB$obj\fB\->debug($num)\fR" 4
.el .IP "\fB\f(CB$obj\fB\->debug($num)\fR" 4
.IX Item "$obj->debug($num)"
Set the debug level in the genders object.  By default, the debug
level is 0 and all debugging is turned off.  To turn it on, set the
level to 1.
.ie n .IP "\fB\fB$obj\fB\->\f(BIgetnodename()\fB\fR" 4
.el .IP "\fB\f(CB$obj\fB\->\f(BIgetnodename()\fB\fR" 4
.IX Item "$obj->getnodename()"
Returns the name of the current node.
.ie n .IP "\fB\fB$obj\fB\->getnodes([$attr, [$val]])\fR" 4
.el .IP "\fB\f(CB$obj\fB\->getnodes([$attr, [$val]])\fR" 4
.IX Item "$obj->getnodes([$attr, [$val]])"
Returns a list of nodes with the specified attribute and value.  If a
value is not specified only the attribute is considered.  If the
attribute is not specified, all nodes listed in the genders file are
returned.
.ie n .IP "\fB\fB$obj\fB\->getattr([$node])\fR" 4
.el .IP "\fB\f(CB$obj\fB\->getattr([$node])\fR" 4
.IX Item "$obj->getattr([$node])"
Returns a list of attributes for the specified node.  If the node
is not specified, the local node's attributes returned.
.ie n .IP "\fB\fB$obj\fB\->\f(BIgetattr_all()\fB\fR" 4
.el .IP "\fB\f(CB$obj\fB\->\f(BIgetattr_all()\fB\fR" 4
.IX Item "$obj->getattr_all()"
Returns a list of all attributes listed in the genders file.
.ie n .IP "\fB\fB$obj\fB\->getattrval($attr, [$node])\fR" 4
.el .IP "\fB\f(CB$obj\fB\->getattrval($attr, [$node])\fR" 4
.IX Item "$obj->getattrval($attr, [$node])"
Returns the value of the specified attribute for the specified node.
If the attribute does not exist or the attribute has no value, an
empty string is returned.  If the node is not specified, the local
node's attribute value is returned.
.ie n .IP "\fB\fB$obj\fB\->testattr($attr, [$node])\fR" 4
.el .IP "\fB\f(CB$obj\fB\->testattr($attr, [$node])\fR" 4
.IX Item "$obj->testattr($attr, [$node])"
Returns 1 if the specified node has the specified attribute, 0 if it
does not.  If the node is not specified, the local node is checked.
.ie n .IP "\fB\fB$obj\fB\->testattrval($attr, \f(BI$val\fB, [$node])\fR" 4
.el .IP "\fB\f(CB$obj\fB\->testattrval($attr, \f(CB$val\fB, [$node])\fR" 4
.IX Item "$obj->testattrval($attr, $val, [$node])"
Returns 1 if the specified node has the specified attribute and value,
0 if it does not.  If the node is not specified, the local node is
checked.
.ie n .IP "\fB\fB$obj\fB\->isnode([$node])\fR" 4
.el .IP "\fB\f(CB$obj\fB\->isnode([$node])\fR" 4
.IX Item "$obj->isnode([$node])"
Returns 1 if the specified node is listed in the genders file, 0 if it
is not.  If the node is not specified, the local node is checked.
.ie n .IP "\fB\fB$obj\fB\->isattr($attr)\fR" 4
.el .IP "\fB\f(CB$obj\fB\->isattr($attr)\fR" 4
.IX Item "$obj->isattr($attr)"
Returns 1 if the specified attribute is listed in the genders file, 0
if it is not.
.ie n .IP "\fB\fB$obj\fB\->isattrval($attr, \f(BI$val\fB)\fR" 4
.el .IP "\fB\f(CB$obj\fB\->isattrval($attr, \f(CB$val\fB)\fR" 4
.IX Item "$obj->isattrval($attr, $val)"
Returns 1 if the specified attribute is equal to the specified value
for some node in the genders file, 0 if it is not.
.ie n .IP "\fB\fB$obj\fB\->index_attrvals($attr)\fR" 4
.el .IP "\fB\f(CB$obj\fB\->index_attrvals($attr)\fR" 4
.IX Item "$obj->index_attrvals($attr)"
Internally indexes genders attribute values for faster search times.
Subsequent calls with a different attribute will overwrite earlier
indexes.
.ie n .IP "\fB\fB$obj\fB\->query($query)\fR" 4
.el .IP "\fB\f(CB$obj\fB\->query($query)\fR" 4
.IX Item "$obj->query($query)"
Returns a list of nodes specified by a genders query.  A genders query
is based on the union, intersection, set difference, or complement
between genders attributes and values.  Union is represented by two
pipe symbols ('||'), intersection by two ampersand symbols ('&&'),
difference by two minus symbols ('\-\-'), and complement by a tilde
('~') Operations are performed from left to right.  Parentheses may be
used to change the order of operations.  For example, the following
query would retrieve all nodes other than management or login nodes:
\&\*(L"~(mgmt||login)\*(R".  If the query is not specified, all nodes listed
in the genders file are returned.
.ie n .IP "\fB\fB$obj\fB\->testquery($query, [$node])\fR" 4
.el .IP "\fB\f(CB$obj\fB\->testquery($query, [$node])\fR" 4
.IX Item "$obj->testquery($query, [$node])"
Returns 1 if the specified node meets the conditions of the specified
query, 0 if it does not.  If the node is not specified, the local node
is checked.
.SH "AUTHOR"
.IX Header "AUTHOR"
Albert Chu <chu11@llnl.gov>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Libgenders.
.PP
libgenders.