\name{parseAMD}
\alias{parseAMD}
\alias{xmlAMD}
\alias{writeAMD}
\title{Parses a StatShop Assessment Model Description file}
\description{
  Parses an assessment model description (\code{amd.xml} file) and all
  of its associated graphical model (\code{gm.xml}) files.  Produces an
  object of class \code{amd} which contains all of the model
  information.

  The function \code{writeAMD} inverts this process, writing the
  \code{amd.xml} and associated \code{gm.xml} out to a directory.  
  The function \code{xmlAMD} creates the XML for the \code{amd} object. 
}
\usage{
parseAMD(filename, chatty=FALSE)
writeAMD(amd, directory = getwd(),
         amdfile = paste(deparse(substitute(amd)), "amd.xml", sep="."))
xmlAMD(amd, toplevel = TRUE)
}
\arguments{
  \item{filename}{Pathname to an \code{amd.xml} file containing
    assessment model description.}
  \item{chatty}{A logical value, if true, then progress messages about
    files read will printed.}
  \item{amd}{An Assessment Model Description (\code{amd}) object.}
  \item{directory}{The directory which will contain the complete AMD
    package (AMD and all GM files).}
  \item{amdfile}{The file name for the AMD file.}
  \item{toplevel}{A logical flag, if true the appropriate XML namespace
    and schema attributes are added to the top level node.}
}
\value{
  For \sQuote{parseAMD}, an \code{amd} object containing information
  about all of the models in this assessment description.

  For \sQuote{xmlAMD} an \code{XMLNode} object containing the basic
  information for \code{amd} (but not model details).
}
\details{
  An Assessment Model Description is actually a collection of files:  a
  master \code{amd.xml} file and a number of supporting \code{gm.xml}
  files which contain information about the student, evidence and link
  models referenced in the master \code{amd.xml}.  These files are all
  assumed to exist in the same directory.

  The function \code{parseAMD} calls this package and recursively calls
  \code{parseGmModel} to get the supporting details for the component
  models.  The function \code{writeAMD} reverses that process, writing
  out XML descriptions of both the \code{amd} object and all of the
  models that it contains.

  The function \code{xmlAMD} handles just the XML code for the master
  file.  It produces an object of type \code{XMLNode} (which
  \code{writeAMD} writes to \code{amdfile}).  As this is the top level
  XML object, the constant \code{amdf.prefix} gives the namespace prefix
  and the constants \code{amdf.namespace} and \code{amdf.schemaLocation}
  provide details about the schema location.
}
\references{
  \url{http://research.ets.org/~ralmond/StatShop/dataFormats.html}
}
\section{Side Effects}{
  The function \code{writeAMD} creates a single \code{amd.xml} file
  (named \code{amdfile}) and a \code{gm.xml} for each student, evidence
  and link model in \code{amd} in the directory \code{directory}.
}
\author{Russell Almond}
\seealso{\code{\link{amd}}, \code{\link{printAMDParameterValues}},
  \code{\link{gmModel}}, \code{\link{compareAMD}},
  \code{\link[XML]{XMLNode}}, \code{\link{amdf.namespace}},
  \code{\link{amdf.prefix}}, \code{\link{amdf.schemaLocation}}
}
\examples{
StatShop <- Sys.getenv("STATSHOP")
if (StatShop == "") {
  warn("StatShop not installed, skipping test.")
} else {
fc <- paste(StatShop,"TestScripts","ICT","Version0","Hybrid","FixedContext",sep=.Platform$file.sep)

## This command finds the name of the AMD files in the current
## directory.  Rest of the script assumes that the first one is the
## one you want to use.
amds <- list.files(fc,pattern=".amd.xml$")

## This version of the command for Assessment Description files, it
## looks at link models.
anAmp <- parseAMD(paste(fc,amds[1],sep=.Platform$file.sep))


### This command builds the V-Matrix
printAMDParameterValues(anAmp)

## Create an XML version
anAmpNode <- xmlAMD(anAmp)

## Need a writeable directory.
outdir <- ifelse(.Platform$OS.type == "windows", "C:/temp","/tmp")
## Write it out.
writeAMD(anAmp,outdir)
}
}
\keyword{interface}