#lang scribble/doc
@; THIS FILE IS GENERATED
@(require scribble/manual)
@(require (for-label (planet neil/xexp:1:=0)))
@(require (for-label racket))
@title[#:version "0.1"]{@bold{xexp}: SXML/xexp Representation of XML and HTML in Racket}
@author{Neil Van Dyke}


License: @seclink["Legal" #:underline? #f]{LGPL 3} @(hspace 1) Web: @link["http://www.neilvandyke.org/racket-xexp/" #:underline? #f]{http://www.neilvandyke.org/racket-xexp/}

@defmodule[(planet neil/xexp:1:=0)]

      

@section{Introduction}


      

@emph{Note: This package is in a state of active development, and some interface changes, perhaps not backward-compatible, are expected. Documentation is gravely lacking.}


      

@link["http://pobox.com/~oleg/ftp/Scheme/SXML.html"]{SXML} is a representation for XML in Scheme, defined by Oleg Kiselyov. ``SXML/@emph{xexp}'' is the temporary name for a format for Racket that's based on SXML and is mostly compatible with it.  The current plan is, hopefully, for the ``/@emph{xexp}'' part of the name to go away, and for SXML and @emph{xexp} to merge.  For now, Racket language identifiers based on SXML/@emph{xexp} will have ``@tt{xexp}'' instead of ``@tt{sxml}'', because we do not want to call something ``SXML'' if it is not strictly SXML. (And, historically, @emph{xexp} was much more different from SXML, while we experimented with unifying SXML, SHTML, and PLT @emph{xexpr}, but we have decided to move back to as compatible with SXML as practical.)  This documentation will be fleshed out in a later version of the SXML/@emph{xexpr} tools.


    
      

@section{xexp and SXML Tools}


      

Libraries using @emph{xexp} include:


      

@itemize[

@item{@link["http://www.neilvandyke.org/racket-html-parsing/"]{html-parsing}
            

Permissively parsing HTML to @emph{xexp}.


          }


@item{@link["http://www.neilvandyke.org/racket-html-writing/"]{html-writing}
            

Writing HTML from @emph{xexp}.


          }


@item{@link["http://www.neilvandyke.org/racket-html-template/"]{html-template}
            

Writing HTML from @emph{xexp} templates.


          }


@item{@link["http://www.neilvandyke.org/webscraperhelper/"]{WebScraperHelper}
            

Example-based SXPath query generation for @emph{xexp}.


          }



]


      

There are also libraries for SXML, which generally can be used for @emph{xexp}:


      

@itemize[

@item{@link["http://okmij.org/ftp/Scheme/xml.html#SXPath"]{SXPath}
            

XPath query language implementation for SXML, by Oleg Kiselyov.


          }


@item{@link["http://celtic.benderweb.net/sxml-match/"]{sxml-match}
            

Pattern-matching of SXML, by Jim Bender.


          }


@item{@link["http://www196.pair.com/lisovsky/xml/ssax/"]{SSAX}
            

Parsing of XML to SXML, by Oleg Kiselyov, and maintained by Kirill Lisovsky.


          }



]


    
      

@section{Definitions}


      

Some definitions used by many SXML/@emph{xexp} packages...



      
        

@subsection{Exceptions}


        

@defproc[ (make-invalid (xexp-exc any/c)) any/c]{
            

!!!


          }

        

@defproc[ (raise-invalid-xexp-error) any/c]{
            

!!!


          }

      

      
        

@subsection{Misc.}


        

The following definitions are used by some @emph{xexp}-related libraries.


        

@defproc[ (make-xexp-char-ref (val any/c)) any/c]{
            

Yields an @emph{xexp} character entity reference for @schemevarfont{val}.  For example:


            

@SCHEMEBLOCK[
(make-xexp-char-ref "rArr")                  ==> (& rArr)
(make-xexp-char-ref (string->symbol "rArr")) ==> (& rArr)
(make-xexp-char-ref 151)                     ==> (& 151)
]


          }

        

@defproc[ (xexp-char-ref-value (obj any/c)) any/c]{
            

Yields the value for the @emph{xexp} entity @schemevarfont{obj}, or @tt{#f} if @schemevarfont{obj} is not a recognized entity.  Values of named entities are symbols, and values of numeric entities are numbers.  An error may raised if @schemevarfont{obj} is an entity with system ID inconsistent with its public ID.  For example:


            

@SCHEMEBLOCK[
(define (f s) (xexp-char-ref-value (cadr (html->xexp s))))
(f " ")  ==> nbsp
(f "ߐ") ==> 2000
]


          }

      
    
      

@section{History}


      

@itemize[

@item{Version 0.1 --- 2011-08-21 --- PLaneT @tt{(1 0)}
            

Part of forked development from HtmlPrag.


          }



]


    

@section[#:tag "Legal"]{Legal}



Copyright (c) 2011 Neil Van Dyke.  This program is Software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License (LGPL 3), or (at your option) any later version. This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.  See http://www.gnu.org/licenses/ for details.  For other licenses and consulting, please contact the author.



@italic{@smaller{Standard Documentation Format Note: The API
signatures in this documentation are likely incorrect in some regards, such as
indicating type @tt{any/c} for things that are not, and not indicating when
arguments are optional.  This is due to a transitioning from the Texinfo
documentation format to Scribble, which the author intends to finish
someday.}}