~kiithsacmp/miniini/trunk : contents of README.html at revision 94

~kiithsacmp/miniini/trunk : (revision 94)

48 by Ferdinand Majerech Done the last changes for the 0.7 release	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<HTML>
	3	<HEAD>
	4	<META NAME="generator" CONTENT="http://txt2tags.sf.net">
	5	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8">
	6	<LINK REL="stylesheet" TYPE="text/css" HREF="doc/docstyle.css">
91 by Ferdinand Majerech Done last changes before the 0.9 release	7	<TITLE>MiniINI version 0.9.0</TITLE>
48 by Ferdinand Majerech Done the last changes for the 0.7 release	8	</HEAD>
	9	<BODY>
	10
	11	<DIV CLASS="header" ID="header">
91 by Ferdinand Majerech Done last changes before the 0.9 release	12	<H1>MiniINI version 0.9.0</H1>
48 by Ferdinand Majerech Done the last changes for the 0.7 release	13	</DIV>
	14
	15	<DIV CLASS="body" ID="body">
	16	<H2>Introduction</H2>
	17	<P>
88 by Ferdinand Majerech Rewrote README.txt to improve readability	18	MiniINI is a free/open source, minimalistic, easy to use C++ library for reading
	19	INI (aka CFG) files. It has no dependencies other than the standard library and
	20	should compile on any platform with a standards compliant compiler with C99
	21	support. (only a makefile for GCC is included at the moment, though)
48 by Ferdinand Majerech Done the last changes for the 0.7 release	22	</P>
	23	<P>
	24	Main priority of MiniINI is, as its name suggests, minimalism and speed. Its
88 by Ferdinand Majerech Rewrote README.txt to improve readability	25	goal is to create fastest INI parser possible without sacrificing ease of use.
	26	MiniINI should be especially useful for game development, for instance game
	27	settings, properties of units in strategy games, etc. MiniINI is already very
	28	fast. It takes under 50 ms to load, parse and unload an INI file about 1MB large
	29	with 512 sections according to benchmarks. This is on a ~1.7 GHz dual-core
	30	machine (although MiniINI can only use one core).
	31	</P>
	32	<P>
	33	MiniINI can also check files it reads, and issue warnings for the most common
	34	mistakes in ini code. This should be useful mainly for users of programs based
	35	on MiniINI, for instance game modders.
	36	</P>
	37	<P>
	38	At the moment, MiniINI can only read INI files, not write to them. This should
48 by Ferdinand Majerech Done the last changes for the 0.7 release	39	change in future versions.
	40	</P>
	41	<P>
88 by Ferdinand Majerech Rewrote README.txt to improve readability	42	You can get newest versions of MiniINI at miniini.tuxfamily.org .
48 by Ferdinand Majerech Done the last changes for the 0.7 release	43	</P>
	44	<H3>INI file format</H3>
	45	<P>
	46	INI files are text files containing simple values formatted as tag=value pairs,
	47	for example:
	48	</P>
	49	<PRE>
	50	answer=42
	51	</PRE>
	52	<P>
88 by Ferdinand Majerech Rewrote README.txt to improve readability	53	These are grouped in sections which start by headers containing names in square
	54	brackets, for example:
48 by Ferdinand Majerech Done the last changes for the 0.7 release	55	</P>
	56	<PRE>
	57	[section]
	58	</PRE>
	59	<P>
88 by Ferdinand Majerech Rewrote README.txt to improve readability	60	INI files can contain comments, which are ignored. Comments usually start by a
	61	semicolon (default in MiniINI) or hash and continue to the end of line. Example:
48 by Ferdinand Majerech Done the last changes for the 0.7 release	62	</P>
	63	<PRE>
	64	tag=value ;comment
	65	</PRE>
	66	<P>
88 by Ferdinand Majerech Rewrote README.txt to improve readability	67	A simple complete INI file example:
48 by Ferdinand Majerech Done the last changes for the 0.7 release	68	</P>
	69	<PRE>
	70	[General]
	71	OS=Linux
	72	Version=0.4
	73	Renderers=OpenGLRenderer, SWRenderer
	74	CurrentRenderer=OpenGLRenderer
	75
	76	[OpenGLRenderer]
	77	ScreenWidth=1024
	78	ScreenHeight=768
	79	UseShaders=true
	80	</PRE>
	81	<P></P>
	82	<H2>Features</H2>
87 by Ferdinand Majerech Updated features list and split it into groups	83	<H4>INI parsing</H4>
48 by Ferdinand Majerech Done the last changes for the 0.7 release	84	<UL>
87 by Ferdinand Majerech Updated features list and split it into groups	85	<LI>Reads from INI/CFG files, or from user provided buffer containing contents
	86	of an INI/CFG file. This allows the user e.g. to load data from a compressed
	87	file and pass it to MiniINI.
	88	<LI>Can read headerless ini/cfg files.
	89	<LI>Only plain ASCII files are supported. There is no support for Unicode, and
	90	there probably never will be.
48 by Ferdinand Majerech Done the last changes for the 0.7 release	91	<LI>Case-sensitive. That means that [CASE], [case] and [Case] are not the same
	92	and there is a difference between Tag= and TAG=
87 by Ferdinand Majerech Updated features list and split it into groups	93	<LI>Ignores all spaces, i.e. no spaces/tabs in tags or values. For example: +
	94	+
	95	tag=125685 +
	96	and +
	97	t a g = 125 685 +
	98	+
	99	both have the same meaning. Spaces _might_ be supported in the future for values,
	100	if there will be a need, but are not planned at the moment.
48 by Ferdinand Majerech Done the last changes for the 0.7 release	101	<LI>Can read arrays of data from tags with multiple, comma separated values.
88 by Ferdinand Majerech Rewrote README.txt to improve readability	102	<LI>Can also read arrays from numbered sequences of tags, for example:
48 by Ferdinand Majerech Done the last changes for the 0.7 release	103	+
	104	+
	105	a1=1 +
	106	a2=2 +
	107	a3=3 +
	108	+
87 by Ferdinand Majerech Updated features list and split it into groups	109	<LI>Cannot write to ini files at this time. This should be implemented in future.
	110	</UL>
	111
	112	<H4>Interface</H4>
	113	<UL>
88 by Ferdinand Majerech Rewrote README.txt to improve readability	114	<LI>Provides methods to read strings, ints, floats and bools from inifile
	115	and checks the ini data for errors, allowing the programmer to use
	116	their own default values.
48 by Ferdinand Majerech Done the last changes for the 0.7 release	117	<LI>Supports both plain strings and arrays and STL strings and vectors. STL
	118	functionality can be disabled for more minimalism.
87 by Ferdinand Majerech Updated features list and split it into groups	119	<LI>Supports iteration over contents of INI files.
	120	</UL>
	121
	122	<H4>Configurability</H4>
	123	<UL>
	124	<LI>Supports single line comments with a configurable comment character. So if you
	125	want to use # instead of ; , you can. There is no support for multiple
48 by Ferdinand Majerech Done the last changes for the 0.7 release	126	comment characters at the same time for performance reasons.
	127	<LI>Name=value separator is configurable as well, '=' by default.
87 by Ferdinand Majerech Updated features list and split it into groups	128	</UL>
	129
	130	<H4>Documentation</H4>
	131	<UL>
91 by Ferdinand Majerech Done last changes before the 0.9 release	132	<LI>Tutorials detailing every feature of the library.
	133	<LI>Maintained API documentation.
87 by Ferdinand Majerech Updated features list and split it into groups	134	</UL>
	135
	136	<H4>Performance</H4>
	137	<UL>
	138	<LI>Extremely fast. Even multi-MB ini files with hundreds or thousands of sections
	139	can be processed in fractions of a second.
	140	<LI>Low memory usage. Data structure overhead is reduced as much as possible.
	141	</UL>
	142
	143	<H4>Debugging</H4>
	144	<UL>
	145	<LI>Debug build can issue warnings to the user using a callback function
	146	specified by the programmer. For example when a tag from which the program
	147	tries to load an integer contains something else.
48 by Ferdinand Majerech Done the last changes for the 0.7 release	148	</UL>
	149
	150	<H2>New in this release</H2>
	151	<P>
91 by Ferdinand Majerech Done last changes before the 0.9 release	152	There are almost no changes to the interface in MiniINI 0.9 . However, all
	153	testing and benchmarking code was rewritten, some library code was refactored,
	154	and there was a fucus on improving documentation.
	155	</P>
	156	<P>
	157	Tutorials were rewritten to improve readability. The API documentation has also
	158	seen heavy changes. Many bugs were fixed and descriptions should now be more,
	159	well, descriptive.
	160	</P>
	161	<P>
	162	Allocator, INIFile and logging code was refactored.
	163	</P>
	164	<P>
	165	Regression testing code was completely rewritten, and should be more
	166	maintainable now.
	167	</P>
	168	<P>
	169	Benchmarking code was rewritten, separated from MiniINI code and more
	170	benchmarking functionality was added.
	171	</P>
	172	<P>
	173	All testing and benchmarking scripts were rewritten in Python 3.1 , and again
	174	the new code should be more maintainable.
	175	</P>
	176	<P>
	177	There were also some small bugfixes. See CHANGES.txt for more details.
55 by Ferdinand Majerech Fixed conflicts with windows.h, made minor changes and fixes. Finished changes for the 0.7.2 release.	178	</P>
48 by Ferdinand Majerech Done the last changes for the 0.7 release	179	<H2>Compiling/Installing/Using</H2>
	180	<H3>Directory structure</H3>
	181	<P>
	182	MiniINI files are split into multiple directories:
	183	</P>
	184	<PRE>
	185	./ (top-level directory) MiniINI include file and this readme.
	186
	187	./miniini MiniINI source code
	188
	189	./bin Compiled binary files, e.g. the library itself.
	190
88 by Ferdinand Majerech Rewrote README.txt to improve readability	191	./doc Documentation.
	192
	193	./example Example programs.
	194
	195	./test Files for regression tester and benchmark scripts.
48 by Ferdinand Majerech Done the last changes for the 0.7 release	196	</PRE>
	197	<P></P>
	198	<H3>Requirements</H3>
	199	<P>
	200	MiniINI should compile on any standards compliant C++ compiler, and requires no
88 by Ferdinand Majerech Rewrote README.txt to improve readability	201	third-party libraries. Basic C99 support is also required. If you have gcc,
	202	there is a GNU makefile tested with gcc 4.x , which should also work with older
	203	gcc versions.
48 by Ferdinand Majerech Done the last changes for the 0.7 release	204	</P>
	205	<P>
88 by Ferdinand Majerech Rewrote README.txt to improve readability	206	MiniINI also includes benchmarking scripts, which require Python and Valgrind to
	207	run. These scripts are not necessary to compile or use MiniINI and are used for
	208	development of MiniINI.
48 by Ferdinand Majerech Done the last changes for the 0.7 release	209	</P>
	210	<H3>Compiling/Installing with gcc</H3>
	211	<P>
88 by Ferdinand Majerech Rewrote README.txt to improve readability	212	Type <U>make</U> in terminal.
	213	You can now link to compiled libraries (in ./bin) directly, or, if you're on
	214	a Linux/Unix system, you can install MiniINI by typing <U>make install</U> as a
	215	root user (e.g. <U>sudo make install</U> if you have sudo) This will compile and
	216	copy optimized build to <U>/usr/lib/libminiini.a</U> , debug build to
	217	<U>/usr/lib/libminiini-dbg.a</U> , and MiniINI headers to <U>/usr/include/</U>.
	218	</P>
	219	<P>
	220	Debug and optimized builds can also be compiled separately using <U>make debug</U>
	221	and <U>make optimized</U> .
	222	</P>
	223	<P>
	224	You can uninstall MiniINI by typing <U>make uninstall</U> as a root user.
48 by Ferdinand Majerech Done the last changes for the 0.7 release	225	</P>
	226	<H3>Using MiniINI</H3>
	227	<P>
88 by Ferdinand Majerech Rewrote README.txt to improve readability	228	First, you will need to include <U>miniini.h</U> header file and link with either
	229	debug or optimized build. To include MiniINI, add this line to your code:
48 by Ferdinand Majerech Done the last changes for the 0.7 release	230	</P>
	231	<PRE>
	232	#include<miniini.h>
	233	</PRE>
	234	<P>
	235	To link with MiniINI using GCC, add this to your compiler options:
	236	</P>
	237	<PRE>
	238	-lminiini
	239	</PRE>
	240	<P>
	241	for optimized or
	242	</P>
	243	<PRE>
	244	-lminiini-dbg
	245	</PRE>
	246	<P>
	247	for debug build.
	248	</P>
	249	<P>
88 by Ferdinand Majerech Rewrote README.txt to improve readability	250	If you didn't install MiniINI, you'll also need to add path with <U>miniini.h</U>
	251	to header paths of your compiler and path with <U>libminiini.a</U> and/or
	252	<U>libminiini-dbg.a</U> to linker paths.
48 by Ferdinand Majerech Done the last changes for the 0.7 release	253	</P>
	254	<P>
88 by Ferdinand Majerech Rewrote README.txt to improve readability	255	For more info you can check <A HREF="doc/index.html">tutorials and API documentation</A>
	256	in <U>./doc</U> directory and examples in <U>./example</U> directory.
48 by Ferdinand Majerech Done the last changes for the 0.7 release	257	</P>
	258	<H2>License</H2>
	259	<P>
88 by Ferdinand Majerech Rewrote README.txt to improve readability	260	MiniINI is free/open source software distributed under the MIT/X11 license. This
	261	license allows you to use MiniINI in both open and closed source software, free
	262	of charge, and modify it if you need to.
48 by Ferdinand Majerech Done the last changes for the 0.7 release	263	</P>
	264	<P>
	265	Full text of the license:
	266	</P>
	267	<PRE>
	268	Copyright (c) 2009-2010 Ferdinand Majerech
	269
	270	Permission is hereby granted, free of charge, to any person
	271	obtaining a copy of this software and associated documentation
	272	files (the "Software"), to deal in the Software without
	273	restriction, including without limitation the rights to use,
	274	copy, modify, merge, publish, distribute, sublicense, and/or sell
	275	copies of the Software, and to permit persons to whom the
	276	Software is furnished to do so, subject to the following
	277	conditions:
	278
	279	The above copyright notice and this permission notice shall be
	280	included in all copies or substantial portions of the Software.
	281
	282	THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
	283	EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
	284	OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
	285	NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
	286	HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
	287	WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
	288	FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
	289	OTHER DEALINGS IN THE SOFTWARE.
	290	</PRE>
	291	<P></P>
	292	<H2>Contact/Credits</H2>
	293	<P>
88 by Ferdinand Majerech Rewrote README.txt to improve readability	294	MiniINI homepage: miniini.tuxfamily.org
	295	</P>
	296	<P>
	297	MiniINI Launchpad page: <A HREF="https://launchpad.net/miniini">https://launchpad.net/miniini</A>
48 by Ferdinand Majerech Done the last changes for the 0.7 release	298	</P>
	299	<P>
	300	MiniINI was created by Ferdinand Majerech aka Kiith-Sa kiithsacmp[AT]gmail.com
	301	</P>
	302	<P>
88 by Ferdinand Majerech Rewrote README.txt to improve readability	303	MiniINI was created using Vim and GCC on Ubuntu Linux, as an INI parsing
48 by Ferdinand Majerech Done the last changes for the 0.7 release	304	library for Catom <A HREF="https://launchpad.net/catom">https://launchpad.net/catom</A> .
	305	</P>
84 by Ferdinand Majerech Added modification dates to txt2tags files	306	<HR NOSHADE SIZE=1>
	307	<P></P>
	308	<P>
91 by Ferdinand Majerech Done last changes before the 0.9 release	309	<B>Last update: 09-07-2010</B>
84 by Ferdinand Majerech Added modification dates to txt2tags files	310	</P>
48 by Ferdinand Majerech Done the last changes for the 0.7 release	311	</DIV>
	312
	313	<!-- html code generated by txt2tags 2.5 (http://txt2tags.sf.net) -->
	314	<!-- cmdline: txt2tags -t html -v -\-encoding utf-8 -\-css-sugar -\-style doc/docstyle.css README.txt -->
	315	</BODY></HTML>