# XML agent description

## Purpose

The XML agent (`ag_XML`) is used to access to create XML documents from YCP data structures and also read XML files into YCP. It is part of YaST2 SCR, the system configuration repository, used to access configuration data on the target system. The general SCR API allows `Read()` and `Write()` access to get and change data.

## Implementation

The agent is implemented using the XML extensions of the Qt library. Parsing and creating the documents is done using the DOM classes of the Qt library.

Note: The complete development documentation is available in the `autodocs/` directory.

## Interface for XML-agent

The interface is implemented as a SCR agent with the usual `Read()` and `Write()` interfaces. The path prefix used is

`.xml`

## Restrictions, limits and future enhancements

`...`

See the TODO.txt file for the current status of support and also for the list of possible future enhancements.

## Read options

To read an XML file into ycp, the following syntax is required:
Read(.xml,"<file_name>");

## Write options

To write an XML file into ycp, the following syntax is required:
Write(.xml,$[<options map>], $[ycp data]);

The options map contains the following data:

- "CDATA": A List containing sections that should be treated as CDATA (i.e. source code)
- "DocType": Document Type
- "rootElement": Root Element of the XML document
- "SystemID": still not supported
- "PublicID": still not supported
- "fileName": filename in which the data should be stored (as XML)
- "NameSpace": still not supported