local-lib5/man/man3/XML::LibXML::Text.3pm

   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(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/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(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/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'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/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(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/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::LibXML::Text 3"
 127 .TH XML::LibXML::Text 3 "2009-10-07" "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::LibXML::Text \- XML::LibXML Class for Text Nodes
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 3
 137 \&  use XML::LibXML;
 138 \&  # Only methods specific to Text nodes are listed here,
 139 \&  # see XML::LibXML::Node manpage for other methods
 140 \&
 141 \&  $text = XML::LibXML::Text\->new( $content );
 142 \&  $nodedata = $text\->data;
 143 \&  $text\->setData( $text_content );
 144 \&  $text\->substringData($offset, $length);
 145 \&  $text\->appendData( $somedata );
 146 \&  $text\->insertData($offset, $string);
 147 \&  $text\->deleteData($offset, $length);
 148 \&  $text\->deleteDataString($remstring, $all);
 149 \&  $text\->replaceData($offset, $length, $string);
 150 \&  $text\->replaceDataString($old, $new, $flag);
 151 \&  $text\->replaceDataRegEx( $search_cond, $replace_cond, $reflags );
 152 .Ve
 153 .SH "DESCRIPTION"
 154 .IX Header "DESCRIPTION"
 155 Unlike the \s-1DOM\s0 specification, XML::LibXML implements the text node as the base
 156 class of all character data node. Therefor there exists no CharacterData class.
 157 This allows one to apply methods of text nodes also to Comments and
 158 CDATA-sections.
 159 .SH "METHODS"
 160 .IX Header "METHODS"
 161 The class inherits from XML::LibXML::Node. The documentation for Inherited methods is not listed here.
 162 .PP
 163 Many functions listed here are extensively documented in the \s-1DOM\s0 Level 3 specification (<http://www.w3.org/TR/DOM\-Level\-3\-Core/>). Please refer to the specification for extensive documentation.
 164 .IP "new" 4
 165 .IX Item "new"
 166 .Vb 1
 167 \&  $text = XML::LibXML::Text\->new( $content );
 168 .Ve
 169 .Sp
 170 The constructor of the class. It creates an unbound text node.
 171 .IP "data" 4
 172 .IX Item "data"
 173 .Vb 1
 174 \&  $nodedata = $text\->data;
 175 .Ve
 176 .Sp
 177 Although there exists the \f(CW\*(C`nodeValue\*(C'\fR attribute in the Node class, the \s-1DOM\s0 specification defines data as a separate
 178 attribute. \f(CW\*(C`XML::LibXML\*(C'\fR implements these two attributes not as different attributes, but as aliases,
 179 such as \f(CW\*(C`libxml2\*(C'\fR does. Therefore
 180 .Sp
 181 .Vb 1
 182 \&  $text\->data;
 183 .Ve
 184 .Sp
 185 and
 186 .Sp
 187 .Vb 1
 188 \&  $text\->nodeValue;
 189 .Ve
 190 .Sp
 191 will have the same result and are not different entities.
 192 .IP "setData($string)" 4
 193 .IX Item "setData($string)"
 194 .Vb 1
 195 \&  $text\->setData( $text_content );
 196 .Ve
 197 .Sp
 198 This function sets or replaces text content to a node. The node has to be of
 199 the type \*(L"text\*(R", \*(L"cdata\*(R" or \*(L"comment\*(R".
 200 .IP "substringData($offset,$length)" 4
 201 .IX Item "substringData($offset,$length)"
 202 .Vb 1
 203 \&  $text\->substringData($offset, $length);
 204 .Ve
 205 .Sp
 206 Extracts a range of data from the node. (\s-1DOM\s0 Spec) This function takes the two
 207 parameters \f(CW$offset\fR and \f(CW$length\fR and returns the sub-string, if available.
 208 .Sp
 209 If the node contains no data or \f(CW$offset\fR refers to an non-existing string index,
 210 this function will return \fIundef\fR. If \f(CW$length\fR is out of range \f(CW\*(C`substringData\*(C'\fR will return the data starting at \f(CW$offset\fR instead of causing an error.
 211 .IP "appendData($string)" 4
 212 .IX Item "appendData($string)"
 213 .Vb 1
 214 \&  $text\->appendData( $somedata );
 215 .Ve
 216 .Sp
 217 Appends a string to the end of the existing data. If the current text node
 218 contains no data, this function has the same effect as \f(CW\*(C`setData\*(C'\fR.
 219 .IP "insertData($offset,$string)" 4
 220 .IX Item "insertData($offset,$string)"
 221 .Vb 1
 222 \&  $text\->insertData($offset, $string);
 223 .Ve
 224 .Sp
 225 Inserts the parameter \f(CW$string\fR at the given \f(CW$offset\fR of the existing data of the
 226 node. This operation will not remove existing data, but change the order of the
 227 existing data.
 228 .Sp
 229 The \f(CW$offset\fR has to be a positive value. If \f(CW$offset\fR is out of range, \f(CW\*(C`insertData\*(C'\fR will have the same behaviour as \f(CW\*(C`appendData\*(C'\fR.
 230 .ie n .IP "deleteData($offset, $length)" 4
 231 .el .IP "deleteData($offset, \f(CW$length\fR)" 4
 232 .IX Item "deleteData($offset, $length)"
 233 .Vb 1
 234 \&  $text\->deleteData($offset, $length);
 235 .Ve
 236 .Sp
 237 This method removes a chunk from the existing node data at the given offset.
 238 The \f(CW$length\fR parameter tells, how many characters should be removed from the
 239 string.
 240 .IP "deleteDataString($string, [$all])" 4
 241 .IX Item "deleteDataString($string, [$all])"
 242 .Vb 1
 243 \&  $text\->deleteDataString($remstring, $all);
 244 .Ve
 245 .Sp
 246 This method removes a chunk from the existing node data. Since the \s-1DOM\s0 spec is
 247 quite unhandy if you already know \f(CW\*(C`which\*(C'\fR string to remove from a text node, this method allows more perlish code :)
 248 .Sp
 249 The functions takes two parameters: \fI\f(CI$string\fI\fR and optional the \fI\f(CI$all\fI\fR flag. If \f(CW$all\fR is not set, \fIundef\fR or \fI0\fR, \f(CW\*(C`deleteDataString\*(C'\fR will remove only the first occurrence of \f(CW$string\fR. If \f(CW$all\fR is \fI\s-1TRUE\s0\fR\f(CW\*(C`deleteDataString\*(C'\fR will remove all occurrences of \fI\f(CI$string\fI\fR from the node data.
 250 .ie n .IP "replaceData($offset, $length, $string)" 4
 251 .el .IP "replaceData($offset, \f(CW$length\fR, \f(CW$string\fR)" 4
 252 .IX Item "replaceData($offset, $length, $string)"
 253 .Vb 1
 254 \&  $text\->replaceData($offset, $length, $string);
 255 .Ve
 256 .Sp
 257 The \s-1DOM\s0 style version to replace node data.
 258 .ie n .IP "replaceDataString($oldstring, $newstring, [$all])" 4
 259 .el .IP "replaceDataString($oldstring, \f(CW$newstring\fR, [$all])" 4
 260 .IX Item "replaceDataString($oldstring, $newstring, [$all])"
 261 .Vb 1
 262 \&  $text\->replaceDataString($old, $new, $flag);
 263 .Ve
 264 .Sp
 265 The more programmer friendly version of \fIreplaceData()\fR :)
 266 .Sp
 267 Instead of giving offsets and length one can specify the exact string (\fI\f(CI$oldstring\fI\fR) to be replaced. Additionally the \fI\f(CI$all\fI\fR flag allows to replace all occurrences of \fI\f(CI$oldstring\fI\fR.
 268 .ie n .IP "replaceDataRegEx( $search_cond, $replace_cond, $reflags )" 4
 269 .el .IP "replaceDataRegEx( \f(CW$search_cond\fR, \f(CW$replace_cond\fR, \f(CW$reflags\fR )" 4
 270 .IX Item "replaceDataRegEx( $search_cond, $replace_cond, $reflags )"
 271 .Vb 1
 272 \&  $text\->replaceDataRegEx( $search_cond, $replace_cond, $reflags );
 273 .Ve
 274 .Sp
 275 This method replaces the node's data by a \f(CW\*(C`simple\*(C'\fR regular expression. Optional, this function allows to pass some flags that will
 276 be added as flag to the replace statement.
 277 .Sp
 278 \&\fI\s-1NOTE:\s0\fR This is a shortcut for
 279 .Sp
 280 .Vb 3
 281 \&  my $datastr = $node\->getData();
 282 \&   $datastr =~ s/somecond/replacement/g; # \*(Aqg\*(Aq is just an example for any flag
 283 \&   $node\->setData( $datastr );
 284 .Ve
 285 .Sp
 286 This function can make things easier to read for simple replacements. For more
 287 complex variants it is recommended to use the code snippet above.
 288 .SH "AUTHORS"
 289 .IX Header "AUTHORS"
 290 Matt Sergeant,
 291 Christian Glahn,
 292 Petr Pajas
 293 .SH "VERSION"
 294 .IX Header "VERSION"
 295 1.70
 296 .SH "COPYRIGHT"
 297 .IX Header "COPYRIGHT"
 298 2001\-2007, AxKit.com Ltd.
 299 .PP
 300 2002\-2006, Christian Glahn.
 301 .PP
 302 2006\-2009, Petr Pajas.