 ###################################################################
 #  libReadINI - Libreria de lectura de ficheros INI en ANSI C
 #  Por David Colmenero AKA D_Skywalk <dantoine@gmail.com>
 #
 #  Version 0.8f - 15 Enero de 2006
 #		por D_Skywalk

 ( si, los acentos han sido omitidos y las enyes evitadas :P )

--------------------------------------------
(I) Introduccion y el por que de la libreria
--------------------------------------------

LibReadINI es libreria que lee ficheros INI, hecha completamente en C, 
lo que permite ser usada tambin en proyectos de GP32 sin problemas :D

No tiene dependencias externas de SDL, libxml o similares, como la "oficial" de GP2X. 
Lo mejor pesa muy poquito -unos 6kb- y es bastante rapida, aunque seguro que se podria 
mejorar, asi comparte tus mejoras ;)

La libreria lee dos tipos de ficheros INI tipo, M$ (los que todos conocemos), 
o tipo "conf" de linux. 

Un fichero INI podria ser algo como esto:

###########################################################################

[General]
    name = Junk Config File Test
    version = 2
    
    
[Mode]
    StrictMode = yes
    useflags = no
    phase = 5
    

[OtherSection]
    name = Hello


[AnotherSection]
    name = Bye
    
###########################################################################

---------------------------
(II) Instalando la libreria
---------------------------

Vea el fichero: INSTALL.txt


-------------------
(III) Documentacion
-------------------

-  int cfgOpen ( const char * Filename, const int Style )

  Abre un fichero de configuracion del estilo indicado. 
  Los estilos soportados actualmente son: "MS_STYLE" y "NOT_MS_STYLE".
  
  Un ejemplo de un fichero de configuracion "MS_STYLE":
     [section]
         version = 2.4
     [foo]
         bar=hello
         foobar=world

  Un ejemplo de un fichero de configuracion "NOT_MS_STYLE":
     [section]
             2.4
     [foo]
             hello
             world


-  int cfgSelectSection ( const char * SectionName );

  Selecciona (y lee) la seccion dada del fichero de configuracion abierto.
  Atencion: Esta funcion distigue entre mayusculas y minusculas,
            no es lo mismo "Color" que "color".


-  int cfgReadInt ( const char * VariableName, const int Default );

  Devuelve un entero de la seccion seleccionada en el fichero de 
  configuracion abierto. Si no se encuentra retorna el valor por defecto.
  Atencion: Esta funcion NO hace distincion entre mayusculas y minusculas,
            para ella es lo mismo "Valor", que "valor", que "VALOR", que "VaLoR"...

-  char * cfgReadText ( const char * VariableName, const char * Default );

  Devuelve una cadena de la seccion seleccionada en el fichero de 
  configuracion abierto. Si no se encuentra retorna el valor por defecto.
  Atencion: Esta funcion NO hace distincion entre mayusculas y minusculas.


-  bool cfgReadBool ( const char * VariableName, const bool Default );

  Devuelve un booleano de la seccion seleccionada en el fichero de 
  configuracion abierto. Si no se encuentra retorna el valor por defecto.
  Atencion: Esta funcion NO hace distincion entre mayusculas y minusculas.


-  void cfgClose( void );

  Cierra el fichero de configuracion abierto y libera la memoria usada.
  
---------------------
(IV) Ejemplo Practico
---------------------


Su uso es muy simple:
- Primero abrimos el fichero, que podria ser algo como:

###########################################################################

    if(!cfgOpen("./configs/ejemplo.ini", MS_STYLE))
    {
       //no encontre el fichero
    }else
    {
        //fichero leido!
    }
    
###########################################################################

- Una vez abierto, hay que elegir una seccion que la libreria se encargara de 
  buscar. Para seleccionar una seccion seria:

###########################################################################

    if(cfgSelectSection("General"))
    {
        //haz lo que sea...
    }else
    {
        //pues se ve que no la encontro!!! xD
    }

###########################################################################

- Una vez seleccionada se pueden pedir datos de la misma usando funciones para 
  cadenas, numeros y booleanos...
  unos ejemplos finales:

###########################################################################

        currentVersion = (Uint8) cfgReadInt("version", 1);

###########################################################################
 Ex: Lee la variable version del fichero INI y la almacena en nuestra variable, currentVersion.
     (El numero del final es un valor por defecto, por si no lo encuentra, etc.)

Finalmente cuando hemos terminado de trastearla debemos hacer, simplemente:

###########################################################################

    cfgClose();

###########################################################################

La ventaja de usar ficheros INI es que puede hacer cambios en las configuraciones
de sus programas y ver los cambios sin que se requiera una nueva compilacin. Y si
luego lo necesita siempre podra encapsular todo el cdigo "INI" en un fichero binario... ;)


-----------------
(V) Notas finales
-----------------

- Libreria no usa practicamente nada de memoria, ya que usa el propio fichero 
  para buscar los valores requeridos. Una vez se tenga todo lo necesario recuerda 
  cerrar el fichero con "cfgClose".

- Quizas se podia haber hecho una version mas rapida simplemente leyendo la estructura 
  del fichero y guardandola completamente en memoria en forma de nodos, pero requeriria 
  mas RAM y mas reservas de memoria dinamica, que tampoco son muy rapidas.

  # Si lo que quieres es darle mas velocidad quizas podrias hacer las modificaciones 
    pertinentes para usar memoria estatica, aunque haria que los requerimientos de memoria 
    del programa que la utilizaran aumentaran por defecto, por eso esta opcin fue desestimada.
  
  # Ante estas opciones la libreria usa la via de en medio, guarda los valores de la seccion 
    requerida en memoria dinamica, y si se le indica otra seccion, libera la memoria ocupada
    y relee el fichero una vez mas.

- Seguramente el codigo tenga algun fallo o podria haber sido mejor escrito, todas las 
  modificaciones seran muy bien recibidas!!
  
- Me alegraria recibir correos de los coders que usen esta libreria, asi tambien podria 
  poner en la pagina del proyecto todos los programas que la usen :)

--------------------
(VI) Haz tu Donacion
--------------------

Yo programo para la "Escena" en mi tiempo libre. Donando ayudaras a que pueda mantener el
codigo, actualizar mis proyectos y crear nuevos programas, juegos o ayudas. Esta una forma 
de dar un enorme >>GRACIAS<< si alguno de mis programas te fue util.

Algunos de mis proyectos: Pituka (GP32/GP2x?), 
                          ScummVM (GP2X), 
                          Developer SDK & Environment for GP32/GP2X, 
                          Abalon RPG Enigne (GP32/GP2x).

Mas informacion en:
http://david.dantoine.org/seccion/1/


-----------------------------------
David Skywalker (D_Skywalk) dantoine@gmail.com
http://david.dantoine.org

