[adobe-source-commits] sandbox/adobe-source/adobe/documentation/sources/asl xstr.dox,NONE,1.1

[Foster B. <fos...@us...>]

Update of /cvsroot/adobe-source/sandbox/adobe-source/adobe/documentation/sources/asl
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv25640/adobe/documentation/sources/asl

Added Files:
	xstr.dox 
Log Message:
xstr initial commmit.

--- NEW FILE: xstr.dox ---
/*!
\class adobe::xstr_t xstr.hpp <adobe/xstr.hpp>
\ingroup asl_libraries

\brief A context-sensitive string lookup system (pronounced 'x-string')

\par Model Of:
	- \ref concept_regular_type

\note
The xstr class is thread safe when compiled with BOOST_HAS_THREADS defined.

\todo (fbrereto) The language code should be obtained at runtime instead of hard-coded to 'en-us'

\section context Context Lookup

\subsection context_overview Overview

The context of a string is a runtime evaluated collection of information about the state of the machine and the xstr that we currently care about. This context is gathered from several locations:

	-# the context defaults of the xstr system
	-# the static attributes of the xstr definition
	-# a client-passed dictionary of additional context information

The context defaults of the xstr system can be set by the client of the library. It is important to know that context already exists here for the xstr system. These pieces are:
	- lang		:	defaults to 'en-us'
	- platform	:	defaults to 'macintosh', 'windows', or 'unknown' depending on the platform on which the library was compiled.

The static attributes of the xstr definition also provide context. Example:
\verbatim
<xstr id='hello_world' lang='es-sp'>Hola, mundo!</xstr>
\endverbatim

In the above example the two bits of context are 'id' and 'lang'. These override specific context information as outlined in the "Context Merging" section.

Finally, the client can also pass in an adobe::dictionary_t with runtime-obtained context information. This is useful when you have both static information provided by the xstr defintion directly, as well as context information that can only be obtained at runtime. The runtime context overrides specific context information as outlines in the "Context Merging" section.

\subsection context_merging Merging
There are several context merges that take place in the use of the xstr system. Context merges are necessary because there are several places from which the context of a string is gathered, and conflicting pieces of context must be resolved before the string can be imported into or looked up in the xstr glossary.

\subsubsection context_merging_import Importing Into the Glossary
When importing into the glossary (either an append or an assign), the following contexts take precedence in the following order:
	-# static context defined in the xstr
	-# xstr system default context

\subsubsection context_merging_lookup_static Lookup with Static Context
When looking up an xstr in the glossary with only the static context of the xstr taken into account, the following contexts take precedence in the following order:
	-# static context defined in the xstr
	-# xstr system default context

\subsubsection context_merging_lookup_runtime Lookup with Runtime Context
When looking up an xstr in the glossary with the static context of the xstr and the runtime context taken into account, the following contexts take precedence in the following order:
	-# runtime defined context in the adobe::dictionary_t
	-# static context defined in the xstr
	-# xstr system default context
*/

/*!
\typedef adobe::xstr_t::parse_range_t

The range [first, second) that the parser will use to fill the content of the lookup glossary. 
*/

/*!
\fn adobe::xstr_t::xstr_t(const char* xstr)

\param xstr the NTBS static xstr definition to be used for string lookup

This is one of the constructors you want to use if you have only compile-time context. The context is the attribute set defined in the xstr.
*/

/*!
\fn adobe::xstr_t::xstr_t(const char* xstr, std::size_t n)

\param xstr the static xstr definition to be used for string lookup
\param n the length of the xstr string

This is one of the constructors you want to use if you have only compile-time context. The context is the attribute set defined in the xstr.
*/

/*!
\fn adobe::xstr_t::xstr_t(const char* xstr, std::size_t n, const adobe::dictionary_t& context)

\param xstr the static xstr definition to be used for string lookup
\param n the length of the xstr string
\param context Additional context obtained at runtime for use in string lookup

Takes an xstr and an additional dictionary_t whose contents are additional context arguments that will augment the compile-time context found in the xstr. The dictionary arguments will replace the compile-time context if the keys are the same.
*/

/*!
\fn const char* adobe::xstr_t::get() const

\return
The content of the xstr after glossary lookup as UTF-8. If no string was found to be the closest match, this returns the default string as defined by the xstr. The empty string is a valid default string. The result of this function will always be a valid string pointer.
*/

/*!
\fn void adobe::xstr_t::set_default_context(const adobe::dictionary_t& context)

\param context Runtime-obtained context to be used as default context information.

Sets the default context of the xstr glossary system. Every xstr parsed after this call is made will have the default context imposed upon it. Note that this is done at the time of the parse, not at the time of the lookup, so it is possible to have a parsed glossary with xstr values that originated with differing default contexts. Therefore it is highly recommended to set the default context once, and to do so before you begin populating the xstr glossary.
*/

/*!
\fn adobe::dictionary_t adobe::xstr_t::get_default_context()

\return
	A dictionary containing the default context information currently stored in the xstr system.
*/

/*!
\fn void adobe::xstr_t::assign_glossary(const parse_range_t& parse_range)

\param parse_range The range of text the parser will traverse when assigning the contents of the lookup glossary

This completely replaces the contents of the glossary in the xstr system.
*/

/*!
\fn void adobe::xstr_t::append_glossary(const parse_range_t& parse_range)

\param parse_range The range of text the parser will traverse when appending in the contents of the lookup glossary

\todo (fbrereto) Right now the augmentation of the glossary will not replace strings already found in the glossary. This should not be the case (i.e., new strings that are identical to ones already in the glossary should replace the old one.) This also means that inside the glossary to parse, for the time being, specializations of a string should come BEFORE the general result for a string.
*/