ini.library documentation (html)

ini.library

ini.library is a shared Amiga library providing easy creation, access and maintenance of ASCII based preference files.

Introduction	Background, features and examples.
Contents	What's in the archive.
Disclaimer	Important reading!
Installing	How to install the components.
Usage	How to benefit from the advantages.
History	History of the development.
Authors	Contact and support!
Seasons	Surprisingly fruity!

Introduction

The Amiga had no easy way of handling settings - - most people created their own, non-standard fileformat for storing settings. We got iffparse.library, which helped a bit - - however not enough.

We know that the majority of Amiga owners like to customize applications according to their own taste and feel. The structure of the Workbench taught us this, seeing as today there exists a vast amount of patches we can apply to our beloved OS.

It's a love/hate relationship - - we don't like that it HAVE to be that way, but on the other hand we like to be in control of our OS. As you know, the original OS distribution left little room for customization.

Anyway, I digress.

As a user, you like to have control of the applications by customizing them to your own needs and taste.

As a software vendor, you like that users are in control, but you're not too happy about coding a full-fledged prefs editor in the last minute before the release.

ini.library will solve your problems!

Advantages:

You won't need to code a prefs GUI in the last minute - - The users can simply edit settings using their favourite text-editor! Ofcourse you may additionally code a prefs GUI (that handles settings through ini.library), but now you got more time to spend on it - - making it great!
The library, being a standard shared Amiga library, gives you full control of prefs settings - you may choose to go the easy way (basic functions), or a more complex way (even more control of your settings-file!)
You won't worry about incompability with older versions of your program's settings - - Just ignore and/or delete the settings unused in your new version! No more "remember to convert your old settings file or else this program will crash!" incidents.

Key features for the programmer:

Handles longs, words (ints) and bytes (chars)!
Handles decimal, hexadecimal, binary and octal numbers!
Handles strings!
Handles simple floating point numbers!
Handles field-arrays, to use in e.g. palettes!
Handles C-style comments and one-line assembler style comments! Comments are even preserved when editing the fields!
Easy access for quick handling, or Complex access for complete control!

Look at Examples/Example.INI to see an example of an ini file!

Contents

Contents of ini.library archive.

AutoDoc/	AutoDocs for ini.library, text and Guide versions.
Docs/	AmigaGuide and HTML docs.
Examples/	Example sourcecode in C and Assembler.
fd/	Function descriptor file.
Include/	Include files for C and Assembler.
Libs/	The ini.library itself and a brief ReadMe file�

� This ReadMe file must accompany any software that distributes ini.library as a single file. It informs users on where to get the full ini.library distribution.

Disclaimer

A copy of the Thor License Agreement, made valid for ini.library.

Seasons has made every effort possible to ensure that ini.library will function as described, but no warranty of any kind, expressed or implied, is made by us. Seasons will not be liable for any direct or indirect damages to either machinal equipment or mental health arising from a failure of the program to operate in the manner desired by the user. In no event will we be liable for any loss of profits or savings.

AMIGAGUIDE SOFTWARE IS PROVIDED "AS-IS" AND SUBJECT TO CHANGE; NO WARRANTIES ARE MADE. ALL USE IS AT YOUR OWN RISK. NO LIABILITY OR RESPONSIBILITY IS ASSUMED.

This ini.library distribution is Copyright � 1999-2000 Seasons. All Rights Reserved. Patching, reassembling or any other modification prohibited. This archive may NOT be sold for profit without written permission from Seasons. Only a modest post & package fee is allowed. You are however allowed to use and distribute the libs: (and readme!) file with your own programs, non-commercial or commercial without paying royalties.

If you agree with these conditions, you may proceed to install the software. If not, we kindly ask you not to install the software, and delete the archive.

Installing

How to install the components.

User install

Simply copy the file libs/ini.library to your LIBS: directory! For applications that supports it, you can now edit it's settings using your favourite text editor!

Installing upgrades

To install an upgraded version of ini.library, overwrite the existing library with the new one, and either type "flushlibs" in Shell or reboot your Amiga.

Developer install

From	To
libs/ini.library	LIBS:
AutoDoc/ini.doc	Your common AutoDocs directory.
fd/ini.fd	Your common FD directory.
include/clib/ini_protos.h	INCLUDE:clib/
include/libraries/ini_lib.h	INCLUDE:libraries/
include/libraries/ini_lib.i	INCLUDE:libraries/
include/pragmas/ini_pragmas.h	INCLUDE:pragmas
include/proto/ini.h	INCLUDE:proto/
Remaining files	Wherever you want!

Now you're ready to either run applications that utilizes ini.library, or starting to incorporate ini's power into your C / C++ or Asm sourcecode!

Usage

An "ini" file (Initialization file) is built up as follows:

[Context]

Item1 = Value1
Item2 = Value1, Value2, Value3, Value4, Value5
Item3 = Float1

[Context2]

Item1 = Float1
...

Here's the basic operation on ini files:

1. open a default ini file. (You may even specify a buffer to use as a default file that will be created and processed)
2. get context.
3. get values of items related to this context. (Store the values in your own variables)
4. close ini file.

To create or modify an ini file, you're able to add, remove and modify contexts and items to your liking. Even "TRUE/FALSE" or "YES/NO" values are implemented, making your setting file easy to read for users!

Have a look at the file Examples/src/C/INI_Example.C to see the C sourcecode of how to use ini.library.

History

Most recent version is always on the top of the list.

v32.01 (08 Aug 2000)

Autodocs are finally up to date.
Added Amigaguide version of Autodocs.

v32.00 (22 Jul 2000)

Bug fix: ini.library would crash using empty contexts or empty files.
Bug fix: iniGetStr() did not allocate string.
Bug fix: iniCreateContext() did not set brackets and linefeed in the line buffer.
Bug fix: iniPutxxxA() did not check for valid context item.
iniPutxxxA() now expands data array if required.
iniReadxxx() now acccepts NULL pointer as context name. In this case the functions scan through all contexts.
iniWritexxx() now now creates a context or context item if nonexistant.

v31.02 (06 Sep 1999)

Tidied up some includes. Added inline/ includefile.
Fixed a few minor bugs in example sources.
Added Bin2Hex utility.

v31.00 (13 Aug 1999)

First public release.

Authors

All library code, examples and AutoDocs by
Sebastian "Basty" Vater

AmigaGuide and HTML documentation by
Lloyd Rosen

Bug reports, suggestions and flowers ? Please send to
Basty (cdgs.basty@usa.net)
or
Seasons (seasons@softhome.net)

Basty is currently working on TuComposer, a revolutionary piece of audio software! Read more about it at our website www.lobster.demon.nl

Seasons

Seasons is a creative software development team with a goal of creating more quality software - - games and applications - - for the Amiga. The products we release are strictly non-commercial, except for a modest shareware fee whenever appropriate.

We have a number of projects under development:

Balls (working title). Yet Another Addictive Puzzle Game. With a twist.
TuComposer.A winning, extremely powerful and flexible audio system and tracker which will be available for multiple platforms!
Midland (working title). A CRPG (Arcade based RPG) game inspired by Final Fantasy Trilogy and Chrono Trigger on the SNES!
Numerous other projects, tools, ports and general grooviness!

IN-DEPTH INFORMATION ABOUT OUR PROJECTS
IS AVAILABLE ON OUR WEBSITE
www.lobster.demon.nl

Visit regularly for new updates of ini.library and our other products!
Downloads will be made available at our site around two weeks before the Aminet release!