local-lib5/man/man3/YAML::Node.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "YAML::Node 3"
 132 .TH YAML::Node 3 "2009-08-10" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 YAML::Node \- A generic data node that encapsulates YAML information
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 2
 138 \&    use YAML;
 139 \&    use YAML::Node;
 140 .Ve
 141 .PP
 142 .Vb 3
 143 \&    my $ynode = YAML::Node\->new({}, 'ingerson.com/fruit');
 144 \&    %$ynode = qw(orange orange apple red grape green);
 145 \&    print Dump $ynode;
 146 .Ve
 147 .PP
 148 yields:
 149 .PP
 150 .Vb 4
 151 \&    \-\-\- !ingerson.com/fruit
 152 \&    orange: orange
 153 \&    apple: red
 154 \&    grape: green
 155 .Ve
 156 .SH "DESCRIPTION"
 157 .IX Header "DESCRIPTION"
 158 A generic node in \s-1YAML\s0 is similar to a plain hash, array, or scalar node
 159 in Perl except that it must also keep track of its type. The type is a
 160 \&\s-1URI\s0 called the \s-1YAML\s0 type tag.
 161 .PP
 162 YAML::Node is a class for generating and manipulating these containers.
 163 A \s-1YAML\s0 node (or ynode) is a tied hash, array or scalar. In most ways it
 164 behaves just like the plain thing. But you can assign and retrieve and
 165 \&\s-1YAML\s0 type tag \s-1URI\s0 to it. For the hash flavor, you can also assign the
 166 order that the keys will be retrieved in. By default a ynode will offer
 167 its keys in the same order that they were assigned.
 168 .PP
 169 YAML::Node has a class method call \fInew()\fR that will return a ynode. You
 170 pass it a regular node and an optional type tag. After that you can
 171 use it like a normal Perl node, but when you YAML::Dump it, the magical
 172 properties will be honored.
 173 .PP
 174 This is how you can control the sort order of hash keys during a \s-1YAML\s0
 175 serialization. By default, \s-1YAML\s0 sorts keys alphabetically. But notice
 176 in the above example that the keys were Dumped in the same order they
 177 were assigned.
 178 .PP
 179 YAML::Node exports a function called \fIynode()\fR. This function returns the tied object so that you can call special methods on it like \->\fIkeys()\fR.
 180 .PP
 181 \&\fIkeys()\fR works like this:
 182 .PP
 183 .Vb 2
 184 \&    use YAML;
 185 \&    use YAML::Node;
 186 .Ve
 187 .PP
 188 .Vb 4
 189 \&    %$node = qw(orange orange apple red grape green);
 190 \&    $ynode = YAML::Node\->new($node);
 191 \&    ynode($ynode)\->keys(['grape', 'apple']);
 192 \&    print Dump $ynode;
 193 .Ve
 194 .PP
 195 produces:
 196 .PP
 197 .Vb 3
 198 \&    \-\-\-
 199 \&    grape: green
 200 \&    apple: red
 201 .Ve
 202 .PP
 203 It tells the ynode which keys and what order to use.
 204 .PP
 205 ynodes will play a very important role in how programs use \s-1YAML\s0. They
 206 are the foundation of how a Perl class can marshall the Loading and
 207 Dumping of its objects.
 208 .PP
 209 The upcoming versions of \s-1YAML\s0.pm will have much more information on this.
 210 .SH "AUTHOR"
 211 .IX Header "AUTHOR"
 212 Ingy döt Net <ingy@cpan.org>
 213 .SH "COPYRIGHT"
 214 .IX Header "COPYRIGHT"
 215 Copyright (c) 2006. Ingy döt Net. All rights reserved.
 216 .PP
 217 Copyright (c) 2002. Brian Ingerson. All rights reserved.
 218 .PP
 219 This program is free software; you can redistribute it and/or modify it
 220 under the same terms as Perl itself.
 221 .PP
 222 See <http://www.perl.com/perl/misc/Artistic.html>