[comment {-*- tcl -*- doctools manpage}]
[manpage_begin page_util_quote n 1.0]
[copyright {2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>}]
[moddesc   {Parser generator tools}]
[titledesc {page character quoting utilities}]
[category  {Page Parser Generator}]
[require page::util::quote [opt 0.1]]
[require snit]
[keywords page quoting {parser generator} {text processing}]
[description]
[para]

This package provides a few utility commands to convert characters
into various forms.

[section API]

[list_begin definitions]
[call [cmd ::page::util::quote::unquote] [arg char]]

A character, as stored in an abstract syntax tree by a PEG processor
(See the packages [package grammar::peg::interpreter],
[package grammar::me], and their relations), i.e. in some quoted form,
is converted into the equivalent Tcl character. The character is returned
as the result of the command.

[call [cmd ::page::util::quote::quote'tcl] [arg char]]

This command takes a Tcl character (internal representation) and
converts it into a string which is accepted by the Tcl parser, will
regenerate the character in question and is 7bit ASCII. The string is
returned as the result of this command.

[call [cmd ::page::util::quote::quote'tclstr] [arg char]]

This command takes a Tcl character (internal representation) and
converts it into a string which is accepted by the Tcl parser and will
generate a human readable representation of the character in question.
The string is returned as the result of this command.

[para]

The string does not use any unprintable characters. It may use
backslash-quoting. High UTF characters are quoted to avoid problems
with the still prevalent ascii terminals. It is assumed that the
string will be used in a double-quoted environment.

[call [cmd ::page::util::quote::quote'tclcom] [arg char]]

This command takes a Tcl character (internal representation) and
converts it into a string which is accepted by the Tcl parser when
used within a Tcl comment. The string is returned as the result of
this command.

[list_end]

[section {BUGS, IDEAS, FEEDBACK}]

This document, will undoubtedly contain bugs and other problems.

Please report such in the category [emph page] of the
[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}].

Please also report any ideas for enhancements you may have.

[manpage_end]