home *** CD-ROM | disk | FTP | other *** search
/ The CDPD Public Domain Collection for CDTV 4 / CDPD_IV.bin / fish / 931-950 / ff948 / snoopy / ini / ini.doc < prev    next >
Text File  |  1993-12-22  |  33KB  |  928 lines
  1. TABLE OF CONTENTS
  2.  
  3. ini.library/--background--
  4. ini.library/ini_ChangeString
  5. ini.library/ini_CheckProtection
  6. ini.library/ini_Delete
  7. ini.library/ini_DeleteFilename
  8. ini.library/ini_ErrorString
  9. ini.library/ini_GetBool
  10. ini.library/ini_GetHeader
  11. ini.library/ini_GetInteger
  12. ini.library/ini_GetString
  13. ini.library/ini_GetVariable
  14. ini.library/ini_LocalConfig
  15. ini.library/ini_New
  16. ini.library/ini_NewConfig
  17. ini.library/ini_NewFilename
  18. ini.library/ini_OpenFile
  19. ini.library/ini_ProtectSection
  20. ini.library/ini_RemoveVariable
  21. ini.library/ini_Save
  22. ini.library/--background--                         ini.library/--background--
  23.  
  24.    PURPOSE
  25.     The ini.library was written to give the amiga user a more consistent
  26.     configuration file format, and programmers a much easier way of 
  27.     storing config or project information on disks. 
  28.     
  29.     Most programs have config files to store global settings and such. 
  30.     These files have all different structures people in the real world
  31.     (the users) cannot examine or understand; and, worse yet, often differ
  32.     from version to version. We all know the hassle with those 'old->new'
  33.     configuration file converters...With the ini.library this changes: you
  34.     have access to a standardized ini file format known from other
  35.     operating systems such as unix, windows and so on; it allows
  36.     you to save your config stuff much easier (less code), and it
  37.     enables the user to read and even modify configuration data with
  38.     a simple text editor (or, a wide-range field for unemployed PD
  39.     programmers: using an INI editor)
  40.     
  41.     As the ini.library is I-WANT-TO-BE-FREE-WARE you are ENCOURAGED to
  42.     use it - its free of charge! (go ahead, do it!) and it offers much
  43.     more comfort to your applications. PD dealers, diskmags, everyone,
  44.     I'd like you to push'n'hype the ini.library ;-). 
  45.     
  46.     INI files are plain line-oriented ASCII texts that can contain three
  47.     possible types of lines : COMMENTS, HEADERS and VARIABLES. COMMENTS are
  48.     lines that include additional information not used by the parser.
  49.     You can use these comment lines to give the user ideas about what
  50.     your variables mean and what reasonable changes s(he) is allowed
  51.     to make to that variables. HEADERS are identifiers for sections and
  52.     are enclosed in [] brackets. A SECTION is a group of zero to infinite (?)
  53.     number of variables and provides a simple but efficient means of
  54.     logically grouping data. VARIABLES are simple statements in the
  55.     form "<variable>=<contents>" where both <variable> and <contents>
  56.     could be virtually anything - you name it. 
  57.  
  58.     Each INI file must start with a sequence of 4 characters ";INI"
  59.     otherwise the ini.library will return the INIERROR_INVALID_INI_FILE. 
  60.     This was included to prevent misuse of the ini.library: imagine your
  61.     program has a 'load user configuration' menu and the user tries out
  62.     some binary hack or an IFF picture (you know users, don't you?! ;-)
  63.     If you watch out for INIERROR_INVALID_INI_FILE, you can send the user
  64.     a message of complaint and ignore its wishes -> great. 
  65.     Since this is a cause for many first-time problems, from version 2.1
  66.     upwards this checking can be made optional; see ini_NewConfig() for
  67.     details
  68.  
  69.    COMMENTS
  70.     Comments can be placed anywhere [well, almost]. If you want
  71.     to have a full-line comment, place a ';' or a '*' in the first
  72.     column of that line. Anything after these two characters will be ignored.
  73.     If you want to place a comment at the end of a line you should use
  74.     the ';' sign ONLY. Also note that if you make a comment after a 
  75.     variable you should probably enclose its contents in quotation marks;
  76.     otherwise the whitespaces between the last character of the contents
  77.     and the comment start will be part of the contents. This is
  78.     no problem if you are using integer or boolean variables; it might
  79.     be a problem for SOME string variables, but doesn't necessarily have
  80.     to - its up to your interpretation of the input data.
  81.     
  82.     Examples:
  83.     
  84.         ;INI for MUIMon release version
  85.         
  86.         * another piece of wisdom
  87.         best part of munich=ULTRAWORLD ; 100% wild techno
  88.         
  89.  
  90.    SECTIONS
  91.     Sections are used to group variables logically. You should try to place
  92.     all your data in groups so that your inifiles have a more consistent
  93.     look and both you and the user can find data easier. The concept of
  94.     sections can have various usages, one is to handle logic groupings
  95.     for one program, another is to handle data related to different
  96.     programs accessing the same INI file, yet another is to just make
  97.     your INI more readable. Of course,the ini.library is flexible enough
  98.     to ignore sections altogether, but you shouldn't force it! Sections
  99.     cost you nothing and make for a lot better programs.
  100.  
  101.    HEADERS
  102.     Headers start a new section. Headers are strings enclosed in
  103.     [] brackets and can be any string you like. Everything following
  104.     a header is logically assigned to that header - up to the next
  105.     section header or an end-of-file. 
  106.  
  107.     Examples:
  108.  
  109.         [drivers]
  110.         pc0=storage:dosdrivers/pc0
  111.         cd=devs:CDROM
  112.  
  113.         [Disko Lovers,International]        
  114.         best ULTRAWORLD DJs=MONIKA,TIN-A-303,BLEEP & TRIPPLE R,DJ HELL
  115.         ; hi to SMC all ravers around the globe. See you on MAYDAY V
  116.  
  117.         [hermeneutic philosophy revisited]
  118.         zizek=no meta language exists
  119.    
  120.    VARIABLES
  121.     Variables are basically strings that are assigned a name. The
  122.     names is what you search for, the strings is what you get -it is as
  123.     simple as that. For instance, in "TABS=8" the string "TABS" is
  124.     the name (also called the variable), the string "8" is its value.
  125.     The interpretation of the string value is up to you. The ini.library
  126.     provides three basic types of interpretation : Strings, Integers (LONGs)
  127.     and  boolean Values (BOOLs). You can of course add your own
  128.     interpretations as you like, and this is why the ini concept is so
  129.     flexible: You can virtually store ALL information you need in such
  130.     a way that it is represented as an ASCII string. If you want your
  131.     strings to be of a certain length, you can enclose them in
  132.     brackets, for example such as in
  133.     
  134.         user="T\"N\"I and THE DREAM TEAM"
  135.  
  136.     where you can assign the string >T"N"I AND THE DREAM TEAM< to
  137.     the variable named >user<. Note that a sequence of \" is used
  138.     as an escape character in the above example.
  139.  
  140.     If you have ideas for additional datatypes of general interest
  141.     the ini.library should understand, please contact me. If possible,
  142.     I'll include them.
  143.  
  144.     Examples:
  145.     --------------------------------------------------------------
  146.        ;INI
  147.        
  148.        [GLOBAL]
  149.        user="T'N'I and The Dream Team" ;from INTENSE Records
  150.        tabs=8
  151.        indent=YES
  152.     autofold=FALSE
  153.     preferences=
  154.        
  155.        [DIRECTORYS]
  156.        home=work:assembler/
  157.        ; add multiple directorys by using '+' or ','
  158.        include=include:+dh1:more_includes/
  159.        libs=dh2:code/libs/asm/+lib:+disko:love
  160.        
  161.     --------------------------------------------------------------
  162.     The above example shows you some ideas of inifiles: Two groups
  163.     are part of this inifile: GLOBAL and DIRECTORYS. Each section
  164.     can (but doesn't have to) have different variables, each variable
  165.     can be any string enclosed in quotation marks or from the = sign
  166.     to the end of the line. If you want to add comments, enclose the
  167.     string in quotes, and add a comment like in the "user=" line above.
  168.     Note that the feature described as "add multiple directorys by ..."
  169.     is a description of an add-on datatype used by the application for
  170.     this INI file and NOT provided by the ini.library itself. 
  171.  
  172.     Now you should be able to read inifiles. More complex features such
  173.     as section protection and file location are described in the
  174.     "programmers.guide" document which should be part of this distribution.
  175.  
  176.    HINTS
  177.     If you decide to use the ini.library -WHICH I STRONGLY HOPE YOU DO-
  178.     you should always check for error returns - you may never know when
  179.     they come in handy for you.
  180.  
  181.     If you save your files, make use of the grouping feature; that is,
  182.     at least provide some GLOBAL section so that the user knows what
  183.     he's up for. It makes INIfiles more readable and doesn't cost
  184.     you anything.
  185.  
  186.    LIMITATIONS
  187.        Yes, there are some.
  188.        
  189.     * currently no whitespaces before and after the "=" are allowed.
  190.       This means that the two following lines are different for 
  191.       the ini.library parser functions
  192.       
  193.              ultraworld=great
  194.              ultraworld = great
  195.  
  196.       There is a simple workaround for this: just do your own variable
  197.       and contents parsing (explicit datatypes, see above). Future
  198.       versions WILL include a fix on that, I PROMISE.
  199.  
  200.        * the ini.library uses approximately twice as much memory as the
  201.          ini file is in size (less for larger files). This is not a
  202.          problem for most users, because inifiles seldom grow over
  203.          a size of some 10-20 kb (even on windows I haven't seen a inifile
  204.          larger than 25kb up to this day), and many applications not even
  205.          reach a 5kb limit. (You can write a LOT variables in a 5 kb file).
  206.       However, this memory is needed only while your parser is active,
  207.       (i.e. between calls to ini_New() and ini_Delete() ). Afterwards,
  208.       only the library code (5kb) is kept in memory. 
  209.  
  210. ini.library/ini_ChangeString                     ini.library/ini_ChangeString
  211.  
  212.    NAME
  213.     ini_ChangeString -- change an existing string for a variable
  214.     
  215.    SYNOPSIS
  216.        error = ini_ChangeString( parser, header, variable, value )
  217.     d0              A0      A1      A2        A3
  218.  
  219.     INIERROR ini_ChangeString(INIPARSER *,STRPTR,STRPTR,STRPTR);
  220.  
  221.    FUNCTION
  222.     Changes the contents of a variable to a new value. If you have
  223.     made changes to the data represented in an inifile (e.g. your
  224.     internal configuration structure) you can use this function
  225.     to fix those changes and then write back your file with ini_Save().
  226.     If the variable already existed, its contents will be replaced by
  227.     the new contents; if it didn't exist, it will be appended to the
  228.     section it is assigned to. Unless you use explicit saving of
  229.     ini-files you *MUST* use ini_ChangeString() to change the
  230.     contents of variables, **NEVER** try to do it on your own
  231.     (its quite tricky, actually!).     
  232.  
  233.    INPUTS
  234.     parser - pointer to a valid INIPARSER
  235.     header - section header name
  236.     variable - section variable name 
  237.     value - new contents
  238.  
  239.    RESULTS
  240.     error - INIERROR as defined in libraries/ini.h
  241.  
  242.    NOTE
  243.     old end-of-line comments will be stripped by this function. You can
  244.     explicitly set one by using contents such as
  245.  
  246.         char *newContents = "\"blabla\" ;comment "; or
  247.  
  248.         dc.b    '"blabla" ;comment',0
  249.  
  250.    SEE ALSO
  251.     ini_RemoveVariable, ini_Save
  252.  
  253. ini.library/ini_CheckProtection               ini.library/ini_CheckProtection
  254.  
  255.    NAME
  256.     ini_CheckProtection -- check if a section has a valid protection
  257.     
  258.    SYNOPSIS
  259.        error = ini_CheckProtection( header, password )
  260.     d0                     A0         A1
  261.  
  262.     INIERROR ini_CheckProtection( INILINEINFO *, STRPTR )
  263.  
  264.    FUNCTION
  265.     This function checks if it can find a "$code" variable in the given
  266.     section and if that code matches the password given as an argument. 
  267.     The password is case sensitive and must match *EXACTLY* the one used
  268.     to code that particular section (including whitespaces and so on).
  269.     It is up the caller to decide what to do if a section is not
  270.     properly coded : you can make it a fatal problem or just ignore
  271.     it - whatever you like. This means, the ini.library will load files
  272.     with or without invalid passwords - YOU have the "power" to handle
  273.     this situation (actually, this was done because it is not a feature
  274.     of the normal inifile "standard", its a addon bonus of the ini.library)
  275.  
  276.    INPUTS
  277.     header - pointer to a INILINEINFO structure for a section header
  278.         (i.e. ili_Flags must be INIFLAG_HEADER )
  279.     password - pointer to the password (assumably) used to protect this
  280.         section
  281.  
  282.    RESULTS
  283.     error - INIERROR as defined in libraries/ini.h; you should look out
  284.         for INIERROR_NONE = good, INIERROR_INVALID_PASSWORD = bad
  285.  
  286.    SEE ALSO
  287.     ini_ProtectSection
  288.  
  289. ini.library/ini_Delete                                 ini.library/ini_Delete
  290.  
  291.    NAME
  292.     ini_Delete -- delete INI parser
  293.  
  294.    SYNOPSIS
  295.     error = ini_Delete( parser )
  296.     D0            A0
  297.  
  298.     INIERROR ini_Delete( INIPARSER * );
  299.  
  300.    FUNCTION
  301.     Free all memory used by an INI parser and reset all accompaning 
  302.     internal data structures. You should ALWAYS call this function
  303.     after you have finished using the INI file so that you don't loose
  304.     any precious memory. You must call ini_Delete() even if ini_New()
  305.     wasn't able to create the parser for you (there still might be 
  306.     some memory somewhere only ini_Delete can take care of)
  307.  
  308.    WARNING
  309.     This function does not arbitrate for access to the parser.  The
  310.     calling task must be the owner of the involved parser.
  311.  
  312.    INPUTS
  313.     parser - a pointer to a parser structure initialized with ini_New()
  314.  
  315.    RESULTS
  316.     error - INIERROR as defined in libraries/ini.h
  317.  
  318.    SEE ALSO
  319.     ini_New
  320.  
  321. ini.library/ini_DeleteFilename                 ini.library/ini_DeleteFilename
  322.  
  323.    NAME
  324.     ini_DeleteFilename() -- destructor for ini_NewFilename()
  325.     
  326.    SYNOPSIS
  327.        ini_DeleteFilename( filename )
  328.                  D0
  329.  
  330.     void ini_DeleteFilename( STRPTR )
  331.  
  332.    FUNCTION
  333.     This function will deallocate memory associated with a filename
  334.     generated by ini_NewFilename()
  335.  
  336.    INPUTS
  337.     filename - a filename returned from ini_NewFilename
  338.  
  339.    NOTE
  340.     after calling ini_DeleteFilename() your "filename" variable is
  341.     invalid : DO NOT USE IT ANY LONGER!
  342.  
  343.    RESULTS
  344.     none
  345.  
  346.    SEE ALSO
  347.        ini_NewFilename()
  348.  
  349. ini.library/ini_ErrorString                       ini.library/ini_ErrorString
  350.  
  351.    NAME
  352.     ini_ErrorString -- find error message to an INIERROR
  353.     
  354.    SYNOPSIS
  355.        message = ini_ErrorString( error )
  356.        D0               D0
  357.  
  358.     STRPTR ini_ErrorString( INIERROR )
  359.  
  360.    FUNCTION
  361.     Used to find an ini.library error message. Currently the error 
  362.     strings are in english but a localized version is planed for the 
  363.     next update of this library, so you should use ini_ErrorString()
  364.     when printing warnings instead of your own error strings. Also, if
  365.     you use ini_ErrorString() you automagically can handle errors that 
  366.     result from higher library versions.
  367.  
  368.    INPUTS
  369.     error - some INIERROR code returned by one of the ini.library functions
  370.  
  371.    RESULTS
  372.     message - the error message for that error code (soon to be localized)
  373.         If there was no error message (because of INIERROR_NONE or an
  374.         invalid error code) ini_ErrorString() will return an EMPTY
  375.         string ( "" ) and not NULL, so you can always do something
  376.         like
  377.  
  378.         printf("%s\n", ini_ErrorString( ini_Whatever(...) ) );. 
  379.  
  380.    NOTE
  381.     You are NOT allowed to modify this string, if you need to do so, 
  382.     make a copy of the string and use that copy instead.
  383.  
  384. ini.library/ini_GetBool                               ini.library/ini_GetBool
  385.  
  386.    NAME
  387.     ini_GetBool -- find a boolean variable
  388.     
  389.    SYNOPSIS
  390.        error = ini_GetBool(parser,head,var,defaultBool,target)
  391.     d0            A0       A1   A2  D0        A3
  392.  
  393.     INIERROR ini_GetBool(INIPARSER *,STRPTR,STRPTR,BOOL,BOOL *);
  394.  
  395.    FUNCTION
  396.     Used to find a boolean in an inifile. If the value cannot be found
  397.     for any reason, a default value is used. The variable should be
  398.         
  399.         "YES",
  400.         "Y",
  401.         "ON" or
  402.         "ACTIVE"
  403.     
  404.     if the returned value is to be TRUE, otherwise FALSE will be returned.
  405.     Future Versions of the ini.library will probably include locale-dependant
  406.     IDs in addition to those above. You can use ini_GetBool() very good to
  407.     handle boolean flags in your configuration - and it is a lot more 
  408.     readable than other solutions.
  409.  
  410.    INPUTS
  411.     parser - pointer to an INIPARSER opened by ini_New()
  412.     head - section header name
  413.     var - section variable name
  414.     defaultBool - default value if boolean value not found 
  415.     target - adress of target Bool
  416.  
  417.    RESULTS
  418.     error - INIERROR as defined in libraries/ini.h. Actually, you can
  419.         normally ignore this error code, because you must provide a
  420.         default value anyway.
  421.  
  422.    SEE ALSO
  423.     ini_GetInteger, ini_GetString
  424.  
  425. ini.library/ini_GetHeader                           ini.library/ini_GetHeader
  426.  
  427.    NAME
  428.     ini_GetHeader -- find a section header
  429.     
  430.    SYNOPSIS
  431.     header = ini_GetHeader( parser, headerString )
  432.     D0            A0    A1
  433.  
  434.     INILINEINFO *ini_GetHeader( INIPARSER *, STRPTR )
  435.  
  436.    FUNCTION
  437.     This function is used to locate a section in an INI file by looking
  438.     for the section header. If you are looking for a specific variable,
  439.     ini_GetString() is probably the better choice, but you can do your
  440.     own parsing of INI sections, e.g. if you have 'intelligent' sections;
  441.     that is sections with flexible concepts or whatever. You could use
  442.     ini_GetVariable() in that case.
  443.  
  444.    INPUTS
  445.     parser - a pointer to a parser structure initialized with ini_New()
  446.     headerString - name of the section header you are looking for, without
  447.         enclosing brackets (ie. "global" )
  448.  
  449.    RESULTS
  450.     header - pointer to an INILINEINFO or NULL if that header could not
  451.         be found. This can be the case either if the INI file does not
  452.         include that particular section, or (worse) the INI parser
  453.         wasn't able to complete its job (as you know, all ini.library
  454.         functions are save to use). If this is NON-NULL, you can use
  455.         it as an argument to ini_GetVariable() or you can do your own
  456.         section looping (see "advanced concepts" in the "programmers guide")
  457.  
  458.    SEE ALSO
  459.     ini_GetVariable, ini_GetString, ini_New
  460.  
  461. ini.library/ini_GetInteger                         ini.library/ini_GetInteger
  462.  
  463.    NAME
  464.     ini_GetInteger -- find a long integer variable
  465.     
  466.    SYNOPSIS
  467.        error = ini_GetInteger(parser,head,var,defaultLong,target)
  468.     d0               A0     A1   A2  D0       A3
  469.  
  470.     INIERROR ini_GetString(INIPARSER *,STRPTR,STRPTR,LONG,LONG *);
  471.  
  472.    FUNCTION
  473.     Used to find an integer in an inifile. If the integer cannot be found
  474.     for any reason, a default value is used. The ini section should
  475.     contain a string representing a long decimal value. If the string
  476.     starts with a $ sign, a hexadecimal value is expected, % indicates
  477.     binary digits and finally @ sets an octal number. Therefor, the
  478.     following four entries will all return the same number
  479.     
  480.         decimal=123
  481.         octal=@173
  482.         binary=%1111011
  483.         hex=$7B
  484.  
  485.     The prefixes are compatible to most assemblers (now you know which
  486.     language the ini.library was written in ;-) but a future update
  487.     will probably include C-style prefixes (0x and so on). 
  488.  
  489.    INPUTS
  490.     parser - pointer to an INIPARSER opened by ini_New()
  491.     head - section header name
  492.     var - section variable name
  493.     defaultLong - default value if integer not found 
  494.     target - adress of target long
  495.  
  496.    RESULTS
  497.     error - INIERROR as defined in libraries/ini.h. Actually, you can
  498.         normally ignore this error code, because you must provide a
  499.         default value anyway.
  500.  
  501.    SEE ALSO
  502.     ini_GetBool, ini_GetString
  503.  
  504.  
  505. ini.library/ini_GetString                           ini.library/ini_GetString
  506.  
  507.    NAME
  508.     ini_GetString -- find a string variable
  509.     
  510.    SYNOPSIS
  511.        error = ini_GetString(parser,head,var,defaultStr,target,sizeOfTarget)
  512.        D0              A0     A1   A2  A3         D0     A4
  513.  
  514.     INIERROR ini_GetString(INIPARSER *,STRPTR,STRPTR,STRPTR,STRPTR,WORD);
  515.  
  516.    FUNCTION
  517.     Used to find a string in an inifile. If the string cannot be found
  518.     for any reason, a default string is used; so unless you desperately
  519.     rely on a string to exist as part of an inifile, you can call this
  520.     function without even checking for error returns. You can add a 
  521.     series of ini_GetString() statements for all strings you need to
  522.     check without having to worry if they exist or not.
  523.  
  524.    INPUTS
  525.     parser - pointer to an INIPARSER opened by ini_New()
  526.     head - section header name
  527.     var - section variable name
  528.     defaultStr - default string to use (NULL is possible)
  529.     target - target string
  530.     sizeOfTarget - size of target string. ini_GetString() promises
  531.         not to overwrite its bounds AND to keep a zero byte at the
  532.         end, so actually a maximum of (sizeOfTarget-1) characters
  533.         will be written.
  534.  
  535.    RESULTS
  536.     error - INIERROR as defined in libraries/ini.h. Actually, you can
  537.         normally ignore this error code, because you must provide a
  538.         default value anyway.
  539.  
  540.    SEE ALSO
  541.     ini_GetBool, ini_GetInteger
  542.  
  543. ini.library/ini_GetVariable                       ini.library/ini_GetVariable
  544.  
  545.    NAME
  546.     ini_GetVariable -- find a section variable
  547.     
  548.    SYNOPSIS
  549.     variable = ini_GetVariable( header, variableName )
  550.     D0                A0        A1
  551.  
  552.     INILINEINFO *ini_GetVariable( INILINEINFO *, STRPTR )
  553.  
  554.    FUNCTION
  555.     This function is used to locate a variable following a given header
  556.     (or, for that matter, any given INILINEINFO). You can use this function
  557.     if you want to manually parse a section, if you want to find out if
  558.     there are more variables of a given name following a specific variable,
  559.     or for anything else you could think of. Note that you cannot pass
  560.     the INIPARSER as function arguments, use (parser->table.ln_Head) if
  561.     you have to do so.
  562.  
  563.    INPUTS
  564.     parser - a pointer to an INILINEINFO structure (from your INIPARSER.table)
  565.         or -preferably- as returned by ini_GetHeader() 
  566.     varibaleString - name of the variable you are looking for, without
  567.         enclosing brackets and "=" (ie. "variable" )
  568.  
  569.    RESULTS
  570.     variable - pointer to an INILINEINFO or NULL if that variable could not
  571.         be found. This can be the case either if the INI file does not
  572.         include that particular section, or (worse) the INI parser
  573.         wasn't able to complete its job (as you know, all ini.library
  574.         functions are save to use).
  575.  
  576.    NOTE
  577.        ini_GetVariable() doesn't promise the variable to be a member of
  578.        the section you specified with your header. For example, 
  579.        
  580.         head = ini_GetHeader( parser, "HEAD ONE" );
  581.            info = ini_GetVariable( head, "VARIABLE" );
  582.  
  583.     would find the "VARIABLE=FOUND" entry in the "HEAD TWO" section
  584.     if the inifile looked something like this :
  585.  
  586.         [HEAD ONE]
  587.         size=3551
  588.         
  589.         [HEAD TWO]
  590.         VARIABLE=FOUND
  591.  
  592.     This is A FEATURE, NOT A BUG ;-), yes, because you normally will
  593.     use ini_GetVariable() to loop through the complete inifile.
  594.  
  595.    SEE ALSO
  596.     ini_GetVariable, ini_GetString, ini_New, ini_ParseSection
  597.  
  598. ini.library/ini_LocalConfig                       ini.library/ini_LocalConfig
  599.  
  600.    NAME
  601.     ini_LocalConfig() -- get the local configuration
  602.     
  603.    SYNOPSIS
  604.        config = ini_LocalConfig()
  605.  
  606.     INICONFIG *ini_LocalConfig( void )
  607.  
  608.    FUNCTION
  609.     This function will return the local configuration if one is
  610.     defined for the current task. Local configurations are "task
  611.     sensitive", which means that one task can have one local config.
  612.     ini_LocalConfig() will NOT fall back to the global config, so 
  613.     if you want to read the current config you would probably write
  614.     something like
  615.     
  616.         if( ( config = ini_LocalConfig() ) == NULL ) 
  617.             config = IniBase->GlobalConfig;
  618.  
  619.    INPUTS
  620.     none
  621.  
  622.    RESULTS
  623.     config - local configuration or NULL if none exists
  624.     
  625.    SEE ALSO
  626.     ini_NewConfig(), ini_DeleteConfig()
  627.  
  628. ini.library/ini_New                                       ini.library/ini_New
  629.  
  630.    NAME
  631.     ini_New -- open INI parser
  632.  
  633.    SYNOPSIS
  634.     error = ini_New( fileName, parser )
  635.     D0         A0       A1
  636.  
  637.     INIERROR ini_New( STRPTR, INIPARSER * );
  638.  
  639.    FUNCTION
  640.     Open an inifile and parse its contents. After successfully calling 
  641.     an inifile with this function you can examine its contents using
  642.     the functions provided (eg.ini_GetString()) or manually. You must
  643.     call this function before calls to any other ini.library functions.
  644.     Don't even think about creating an INIPARSER yourself. 
  645.     
  646.    WARNING
  647.     This function does not arbitrate for access to the parser.  The
  648.     calling task must be the owner of the involved parser. Use semaphores
  649.     if you want to share parser information with other tasks.
  650.  
  651.     You should always call ini_Delete() on the parser EVEN IF ini_New()
  652.     failed. Otherwise some internal memory might get lost somewhere
  653.  
  654.    INPUTS
  655.     fileName - name of the input file. This is currently a plain filename
  656.         with or without pathname; however you should try to use only
  657.         plain filenames ("test.ini" instead of "dh1:somewhere/test.ini")
  658.         so that the ini.library can fix inifiles to S:, INI: or whereever
  659.         the user wants them located. See "locating files" in the
  660.         "programmers guide" for details.
  661.  
  662.     parser - pointer to an empty INIPARSER structure. C programmers simply
  663.         add the adress of an INIPARSER variable, ASM programmers 
  664.         can use a (DS.B ip_SIZEOF) statement (See example TEST.ASM)
  665.  
  666.    RESULTS
  667.     error - INIERROR as defined in libraries/ini.h. Proceed ONLY if
  668.         error = INIERROR_NONE, else you can forget about it.
  669.  
  670.    SEE ALSO
  671.     ini_Delete
  672.  
  673. ini.library/ini_NewConfig                           ini.library/ini_NewConfig
  674.  
  675.    NAME
  676.     ini_NewConfig() -- setup a local configuration
  677.     
  678.    SYNOPSIS
  679.        error = ini_LocalConfig( tagList  )
  680.     d0                  A0
  681.  
  682.     INIERROR ini_LocalConfig( struct TagItem * )
  683.  
  684.    FUNCTION
  685.     This function creates a local configuration for your program.
  686.     If one already exists it will be modified to use the new values.
  687.     See "ini.introduction" for more details on the concept of local
  688.     and global ini.library configurations
  689.  
  690.    NOTE
  691.        Sorry, no vararg-stub for C-programmers (yet?); I didn't want
  692.        to have to write a linklib for only one function...
  693.  
  694.    INPUTS
  695.     tagList - a list of tag items. Currently defined tags are :
  696.  
  697.         ICFG_ENABLE_S
  698.         ti_Data is BOOL, default = TRUE
  699.  
  700.         ICFG_ENABLE_INI
  701.         ti_Data is BOOL default = TRUE
  702.  
  703.         ICFG_ENABLE_ENV
  704.         ti_Data is BOOL, default = TRUE
  705.  
  706.         ICFG_ENABLE_USER
  707.         ti_Data is BOOL, default = TRUE
  708.  
  709.         ICFG_INIMASK
  710.         ti_Data is BOOL, default = FALSE. If set to TRUE, the
  711.         ini.library no longer requires the ";INI" at the start
  712.         of an input file.
  713.  
  714.         ICFG_ASSIGN
  715.         user-assign directory, ti_Data is STRPTR to a
  716.         static memory! (i.e. the ini.library will not copy
  717.         name name of the user-assign so you MUST keep it in
  718.         memory yourself!!!!!! this may change for future releases
  719.         but right now its a requirement)
  720.  
  721.    RESULTS
  722.     error - INIERROR as defined in libraries/ini.h;
  723.  
  724.    SEE ALSO
  725.     ini_LocalConfig(), ini_DeleteConfig()
  726.  
  727. ini.library/ini_NewFilename                       ini.library/ini_NewFilename
  728.  
  729.    NAME
  730.     ini_NewFilename -- build a config-sensitive INI filename
  731.     
  732.    SYNOPSIS
  733.     newname = ini_NewFilename( filename )
  734.     d0                   A0
  735.  
  736.     STRPTR ini_NewFilename( STRPTR )
  737.  
  738.    FUNCTION
  739.     This function builds a complete path+filename for a simple filename
  740.     based upon the local (or global) configuration. The problem is simple:
  741.     a file named "application.ini" could be located in S:, in INI:, in ENV:,
  742.     in a user-defined directory or the current directory. BASED UPON THE
  743.     CURRENT CONFIGURATION this function will build a correct filename
  744.     for you. Example:
  745.     
  746.         ini_NewFilename( "application.ini" )
  747.  
  748.     could return
  749.     
  750.         "s:application.ini"
  751.         "ini:application.ini"
  752.         "env:application.ini"
  753.         "<user>:application.ini" or just
  754.         "application.ini"
  755.  
  756.     You must call ini_DeleteFilename() on a filename returned by this
  757.     function.
  758.  
  759.    INPUTS
  760.     filename - the basic filename; should NOT contain any path information
  761.     (except for subdirectorys: if you are using multiple INIs grouped in
  762.     a subdirectory (i.e. "tool/users.ini" -> "ini:tool/users.ini" ))
  763.  
  764.    RESULTS
  765.        newname - path + filename, or NULL for OUT_OF_MEMORY error
  766.  
  767.    SEE ALSO
  768.     ini_DeleteFilename()
  769.  
  770. ini.library/ini_OpenFile                             ini.library/ini_OpenFile
  771.  
  772.    NAME 
  773.     ini_OpenFile() - open an INI-file
  774.     
  775.    SYNOPSIS
  776.     file = ini_OpenFile( filename, mode, parser )
  777.     d0             d1        d2    a0
  778.  
  779.     BPTR ini_OpenFile(STRPTR,WORD,INIPARSER *);
  780.  
  781.    FUNCTION
  782.     This function opens an INI-File just like dos/Open() would do. However,
  783.     it does a little bit more: if you use it in MODE_NEWFILE and have a 
  784.     valid parser structure, ini_OpenFile() will open the file in that directory
  785.     where the original parser was located. The problem is this: because 
  786.     your program doesn't know where the INI file was loaded from (it could
  787.     be INI:, it could be S:, it could be anywhere in the known galaxy) 
  788.     you wouldn't normally know where to save it back to (unless of course
  789.     you don't need explicit saving and use ini_Save() instead of all the fuss).
  790.  
  791.    INPUTS
  792.     filename - filename without path or anything
  793.     mode - just like dos/Open(), MODE_NEWFILE, MODE_OLDFILE etc.
  794.     parser - parser structure. Because the parser has to be initialized, this
  795.         probably restricts use of ini_OpenFile() for the general public
  796.         to the situation described above: explicitly saving an ini-file
  797.  
  798.    RESULTS
  799.     file - just like dos/Open() a pointer to a filehandle you can Read() or
  800.         Write() to (or whatever). You must Close() it yourself!
  801.  
  802. ini.library/ini_ProtectSection                 ini.library/ini_ProtectSection
  803.  
  804.    NAME
  805.     ini_ProtectSection -- protect an INI file section
  806.     
  807.    SYNOPSIS
  808.        error = ini_ProtectSection( parser, header, password )
  809.     d0                     A0         A1      A2
  810.  
  811.     INIERROR ini_ProtectSection( INIPARSER *, INILINEINFO *, STRPTR )
  812.  
  813.    FUNCTION
  814.     This function protects a INI file section by adding a new (or updating
  815.     an existing) "$code" variable to contain a coded value. The coding
  816.     mechanism uses all data given in variables of a section plus a 
  817.     special password known only to the caller of ini_ProtectSection.
  818.     Thus, if a user a) changes contents of variables or b) tries to use
  819.     this function with an invalid password the "$code" variable will
  820.     become invalid. You can use ini_CheckProtection to see if the
  821.     "$code" variable is valid, so there you have your protection mechanism!
  822.  
  823.     In general, if you intend to protect a section, you should do the
  824.     following :
  825.  
  826.         * call ini_CheckProtection() : if the section is invalid, send
  827.           some error message (or do-what-you-like)
  828.         * edit the protected section
  829.         * call ini_ProtectSection()
  830.         * call ini_Save()
  831.  
  832.     Of course, you should probably skip ini_CheckProtection() during the
  833.     development of your application, since you may find the need to quickly
  834.     change var contents while debugging and so on. Once working you can use
  835.     protected sections to contain "read-only" data you still want to make
  836.     public (such as for debugging purposes, or for pure fun, or for making
  837.     people jealous and encouraging hackers to take a deeper look at your code)
  838.  
  839.     The concept for protected sections is an add-on to the INI standard
  840.     made by the ini.library so you shouldn't expect it to work if you 
  841.     port code to other OS such as Windows.
  842.  
  843.    NOTE    
  844.        The password is case sensitive and must match EXACTLY for calls
  845.        to ini_ProtectSection()/ini_CheckProtection(); i.e.
  846.  
  847.         "ultraworld" != "Ultraworld" != "ultraworld "
  848.                          ^                         ^
  849.  
  850.    INPUTS
  851.     parser - pointer to the INIPARSER structure
  852.     header - pointer to a INILINEINFO structure for a section header
  853.         (i.e. ili_Flags must be INIFLAG_HEADER )
  854.     password - pointer to the password you want to use for protection
  855.  
  856.    RESULTS
  857.     error - INIERROR as defined in libraries/ini.h; you should look out
  858.         for INIERROR_NONE = good, INIERROR_INVALID_PASSWORD = bad
  859.  
  860.    SEE ALSO
  861.     ini_CheckProtection
  862.  
  863. ini.library/ini_RemoveVariable                 ini.library/ini_RemoveVariable
  864.  
  865.    NAME
  866.     ini_RemoveVariable() -- remove an existing variable
  867.     
  868.    SYNOPSIS
  869.        error = ini_RemoveVariable( parser, header, variable )
  870.     d0                A0         A1        A2
  871.  
  872.     INIERROR ini_RemoveVariable( INIPARSER *,STRPTR,STRPTR );
  873.  
  874.    FUNCTION
  875.     This function removes an existing variable from an INIPARSER.
  876.     You can use this if you don't need a particular variable anymore;
  877.     however you don't have to kill unused variables, because they are
  878.     ignored anyway based upon your read requests. DON'T ever remove
  879.     a variable manually.
  880.  
  881.    INPUTS
  882.     parser - pointer to an INIPARSER
  883.     header - section header name
  884.     variable - section variable name
  885.  
  886.    RESULTS
  887.     error - INIERROR as defined in libraries/ini.h
  888.  
  889.    SEE ALSO
  890.     ini_Save, ini_ChangeString
  891.  
  892. ini.library/ini_Save                                     ini.library/ini_Save
  893.  
  894.    NAME
  895.     ini_Save -- save an inifile back to disk
  896.     
  897.    SYNOPSIS
  898.        error = ini_Save( fileName, parser )
  899.     d0          A0        A1
  900.  
  901.     INIERROR ini_Save( STRPTR, INIPARSER * )
  902.  
  903.    FUNCTION
  904.     Save a parser structure back to an inifile. If you have made
  905.     changes to an INIPARSER (e.g. by calling ini_ChangeString()), you
  906.     can save the complete inifile to disk using this function. If you
  907.     have to make lots of changes on the input data, for example if you
  908.     save project file information there, you could explicitly save 
  909.     the file yourself: open it using ini_OpenFile(..,MODE_NEWFILE,..),
  910.     then dos/FPrintf() all the contents and finally dos/Close() it.
  911.     You have to decide yourself what you prefer; making changes with
  912.     ini_ChangeString() and ini_Save() makes more readable code and is
  913.     a lot saver (and preserves any comments the user has made); exporting
  914.     your internal data as inifiles is probably more straight-forward but
  915.     not quite as bullet-proof. Whatever.
  916.  
  917.    INPUTS
  918.     fileName - name of inifile to create. No checking is done if
  919.         the file already exists; so you must make some provision
  920.         for this yourself if you think this could be important. 
  921.     parser - pointer to an INIPARSER to write back to disk
  922.  
  923.    RESULTS
  924.     error - INIERROR as defined in libraries/ini.h
  925.  
  926.    SEE ALSO
  927.     ini_ChangeString, ini_RemoveVariable
  928.