The xml-emitter Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The xml-emitter Reference Manual

This is the xml-emitter Reference Manual, version 1.0.4, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:46:38 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

Update:
    This project has been taken over from Peter Scott
    HomePage: https://github.com/VitoVan/xml-emitter
    Check README.md for new changes

Original:

xml-emitter: An XML emitter
===========================

Often, programs have to generate XML output. This is fairly easy, but
not quite trivial. You need to do escaping, and indentation can be a
little tricky to keep track of. One approach you could use is to get
an XML parser/unparser like XMLS, build your XML data structure in
memory, then dump the whole thing. This is fairly easy, but not as
easy as it could be, and it requires holding the whole structure in
memory. Oh, and XMLS doesn't handle indentation for you.

So, I wrote xml-emitter. xml-emitter simply emits XML, with some
complexity for handling indentation. It can be used to produce all
sorts of useful XML output; it has an RSS 2.0 emitter built in.

There is no real home page, but you can download it from the
asdf-packaging project:

http://common-lisp.net/project/asdf-packaging/

If you have comments, questions, or bug reports, email them to Peter
Scott .

Installation
------------

There are two ways to install xml-emitter. Via asdf-install:

(asdf-install:install :xml-emitter)

Or you can download the latest version at:

http://common-lisp.net/project/asdf-packaging/xml-emitter-latest.tar.gz

Usage
-----

The WITH-XML-OUTPUT macro wraps all XML output to a stream.

The WITH-TAG macro places the XML produced by its body inside a
tag. Its output cannot be on just one line, since it puts starting and
closing tags on their own lines.

The WITH-SIMPLE-TAG macro is like WITH-TAG, but starting and closing
tags don't get their own lines.

XML-OUT prints its argument to the XML output stream, escaped.

XML-AS-IS prints its argument to the XML output stream, unescaped.

SIMPLE-TAG prints a simple value tag. It's a shortened
version of a typical use of WITH-SIMPLE-TAG and XML-OUT.

EMIT-SIMPLE-TAGS takes a plist of tag names and tag values. For every
tag with a non-NIL value, it prints the tag with SIMPLE-TAG. Tag names
given as keyword symbols (like :this) are downcased.

Example:

(with-xml-output (*standard-output*)
  (with-tag ("person" '(("age" "19")))
    (with-simple-tag ("firstName")
      (xml-out "Peter"))
    (simple-tag "lastName" "Scott")
    (emit-simple-tags :age 17
		      :school "Iowa State Univeristy"
		      "mixedCaseTag" "Check out the mixed case!"
		      "notShown" nil)))

The RSS 2.0 emitter
-------------------

The WITH-RSS2 macro wraps up all output of RSS.

RSS-CHANNEL-HEADER outputs the RSS channel information.

RSS-ITEM outputs information about one RSS item.

Example:

(with-rss2 (*standard-output*)
  (rss-channel-header "Peter's Blog" "http://peter.blogspot.com/"
		      :description "A place where I sometimes post stuff"
		      :image "myhead.jpg"
		      :image-title "My glorious visage")
  (rss-item "Breaking news!"
	    :link "http://google.com/"
	    :description "The biggest problem with the DO-ODD macro above is that it puts BODY
into LOOP. Code from the user of the macro should never be run in the
environment established by the LOOP macro. LOOP does a number of
things behind your back, and it's hard to disable them. For example,
what happens here?"
	    :author "Peter Scott"
	    :category "Lisp"
	    :pubDate "Sun, 29 Sep 2002 19:59:01 GMT")
  (rss-item "RSS emitter created"
	    :description "An RSS emitter has been released! Hahahahaha!"
	    :author "Peter Scott"
	    :link "http://gmail.google.com/"))

There is also a complete example of how you might use the RSS emitter
in mailbox.lisp

License
-------

I, Peter Scott, place this code in the public domain. You can do
whatever you like with it.

-Peter Scott, 

Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 xml-emitter

Author

Peter Scott / Vito Van / Philipp Marek

License

Public Domain / 0-clause MIT

Description

xml-emitter simply emits XML, with some
complexity for handling indentation. It can be used to produce all sorts of useful XML output; it has an RSS 2.0 emitter built in.

Version

1.0.4

Dependency

cl-utilities

Source

xml-emitter.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Next: , Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 xml-emitter.asd

Location

xml-emitter.asd

Systems

xml-emitter (system)

Packages

xml-emitter-system


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 xml-emitter/package.lisp

Dependency

licence (file)

Parent

xml-emitter (system)

Location

package.lisp

Packages

xml-emitter


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 xml-emitter/xml.lisp

Dependency

package.lisp (file)

Parent

xml-emitter (system)

Location

xml.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.4 xml-emitter/rss2.lisp

Dependency

xml.lisp (file)

Parent

xml-emitter (system)

Location

rss2.lisp

Exported Definitions

Previous: , Up: Files   [Contents][Index]

3.2 Other


Previous: , Up: Other files   [Contents][Index]

3.2.1 xml-emitter/LICENCE

Parent

xml-emitter (system)

Location

LICENCE


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

4.1 xml-emitter-system

Source

xml-emitter.asd

Use List

Previous: , Up: Packages   [Contents][Index]

4.2 xml-emitter

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Macros

Macro: with-rss2 (STREAM &key ENCODING) &body BODY
Package

xml-emitter

Source

rss2.lisp (file)

Macro: with-simple-tag (NAME &optional ATTRS NAMESPACE) &body BODY

Like WITH-TAG, but without the linebreaks.

Package

xml-emitter

Source

xml.lisp (file)

Macro: with-tag (NAME &optional ATTRS NAMESPACE) &body BODY

Wrap BODY in a tag. BODY is indented, and linebreaks are added.

Package

xml-emitter

Source

xml.lisp (file)

Macro: with-xml-output (STREAM &key ENCODING) &body BODY

Wrap XML output on STREAM with the necessary XML heading information

Package

xml-emitter

Source

xml.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: emit-simple-tags &rest TAGS-PLIST

Given a plist mapping tag names to values (or nil), emit tags in the order given, skipping ones with nil values. Tag names are downcased unless they’re passed as strings.

Package

xml-emitter

Source

xml.lisp (file)

Function: empty-tag NAME &optional ATTRS NAMESPACE
Package

xml-emitter

Source

xml.lisp (file)

Function: rss-channel-header TITLE LINK &key DESCRIPTION LANGUAGE IMAGE IMAGE-TITLE IMAGE-LINK
Package

xml-emitter

Source

rss2.lisp (file)

Function: rss-item TITLE &key LINK DESCRIPTION AUTHOR CATEGORY COMMENTS GUID PUBDATE SOURCE
Package

xml-emitter

Source

rss2.lisp (file)

Function: simple-tag NAME CONTENT &optional ATTRS NAMESPACE

Emit a simple tag with given content

Package

xml-emitter

Source

xml.lisp (file)

Function: xml-as-is X &key INDENT

Write X to XML output, unescaped and optionally indented

Package

xml-emitter

Source

xml.lisp (file)

Function: xml-out X &key INDENT

Write X to XML output, escaped and optionally indented

Package

xml-emitter

Source

xml.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *char-escapes*
Package

xml-emitter

Source

xml.lisp (file)

Special Variable: *entities*
Package

xml-emitter

Source

xml.lisp (file)

Special Variable: *indent*

Number of spaces to indent each line of XML output

Package

xml-emitter

Source

xml.lisp (file)

Special Variable: *whitespace*
Package

xml-emitter

Source

xml.lisp (file)

Special Variable: *xml-output-stream*

The stream to write XML to

Package

xml-emitter

Source

xml.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Macros

Macro: with-indent (&optional SPACES) &body BODY

Increase the indentation level in BODY by SPACES

Package

xml-emitter

Source

xml.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Functions

Function: end-tag NAME

Write en ending tag to XML output

Package

xml-emitter

Source

xml.lisp (file)

Function: indent &optional SPACES

Indent a given number of spaces

Package

xml-emitter

Source

xml.lisp (file)

Function: start-tag NAME &optional ATTRS NAMESPACE END-IT

Write a start tag to XML output

Package

xml-emitter

Source

xml.lisp (file)

Function: write-escaped STRING STREAM

Writes string to stream with all character entities escaped.

Package

xml-emitter

Source

xml.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   O   X  
Index Entry  Section

F
File, Lisp, xml-emitter.asd: The xml-emitter<dot>asd file
File, Lisp, xml-emitter/package.lisp: The xml-emitter/package<dot>lisp file
File, Lisp, xml-emitter/rss2.lisp: The xml-emitter/rss2<dot>lisp file
File, Lisp, xml-emitter/xml.lisp: The xml-emitter/xml<dot>lisp file
File, other, xml-emitter/LICENCE: The xml-emitter/licence file

L
Lisp File, xml-emitter.asd: The xml-emitter<dot>asd file
Lisp File, xml-emitter/package.lisp: The xml-emitter/package<dot>lisp file
Lisp File, xml-emitter/rss2.lisp: The xml-emitter/rss2<dot>lisp file
Lisp File, xml-emitter/xml.lisp: The xml-emitter/xml<dot>lisp file

O
Other File, xml-emitter/LICENCE: The xml-emitter/licence file

X
xml-emitter.asd: The xml-emitter<dot>asd file
xml-emitter/LICENCE: The xml-emitter/licence file
xml-emitter/package.lisp: The xml-emitter/package<dot>lisp file
xml-emitter/rss2.lisp: The xml-emitter/rss2<dot>lisp file
xml-emitter/xml.lisp: The xml-emitter/xml<dot>lisp file

Jump to:   F   L   O   X  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   E   F   I   M   R   S   W   X  
Index Entry  Section

E
emit-simple-tags: Exported functions
empty-tag: Exported functions
end-tag: Internal functions

F
Function, emit-simple-tags: Exported functions
Function, empty-tag: Exported functions
Function, end-tag: Internal functions
Function, indent: Internal functions
Function, rss-channel-header: Exported functions
Function, rss-item: Exported functions
Function, simple-tag: Exported functions
Function, start-tag: Internal functions
Function, write-escaped: Internal functions
Function, xml-as-is: Exported functions
Function, xml-out: Exported functions

I
indent: Internal functions

M
Macro, with-indent: Internal macros
Macro, with-rss2: Exported macros
Macro, with-simple-tag: Exported macros
Macro, with-tag: Exported macros
Macro, with-xml-output: Exported macros

R
rss-channel-header: Exported functions
rss-item: Exported functions

S
simple-tag: Exported functions
start-tag: Internal functions

W
with-indent: Internal macros
with-rss2: Exported macros
with-simple-tag: Exported macros
with-tag: Exported macros
with-xml-output: Exported macros
write-escaped: Internal functions

X
xml-as-is: Exported functions
xml-out: Exported functions

Jump to:   E   F   I   M   R   S   W   X  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*char-escapes*: Internal special variables
*entities*: Internal special variables
*indent*: Internal special variables
*whitespace*: Internal special variables
*xml-output-stream*: Internal special variables

S
Special Variable, *char-escapes*: Internal special variables
Special Variable, *entities*: Internal special variables
Special Variable, *indent*: Internal special variables
Special Variable, *whitespace*: Internal special variables
Special Variable, *xml-output-stream*: Internal special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   P   S   X  
Index Entry  Section

P
Package, xml-emitter: The xml-emitter package
Package, xml-emitter-system: The xml-emitter-system package

S
System, xml-emitter: The xml-emitter system

X
xml-emitter: The xml-emitter system
xml-emitter: The xml-emitter package
xml-emitter-system: The xml-emitter-system package

Jump to:   P   S   X