[catagits/Gitalist.git] / local-lib5 / man / man3 / XML::Atom::Entry.3pm

.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
.\"
.\" 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 "XML::Atom::Entry 3"
.TH XML::Atom::Entry 3 "2009-04-24" "perl v5.8.7" "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"
XML::Atom::Entry \- Atom entry
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 7
\&    use XML::Atom::Entry;
\&    my $entry = XML::Atom::Entry\->new;
\&    $entry\->title(\*(AqMy Post\*(Aq);
\&    $entry\->content(\*(AqThe content of my post.\*(Aq);
\&    my $xml = $entry\->as_xml;
\&    my $dc = XML::Atom::Namespace\->new(dc => \*(Aqhttp://purl.org/dc/elements/1.1/\*(Aq);
\&    $entry\->set($dc, \*(Aqsubject\*(Aq, \*(AqFood & Drink\*(Aq);
.Ve
.SH "USAGE"
.IX Header "USAGE"
.ie n .SS "XML::Atom::Entry\->new([ $stream ])"
.el .SS "XML::Atom::Entry\->new([ \f(CW$stream\fP ])"
.IX Subsection "XML::Atom::Entry->new([ $stream ])"
Creates a new entry object, and if \fI\f(CI$stream\fI\fR is supplied, fills it with the
data specified by \fI\f(CI$stream\fI\fR.
.PP
Automatically handles autodiscovery if \fI\f(CI$stream\fI\fR is a \s-1URI\s0 (see below).
.PP
Returns the new \fIXML::Atom::Entry\fR object. On failure, returns \f(CW\*(C`undef\*(C'\fR.
.PP
\&\fI\f(CI$stream\fI\fR can be any one of the following:
.IP "\(bu" 4
Reference to a scalar
.Sp
This is treated as the \s-1XML\s0 body of the entry.
.IP "\(bu" 4
Scalar
.Sp
This is treated as the name of a file containing the entry \s-1XML\s0.
.IP "\(bu" 4
Filehandle
.Sp
This is treated as an open filehandle from which the entry \s-1XML\s0 can be read.
.ie n .SS "$entry\->content([ $content ])"
.el .SS "\f(CW$entry\fP\->content([ \f(CW$content\fP ])"
.IX Subsection "$entry->content([ $content ])"
Returns the content of the entry. If \fI\f(CI$content\fI\fR is given, sets the content
of the entry. Automatically handles all necessary escaping.
.ie n .SS "$entry\->author([ $author ])"
.el .SS "\f(CW$entry\fP\->author([ \f(CW$author\fP ])"
.IX Subsection "$entry->author([ $author ])"
Returns an \fIXML::Atom::Person\fR object representing the author of the entry,
or \f(CW\*(C`undef\*(C'\fR if there is no author information present.
.PP
If \fI\f(CI$author\fI\fR is supplied, it should be an \fIXML::Atom::Person\fR object
representing the author. For example:
.PP
.Vb 4
\&    my $author = XML::Atom::Person\->new;
\&    $author\->name(\*(AqFoo Bar\*(Aq);
\&    $author\->email(\*(Aqfoo@bar.com\*(Aq);
\&    $entry\->author($author);
.Ve
.ie n .SS "$entry\->link"
.el .SS "\f(CW$entry\fP\->link"
.IX Subsection "$entry->link"
If called in scalar context, returns an \fIXML::Atom::Link\fR object
corresponding to the first \fI<link>\fR tag found in the entry.
.PP
If called in list context, returns a list of \fIXML::Atom::Link\fR objects
corresponding to all of the \fI<link>\fR tags found in the entry.
.ie n .SS "$entry\->add_link($link)"
.el .SS "\f(CW$entry\fP\->add_link($link)"
.IX Subsection "$entry->add_link($link)"
Adds the link \fI\f(CI$link\fI\fR, which must be an \fIXML::Atom::Link\fR object, to
the entry as a new \fI<link>\fR tag. For example:
.PP
.Vb 5
\&    my $link = XML::Atom::Link\->new;
\&    $link\->type(\*(Aqtext/html\*(Aq);
\&    $link\->rel(\*(Aqalternate\*(Aq);
\&    $link\->href(\*(Aqhttp://www.example.com/2003/12/post.html\*(Aq);
\&    $entry\->add_link($link);
.Ve
.ie n .SS "$entry\->get($ns, $element)"
.el .SS "\f(CW$entry\fP\->get($ns, \f(CW$element\fP)"
.IX Subsection "$entry->get($ns, $element)"
Given an \fIXML::Atom::Namespace\fR element \fI\f(CI$ns\fI\fR and an element name
\&\fI\f(CI$element\fI\fR, retrieves the value for the element in that namespace.
.PP
This is useful for retrieving the value of elements not in the main Atom
namespace, like categories. For example:
.PP
.Vb 2
\&    my $dc = XML::Atom::Namespace\->new(dc => \*(Aqhttp://purl.org/dc/elements/1.1/\*(Aq);
\&    my $subj = $entry\->get($dc, \*(Aqsubject\*(Aq);
.Ve
.ie n .SS "$entry\->getlist($ns, $element)"
.el .SS "\f(CW$entry\fP\->getlist($ns, \f(CW$element\fP)"
.IX Subsection "$entry->getlist($ns, $element)"
Just like \fI\f(CI$entry\fI\->get\fR, but if there are multiple instances of the
element \fI\f(CI$element\fI\fR in the namespace \fI\f(CI$ns\fI\fR, returns all of them. \fIget\fR
will return only the first.
.SH "AUTHOR & COPYRIGHT"
.IX Header "AUTHOR & COPYRIGHT"
Please see the \fIXML::Atom\fR manpage for author, copyright, and license
information.
Commit	Line	Data
3fea05b9	1	.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
	2	.\"
	3	.\" Standard preamble:
	4	.\" ========================================================================
	5	.de Sp \" Vertical space (when we can't use .PP)
	6	.if t .sp .5v
	7	.if n .sp
	8	..
	9	.de Vb \" Begin verbatim text
	10	.ft CW
	11	.nf
	12	.ne \\$1
	13	..
	14	.de Ve \" End verbatim text
	15	.ft R
	16	.fi
	17	..
	18	.\" Set up some character translations and predefined strings. \*(-- will
	19	.\" give an unbreakable dash, \(PI will give pi, \(L" will give a left
	20	.\" double quote, and \(R" will give a right double quote. \(C+ will
	21	.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
	22	.\" therefore won't be available. \(C` and \(C' expand to `' in nroff,
	23	.\" nothing in troff, for use with C<>.
	24	.tr \(*W-
	25	.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
	26	.ie n \{\
	27	. ds -- \(*W-
	28	. ds PI pi
	29	. if (\n(.H=4u)&(1m=24u) .ds -- \(W\h'-12u'\(W\h'-12u'-\" diablo 10 pitch
	30	. if (\n(.H=4u)&(1m=20u) .ds -- \(W\h'-12u'\(W\h'-8u'-\" diablo 12 pitch
	31	. ds L" ""
	32	. ds R" ""
	33	. ds C` ""
	34	. ds C' ""
	35	'br\}
	36	.el\{\
	37	. ds -- \\|\(em\\|
	38	. ds PI \(*p
	39	. ds L" ``
	40	. ds R" ''
	41	'br\}
	42	.\"
	43	.\" Escape single quotes in literal strings from groff's Unicode transform.
	44	.ie \n(.g .ds Aq \(aq
	45	.el .ds Aq '
	46	.\"
	47	.\" If the F register is turned on, we'll generate index entries on stderr for
	48	.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
	49	.\" entries marked with X<> in POD. Of course, you'll have to process the
	50	.\" output yourself in some meaningful fashion.
	51	.ie \nF \{\
	52	. de IX
	53	. tm Index:\\$1\t\\n%\t"\\$2"
	54	..
	55	. nr % 0
	56	. rr F
	57	.\}
	58	.el \{\
	59	. de IX
	60	..
	61	.\}
	62	.\"
	63	.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
	64	.\" Fear. Run. Save yourself. No user-serviceable parts.
65	. \" fudge factors for nroff and troff
66	.if n \{\
67	. ds #H 0
68	. ds #V .8m
69	. ds #F .3m
70	. ds #[ \f1
71	. ds #] \fP
72	.\}
73	.if t \{\
74	. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75	. ds #V .6m
76	. ds #F 0
77	. ds #[ \&
78	. ds #] \&
79	.\}
80	. \" simple accents for nroff and troff
81	.if n \{\
82	. ds ' \&
83	. ds ` \&
84	. ds ^ \&
85	. ds , \&
86	. ds ~ ~
87	. ds /
88	.\}
89	.if t \{\
90	. ds ' \\k:\h'-(\\n(.wu8/10-\(#H)'\'\h"\|\\n:u"
91	. ds ` \\k:\h'-(\\n(.wu8/10-\(#H)'\`\h'\|\\n:u'
92	. ds ^ \\k:\h'-(\\n(.wu10/11-\(#H)'^\h'\|\\n:u'
93	. ds , \\k:\h'-(\\n(.wu*8/10)',\h'\|\\n:u'
94	. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'\|\\n:u'
95	. ds / \\k:\h'-(\\n(.wu8/10-\(#H)'\z\(sl\h'\|\\n:u'
96	.\}
97	. \" troff and (daisy-wheel) nroff accents
98	.ds : \\k:\h'-(\\n(.wu8/10-\(#H+.1m+\(#F)'\v'-\(#V'\z.\h'.2m+\(#F'.\h'\|\\n:u'\v'\(#V'
99	.ds 8 \h'\(#H'\(b\h'-\*(#H'
100	.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\(#H)/2u'\v'-.3n'\(#[\z\(de\v'.3n'\h'\|\\n:u'\*(#]
101	.ds d- \h'\(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\(#H'
102	.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'\|\\n:u'
103	.ds th \(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u2/3)'\s-1o\s+1\*(#]
104	.ds Th \(#[\s+2I\s-2\h'-\w'I'u3/5'\v'-.3m'o\v'.3m'\*(#]
105	.ds ae a\h'-(\w'a'u*4/10)'e
106	.ds Ae A\h'-(\w'A'u*4/10)'E
107	. \" corrections for vroff
108	.if v .ds ~ \\k:\h'-(\\n(.wu9/10-\(#H)'\s-2\u~\d\s+2\h'\|\\n:u'
109	.if v .ds ^ \\k:\h'-(\\n(.wu10/11-\(#H)'\v'-.4m'^\v'.4m'\h'\|\\n:u'
110	. \" for low resolution devices (crt and lpr)
111	.if \n(.H>23 .if \n(.V>19 \
112	\{\
113	. ds : e
114	. ds 8 ss
115	. ds o a
116	. ds d- d\h'-1'\(ga
117	. ds D- D\h'-1'\(hy
118	. ds th \o'bp'
119	. ds Th \o'LP'
120	. ds ae ae
121	. ds Ae AE
122	.\}
123	.rm #[ #] #H #V #F C
124	.\" ========================================================================
125	.\"
126	.IX Title "XML::Atom::Entry 3"
127	.TH XML::Atom::Entry 3 "2009-04-24" "perl v5.8.7" "User Contributed Perl Documentation"
128	.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129	.\" way too many mistakes in technical documents.
130	.if n .ad l
131	.nh
132	.SH "NAME"
133	XML::Atom::Entry \- Atom entry
134	.SH "SYNOPSIS"
135	.IX Header "SYNOPSIS"
136	.Vb 7
137	\& use XML::Atom::Entry;
138	\& my $entry = XML::Atom::Entry\->new;
139	\& $entry\->title(\(AqMy Post\(Aq);
140	\& $entry\->content(\(AqThe content of my post.\(Aq);
141	\& my $xml = $entry\->as_xml;
142	\& my $dc = XML::Atom::Namespace\->new(dc => \(Aqhttp://purl.org/dc/elements/1.1/\(Aq);
143	\& $entry\->set($dc, \(Aqsubject\(Aq, \(AqFood & Drink\(Aq);
144	.Ve
145	.SH "USAGE"
146	.IX Header "USAGE"
147	.ie n .SS "XML::Atom::Entry\->new([ $stream ])"
148	.el .SS "XML::Atom::Entry\->new([ \f(CW$stream\fP ])"
149	.IX Subsection "XML::Atom::Entry->new([ $stream ])"
150	Creates a new entry object, and if \fI\f(CI$stream\fI\fR is supplied, fills it with the
151	data specified by \fI\f(CI$stream\fI\fR.
152	.PP
153	Automatically handles autodiscovery if \fI\f(CI$stream\fI\fR is a \s-1URI\s0 (see below).
154	.PP
155	Returns the new \fIXML::Atom::Entry\fR object. On failure, returns \f(CW\(C`undef\(C'\fR.
156	.PP
157	\&\fI\f(CI$stream\fI\fR can be any one of the following:
158	.IP "\(bu" 4
159	Reference to a scalar
160	.Sp
161	This is treated as the \s-1XML\s0 body of the entry.
162	.IP "\(bu" 4
163	Scalar
164	.Sp
165	This is treated as the name of a file containing the entry \s-1XML\s0.
166	.IP "\(bu" 4
167	Filehandle
168	.Sp
169	This is treated as an open filehandle from which the entry \s-1XML\s0 can be read.
170	.ie n .SS "$entry\->content([ $content ])"
171	.el .SS "\f(CW$entry\fP\->content([ \f(CW$content\fP ])"
172	.IX Subsection "$entry->content([ $content ])"
173	Returns the content of the entry. If \fI\f(CI$content\fI\fR is given, sets the content
174	of the entry. Automatically handles all necessary escaping.
175	.ie n .SS "$entry\->author([ $author ])"
176	.el .SS "\f(CW$entry\fP\->author([ \f(CW$author\fP ])"
177	.IX Subsection "$entry->author([ $author ])"
178	Returns an \fIXML::Atom::Person\fR object representing the author of the entry,
179	or \f(CW\(C`undef\(C'\fR if there is no author information present.
180	.PP
181	If \fI\f(CI$author\fI\fR is supplied, it should be an \fIXML::Atom::Person\fR object
182	representing the author. For example:
183	.PP
184	.Vb 4
185	\& my $author = XML::Atom::Person\->new;
186	\& $author\->name(\(AqFoo Bar\(Aq);
187	\& $author\->email(\(Aqfoo@bar.com\(Aq);
188	\& $entry\->author($author);
189	.Ve
190	.ie n .SS "$entry\->link"
191	.el .SS "\f(CW$entry\fP\->link"
192	.IX Subsection "$entry->link"
193	If called in scalar context, returns an \fIXML::Atom::Link\fR object
194	corresponding to the first \fI<link>\fR tag found in the entry.
195	.PP
196	If called in list context, returns a list of \fIXML::Atom::Link\fR objects
197	corresponding to all of the \fI<link>\fR tags found in the entry.
198	.ie n .SS "$entry\->add_link($link)"
199	.el .SS "\f(CW$entry\fP\->add_link($link)"
200	.IX Subsection "$entry->add_link($link)"
201	Adds the link \fI\f(CI$link\fI\fR, which must be an \fIXML::Atom::Link\fR object, to
202	the entry as a new \fI<link>\fR tag. For example:
203	.PP
204	.Vb 5
205	\& my $link = XML::Atom::Link\->new;
206	\& $link\->type(\(Aqtext/html\(Aq);
207	\& $link\->rel(\(Aqalternate\(Aq);
208	\& $link\->href(\(Aqhttp://www.example.com/2003/12/post.html\(Aq);
209	\& $entry\->add_link($link);
210	.Ve
211	.ie n .SS "$entry\->get($ns, $element)"
212	.el .SS "\f(CW$entry\fP\->get($ns, \f(CW$element\fP)"
213	.IX Subsection "$entry->get($ns, $element)"
214	Given an \fIXML::Atom::Namespace\fR element \fI\f(CI$ns\fI\fR and an element name
215	\&\fI\f(CI$element\fI\fR, retrieves the value for the element in that namespace.
216	.PP
217	This is useful for retrieving the value of elements not in the main Atom
218	namespace, like categories. For example:
219	.PP
220	.Vb 2
221	\& my $dc = XML::Atom::Namespace\->new(dc => \(Aqhttp://purl.org/dc/elements/1.1/\(Aq);
222	\& my $subj = $entry\->get($dc, \(Aqsubject\(Aq);
223	.Ve
224	.ie n .SS "$entry\->getlist($ns, $element)"
225	.el .SS "\f(CW$entry\fP\->getlist($ns, \f(CW$element\fP)"
226	.IX Subsection "$entry->getlist($ns, $element)"
227	Just like \fI\f(CI$entry\fI\->get\fR, but if there are multiple instances of the
228	element \fI\f(CI$element\fI\fR in the namespace \fI\f(CI$ns\fI\fR, returns all of them. \fIget\fR
229	will return only the first.
230	.SH "AUTHOR & COPYRIGHT"
231	.IX Header "AUTHOR & COPYRIGHT"
232	Please see the \fIXML::Atom\fR manpage for author, copyright, and license
233	information.