[rkward-cvs] [rkward] packages/XiMpLe: "fixed" definitions of generics to cope with roxygen2 not recognizing function bodies without curly brackets. while at it, completed the docs of several methods.
m.eik michalke
meik.michalke at uni-duesseldorf.de
Tue Dec 2 15:10:17 UTC 2014
Git commit aa350f1a646786d5a1ead54d286f681b36e4dd00 by m.eik michalke.
Committed on 02/12/2014 at 15:08.
Pushed by meikm into branch 'master'.
"fixed" definitions of generics to cope with roxygen2 not recognizing function bodies without curly brackets. while at it, completed the docs of several methods.
M +5 -1 packages/XiMpLe/ChangeLog
M +4 -2 packages/XiMpLe/DESCRIPTION
M +16 -16 packages/XiMpLe/NAMESPACE
M +4 -1 packages/XiMpLe/R/01_method_01_pasteXML.R
M +1 -0 packages/XiMpLe/R/01_method_02_node.R
M +3 -2 packages/XiMpLe/R/XiMpLe-package.R
M +55 -33 packages/XiMpLe/R/zzz_is_get_utils.R
M +15 -1 packages/XiMpLe/inst/NEWS.Rd
A +261 -0 packages/XiMpLe/inst/doc/XiMpLe_vignette.Rnw
R +- -- packages/XiMpLe/inst/doc/XiMpLe_vignette.pdf [from: packages/XiMpLe/vignettes/XiMpLe_vignette.pdf - 089% similarity]
M +12 -0 packages/XiMpLe/man/XMLGetters-methods.Rd
M +3 -2 packages/XiMpLe/man/XiMpLe-package.Rd
M +2 -0 packages/XiMpLe/man/node.Rd
M +2 -0 packages/XiMpLe/man/pasteXML-methods.Rd
http://commits.kde.org/rkward/aa350f1a646786d5a1ead54d286f681b36e4dd00
diff --git a/packages/XiMpLe/ChangeLog b/packages/XiMpLe/ChangeLog
index 7afb927..4e084d0 100644
--- a/packages/XiMpLe/ChangeLog
+++ b/packages/XiMpLe/ChangeLog
@@ -1,8 +1,12 @@
ChangeLog for package XiMpLe
changes in version 0.03-22 (2014-12-02)
+fixed:
+ - added curly brackets to the function bodies of all setGeneric() calls to
+ satisfy roxygen2
changed:
- - allowing empty attributes (attr=""), these were skipped, but only if there was more than one attribute
+ - allowing empty attributes (attr=""), these were skipped, but only if
+ there was more than one attribute
changes in version 0.03-21 (2013-12-21)
added:
diff --git a/packages/XiMpLe/DESCRIPTION b/packages/XiMpLe/DESCRIPTION
index 3fe023a..54704d5 100644
--- a/packages/XiMpLe/DESCRIPTION
+++ b/packages/XiMpLe/DESCRIPTION
@@ -12,7 +12,9 @@ Description: This package provides a simple XML tree parser/generator. It
includes functions to read XML files into R objects, get information out of
and into nodes, and write R objects back to XML code. It's not as powerful
as the XML package and doesn't aim to be, but for simple XML handling it
- could be useful. It was originally programmed for RKWard.
+ could be useful. It was originally programmed for the R GUI and IDE
+ RKWard, to make plugin development easier. You can install RKWard from
+ http://rkward.sf.net.
License: GPL (>= 3)
Encoding: UTF-8
LazyLoad: yes
@@ -20,7 +22,7 @@ URL: http://reaktanz.de/?c=hacking&s=XiMpLe
Authors at R: c(person(given="Meik", family="Michalke",
email="meik.michalke at hhu.de", role=c("aut", "cre")))
Version: 0.03-22
-Date: 2014-03-05
+Date: 2014-12-02
Collate:
'00_class_01_XiMpLe.node.R'
'00_class_02_XiMpLe.doc.R'
diff --git a/packages/XiMpLe/NAMESPACE b/packages/XiMpLe/NAMESPACE
index e0c3af5..39cd99c 100644
--- a/packages/XiMpLe/NAMESPACE
+++ b/packages/XiMpLe/NAMESPACE
@@ -1,9 +1,25 @@
# Generated by roxygen2 (4.0.2): do not edit by hand
+export("XMLAttrs<-")
+export("XMLChildren<-")
+export("XMLDTD<-")
+export("XMLDecl<-")
+export("XMLFile<-")
+export("XMLName<-")
+export("XMLValue<-")
export("node<-")
export()
+export(XMLAttrs)
+export(XMLChildren)
+export(XMLDTD)
+export(XMLDecl)
+export(XMLFile)
+export(XMLName)
export(XMLNode)
+export(XMLScan)
+export(XMLScanDeep)
export(XMLTree)
+export(XMLValue)
export(is.XiMpLe.doc)
export(is.XiMpLe.node)
export(node)
@@ -14,22 +30,6 @@ export(pasteXMLTag)
export(pasteXMLTree)
exportClasses(XiMpLe.doc)
exportClasses(XiMpLe.node)
-exportMethods("XMLAttrs<-")
-exportMethods("XMLChildren<-")
-exportMethods("XMLDTD<-")
-exportMethods("XMLDecl<-")
-exportMethods("XMLFile<-")
-exportMethods("XMLName<-")
exportMethods("XMLScan<-")
-exportMethods("XMLValue<-")
-exportMethods(XMLAttrs)
-exportMethods(XMLChildren)
-exportMethods(XMLDTD)
-exportMethods(XMLDecl)
-exportMethods(XMLFile)
-exportMethods(XMLName)
-exportMethods(XMLScan)
-exportMethods(XMLScanDeep)
-exportMethods(XMLValue)
exportMethods(show)
import(methods)
diff --git a/packages/XiMpLe/R/01_method_01_pasteXML.R b/packages/XiMpLe/R/01_method_01_pasteXML.R
index 1dea42e..9707f3f 100644
--- a/packages/XiMpLe/R/01_method_01_pasteXML.R
+++ b/packages/XiMpLe/R/01_method_01_pasteXML.R
@@ -25,6 +25,7 @@
#' They should no longer be used.
#'
#' @param obj An object of class \code{XiMpLe.node} or \code{XiMpLe.doc}.
+#' @param ... Additional options for the generic method, see options for a specific method, respectively.
#' @aliases
#' pasteXML,-methods
#' pasteXML,XiMpLe.doc-method
@@ -38,7 +39,7 @@
#' @include 00_class_02_XiMpLe.doc.R
#' @docType methods
#' @export
-setGeneric("pasteXML", function(obj, ...) standardGeneric("pasteXML"))
+setGeneric("pasteXML", function(obj, ...){standardGeneric("pasteXML")})
#' @param level Indentation level.
#' @param shine Integer, controlling if the output should be formatted for better readability. Possible values:
@@ -100,6 +101,7 @@ setMethod("pasteXML",
return(pasted.node)
}
)
+
#' @rdname pasteXML-methods
setMethod("pasteXML",
signature=signature(obj="XiMpLe.doc"),
@@ -150,6 +152,7 @@ setMethod("pasteXML",
pasteXMLNode <- function(node, level=1, shine=1, indent.by="\t", tidy=TRUE){
pasteXML(node, level=level, shine=shine, indent.by=indent.by, tidy=tidy)
}
+
#' @export
pasteXMLTree <- function(obj, shine=1, indent.by="\t", tidy=TRUE){
pasteXML(obj, shine=shine, indent.by=indent.by, tidy=tidy)
diff --git a/packages/XiMpLe/R/01_method_02_node.R b/packages/XiMpLe/R/01_method_02_node.R
index c4cc788..4c2d226 100644
--- a/packages/XiMpLe/R/01_method_02_node.R
+++ b/packages/XiMpLe/R/01_method_02_node.R
@@ -177,6 +177,7 @@ setMethod("node",
}
)
+#' @param value The value to set.
#' @export
#' @rdname node
setGeneric("node<-", function(obj, node=list(), what=NULL, cond.attr=NULL, cond.value=NULL, element=NULL, value){standardGeneric("node<-")})
diff --git a/packages/XiMpLe/R/XiMpLe-package.R b/packages/XiMpLe/R/XiMpLe-package.R
index 14b150b..c94a43a 100644
--- a/packages/XiMpLe/R/XiMpLe-package.R
+++ b/packages/XiMpLe/R/XiMpLe-package.R
@@ -4,7 +4,7 @@
#' Package: \tab XiMpLe\cr
#' Type: \tab Package\cr
#' Version: \tab 0.03-22\cr
-#' Date: \tab 2014-03-05\cr
+#' Date: \tab 2014-12-02\cr
#' Depends: \tab R (>= 2.9.0),methods\cr
#' Enhances: \tab rkward\cr
#' Encoding: \tab UTF-8\cr
@@ -16,7 +16,8 @@
#' This package provides a simple XML tree parser/generator. It includes functions to read XML files into R objects,
#' get information out of and into nodes, and write R objects back to XML code.
#' It's not as powerful as the XML package and doesn't aim to be, but for simple XML handling
-#' it could be useful. It was originally programmed for RKWard.
+#' it could be useful. It was originally programmed for the R GUI and IDE RKWard, to make plugin
+#' development easier. You can install RKWard from http://rkward.sf.net.
#'
#' @aliases XiMpLe-package
#' @name XiMpLe-package
diff --git a/packages/XiMpLe/R/zzz_is_get_utils.R b/packages/XiMpLe/R/zzz_is_get_utils.R
index 62593f0..d9f09a6 100644
--- a/packages/XiMpLe/R/zzz_is_get_utils.R
+++ b/packages/XiMpLe/R/zzz_is_get_utils.R
@@ -73,7 +73,7 @@ is.XiMpLe.doc <- function(x){
#' @keywords methods
#' @docType methods
#' @rdname XMLGetters-methods
-#' @exportMethod XMLName
+#' @export
#' @examples
#' xmlTestNode <- XMLNode("foo", XMLNode("testchild"))
#' XMLName(xmlTestNode) # returns "foo"
@@ -84,7 +84,7 @@ is.XiMpLe.doc <- function(x){
#' XMLScan(xmlTestNode, "testchild")
#' # remove nodes of that name
#' XMLScan(xmlTestNode, "testchild") <- NULL
-setGeneric("XMLName", function(obj) standardGeneric("XMLName"))
+setGeneric("XMLName", function(obj){standardGeneric("XMLName")})
#' @rdname XMLGetters-methods
#' @aliases
@@ -100,8 +100,9 @@ setMethod("XMLName",
)
#' @rdname XMLGetters-methods
-#' @exportMethod XMLName<-
-setGeneric("XMLName<-", function(obj, value) standardGeneric("XMLName<-"))
+#' @docType methods
+#' @export
+setGeneric("XMLName<-", function(obj, value){standardGeneric("XMLName<-")})
#' @rdname XMLGetters-methods
#' @aliases
@@ -118,8 +119,9 @@ setMethod("XMLName<-",
)
#' @rdname XMLGetters-methods
-#' @exportMethod XMLAttrs
-setGeneric("XMLAttrs", function(obj) standardGeneric("XMLAttrs"))
+#' @docType methods
+#' @export
+setGeneric("XMLAttrs", function(obj){standardGeneric("XMLAttrs")})
#' @rdname XMLGetters-methods
#' @aliases
@@ -135,8 +137,9 @@ setMethod("XMLAttrs",
)
#' @rdname XMLGetters-methods
-#' @exportMethod XMLAttrs<-
-setGeneric("XMLAttrs<-", function(obj, value) standardGeneric("XMLAttrs<-"))
+#' @docType methods
+#' @export
+setGeneric("XMLAttrs<-", function(obj, value){standardGeneric("XMLAttrs<-")})
#' @rdname XMLGetters-methods
#' @aliases
@@ -153,8 +156,9 @@ setMethod("XMLAttrs<-",
)
#' @rdname XMLGetters-methods
-#' @exportMethod XMLChildren
-setGeneric("XMLChildren", function(obj) standardGeneric("XMLChildren"))
+#' @docType methods
+#' @export
+setGeneric("XMLChildren", function(obj){standardGeneric("XMLChildren")})
#' @rdname XMLGetters-methods
#' @aliases
@@ -182,9 +186,11 @@ setMethod("XMLChildren",
}
)
+#' @param value The new value to set.
#' @rdname XMLGetters-methods
-#' @exportMethod XMLChildren<-
-setGeneric("XMLChildren<-", function(obj, value) standardGeneric("XMLChildren<-"))
+#' @docType methods
+#' @export
+setGeneric("XMLChildren<-", function(obj, value){standardGeneric("XMLChildren<-")})
#' @rdname XMLGetters-methods
#' @aliases
@@ -216,8 +222,9 @@ setMethod("XMLChildren<-",
#' @rdname XMLGetters-methods
-#' @exportMethod XMLValue
-setGeneric("XMLValue", function(obj) standardGeneric("XMLValue"))
+#' @docType methods
+#' @export
+setGeneric("XMLValue", function(obj){standardGeneric("XMLValue")})
#' @rdname XMLGetters-methods
#' @aliases
@@ -233,8 +240,9 @@ setMethod("XMLValue",
)
#' @rdname XMLGetters-methods
-#' @exportMethod XMLValue<-
-setGeneric("XMLValue<-", function(obj, value) standardGeneric("XMLValue<-"))
+#' @docType methods
+#' @export
+setGeneric("XMLValue<-", function(obj, value){standardGeneric("XMLValue<-")})
#' @rdname XMLGetters-methods
#' @aliases
@@ -251,8 +259,9 @@ setMethod("XMLValue<-",
)
#' @rdname XMLGetters-methods
-#' @exportMethod XMLFile
-setGeneric("XMLFile", function(obj) standardGeneric("XMLFile"))
+#' @docType methods
+#' @export
+setGeneric("XMLFile", function(obj){standardGeneric("XMLFile")})
#' @rdname XMLGetters-methods
#' @aliases
@@ -268,8 +277,9 @@ setMethod("XMLFile",
)
#' @rdname XMLGetters-methods
-#' @exportMethod XMLFile<-
-setGeneric("XMLFile<-", function(obj, value) standardGeneric("XMLFile<-"))
+#' @docType methods
+#' @export
+setGeneric("XMLFile<-", function(obj, value){standardGeneric("XMLFile<-")})
#' @rdname XMLGetters-methods
#' @aliases
@@ -286,8 +296,9 @@ setMethod("XMLFile<-",
)
#' @rdname XMLGetters-methods
-#' @exportMethod XMLDecl
-setGeneric("XMLDecl", function(obj) standardGeneric("XMLDecl"))
+#' @docType methods
+#' @export
+setGeneric("XMLDecl", function(obj){standardGeneric("XMLDecl")})
#' @rdname XMLGetters-methods
#' @aliases
@@ -303,8 +314,9 @@ setMethod("XMLDecl",
)
#' @rdname XMLGetters-methods
-#' @exportMethod XMLDecl<-
-setGeneric("XMLDecl<-", function(obj, value) standardGeneric("XMLDecl<-"))
+#' @docType methods
+#' @export
+setGeneric("XMLDecl<-", function(obj, value){standardGeneric("XMLDecl<-")})
#' @rdname XMLGetters-methods
#' @aliases
@@ -321,8 +333,9 @@ setMethod("XMLDecl<-",
)
#' @rdname XMLGetters-methods
-#' @exportMethod XMLDTD
-setGeneric("XMLDTD", function(obj) standardGeneric("XMLDTD"))
+#' @docType methods
+#' @export
+setGeneric("XMLDTD", function(obj){standardGeneric("XMLDTD")})
#' @rdname XMLGetters-methods
#' @aliases
@@ -338,8 +351,9 @@ setMethod("XMLDTD",
)
#' @rdname XMLGetters-methods
-#' @exportMethod XMLDTD<-
-setGeneric("XMLDTD<-", function(obj, value) standardGeneric("XMLDTD<-"))
+#' @docType methods
+#' @export
+setGeneric("XMLDTD<-", function(obj, value){standardGeneric("XMLDTD<-")})
#' @rdname XMLGetters-methods
#' @aliases
@@ -356,9 +370,13 @@ setMethod("XMLDTD<-",
)
## scan a tree for appearances of nodes
+#' @param name Character, name of nodes to scan for.
+#' @param as.list Logical, if \code{TRUE} allways returns a list (or NULL), otherwise if exactly one result is found,
+#' it will be returned as as single \code{XiMpLe.node}.
#' @rdname XMLGetters-methods
-#' @exportMethod XMLScan
-setGeneric("XMLScan", function(obj, name, as.list=FALSE) standardGeneric("XMLScan"))
+#' @docType methods
+#' @export
+setGeneric("XMLScan", function(obj, name, as.list=FALSE){standardGeneric("XMLScan")})
# internal helper function
find.nodes <- function(nodes, nName){
@@ -418,7 +436,7 @@ setMethod("XMLScan",
#' @rdname XMLGetters-methods
#' @exportMethod XMLScan<-
-setGeneric("XMLScan<-", function(obj, name, value) standardGeneric("XMLScan<-"))
+setGeneric("XMLScan<-", function(obj, name, value){standardGeneric("XMLScan<-")})
# internal helper function
replace.nodes <- function(nodes, nName, replacement){
@@ -484,9 +502,13 @@ setMethod("XMLScan<-",
}
)
+#' @param find Character, name of element to scan for.
+#' @param search Character, name of the slot to scan, one of \code{"attributes"},
+#' \code{"name"}, \code{"children"}, or \code{"value"} for nodes.
#' @rdname XMLGetters-methods
-#' @exportMethod XMLScanDeep
-setGeneric("XMLScanDeep", function(obj, find=NULL, search="attributes") standardGeneric("XMLScanDeep"))
+#' @docType methods
+#' @export
+setGeneric("XMLScanDeep", function(obj, find=NULL, search="attributes"){standardGeneric("XMLScanDeep")})
# internal helper function
recursiveScan <- function(robj, rfind, rsearch, recResult=list(), result, envID="all"){
diff --git a/packages/XiMpLe/inst/NEWS.Rd b/packages/XiMpLe/inst/NEWS.Rd
index e54ca07..cb0a8a8 100644
--- a/packages/XiMpLe/inst/NEWS.Rd
+++ b/packages/XiMpLe/inst/NEWS.Rd
@@ -1,7 +1,21 @@
\name{NEWS}
\title{News for Package 'XiMpLe'}
\encoding{UTF-8}
-\section{Changes in XiMpLe version 0.03-22 (2014-03-05)}{
+\section{Changes in XiMpLe version 0.03-22 (2014-12-02)}{
+ \subsection{fixed}{
+ \itemize{
+ \item added curly brackets to the function bodies of all \code{setGeneric()} calls to
+ satisfy roxygen2
+ }
+ }
+ \subsection{changed}{
+ \itemize{
+ \item allowing empty attributes (attr=\code{""}), these were skipped, but only if
+ there was more than one attribute
+ }
+ }
+}
+\section{Changes in XiMpLe version 0.03-21 (2013-12-21)}{
\subsection{added}{
\itemize{
\item new attribute \code{"as.list"} added to \code{XMLScan()}, if TRUE forces the return
diff --git a/packages/XiMpLe/inst/doc/XiMpLe_vignette.Rnw b/packages/XiMpLe/inst/doc/XiMpLe_vignette.Rnw
new file mode 100644
index 0000000..1cd07f2
--- /dev/null
+++ b/packages/XiMpLe/inst/doc/XiMpLe_vignette.Rnw
@@ -0,0 +1,261 @@
+\documentclass[a4paper,10pt]{scrartcl}
+\usepackage[utf8x]{inputenc}
+\usepackage{apacite}
+
+\newcommand{\X}[0]{\texttt{XiMpLe}}
+
+%opening
+\title{The XiMpLe Package}
+%\VignetteIndexEntry{Managing R Packages with roxyPackage}
+\author{m.eik michalke}
+
+\begin{document}
+\maketitle
+
+\begin{abstract}
+This package provides basic tools for parsing and generating XML into and from R. It is not as feature-rich as alternative packages, but it's small and keeps dependencies to a minimum.
+\end{abstract}
+
+\section{Previously on \X{}}
+
+Before I even begin, I would like to stress that \X{} can \textit{not} replace the \texttt{XML} package, and it is not supposed to. It has only a hand full of functions, therefore it can only do so much. Probably the most noteworthy missing feature in this package is any real DTD support. If you need that, you can stop reading here. Another problem is speed -- \X{} is written in pure R, and it's painfully slow with large XML trees. You won't notice this if you're only dealing with portions of some kilobytes, but if you need to parse really huge documents, it can take ages to finish.
+
+Historically, this package was written for exactly one purpose: I wanted to be able to read and write the XML documents of \texttt{RKWard}\footnote{\url{http://rkward.sourceforge.net}}, because I was about to write an R package for scripting plugins for this R GUI. I actually had started another project shortly before, using the \texttt{XML} package as a dependency, but soon got complaints from Windows users. As it turned out, that package was not available for Windows, because somehow it couldn't be built automatically. When I realised that I only needed a small subset of its features anyway, I figured it might be easiest to quickly implement those features myself.
+
+Instead of hiding them in the internals of what eventually became the \texttt{rkwarddev}\footnote{\url{http://rkward.sourceforge.net/R/pckg/rkwarddev}} package, I then started working on this package first. And well, ``quickly'' was rather optimistic... but since I'm happily using \X{} in other packages as well (like \texttt{roxyPackage}\footnote{\url{http://reaktanz.de/?c=hacking\&s=roxyPackage}}), I'm satisfied it was worth it.
+
+So now you know. If you need a full-featured package to parse or generate XML in R, try the \texttt{XML} package. Otherwise, keep on reading.
+
+\section{And now the continuation}
+
+Basically, \X{} can do these things for you:
+
+\begin{itemize}
+ \item parse XML from files into an R object, using the \texttt{parseXML()} function
+ \item generate XML R objects, using the functions \texttt{XMLNode()} and \texttt{XMLTree()}
+ \item extract nodes from XML R objects, or change their content, using the \texttt{node()} function
+ \item write back XML files from R objects, using the \texttt{pasteXML()} function
+\end{itemize}
+
+That about covers it. XML nodes can of course be nested to construct complex trees, but that's all. Let's look at some examples.
+
+\section{Naming conventions}
+Let's quickly explain what we'll be talking about here. If you're parsing an XML document, it will contain an \textbf{XML tree}. This tree is made up of \textbf{XML nodes}. A node is indicated by arrow brackets, \textit{must} have a \textbf{name}, \textit{can} have \textbf{attributes}, and is either \textbf{empty} or not. Nodes can be nested, where nodes inside a node are its \textbf{child nodes}.
+
+\begin{Schunk}
+ \begin{Sinput}
+<!-- following is an empty node named "useless" -->
+<useless />
+
+<!-- the next node is non-empty and has an attribute foo with value bar -->
+<other foo="bar">
+ this text is the child of the "other" node.
+</other>
+ \end{Sinput}
+\end{Schunk}
+
+\section{Generate XML trees}
+
+Now let's see how these nodes can be generated using the \X{} package. Single nodes are the domain of the \texttt{XMLNode()} function, and to get an empty node you just give it the name of that node:
+
+\begin{Schunk}
+ \begin{Sinput}
+> XMLNode("useless")
+ \end{Sinput}
+ \begin{Soutput}
+<useless />
+ \end{Soutput}
+\end{Schunk}
+
+As you see, you will be shown XML code on the console. But what this function returns is actually an R object of class \texttt{XiMpLe.node}, so what you see is an \textit{interpretation} of that object, made by the \texttt{show()} method for objects of this type (see section \ref{Writing XML files} on page \pageref{Writing XML files} on how to export XML to files).
+
+The second node in the example above has an attribute. Attributes can be specified with the \texttt{attrs} argument, which expects a named list:
+
+\begin{Schunk}
+ \begin{Sinput}
+> XMLNode("other", attrs=list(foo="bar"))
+ \end{Sinput}
+ \begin{Soutput}
+<other foo="bar" />
+ \end{Soutput}
+\end{Schunk}
+
+So, by default, as long as our node doesn't have any children, it's assumed to be an empty node. To force it into a non-empty node (i.\,e., opening and closing tag) even without content, we'd have to provide an empty character string as its child. Child nodes can be provided in two ways -- either one by one via the ``$\dots$'' argument, or as one list via the \texttt{.children} argument:
+
+\begin{Schunk}
+ \begin{Sinput}
+> XMLNode("other", "", attrs=list(foo="bar"))
+ \end{Sinput}
+ \begin{Soutput}
+<other foo="bar">
+</other>
+ \end{Soutput}
+ \begin{Sinput}
+> XMLNode("other", attrs=list(foo="bar"), .children=list(""))
+ \end{Sinput}
+ \begin{Soutput}
+<other foo="bar">
+</other>
+ \end{Soutput}
+\end{Schunk}
+
+Of course this is also the place to provide our node with the text value:
+
+\begin{Schunk}
+ \begin{Sinput}
+> XMLNode("other", "this text is the child of the \"other\" node.",
++ attrs=list(foo="bar"))
+ \end{Sinput}
+ \begin{Soutput}
+<other foo="bar">
+ this text is the child of the "other" node.
+</other>
+ \end{Soutput}
+\end{Schunk}
+
+But how about the comments? Well, \X{} does detect some special node names, one being ``!-\,-'' to indicate a comment:
+
+\begin{Schunk}
+ \begin{Sinput}
+> XMLNode("!--", "following is an empty node named \"useless\"")
+ \end{Sinput}
+ \begin{Soutput}
+<!-- following is an empty node named "useless" -->
+ \end{Soutput}
+\end{Schunk}
+
+OK, that's single nodes. In most cases, you want to have nested nodes which combine into an XML tree. As a practical example, this is how you could generate an XHTML document:
+
+\begin{Schunk}
+ \begin{Sinput}
+> sample.XML.a <- XMLNode("a", "klick here!",
++ attrs=list(href="http://example.com", target="_blank"))
+> sample.XML.body <- XMLNode("body", sample.XML.a)
+> sample.XML.html <- XMLNode("html", XMLNode("head", ""),
++ sample.XML.body)
+> sample.XML.tree <- XMLTree(sample.XML.html,
++ xml=list(version="1.0", encoding="UTF-8"),
++ dtd=list(doctype="html", decl="PUBLIC",
++ id="-//W3C//DTD XHTML 1.0 Transitional//EN",
++ refer="http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"))
+> sample.XML.tree
+ \end{Sinput}
+ \begin{Soutput}
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html>
+ <head>
+ </head>
+ <body>
+ <a href="http://example.com" target="_blank">
+ klick here!
+ </a>
+ </body>
+</html>
+ \end{Soutput}
+\end{Schunk}
+
+It should be noted, however, that \X{} doesn't perform even the slightest checks on what you provide as \texttt{DOCTYPE} or \texttt{xml} attributes.
+
+\section{Writing XML files}
+\label{Writing XML files}
+
+We've learned earlier that \texttt{XiMpLe} objects do not contain the actual XML code. If you would like to write the XML code to a file, you should use \texttt{pasteXML()}, which will translate the R objects into a character string:
+
+\begin{Schunk}
+ \begin{Sinput}
+> useless.node <- XMLNode("useless")
+> pasteXML(useless.node)
+ \end{Sinput}
+ \begin{Soutput}
+[1] "<useless />\n"
+ \end{Soutput}
+\end{Schunk}
+
+Now let's write the XHTML code we created in the previous section to a file called \texttt{example.html}:
+
+\begin{Schunk}
+ \begin{Sinput}
+> cat(pasteXML(sample.XML.tree), file="example.html")
+ \end{Sinput}
+\end{Schunk}
+
+And that's it. The method \texttt{pasteXML()} has some arguments to configure the output, like \texttt{shine}, which sets the level of code formatting. If you set \texttt{shine=0}, no formatting is done, not even newlines.
+
+\section{Reading XML files}
+
+We've also just created an example file we can read back in, to see how XML parsing looks like with \X{}:
+
+\begin{Schunk}
+ \begin{Sinput}
+> sample.XML.parsed <- parseXMLTree("example.html")
+ \end{Sinput}
+\end{Schunk}
+
+\texttt{parseXMLTree()} can also digest XML directly if it comes in single character strings or vectors. You only need to tell it that you're not providing a file name this time, using the \texttt{object} argument:
+
+\begin{Schunk}
+ \begin{Sinput}
+> my.XML.stuff <- c("<start>here it begins","</start>")
+> parseXMLTree(my.XML.stuff, object=TRUE)
+\end{Sinput}
+ \begin{Soutput}
+<start>
+ here it begins
+</start>
+ \end{Soutput}
+\end{Schunk}
+
+\section{Mining nodes}
+
+Reading and writing XML files is neat, but what if you need to aquire only certain parts of, say, a parsed XML file? For example, what if we only needed the URL of the \texttt{href} attribute in our XHTML example?
+
+That's a job for \texttt{node()}. This method can be used to extract parts from XML trees, once they are \X{} objects. The branch you'd like to get can be defined by a list of node names, and \texttt{node()} will follow down this hierarchy and then return what nodes are to be found below that. You can also specify that you don't want the whole node(s), but only the attributes:
+
+\begin{Schunk}
+ \begin{Sinput}
+> node(sample.XML.tree, node=list("html","body","a"), what="attributes")
+ \end{Sinput}
+ \begin{Soutput}
+$href
+[1] "http://example.com"
+
+$target
+[1] "_blank"
+ \end{Soutput}
+ \begin{Sinput}
+> node(sample.XML.tree, node=list("html","body","a"), what="value")
+ \end{Sinput}
+ \begin{Soutput}
+[1] "klick here!"
+ \end{Soutput}
+\end{Schunk}
+
+This way it's easy to get the value of all attributes or the link text. You can also change values with \texttt{node()}. Let's change the URL and remove the \texttt{target} attribute completely:
+
+\begin{Schunk}
+ \begin{Sinput}
+> node(sample.XML.tree, node=list("html","body","a"),
++ what="attributes", element="href") <- "http://example.com/foobar"
+> node(sample.XML.tree, node=list("html","body","a"),
++ what="attributes", element="target") <- NULL
+> sample.XML.tree
+ \end{Sinput}
+ \begin{Soutput}
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html>
+ <head>
+ </head>
+ <body>
+ <a href="http://example.com/foobar">
+ klick here!
+ </a>
+ </body>
+</html>
+ \end{Soutput}
+\end{Schunk}
+
+\end{document}
diff --git a/packages/XiMpLe/vignettes/XiMpLe_vignette.pdf b/packages/XiMpLe/inst/doc/XiMpLe_vignette.pdf
similarity index 89%
rename from packages/XiMpLe/vignettes/XiMpLe_vignette.pdf
rename to packages/XiMpLe/inst/doc/XiMpLe_vignette.pdf
index c0d4bbb..2651ba5 100644
Binary files a/packages/XiMpLe/vignettes/XiMpLe_vignette.pdf and b/packages/XiMpLe/inst/doc/XiMpLe_vignette.pdf differ
diff --git a/packages/XiMpLe/man/XMLGetters-methods.Rd b/packages/XiMpLe/man/XMLGetters-methods.Rd
index 88a98d5..dee0afd 100644
--- a/packages/XiMpLe/man/XMLGetters-methods.Rd
+++ b/packages/XiMpLe/man/XMLGetters-methods.Rd
@@ -139,6 +139,18 @@ XMLScanDeep(obj, find = NULL, search = "attributes")
}
\arguments{
\item{obj}{An object of class \code{XiMpLe.node} or \code{XiMpLe.doc}}
+
+\item{value}{The new value to set.}
+
+\item{name}{Character, name of nodes to scan for.}
+
+\item{as.list}{Logical, if \code{TRUE} allways returns a list (or NULL), otherwise if exactly one result is found,
+it will be returned as as single \code{XiMpLe.node}.}
+
+\item{find}{Character, name of element to scan for.}
+
+\item{search}{Character, name of the slot to scan, one of \code{"attributes"},
+\code{"name"}, \code{"children"}, or \code{"value"} for nodes.}
}
\description{
Used to get/set certain slots from objects of class \code{\link[XiMpLe:XiMpLe.doc-class]{XiMpLe.doc}}
diff --git a/packages/XiMpLe/man/XiMpLe-package.Rd b/packages/XiMpLe/man/XiMpLe-package.Rd
index 0631182..069180a 100644
--- a/packages/XiMpLe/man/XiMpLe-package.Rd
+++ b/packages/XiMpLe/man/XiMpLe-package.Rd
@@ -11,7 +11,7 @@ A simple XML tree parser and generator.
Package: \tab XiMpLe\cr
Type: \tab Package\cr
Version: \tab 0.03-22\cr
-Date: \tab 2014-03-05\cr
+Date: \tab 2014-12-02\cr
Depends: \tab R (>= 2.9.0),methods\cr
Enhances: \tab rkward\cr
Encoding: \tab UTF-8\cr
@@ -23,7 +23,8 @@ URL: \tab http://reaktanz.de/?c=hacking&s=XiMpLe\cr
This package provides a simple XML tree parser/generator. It includes functions to read XML files into R objects,
get information out of and into nodes, and write R objects back to XML code.
It's not as powerful as the XML package and doesn't aim to be, but for simple XML handling
-it could be useful. It was originally programmed for RKWard.
+it could be useful. It was originally programmed for the R GUI and IDE RKWard, to make plugin
+development easier. You can install RKWard from http://rkward.sf.net.
}
\author{
Meik Michalke
diff --git a/packages/XiMpLe/man/node.Rd b/packages/XiMpLe/man/node.Rd
index 4d17808..c7a4836 100644
--- a/packages/XiMpLe/man/node.Rd
+++ b/packages/XiMpLe/man/node.Rd
@@ -46,6 +46,8 @@ against the value between a pair of tags.}
\item{element}{A character string naming one list element of the node slot. If \code{NULL}, all
elements will be returned.}
+
+\item{value}{The value to set.}
}
\description{
This method can be used to get parts of a parsed XML tree object, or to fill it with new values.
diff --git a/packages/XiMpLe/man/pasteXML-methods.Rd b/packages/XiMpLe/man/pasteXML-methods.Rd
index 395fc73..b39dd36 100644
--- a/packages/XiMpLe/man/pasteXML-methods.Rd
+++ b/packages/XiMpLe/man/pasteXML-methods.Rd
@@ -20,6 +20,8 @@ pasteXML(obj, ...)
\arguments{
\item{obj}{An object of class \code{XiMpLe.node} or \code{XiMpLe.doc}.}
+\item{...}{Additional options for the generic method, see options for a specific method, respectively.}
+
\item{level}{Indentation level.}
\item{shine}{Integer, controlling if the output should be formatted for better readability. Possible values:
More information about the rkward-tracker
mailing list