# perldoc > XML::Writer

---
type: CommandReference
command: XML::Writer
mode: perldoc
section: ''
source: perldoc
---

## Quick Reference

- `XML::Writer->new(OUTPUT => $output, ...)` — create writer object
- `$writer->startTag($name, %attr)` — open element with attributes
- `$writer->characters($data)` — add escaped character data
- `$writer->endTag($name)` — close element (name optional)
- `$writer->emptyTag($name, %attr)` — self-closing tag
- `$writer->dataElement($name, $data, %attr)` — element with only text content
- `$writer->xmlDecl($encoding)` — add XML declaration
- `$writer->doctype($name)` — add DOCTYPE declaration

## Name

Perl extension for writing XML documents.

## Synopsis

perl
use XML::Writer;
use IO::File;

my $output = IO::File->new(">output.xml");
my $writer = XML::Writer->new(OUTPUT => $output);
$writer->startTag("greeting", "class" => "simple");
$writer->characters("Hello, world!");
$writer->endTag("greeting");
$writer->end();
$output->close();
## Options

### Constructor Parameters

- `OUTPUT` — `IO::Handle` object, string reference, `'self'`, or any object with `print()` method. Default: STDOUT. If `'self'`, output captured internally.
- `NAMESPACES` — boolean; enable namespace processing (use `[$uri, $local]` for element/attribute names).
- `PREFIX_MAP` — hash ref mapping namespace URIs to preferred prefixes. Use `''` for default namespace.
- `FORCED_NS_DECLS` — array ref of URIs to declare on document element.
- `NEWLINES` — boolean; insert extra newline before closing delimiter of tags.
- `UNSAFE` — boolean; skip most well-formedness checks.
- `DATA_MODE` — boolean; auto-insert newlines, disallow mixed content.
- `DATA_INDENT` — numeric or whitespace; indent step in data mode.
- `ENCODING` — `'utf-8'` or `'us-ascii'`; sets output encoding and default for XML declaration.
- `CHECK_PRINT` — boolean; croak on print failures.

## Methods

### Writing XML

- `new(%params)` — create writer object (see Options above).
- `end()` — finish document; checks for single document element and closed tags. Returns generated string if OUTPUT is `'self'`.
- `xmlDecl($encoding, $standalone)` — add `<?xml version="1.0" ...?>` declaration.
- `doctype($name, $publicId, $systemId)` — add DOCTYPE declaration.
- `comment($text)` — add `<!-- ... -->` comment.
- `pi($target, $data)` — add processing instruction.
- `startTag($name, %attr)` — add start tag with optional attributes.
- `emptyTag($name, %attr)` — add self-closing tag.
- `endTag($name)` — add end tag; if omitted, matches current element.
- `dataElement($name, $data, %attr)` — shorthand for startTag + characters + endTag.
- `characters($data)` — add escaped character data.
- `raw($data)` — print unescaped data (unsafe mode only).
- `cdata($data)` — write data in `CDATA` section.
- `cdataElement($name, $data, %attr)` — element content as CDATA sections.
- `setOutput($output)` — change output destination.
- `getOutput()` — return current output.
- `setDataMode($bool)` — enable/disable data mode.
- `getDataMode()` — return data mode.
- `setDataIndent($indent)` — set data indent.
- `getDataIndent()` — return data indent.

### Querying XML

- `in_element($name)` — true if the most recent open element matches `$name`.
- `within_element($name)` — true if any open element matches `$name`.
- `current_element()` — name of the currently open element.
- `ancestor($n)` — name of the nth ancestor (0 = current).

### Additional Namespace Support

- `addPrefix($uri, $prefix)` — add preferred prefix mapping. Use `$prefix = ''` for default namespace.
- `removePrefix($uri)` — remove prefix mapping.
- `forceNSDecl($uri)` — ensure namespace declaration on next start tag.

## Examples

### Basic XML document

perl
my $writer = XML::Writer->new(OUTPUT => 'self');
$writer->xmlDecl('UTF-8');
$writer->doctype('html');
$writer->startTag('html');
$writer->startTag('body');
$writer->dataElement('p', 'Hello, world!');
$writer->endTag('body');
$writer->endTag('html');
print $writer->to_string();
### Namespace processing

perl
my $rdfns = "http://www.w3.org/1999/02/22-rdf-syntax-ns#";
my $writer = XML::Writer->new(
    OUTPUT    => 'self',
    NAMESPACES => 1,
    PREFIX_MAP => { $rdfns => 'rdf' }
);
$writer->startTag([$rdfns, 'Description']);
$writer->characters('Resource description');
$writer->endTag();
print $writer->to_string();
## See Also

- `XML::Parser`

## Exit Codes

Not documented.