home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 2 / FFMCD02.bin / new / amigalibdisks / disk948 / snoopy / ini / ini.manual < prev    next >
Text File  |  1993-12-21  |  16KB  |  413 lines
  1.  
  2.  
  3.                                 ini.library
  4.                             Release Version 2.0
  5.  
  6.                           I-WANT-TO-BE-FREE-WARE
  7.                           written by Gerson Kurz
  8.  
  9.                                 Nov.21,1993
  10.  
  11.    PURPOSE
  12.     The ini.library was written to give the amiga user a more consistent
  13.     configuration file format, and programmers a much easier way of 
  14.     storing config or project information on disks. 
  15.     
  16.     Most programs have config files to store global settings and such. 
  17.     These files have all different structures people in the real world
  18.     (the users) cannot examine or understand; and, worse yet, often differ
  19.     from version to version. We all know the hassle with those 'old->new'
  20.     configuration file converters...With the ini.library this changes: you
  21.     have access to a standardized ini file format known from other
  22.     operating systems such as unix, windows and so on; it allows
  23.     you to save your config stuff much easier (less code), and it
  24.     enables the user to read and even modify configuration data with
  25.     a simple text editor (or, a wide-range field for unemployed PD
  26.     programmers: using an INI editor)
  27.     
  28.     As the ini.library is I-WANT-TO-BE-FREE-WARE you are ENCOURAGED to
  29.     use it - its free of charge! (go ahead, do it!) and it offers much
  30.     more comfort to your applications. PD dealers, diskmags, everyone,
  31.     I'd like you to push'n'hype the ini.library ;-). 
  32.     
  33.     INI files are plain line-oriented ASCII texts that can contain three
  34.     possible types of lines : COMMENTS, HEADERS and VARIABLES. COMMENTS are
  35.     lines that include additional information not used by the parser.
  36.     You can use these comment lines to give the user ideas about what
  37.     your variables mean and what reasonable changes s(he) is allowed
  38.     to make to that variables. HEADERS are identifiers for sections and
  39.     are enclosed in [] brackets. A SECTION is a group of zero to infinite (?)
  40.     number of variables and provides a simple but efficient means of
  41.     logically grouping data. VARIABLES are simple statements in the
  42.     form "<variable>=<contents>" where both <variable> and <contents>
  43.     could be virtually anything - you name it. 
  44.  
  45.     Each INI file must start with a sequence of 4 characters ";INI"
  46.     otherwise the ini.library will return the INIERROR_INVALID_INI_FILE. 
  47.     This was included to prevent misuse of the ini.library: imagine your
  48.     program has a 'load user configuration' menu and the user tries out
  49.     some binary hack or an IFF picture (you know users, don't you?! ;-)
  50.     If you watch out for INIERROR_INVALID_INI_FILE, you can send the user
  51.     a message of complaint and ignore its wishes -> great. 
  52.     Since this is a cause for many first-time problems, from version 2.1
  53.     upwards this checking can be made optional; see ini_NewConfig() for
  54.     details
  55.  
  56.    COMMENTS
  57.     Comments can be placed anywhere [well, almost]. If you want
  58.     to have a full-line comment, place a ';' or a '*' in the first
  59.     column of that line. Anything after these two characters will be ignored.
  60.     If you want to place a comment at the end of a line you should use
  61.     the ';' sign ONLY. Also note that if you make a comment after a 
  62.     variable you should probably enclose its contents in quotation marks;
  63.     otherwise the whitespaces between the last character of the contents
  64.     and the comment start will be part of the contents. This is
  65.     no problem if you are using integer or boolean variables; it might
  66.     be a problem for SOME string variables, but doesn't necessarily have
  67.     to - its up to your interpretation of the input data.
  68.     
  69.     Examples:
  70.     
  71.         ;INI for MUIMon release version
  72.         
  73.         * another piece of wisdom
  74.         best part of munich=ULTRAWORLD ; 100% wild techno
  75.         
  76.  
  77.    SECTIONS
  78.     Sections are used to group variables logically. You should try to place
  79.     all your data in groups so that your inifiles have a more consistent
  80.     look and both you and the user can find data easier. The concept of
  81.     sections can have various usages, one is to handle logic groupings
  82.     for one program, another is to handle data related to different
  83.     programs accessing the same INI file, yet another is to just make
  84.     your INI more readable. Of course,the ini.library is flexible enough
  85.     to ignore sections altogether, but you shouldn't force it! Sections
  86.     cost you nothing and make for a lot better programs.
  87.  
  88.    HEADERS
  89.     Headers start a new section. Headers are strings enclosed in
  90.     [] brackets and can be any string you like. Everything following
  91.     a header is logically assigned to that header - up to the next
  92.     section header or an end-of-file. 
  93.  
  94.     Examples:
  95.  
  96.         [drivers]
  97.         pc0=storage:dosdrivers/pc0
  98.         cd=devs:CDROM
  99.  
  100.         [Disko Lovers,International]        
  101.         best ULTRAWORLD DJs=MONIKA,TIN-A-303,BLEEP & TRIPPLE R,DJ HELL
  102.         ; hi to SMC all ravers around the globe. See you on MAYDAY V
  103.  
  104.         [hermeneutic philosophy revisited]
  105.         zizek=no meta language exists
  106.    
  107.    VARIABLES
  108.     Variables are basically strings that are assigned a name. The
  109.     names is what you search for, the strings is what you get -it is as
  110.     simple as that. For instance, in "TABS=8" the string "TABS" is
  111.     the name (also called the variable), the string "8" is its value.
  112.     The interpretation of the string value is up to you. The ini.library
  113.     provides three basic types of interpretation : Strings, Integers (LONGs)
  114.     and  boolean Values (BOOLs). You can of course add your own
  115.     interpretations as you like, and this is why the ini concept is so
  116.     flexible: You can virtually store ALL information you need in such
  117.     a way that it is represented as an ASCII string. If you want your
  118.     strings to be of a certain length, you can enclose them in
  119.     brackets, for example such as in
  120.     
  121.         user="T\"N\"I and THE DREAM TEAM"
  122.  
  123.     where you can assign the string >T"N"I AND THE DREAM TEAM< to
  124.     the variable named >user<. Note that a sequence of \" is used
  125.     as an escape character in the above example.
  126.  
  127.     If you have ideas for additional datatypes of general interest
  128.     the ini.library should understand, please contact me. If possible,
  129.     I'll include them.
  130.  
  131.     Examples:
  132.     --------------------------------------------------------------
  133.        ;INI
  134.        
  135.        [GLOBAL]
  136.        user="T'N'I and The Dream Team" ;from INTENSE Records
  137.        tabs=8
  138.        indent=YES
  139.     autofold=FALSE
  140.     preferences=
  141.        
  142.        [DIRECTORYS]
  143.        home=work:assembler/
  144.        ; add multiple directorys by using '+' or ','
  145.        include=include:+dh1:more_includes/
  146.        libs=dh2:code/libs/asm/+lib:+disko:love
  147.        
  148.     --------------------------------------------------------------
  149.     The above example shows you some ideas of inifiles: Two groups
  150.     are part of this inifile: GLOBAL and DIRECTORYS. Each section
  151.     can (but doesn't have to) have different variables, each variable
  152.     can be any string enclosed in quotation marks or from the = sign
  153.     to the end of the line. If you want to add comments, enclose the
  154.     string in quotes, and add a comment like in the "user=" line above.
  155.     Note that the feature described as "add multiple directorys by ..."
  156.     is a description of an add-on datatype used by the application for
  157.     this INI file and NOT provided by the ini.library itself. 
  158.  
  159.     Now you should be able to read inifiles. More complex features such
  160.     as section protection and file location are described in the
  161.     "programmers.guide" document which should be part of this distribution.
  162.  
  163.    HINTS
  164.     If you decide to use the ini.library -WHICH I STRONGLY HOPE YOU DO-
  165.     you should always check for error returns - you may never know when
  166.     they come in handy for you.
  167.  
  168.     If you save your files, make use of the grouping feature; that is,
  169.     at least provide some GLOBAL section so that the user knows what
  170.     he's up for. It makes INIfiles more readable and doesn't cost
  171.     you anything.
  172.  
  173.    LIMITATIONS
  174.        Yes, there are some.
  175.        
  176.     * currently no whitespaces before and after the "=" are allowed.
  177.       This means that the two following lines are different for 
  178.       the ini.library parser functions
  179.       
  180.              ultraworld=great
  181.              ultraworld = great
  182.  
  183.       There is a simple workaround for this: just do your own variable
  184.       and contents parsing (explicit datatypes, see above). Future
  185.       versions WILL include a fix on that, I PROMISE.
  186.  
  187.        * the ini.library uses approximately twice as much memory as the
  188.          ini file is in size (less for larger files). This is not a
  189.          proble