本站源代码
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

146 lines
6.8KB

  1. // Package gcfg reads "INI-style" text-based configuration files with
  2. // "name=value" pairs grouped into sections (gcfg files).
  3. //
  4. // This package is still a work in progress; see the sections below for planned
  5. // changes.
  6. //
  7. // Syntax
  8. //
  9. // The syntax is based on that used by git config:
  10. // http://git-scm.com/docs/git-config#_syntax .
  11. // There are some (planned) differences compared to the git config format:
  12. // - improve data portability:
  13. // - must be encoded in UTF-8 (for now) and must not contain the 0 byte
  14. // - include and "path" type is not supported
  15. // (path type may be implementable as a user-defined type)
  16. // - internationalization
  17. // - section and variable names can contain unicode letters, unicode digits
  18. // (as defined in http://golang.org/ref/spec#Characters ) and hyphens
  19. // (U+002D), starting with a unicode letter
  20. // - disallow potentially ambiguous or misleading definitions:
  21. // - `[sec.sub]` format is not allowed (deprecated in gitconfig)
  22. // - `[sec ""]` is not allowed
  23. // - use `[sec]` for section name "sec" and empty subsection name
  24. // - (planned) within a single file, definitions must be contiguous for each:
  25. // - section: '[secA]' -> '[secB]' -> '[secA]' is an error
  26. // - subsection: '[sec "A"]' -> '[sec "B"]' -> '[sec "A"]' is an error
  27. // - multivalued variable: 'multi=a' -> 'other=x' -> 'multi=b' is an error
  28. //
  29. // Data structure
  30. //
  31. // The functions in this package read values into a user-defined struct.
  32. // Each section corresponds to a struct field in the config struct, and each
  33. // variable in a section corresponds to a data field in the section struct.
  34. // The mapping of each section or variable name to fields is done either based
  35. // on the "gcfg" struct tag or by matching the name of the section or variable,
  36. // ignoring case. In the latter case, hyphens '-' in section and variable names
  37. // correspond to underscores '_' in field names.
  38. // Fields must be exported; to use a section or variable name starting with a
  39. // letter that is neither upper- or lower-case, prefix the field name with 'X'.
  40. // (See https://code.google.com/p/go/issues/detail?id=5763#c4 .)
  41. //
  42. // For sections with subsections, the corresponding field in config must be a
  43. // map, rather than a struct, with string keys and pointer-to-struct values.
  44. // Values for subsection variables are stored in the map with the subsection
  45. // name used as the map key.
  46. // (Note that unlike section and variable names, subsection names are case
  47. // sensitive.)
  48. // When using a map, and there is a section with the same section name but
  49. // without a subsection name, its values are stored with the empty string used
  50. // as the key.
  51. // It is possible to provide default values for subsections in the section
  52. // "default-<sectionname>" (or by setting values in the corresponding struct
  53. // field "Default_<sectionname>").
  54. //
  55. // The functions in this package panic if config is not a pointer to a struct,
  56. // or when a field is not of a suitable type (either a struct or a map with
  57. // string keys and pointer-to-struct values).
  58. //
  59. // Parsing of values
  60. //
  61. // The section structs in the config struct may contain single-valued or
  62. // multi-valued variables. Variables of unnamed slice type (that is, a type
  63. // starting with `[]`) are treated as multi-value; all others (including named
  64. // slice types) are treated as single-valued variables.
  65. //
  66. // Single-valued variables are handled based on the type as follows.
  67. // Unnamed pointer types (that is, types starting with `*`) are dereferenced,
  68. // and if necessary, a new instance is allocated.
  69. //
  70. // For types implementing the encoding.TextUnmarshaler interface, the
  71. // UnmarshalText method is used to set the value. Implementing this method is
  72. // the recommended way for parsing user-defined types.
  73. //
  74. // For fields of string kind, the value string is assigned to the field, after
  75. // unquoting and unescaping as needed.
  76. // For fields of bool kind, the field is set to true if the value is "true",
  77. // "yes", "on" or "1", and set to false if the value is "false", "no", "off" or
  78. // "0", ignoring case. In addition, single-valued bool fields can be specified
  79. // with a "blank" value (variable name without equals sign and value); in such
  80. // case the value is set to true.
  81. //
  82. // Predefined integer types [u]int(|8|16|32|64) and big.Int are parsed as
  83. // decimal or hexadecimal (if having '0x' prefix). (This is to prevent
  84. // unintuitively handling zero-padded numbers as octal.) Other types having
  85. // [u]int* as the underlying type, such as os.FileMode and uintptr allow
  86. // decimal, hexadecimal, or octal values.
  87. // Parsing mode for integer types can be overridden using the struct tag option
  88. // ",int=mode" where mode is a combination of the 'd', 'h', and 'o' characters
  89. // (each standing for decimal, hexadecimal, and octal, respectively.)
  90. //
  91. // All other types are parsed using fmt.Sscanf with the "%v" verb.
  92. //
  93. // For multi-valued variables, each individual value is parsed as above and
  94. // appended to the slice. If the first value is specified as a "blank" value
  95. // (variable name without equals sign and value), a new slice is allocated;
  96. // that is any values previously set in the slice will be ignored.
  97. //
  98. // The types subpackage for provides helpers for parsing "enum-like" and integer
  99. // types.
  100. //
  101. // Error handling
  102. //
  103. // There are 3 types of errors:
  104. //
  105. // - programmer errors / panics:
  106. // - invalid configuration structure
  107. // - data errors:
  108. // - fatal errors:
  109. // - invalid configuration syntax
  110. // - warnings:
  111. // - data that doesn't belong to any part of the config structure
  112. //
  113. // Programmer errors trigger panics. These are should be fixed by the programmer
  114. // before releasing code that uses gcfg.
  115. //
  116. // Data errors cause gcfg to return a non-nil error value. This includes the
  117. // case when there are extra unknown key-value definitions in the configuration
  118. // data (extra data).
  119. // However, in some occasions it is desirable to be able to proceed in
  120. // situations when the only data error is that of extra data.
  121. // These errors are handled at a different (warning) priority and can be
  122. // filtered out programmatically. To ignore extra data warnings, wrap the
  123. // gcfg.Read*Into invocation into a call to gcfg.FatalOnly.
  124. //
  125. // TODO
  126. //
  127. // The following is a list of changes under consideration:
  128. // - documentation
  129. // - self-contained syntax documentation
  130. // - more practical examples
  131. // - move TODOs to issue tracker (eventually)
  132. // - syntax
  133. // - reconsider valid escape sequences
  134. // (gitconfig doesn't support \r in value, \t in subsection name, etc.)
  135. // - reading / parsing gcfg files
  136. // - define internal representation structure
  137. // - support multiple inputs (readers, strings, files)
  138. // - support declaring encoding (?)
  139. // - support varying fields sets for subsections (?)
  140. // - writing gcfg files
  141. // - error handling
  142. // - make error context accessible programmatically?
  143. // - limit input size?
  144. //
  145. package gcfg // import "github.com/src-d/gcfg"
上海开阖软件有限公司 沪ICP备12045867号-1