Read Me

:::::::::::::::::::::::: Copyright 2008 Chris Kaynor ::::::::::::::::::::::::


::::::::::::::::::
:: PROGRAM INFO ::
::::::::::::::::::

Program Name........: kLibrary
Version.............: A0.0.4
License Type........: LGPL
OS..................: OS Portable
Release Date........: 5/20/2008
Languages...........: English/Language Independent
Website.............: http://sourceforge.net/projects/klibary
Download URL........: http://sourceforge.net/project/showfiles.php?group_id=228119
Source URL..........: http://klibary.svn.sourceforge.net/viewvc/klibary/

:::::::::::::
:: CONTACT ::
:::::::::::::

Author..............: Chris Kaynor
Email...............: chris@kaynor.net

:::::::::::::::::::::::::::::
:: DESCRIPTION or/and USES ::
:::::::::::::::::::::::::::::

An extension of C++ standardized libraries to provide functionality such as
factories, language loaders, and other fairly common functions. The code
will be designed to be thread-safe and easy-to-use.

:::::::::::
:: PARTS ::
:::::::::::

Common:
Description:
	The Common folder contains various items used in various other parts
	of the library, along with any items which do not cleanly fit into a
	larger category.
Usage:
	Various files have various usage properties. Please see the specific
	files below for more details.
Files:
	NoCopy.h
		Includes a class which explicitly declares the copy constructor
		and assignment operator as private, preventing any derived
		classes from being copied.

Factory:
Description:
	The Factory folder contains various classes used as part of a factory
	in which a specified item may be loaded multiple times, but each item
	with the same name will only be in memory once.
Usage:
	Include factory.h
	itemType should generally be derived from the factory::Item class.
Files:
	factory.h
		NOTE: This file will automatically include all other files
		that are part of this section.
		Contains the declaration for the factory template class. Use
		the load and unload functions to load and unload items. For
		advanced usage, see factory.h's information.
	factory.inl
		Contains the function definitions and code for the Factory
		class (as declared in factory.h).
	factoryItem.h
		Contains the declaration for the factory::Item class. This is
		an abstract base class intended to be the base for all
		classes used as the itemType template parameter for the
		Factory class.
	factoryItem.inl
		Contains the function definitions and code for the
		factory::Item class (as declared in factoryItem.h).
	factoryStorage.h
		Contains the declaration for the factory::_Storage class. This
		class is intended for internal use by the Factory class.
	factoryStorage.inl
		Contains the function definitions and code for the
		factory::_Storage class (as declared in factoryStorage.h).

XML:
Description:
	The XML folder contains files used to load and parse XML. XML may be
	either passed in as a standard template library string or be loaded
	directly from a file.
	NOTICE: This class cannot modify existing XML. It can only read it.
Usage:
	Include xml.h
	For Microsoft Visual Studio 2005, compile XML.vcproj and include the
		output lib as a dependency input for the linker. Otherwise,
		compile all files in the folder as a lib and include that lib
		as a dependency.
Files:
	xml.h
		NOTE: This file automatically includes all other header files
		that are part of this section.
		Contains the various type definitions and class prototypes
		required for the other files to function.
	attribute.h
		Includes a simple class to hold the name and value of any
		XML elements found within the file.
	document.cpp
		Contains the function definitions and code for the the XMLDocument
		class (as declared in document.h).
	document.h
		Contians the declaration of the XMLDocument class. Use the
		constructor or open* functions to parse XML, and the get*
		functions to read the XML.
	element.cpp
		Contains the function definitions and code for the XML::Element
		class (as declared in element.h).
	element.h
		Contains the declaration of the XML::Element class which stores
		element data for any elements found within the XML. Use the
		get*Child* functions to iterate though the tree, and the
		get*Attribute* functions to read any attributes contained
		in the XML element.
	XML.vcproj
		A Microsoft Visual Studio 2005 project which complies this
		section into a lib to be included as a linker dependency

Language:
Description:
	The language folder contains files used to load and parse KLanguage
	files.
Usage:
	Include language.h
	For Microsoft Visual Studio 2005, compile Language.vcproj and include
		the	output lib as a dependency input for the linker. Otherwise,
		compile all files in the folder as a lib and include that lib
		as a dependency.
	Create an object of the Internationalization class, either applying
		language list files and a language during initialization or by
		calling the appendLanguageList and setLanguage functions. To
		retrieve language-specific text from a set of KLanguage files,
		use the getValue function. See the description of the KLanguage
		format for information on how the parameters work.
Files:
	language.h
		NOTE: This file automatically includes all other header files
		that are part of this section.
		Contains the declaration of the Internationalization class. This
		class contains all required functionality to read in and parse
		KLanguage files.
	language.cpp
		Contains the function definitions for the Internationalization class
		(as declared in language.h)
	languageList.h
		Contains the declaration of the LanguageList class. This class holds
		information regarding the known languages and how to read the other
		files which contain the specific codes and their values.
	languageList.cpp
		Contains the function definitions for the LanguageList class.(as
		declared in languageList.h).
	languageSet.h
		Includes a simple class to hold the name and extension codes for
		the various languages loaded from KLanguage list files.

::::::::::::::::
:: WHAT'S NEW ::
::::::::::::::::

Changes from version A0.0.4:
	The factory now has an additional template parameter which allows for changing the
		storage type. Old code should still work, however this will allow developers to
		use a subclassed storage to make the factory into an abstract factory.

Changes from version A0.0.3:
	Language:
		It is now possible to get values for languages other than the current language.
		It is now possible to preload all currently loaded sets for the current language.
		It is now possible to set the default language to be used if a language is accessed
			which is not known, rather than always using the the "" language (*.int).
		Documentation has been added for the language section, along with documentation
			for the KLanguage file structure.
		Changing the language after already having sets loaded will no longer cause a
			run-time error when a previously loaded set is accessed.
		The preload language feature will now preload the correct language rather than the
			current language.

Changes from version A0.0.2:
	Added the Language section. See above and Language/language.h for additional details.
	Some additional Visual Studio projects have been added to the library to improve
		ease-of-use.
	Common:
		NoCopy.h has been renamed to noCopy.h.

Changes from version A0.0.1:
	Added the XML section. See above and XML/xml.h for additional details.
	Factory:
		Added the getBegin() and getEnd() functions to give additional
		access into the storage hash table.

::::::::::::::::
:: CHANGE LOG ::
::::::::::::::::

A0.0.6:
	The language library now has the option of having an open file handler which can redirect
		the file paths used to load the language files.
	The language library now has the option of having a code not found handler which can
		process cases where a code is requested by is not found in the language files.

A0.0.5:
	The factory now has an additional template parameter which allows for changing the
		storage type. Old code should still work, however this will allow developers to
		use a subclassed storage to make the factory into an abstract factory.

A0.0.4:
	It is now possible to get values for languages other than the current language.
	It is now possible to preload all currently loaded sets for the current language.
	It is now possible to set the default language to be used if a language is accessed
		which is not known, rather than always using the the "" language (*.int).
	Documentation has been added for the language section, along with documentation
		for the KLanguage file structure.
	Changing the language after already having sets loaded will no longer cause a
		run-time error when a previously loaded set is accessed.
	The preload language feature will now preload the correct language rather than the
			current language.
	A few minor warnings have been fixed.

A0.0.3
	Renamed all *_code.h files to *.inl files.
	Renamed NoCopy.h to noCopy.h to better comply with the naming conventions.
	Renamed files using an underscore in their name to be in lower camel case.
	Added the Language section which is designed to implement a multilingual
		solution which loads data from external files and should be scalable
		to a very large number of languages.

A0.0.2
	Added the XML section which reads and parses XML.
	Added the ability to directly access the hash table of the factory.

A0.0.1
	Added additional documentation to all files.
	Added the ability to rename items already loaded into the factory.
		See the renameItem function of the Factory class.
	Added proper documentation of the license agreement (LGPL), along
		with copyright statements.
	Added a read-me file.
	Fixed a spelling error thoughout the files where library was spelt as
		"libary". All instances of this mistake have been fixed. Any
		programs using the old spelling will now need to be updated.

A0.0.0
	Initial Release
	Added the factory section. See Factory\factory.h for details.
	Added the NoCopy class to the Common section. See Common\NoCopy.h for
		details.

:::::::::::::
:: LICENSE ::
:::::::::::::

This file is part of kLibrary.

kLibrary is free 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, or(at your option) any
later version.

kLibrary 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 the GNU Lesser General Public License for more
details.

You should have received a copy of the GNU Lesser General Public License.

:::::::::::::::::::::::: Copyright 2008 Chris Kaynor ::::::::::::::::::::::::