1
2\name{getSibling}
3\alias{getSibling}
4\alias{addSibling}
5
6\title{Manipulate sibling XML nodes}
7
8\description{
9     These functions allow us to both access the sibling node
10     to the left or right of a given node and so walk the chain
11     of siblings, and also to insert a new sibling
12   }
13
14\usage{
15getSibling(node, after = TRUE, ...)
16addSibling(node, ..., kids = list(...), after = NA)
17}
18
19\arguments{
20   \item{node}{the internal XML node (XMLInternalNode)
21             whose siblings are of interest}
22   \item{\dots}{the XML nodes to add as siblings or children to node.}
23   \item{kids}{a list containing the XML nodes to add as siblings.
24     This is equivalent to ... but used when we already have the
25      nodes in a list rather than as individual objects. This is used in programmatic
26      calls to
27     \code{addSibling}
28    rather interactive use where we more commonly have
29      the individual node objects.
30    }
31   \item{after}{a logical value indicating whether to retrieve or add the
32      nodes to the right (\code{TRUE}) or to the left (\code{FALSE}) of this sibling.
33   }
34   }
35
36\value{
37
38     \code{getSibling}
39    returns an object of class
40      XMLInternalNode (or some derived S3 class, e.g. XMLInternalTextNode)
41
42
43     \code{addSibling}
44    returns a list whose elements are the newly added
45     XML (internal) nodes.
46   }
47
48\seealso{
49     \code{\link{xmlChildren}},
50     \code{\link{addChildren}}
51      \code{\link{removeNodes}}
52      \code{\link{replaceNodes}}
53   }
54
55\examples{
56
57          # Reading Apple's iTunes files
58     #
59     #           Here we read  a "censored" "database" of songs from Apple's  iTune application
60     #           which is stored in a property list.  The format is quite generic and
61     #            the fields for each song are given in the form
62     #
63     #             <key>Artist</key><string>Person's name</string>
64     #
65     #           So to find the names of the artists for all the songs, we want to
66     #           find all the <key>Artist<key> nodes and then get their next sibling
67     #           which has the actual value.
68     #
69     #           More information can be found in .
70     #
71           fileName = system.file("exampleData", "iTunes.plist", package = "XML")
72
73           doc = xmlParse(fileName)
74           nodes = getNodeSet(doc, "//key[text() = 'Artist']")
75           sapply(nodes, function(x)  xmlValue(getSibling(x)))
76
77
78      f = system.file("exampleData", "simple.xml", package = "XML")
79      tt = as(xmlParse(f), "XMLHashTree")
80
81       tt
82
83      e = getSibling(xmlRoot(tt)[[1]])
84        # and back to the first one again by going backwards along the sibling list.
85      getSibling(e, after = FALSE)
86
87
88         # This also works for multiple top-level "root" nodes
89      f = system.file("exampleData", "job.xml", package = "XML")
90      tt = as(xmlParse(f), "XMLHashTree")
91       x = xmlRoot(tt, skip = FALSE)
92       getSibling(x)
93       getSibling(getSibling(x), after = FALSE)
94}
95
96\keyword{IO}
97