Return to ini_file.txt CVS log

Up to [Synchronet] / sbbs / src / xpdev

Annotation of sbbs/src/xpdev/ini_file.txt, revision 1.1

1.1     ! root        1: $Id: ini_file.txt,v 1.2 2005/10/13 10:16:07 rswindell Exp $
        !             2: 
        !             3: Synchronet/xpdev ini_file module
        !             4: --------------------------------
        !             5: The basic format of the files supported by the xpdev ini_file module is that
        !             6: of the Windows .ini file, with some additional features.
        !             7: 
        !             8: The basic Windows .ini file format is as follows:
        !             9: 
        !            10: 1. The file contains ASCII text only with LF or CR/LF-terminated lines.
        !            11: 
        !            12: 2. The file is separated into logical "sections". Each section may have its
        !            13:    own list of keys with associated values, one per line.
        !            14: 
        !            15: 3. A section begins with a line consisting only of "[" <section name> "]".
        !            16: 
        !            17: 4. White space before or after the section name is ignored.
        !            18: 
        !            19: 5. A section ends when the end of file is reached or a new section begins.
        !            20:  
        !            21: 6. Keys and associated values within a section are specified, each on their
        !            22:    line, in the format: <key_name> "=" <value>
        !            23: 
        !            24: 7. White space before and after the key/value separator ("=") is ignored.
        !            25: 
        !            26: 8. Comments are lines with a semicolon (";") as the first non-whitespace
        !            27:    character.
        !            28: 
        !            29: 9. Blank lines between or within sections are ignored.
        !            30: 
        !            31: Example basic Windows .ini file content:
        !            32: 
        !            33: ; for 16-bit app support
        !            34: [fonts]
        !            35: [extensions]
        !            36: [Mail]
        !            37: MAPI=1
        !            38: CMCDLLNAME32=mapi32.dll
        !            39: CMCDLLNAME=mapi.dll
        !            40: CMC=1
        !            41: MAPIX=1
        !            42: MAPIXVER=1.0.0.1
        !            43: OLEMessaging=1
        !            44: [SciCalc]
        !            45: layout=0
        !            46: [MSUCE]
        !            47: Advanced=1
        !            48: CodePage=Unicode
        !            49: Font=Terminal
        !            50: 
        !            51: 
        !            52: Synchronet/xpdev extended-ini_file format
        !            53: =========================================
        !            54: The Synchronet/xpdev ini_file module supports a somewhat "extended" .ini file
        !            55: format with the following additions:
        !            56: 
        !            57: Filenames
        !            58: ---------
        !            59: INI filenames typically end in a ".ini" suffix, but that is not a requirement.
        !            60: 
        !            61: If the application uses the ini_file module's iniFileName() function to
        !            62: determine the correct ini filename for the current system, different ini files
        !            63: may be used for different systems on the same network, reading from the same
        !            64: directory.
        !            65: 
        !            66: The different ini filename permutations supported (assuming "file.ini" is the
        !            67: base filename) are:
        !            68: 
        !            69:     path/file.<host>.<domain>.ini
        !            70:     path/file.<host>.ini
        !            71:     path/file.<platform>.ini
        !            72:     path/file.ini
        !            73: 
        !            74: Root section
        !            75: ------------
        !            76: Key/value pairs in the file *before* the first section definition are
        !            77: considered part of the "root" section. This section is often used to define
        !            78: key/value pairs that apply globally to all the following sections. The root
        !            79: section may have other uses as well.
        !            80: 
        !            81: Section Prefixes
        !            82: ----------------
        !            83: Section names may be include a section "prefix", a fixed portion of the
        !            84: section name that may be used be the application to logically group
        !            85: related sections. Section pre-fixes typically end in a colon, but that is
        !            86: not a requirement.   
        !            87: 
        !            88: Literal string values
        !            89: ---------------------
        !            90: String values separated by the key name with a colon (':') instead of an
        !            91: equals sign ('='), are parsed as "literal" strings, which means the string
        !            92: will retain any trailing white-space on the line. This may be enhanced in
        !            93: the future to support C escape sequences, multiple/broken lines, etc.
        !            94: 
        !            95: Section name list
        !            96: -----------------
        !            97: If one wishes to specify a list of sections for all values to be applied to
        !            98: they may specify a list of section names, separated by '|', where a single
        !            99: section name would normally be specified. Example:
        !           100: "[telnet|rlogin]"
        !           101: 
        !           102: Boolean values
        !           103: --------------
        !           104: Values with an either true or false (1 or 0) state can have their value
        !           105: specified as a number (0, or non-zero), or the following strings (yes,
        !           106: English only): "true", "yes", or "on" (interpretted as 1), or "false",
        !           107: "no", or "off" (interpretted as 0). Any otherwise unrecognized text strings
        !           108: will be interpretted as 0 (false).
        !           109: 
        !           110: Integer values
        !           111: --------------
        !           112: Integer values may be negative or positive whole numbers of up to 
        !           113: (at least) 32-bits in size.
        !           114: 
        !           115: Integer values may be specified in octal (base 8), decimal (base 10),
        !           116: hexadecimal (base 16), or base 36 formats based on the following
        !           117: interpretation of the specified value text:
        !           118: 
        !           119: If the first character is 0 and the second character is not 'x' or 'X', the
        !           120: string is interpreted as an octal integer; otherwise, it is interpreted as
        !           121: a decimal number. If the first character is '0' and the second character is
        !           122: 'x' or 'X', the string is interpreted as a hexadecimal integer. If the
        !           123: first character is '1' through '9', the string is interpreted as a decimal
        !           124: integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the
        !           125: values 10 through 35.
        !           126: 
        !           127: The exception to this rule are the values of "true", "yes", or "on",
        !           128: always interpretted as the value of 1 (one).
        !           129: 
        !           130: Long integer values
        !           131: -------------------
        !           132: Long integer values may be positive whole numbers of up to (at least)
        !           133: 32-bits in size. Otherwise, long integer values are interpretted the same as
        !           134: normal integer values.
        !           135: 
        !           136: Log levels
        !           137: ----------
        !           138: The ini_file module includes built-in support for the standard Unix syslog
        !           139: levels: Emergency (0), Alert (1), Critical (2), Error (3), Warning (4), 
        !           140: Notice (5), Informational (6), and Debugging (7).
        !           141: 
        !           142: The higher the log level, the more log output will be generated.
        !           143: 
        !           144: Partial or complete log level names may be specified for the log level
        !           145: value, or the numeric equivalent.
        !           146: 
        !           147: Byte counts
        !           148: -----------
        !           149: Byte count values (e.g. file sizes) may be specified as positive numbers
        !           150: (fractional numbers are supported), optionally with a 'T', 'G', 'M', or 'K'
        !           151: suffix to specify terabytes, gigabytes, megabytes, or kilobytes, respectively.
        !           152: 
        !           153: Date/Time stamps
        !           154: ----------------
        !           155: Date and time values may be specified in any of the following formats:
        !           156: 
        !           157: ISO-8601 date and time format:                  "CCYYMMDDThhmmss" 
        !           158: Euro/Canadian numeric date format:              "DD.MM.[CC]YY [time] [p]"
        !           159: American numeric date format:                   "MM/DD/[CC]YY [time] [p]"
        !           160: Perversion of RFC822 date format:               "DD[-]Mon [CC]YY [time] [p]"
        !           161: IETF standard (RFC2822) date format:            "Wday, DD Mon [CC]YY [time]"
        !           162: Preferred date format:                          "Mon DD[,] [CC]YY [time] [p]"
        !           163: JavaScript Date.toString() format:              "Wday Mon DD [CC]YY [time]"
        !           164: ctime() format:                                 "Wday Mon DD [time] [CC]YY"
        !           165: time_t format:                                  seconds since Jan 1, 1970 UTC
        !           166: 
        !           167: where:
        !           168:             CC      = Century (i.e. "19" or "20")
        !           169:             YY      = Year number (e.g. "05")
        !           170:             MM      = Month number (1-12)
        !           171:             DD      = Day of month (1-31)
        !           172:             hh      = Hour of day (0-23)
        !           173:             mm      = Minute of hour (0-59)
        !           174:             ss      = Second of minute (0-59)
        !           175:             p       = AM/PM designation
        !           176:             time    = Time of day specified as "hh[:mm[:ss]]"
        !           177:             Mon     = Month name (e.g. "Jan", "Feb", etc.)
        !           178:             Wday    = Weekday name (e.g. "Mon", "Tue", etc.)
        !           179:             []      = Optional parameter
        !           180: 
        !           181: Bit-fields
        !           182: ----------
        !           183: Bit-field values may be specified as a positive number (same rules of
        !           184: interpretation as integer values), a bit-name, or a list of numbers or
        !           185: bit-names separated by the '|' character.
        !           186: 
        !           187: Bit-fields are often used to specify multiple boolean-type values in
        !           188: a single key/value pair.
        !           189: 
        !           190: Include directive
        !           191: -----------------
        !           192: An ini file may be include/imported/inserted into a another with the 
        !           193: "!include" directive. The line must begin with "!include", followed by 
        !           194: white space, and then a filename to include (optionally with a path). 
        !           195: Sections may span files.
        !           196: 
        !           197: file1.ini:
        !           198: [section_one]
        !           199:     key1 = value1
        !           200: !include file2.ini
        !           201: 
        !           202: file2.ini:
        !           203:     key2 = value2
        !           204: 
        !           205: In the above example, both key1 and key2 are part of section_one.
        !           206: 
        !           207: End-of-file directive
        !           208: ---------------------
        !           209: An ini file may be prematurely terminated with the "!eof" directive. This
        !           210: stops the ini_file module functions from processing any lines following this
        !           211: directive.
        !           212: 
        !           213: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.