Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/rpgoldman/xmls

Simple, lightweight XML library for Common Lisp
https://github.com/rpgoldman/xmls

Last synced: 3 months ago
JSON representation

Simple, lightweight XML library for Common Lisp

Awesome Lists containing this project

README 

          



  XMLS: Common Lisp XML Parser



XMLS


Manual For Version 3



Summary




  Xmls is a small, simple, non-validating xml parser for Common Lisp.  It's

  designed to be a self-contained, easily embedded parser that recognizes a useful

  subset of the XML spec.  It provides a simple mapping from xml to lisp 

  structures or s-expressions and back.



Since XMLS was first released it has gained some additional

complications/features.  In particular:


    

      
  • 

    Now XMLS by default parses XML documents into lisp structures,

      rather than s-expressions.      This makes accessing the structures

      simpler and more reliable. See section on backward compatibility.
    • 

      
  • We have added clearly named accessors to further improve

      extraction of information from parsed XML.
    • 

      
  • Thanks to Max Rottenkolber, we now have the affiliated library,

      xmls/octets that will open streams for the XMLS parser,

      processing any content-type declarations in the process.
    • 




Features


    

      
  • 

        Free (BSD license).

      
    • 

      
  • 

        Understands enough of the xml spec to parse many common documents, including

        those occurring in common internet protocols like xml-rpc, webdav, and BEEP.

        Parses 85 out of the 98 valid documents in the oasis parser compliance suite.

      
    • 

      
  • 

        Small and easily embedded.  The entire parser is contained in one

        file and it's currently less than 600 lines of code.  Xmls is written in

        pure lisp and requires no external parsing tools or foreign libraries.

      
    • 

      
  • 

        Supports xml namespaces.

      
    • 

      
  • 

        Threadsafe.

      
    • 

      
  • 

        Serializes s-expr list structures back to xml as well as parsing xml.

      
    • 




Limitations


    

      
  • 

        Parses entire document into memory and consequently can't handle large

        documents.

      
    • 

      
  • 

        No detailed error reporting.

      
    • 

      
  • 

      Hand-built LR parser, meaning the parser structure is a little hard

      to understand, and can be hard to modify.  Use of CL-YACC or similar

      might be a preferable route for a rewrite.

      
    • 




XML Representation





  Parsed xml is represented as a nested lisp structure, unlike in the

  original version, where it was a lisp list.  The s-expression

  representation is still maintained, and there are functions to

  translate to and from this notation. 




XML representation as lisp structures



In the structure representation, a node, corresponding to an XML

element, is defined as follows:




(defstruct (node (:constructor %make-node))

  name

  ns

  attrs

  children)





  Xmls also includes a helper function, make-node for creating xml nodes

  of this form:





(make-node &key name ns attrs children)






  Xmls provides the corresponding accessor functions node-name, node-ns

  node-attrs, and node-children.




XML representation as s-expressions



In the s-expression representation, a node is represented as follows:




(name (attributes) children*)






  A name is either a simple string, if the element does not belong to a namespace,

  or a list of (name namespace-url) if the element does belong to a namespace.






  Attributes are stored as (name value) lists.






  Children are stored as a list of either element nodes or text nodes.






  For example, the following xml document:





<?xml version="1.0"?>

<!-- test document -->

<book title='The Cyberiad'>

  <!-- comment in here -->

  <author xmlns='http://authors'>Stanislaw Lem</author>

  <info:subject xmlns:info='http://bookinfo' rank='1'>&quot;Cybernetic Fables&quot;</info:subject>

</book>




Would parse as:




("book" (("title" "The Cyberiad"))

 (("author" . "http://authors") NIL "Stanislaw Lem")

 (("subject" . "http://bookinfo") (("rank" "1")) "\"Cybernetic Fables\""))




Backward Compatibility



To detect whether in this version of XMLS the return value of PARSE will be a

list or a structure, check for the feature :XMLS-NODES-ARE-STRUCTS.



For old code that wants XML parsed into lists, instead of

structures, you may replace calls to (parse str) with

(node->nodelist (parse str)).



For greater convenience, we offer PARSE-TO-LIST, which

performs the same function.



Usage





  The interface is straightforward.  The two main functions are

  PARSE and TOXML.





(parse source &key (compress-whitespace t) (quash-errors t)






  Parse accepts either a string or an input stream and attempts to parse the xml

  document contained therein.  It will return the s-expr parse tree if it's

  successful or nil if parsing fails.





  If COMPRESS-WHITESPACE is non-NIL, content nodes will be trimmed of whitespace and

  empty whitespace strings between nodes will be discarded.





(parse-to-list source (&rest args))




Functions as PARSE, but returns a list representation

of the XML document, instead of a structure.




(write-prologue xml-decl doctype stream)






  write-prologue writes the leading

  <?xml ... ?> and <!DOCTYPE ... >

  elements to stream.

  xml-decl is an alist of attribute name value pairs.

  Valid xml-decl attributes per the xml spec are "version", "encoding",

  and "standalone", though write-prologue does not verify this.

  doctype is a string containing the document type definition.





(write-prolog xml-decl doctype stream)





U.S. spelling alternative to write-prologue.





(write-xml xml stream &key (indent nil))






  write-xml accepts a lisp list in the format described above and writes the

  equivalent xml string to stream.  Currently, if nodes use namespaces xmls will not 

  assign namespaces prefixes but will explicitly assign the namespace to each node.  This

  will be changed in a later release.



  Xmls will indent the generated xml output if indent is non-nil.





(toxml node &key (indent nil))






  TOXML is a convenience wrapper around write-xml that returns the in a newly

  allocated string.




Translating to and from s-expressions



XMLS provides two exported functions to translate between the CL

structure representation of the XML tree and the s-expression

representation:




  
node->nodelist


  
Translate the structure representation into s-expressions.



  
nodelist->nodes


  
Translate the s-expression representation of an XMLS parse tree

  into lisp structures.





Helper functions



These are intended to allow programmers to avoid direct manipulation of the

 XMLS element representation.  If you use these, your code should be easier to

  read and you will avoid problems if there is a change in internal

  representation (such changes would be hard to even find, much less correct, if

  using the lists directly).





  




      make-xmlrep  (tag &key attribs children)

  

  


  
Constructor function.



  


    xmlrep-add-child! (xmlrep child)

  


  
Add a new child node to the XMLREP node.



  


    xmlrep-tag (xmlrep)

  


  
Extract the tag from XMLREP.



  


    xmlrep-tagmatch (tag treenode)

  


  
Returns true if TAG is the tag of TREENODE.  Match is

    case insensitive (quite possibly this is the Wrong Thing). 



  


    xmlrep-attribs (xmlrep)

  


  
Extract the attributes from an XMLREP node.



  


    xmlrep-children (xmlrep)

  


  
Extract the children from an XMLREP node.



  


    xmlrep-find-child-tags (tag treenode)

  


  


    Return all of the (direct) children of TREENODE whose tags are TAG.

    Matching done by xmlrep-tagmatch.

  


  

  


    xmlrep-find-child-tag (tag treenode &optional (if-unfound :error))

  


  


    Find a single child of TREENODE with TAG.  Returns an error

    if there is more or less than one such child.

  



  


    xmlrep-string-child (treenode &optional (if-unfound :error))

  


  


    Returns the single string-valued child of TREENODE.

    If there is more than one child, or if a single child is not

    a simple value, returns IF-UNFOUND, which defaults to :ERROR.

  



  


    xmlrep-integer-child (treenode)

  


  


    Find the single child of TREENODE whose value is a string that

    can be parsed into an integer.  Returns an

    error if there is more than one child, or if a single child is not

    appropriately valued.

  



  


    xmlrep-attrib-value (attrib treenode &optional (if-undefined :error))

  


  


    Find the value of ATTRIB, a string, in TREENODE.

    if there is no ATTRIB, will return the value of IF-UNDEFINED,

    which defaults to :ERROR.

  



  


    xmlrep-boolean-attrib-value (attrib treenode &optional (if-undefined :error))

  


  


    Find the value of ATTRIB, a string, in TREENODE.

    The value should be either "true" or "false".  The

    function will return T or NIL, accordingly.  If there is no ATTRIB,

    will return the value of IF-UNDEFINED, which defaults to :ERROR.

  





XMLS/Octets




XMLS itself simply processes strings or streams.  This means that it

does not provide native support for handling character encodings, as

declared in the XML headers.  The system xmls/octets,

which depends on xmls provides that support with the

exported function make-xml-stream, which takes an

octet-stream as argument, processes its header, choosing the

appropriate character encoding, and then returns a stream suitable for

passing to xmls:parse.



Probably make-xml-stream should be made generic, and support

arguments of other types (e.g., strings interpreted as filenames,

pathnames, etc.).



Installation





  xmls can be installed as an asdf system.  An asdf

  system definition is provided with the distribution.

 

Previous versions of XMLS were single files, and could be installed simply by

  loading the file xmls.lisp.  This option is no longer supported.


 

Contact Information
 

 

 

  Please contact Robert Goldman, rpgoldman AT sift.net with any 

  questions or bug reports.