com.aliyun.oss.common.utils

## 类 IniEditor

- java.lang.Object
- - com.aliyun.oss.common.utils.IniEditor

-     public class IniEditor
      extends Object

  Loads, edits and saves INI-style configuration files. While loading from and saving to streams and files, `IniEditor` preserves comments and blank lines as well as the order of sections and lines in general.

  `IniEditor` assumes configuration files to be split in sections. A section starts out with a header, which consists of the section name enclosed in brackets (`'['` and `']'`). Everything before the first section header is ignored when loading from a stream or file. The ``IniEditor.Section`` class can be used to load configuration files without sections (ie Java-style properties).

  A "common section" may be named. All sections inherit the options of this section but can overwrite them.

  `IniEditor` represents an INI file (or rather, its sections) line by line, as comment, blank and option lines. A comment is a line which has a comment delimiter as its first non-white space character. The default comment delimiters, which may be overwritten, are `'#'` and `';'`.

  A blank line is any line that consists only of white space.

  Everything else is an option line. Option names and values are separated by option delimiters `'='`, `':'` or white space (spaces and tabs).

  Here's a minimal example. Suppose, we have this in a file called `users.ini`:

         [root]
         role = administrator
         last_login = 2003-05-04

         [joe]
         role = author
         last_login = 2003-05-13

  Let's load that file, add something to it and save the changes:

       IniEditor users = new IniEditor();
       users.load("users.ini");
       users.set("root", "last_login", "2003-05-16");
       users.addComment("root", "Must change password often");
       users.set("root", "change_pwd", "10 days");
       users.addBlankLine("root");
       users.save("users.ini");

  Now, the file looks like this:

         [root]
         role = administrator
         last_login = 2003-05-16

         # Must change password often
         change_pwd = 10 days

         [joe]
         role = author
         last_login = 2003-05-13

  IniEditor provides services simliar to the standard Java API class `java.util.Properties`. It uses its own parser, though, which differs in these respects from that of `Properties`:

  - Line continuations (backslashes at the end of an option line) are not supported.
  - No kind of character escaping is performed or recognized. Characters are read and written in in the default character encoding. If you want to use a different character encoding, use the `load(InputStreamReader)` and `save(OutputStreamWriter)` methods with a reader and writer tuned to the desired character encoding.
  - As a consequence, option names may not contain option/value separators (normally `'='`, `':'` and white space).
  版本:
    r5 (3/4/2013)

- - ### 嵌套类概要

    嵌套类
    限定符和类型 | 类和说明
    --- | ---
    `static class` | `IniEditor.NoSuchSectionException` Thrown when an non-existent section is addressed.
    `static class` | `IniEditor.Section` Loads, edits and saves a section of an INI-style configuration file.

  - ### 构造器概要

    构造器
    构造器和说明
    `IniEditor()` Constructs new bare IniEditor instance.
    `IniEditor(boolean isCaseSensitive)` Constructs new bare IniEditor instance specifying case-sensitivity.
    `IniEditor(char[] delims)` Constructs new IniEditor defining comment delimiters.
    `IniEditor(char[] delims, boolean isCaseSensitive)` Constructs new IniEditor defining comment delimiters.
    `IniEditor(String commonName)` Constructs new IniEditor instance with a common section.
    `IniEditor(String commonName, boolean isCaseSensitive)` Constructs new IniEditor instance with a common section.
    `IniEditor(String commonName, char[] delims)` Constructs new IniEditor instance with a common section, defining comment delimiters.
    `IniEditor(String commonName, char[] delims, boolean isCaseSensitive)` Constructs new IniEditor instance with a common section, defining comment delimiters.

  - ### 方法概要

    方法
    限定符和类型 | 方法和说明
    --- | ---
    `void` | `addBlankLine(String section)` Adds a blank line to the end of a section.
    `void` | `addComment(String section, String comment)` Adds a comment line to the end of a section.
    `boolean` | `addSection(String name)` Adds a section if it doesn't exist yet.
    `String` | `get(String section, String option)` Returns the value of a given option in a given section or null if either the section or the option don't exist.
    `Map<String,String>` | `getSectionMap(String section)` Returns a map of a given section with option/value pairs or null if the section doesn't exist.
    `boolean` | `hasOption(String section, String option)` Checks whether an option exists in a given section.
    `boolean` | `hasSection(String name)` Checks whether a section with a particular name exists in this instance.
    `void` | `load(File file)` Loads INI formatted input from a file into this instance, using the default character encoding.
    `void` | `load(InputStream stream)` Loads INI formatted input from a stream into this instance, using the default character encoding.
    `void` | `load(InputStreamReader streamReader)` Loads INI formatted input from a stream reader into this instance.
    `void` | `load(String filename)` Loads INI formatted input from a file into this instance, using the default character encoding.
    `List<String>` | `optionNames(String section)` Returns all option names of a section, not including options from the common section.
    `boolean` | `remove(String section, String option)` Removes an option from a section if it exists.
    `boolean` | `removeSection(String name)` Removes a section if it exists.
    `void` | `save(File file)` Writes this instance in INI format to a file.
    `void` | `save(OutputStream stream)` Writes this instance in INI format to an output stream.
    `void` | `save(OutputStreamWriter streamWriter)` Writes this instance in INI format to an output stream writer.
    `void` | `save(String filename)` Writes this instance in INI format to a file.
    `List<String>` | `sectionNames()` Returns all section names in this instance minus the common section if one was defined.
    `void` | `set(String section, String option, String value)` Sets the value of an option in a section, if the option exist, otherwise adds the option to the section.
    `void` | `setOptionFormatString(String formatString)` Sets the option format for this instance to the given string.

    - ### 从类继承的方法 java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### 构造器详细资料

    - #### IniEditor

          public IniEditor()

      Constructs new bare IniEditor instance.

    - #### IniEditor

          public IniEditor(boolean isCaseSensitive)

      Constructs new bare IniEditor instance specifying case-sensitivity.
      参数:
        `isCaseSensitive` - section and option names are case-sensitive if this is true

    - #### IniEditor

          public IniEditor(String commonName)

      Constructs new IniEditor instance with a common section. Options in the common section are used as defaults for all other sections.
      参数:
        `commonName` - name of the common section

    - #### IniEditor

          public IniEditor(String commonName,
                   boolean isCaseSensitive)

      Constructs new IniEditor instance with a common section. Options in the common section are used as defaults for all other sections.
      参数:
        `commonName` - name of the common section
        `isCaseSensitive` - section and option names are case-sensitive if this is true

    - #### IniEditor

          public IniEditor(char[] delims)

      Constructs new IniEditor defining comment delimiters.
      参数:
        `delims` - an array of characters to be recognized as starters of comment lines; the first of them will be used for newly created comments

    - #### IniEditor

          public IniEditor(char[] delims,
                   boolean isCaseSensitive)

      Constructs new IniEditor defining comment delimiters.
      参数:
        `delims` - an array of characters to be recognized as starters of comment lines; the first of them will be used for newly created comments
        `isCaseSensitive` - section and option names are case-sensitive if this is true

    - #### IniEditor

          public IniEditor(String commonName,
                   char[] delims)

      Constructs new IniEditor instance with a common section, defining comment delimiters. Options in the common section are used as defaults for all other sections.
      参数:
        `commonName` - name of the common section
        `delims` - an array of characters to be recognized as starters of comment lines; the first of them will be used for newly created comments

    - #### IniEditor

          public IniEditor(String commonName,
                   char[] delims,
                   boolean isCaseSensitive)

      Constructs new IniEditor instance with a common section, defining comment delimiters. Options in the common section are used as defaults for all other sections.
      参数:
        `commonName` - name of the common section
        `delims` - an array of characters to be recognized as starters of comment lines; the first of them will be used for newly created comments

  - ### 方法详细资料

    - #### setOptionFormatString

          public void setOptionFormatString(String formatString)

      Sets the option format for this instance to the given string. Options will be rendered according to the given format string when printed. The string must contain `%s` three times, these will be replaced with the option name, the option separator and the option value in this order. Literal percentage signs must be escaped by preceding them with another percentage sign (i.e., `%%` corresponds to one percentage sign). The default format string is `"%s %s %s"`. Option formats may look like format strings as supported by Java 1.5, but the string is in fact parsed in a custom fashion to guarantee backwards compatibility. So don't try clever stuff like using format conversion types other than `%s`.
      参数:
        `formatString` - a format string, containing `%s` exactly three times
      抛出:
        `IllegalArgumentException` - if the format string is illegal

    - #### get

          public String get(String section,
                   String option)

      Returns the value of a given option in a given section or null if either the section or the option don't exist. If a common section was defined options are also looked up there if they're not present in the specific section.
      参数:
        `section` - the section's name
        `option` - the option's name
      返回:
        the option's value
      抛出:
        `NullPointerException` - any of the arguments is `null`

    - #### getSectionMap

          public Map<String,String> getSectionMap(String section)

      Returns a map of a given section with option/value pairs or null if the section doesn't exist.
      参数:
        `section` - the section's name
      返回:
        HashMap of option/value pairs from the section
      抛出:
        `NullPointerException` - if section is `null`

    - #### set

          public void set(String section,
                 String option,
                 String value)

      Sets the value of an option in a section, if the option exist, otherwise adds the option to the section. Trims white space from the start and the end of the value and deletes newline characters it might contain.
      参数:
        `section` - the section's name
        `option` - the option's name
        `value` - the option's value
      抛出:
        `IniEditor.NoSuchSectionException` - no section with the given name exists
        `IllegalArgumentException` - the option name is illegal, ie contains a '=' character or consists only of white space
        `NullPointerException` - section or option are `null`

    - #### remove

          public boolean remove(String section,
                       String option)

      Removes an option from a section if it exists. Will not remove options from the common section if it's not directly addressed.
      参数:
        `section` - the section's name
        `option` - the option's name
      返回:
        `true` if the option was actually removed
      抛出:
        `IniEditor.NoSuchSectionException` - no section with the given name exists

    - #### hasOption

          public boolean hasOption(String section,
                          String option)

      Checks whether an option exists in a given section. Options in the common section are assumed to not exist in particular sections, unless they're overwritten.
      参数:
        `section` - the section's name
        `option` - the option's name
      返回:
        true if the given section has the option

    - #### hasSection

          public boolean hasSection(String name)

      Checks whether a section with a particular name exists in this instance.
      参数:
        `name` - the name of the section
      返回:
        true if the section exists

    - #### addSection

          public boolean addSection(String name)

      Adds a section if it doesn't exist yet.
      参数:
        `name` - the name of the section
      返回:
        `true` if the section didn't already exist
      抛出:
        `IllegalArgumentException` - the name is illegal, ie contains one of the characters '[' and ']' or consists only of white space

    - #### removeSection

          public boolean removeSection(String name)

      Removes a section if it exists.
      参数:
        `name` - the section's name
      返回:
        `true` if the section actually existed
      抛出:
        `IllegalArgumentException` - when trying to remove the common section

    - #### sectionNames

          public List<String> sectionNames()

      Returns all section names in this instance minus the common section if one was defined.
      返回:
        list of the section names in original/insertion order

    - #### optionNames

          public List<String> optionNames(String section)

      Returns all option names of a section, not including options from the common section.
      参数:
        `section` - the section's name
      返回:
        list of option names
      抛出:
        `IniEditor.NoSuchSectionException` - no section with the given name exists

    - #### addComment

          public void addComment(String section,
                        String comment)

      Adds a comment line to the end of a section. A comment spanning several lines (ie with line breaks) will be split up, one comment line for each line.
      参数:
        `section` - the section's name
        `comment` - the comment
      抛出:
        `IniEditor.NoSuchSectionException` - no section with the given name exists

    - #### addBlankLine

          public void addBlankLine(String section)

      Adds a blank line to the end of a section.
      参数:
        `section` - the section's name
      抛出:
        `IniEditor.NoSuchSectionException` - no section with the given name exists

    - #### save

          public void save(String filename)
                    throws IOException

      Writes this instance in INI format to a file.
      参数:
        `filename` - the file to write to
      抛出:
        `IOException` - at an I/O problem

    - #### save

          public void save(File file)
                    throws IOException

      Writes this instance in INI format to a file.
      参数:
        `file` - where to save to
      抛出:
        `IOException` - at an I/O problem

    - #### save

          public void save(OutputStream stream)
                    throws IOException

      Writes this instance in INI format to an output stream. This method takes an `OutputStream` for maximum flexibility, internally it does of course use a writer for character based output.
      参数:
        `stream` - where to write
      抛出:
        `IOException` - at an I/O problem

    - #### save

          public void save(OutputStreamWriter streamWriter)
                    throws IOException

      Writes this instance in INI format to an output stream writer.
      参数:
        `streamWriter` - where to write
      抛出:
        `IOException` - at an I/O problem

    - #### load

          public void load(String filename)
                    throws IOException

      Loads INI formatted input from a file into this instance, using the default character encoding. Everything in the file before the first section header is ignored.
      参数:
        `filename` - file to read from
      抛出:
        `IOException` - at an I/O problem

    - #### load

          public void load(File file)
                    throws IOException

      Loads INI formatted input from a file into this instance, using the default character encoding. Everything in the file before the first section header is ignored.
      参数:
        `file` - file to read from
      抛出:
        `IOException` - at an I/O problem

    - #### load

          public void load(InputStream stream)
                    throws IOException

      Loads INI formatted input from a stream into this instance, using the default character encoding. This method takes an `InputStream` for maximum flexibility, internally it does use a reader (using the default character encoding) for character based input. Everything in the stream before the first section header is ignored.
      参数:
        `stream` - where to read from
      抛出:
        `IOException` - at an I/O problem

    - #### load

          public void load(InputStreamReader streamReader)
                    throws IOException

      Loads INI formatted input from a stream reader into this instance. Everything in the stream before the first section header is ignored.
      参数:
        `streamReader` - where to read from
      抛出:
        `IOException` - at an I/O problem

Copyright © 2020. All Rights Reserved.