package toml

Import Path
	github.com/pelletier/go-toml (on go.dev)

Dependency Relation
	imports 15 packages, and imported by one package


Involved Source Files

	
		Package toml is a TOML parser and manipulation library.

		This version supports the specification as described in
		https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.5.0.md

		Marshaling

		Go-toml can marshal and unmarshal TOML documents from and to data
		structures.

		TOML document as a tree

		Go-toml can operate on a TOML document as a tree. Use one of the Load*
		functions to parse TOML data and obtain a Tree instance, then one of its
		methods to manipulate the tree.

		JSONPath-like queries

		The package github.com/pelletier/go-toml/query implements a system
		similar to JSONPath to quickly retrieve elements of a TOML document using a
		single expression. See the package documentation for more information.

	      keysparsing.go
	      lexer.go
	
		Package civil implements types for civil time, a time-zone-independent
		representation of time that follows the rules of the proleptic
		Gregorian calendar with exactly 24-hour days, 60-minute hours, and 60-second
		minutes.

		Because they lack location information, these types do not represent unique
		moments or intervals of time. Use time.Time for that purpose.

	      marshal.go
	      parser.go
	      position.go
	      token.go
	      toml.go
	      tomlpub.go
	      tomltree_create.go
	      tomltree_write.go
	      tomltree_writepub.go


Package-Level Type Names (total 27, in which 13 are exported)


	/* sort exporteds by:  |  */
	
		Decoder reads and decodes TOML values from an input stream.

		
			
		
			
				Decode reads a TOML-encoded value from it's input
				and unmarshals it in the value pointed at by v.

				See the documentation for Marshal for details.

			
				SetTagName allows changing default tag "toml"

			
				Strict allows changing to strict decoding. Any fields that are found in the
				input data and do not have a corresponding struct member cause an error.

			
		
			func NewDecoder(r io.Reader) *Decoder
			func (*Decoder).SetTagName(v string) *Decoder
			func (*Decoder).Strict(strict bool) *Decoder


	
		Encoder writes TOML values to an output stream.

		
			
		
			
				ArraysWithOneElementPerLine sets up the encoder to encode arrays
				with more than one element on multiple lines instead of one.

				For example:

				  A = [1,2,3]

				Becomes

				  A = [
				    1,
				    2,
				    3,
				  ]

			
				CompactComments removes the new line before each comment in the tree.

			
				Encode writes the TOML encoding of v to the stream.

				See the documentation for Marshal for details.

			
				Indentation allows to change indentation when marshalling.

			
				Order allows to change in which order fields will be written to the output stream.

			
				PromoteAnonymous allows to change how anonymous struct fields are marshaled.
				Usually, they are marshaled as if the inner exported fields were fields in
				the outer struct. However, if an anonymous struct field is given a name in
				its TOML tag, it is treated like a regular struct field with that name.
				rather than being anonymous.

				In case anonymous promotion is enabled, all anonymous structs are promoted
				and treated like regular struct fields.

			
				QuoteMapKeys sets up the encoder to encode
				maps with string type keys with quoted TOML keys.

				This relieves the character limitations on map keys.

			
				SetTagComment allows changing default tag "comment"

			
				SetTagCommented allows changing default tag "commented"

			
				SetTagMultiline allows changing default tag "multiline"

			
				SetTagName allows changing default tag "toml"

			
		
			func NewEncoder(w io.Writer) *Encoder
			func (*Encoder).ArraysWithOneElementPerLine(v bool) *Encoder
			func (*Encoder).CompactComments(cc bool) *Encoder
			func (*Encoder).Indentation(indent string) *Encoder
			func (*Encoder).Order(ord MarshalOrder) *Encoder
			func (*Encoder).PromoteAnonymous(promote bool) *Encoder
			func (*Encoder).QuoteMapKeys(v bool) *Encoder
			func (*Encoder).SetTagComment(v string) *Encoder
			func (*Encoder).SetTagCommented(v string) *Encoder
			func (*Encoder).SetTagMultiline(v string) *Encoder
			func (*Encoder).SetTagName(v string) *Encoder


	
		A LocalDate represents a date (year, month, day).

		This type does not include location information, and therefore does not
		describe a unique 24-hour timespan.

		
			
				// Day of the month, starting at 1.

			
				// Month of the year (January = 1, ...).

			
				// Year (e.g., 2014).

		
			
				AddDays returns the date that is n days in the future.
				n can also be negative to go into the past.

			
				After reports whether d1 occurs after d2.

			
				Before reports whether d1 occurs before d2.

			
				DaysSince returns the signed number of days between the date and s, not including the end day.
				This is the inverse operation to AddDays.

			
				In returns the time corresponding to time 00:00:00 of the date in the location.

				In is always consistent with time.LocalDate, even when time.LocalDate returns a time
				on a different day. For example, if loc is America/Indiana/Vincennes, then both
				    time.LocalDate(1955, time.May, 1, 0, 0, 0, 0, loc)
				and
				    civil.LocalDate{Year: 1955, Month: time.May, Day: 1}.In(loc)
				return 23:00:00 on April 30, 1955.

				In panics if loc is nil.

			
				IsValid reports whether the date is valid.

			
				MarshalText implements the encoding.TextMarshaler interface.
				The output is the result of d.String().

			
				String returns the date in RFC3339 full-date format.

			
				UnmarshalText implements the encoding.TextUnmarshaler interface.
				The date is expected to be a string in a format accepted by ParseLocalDate.

		
			 T : encoding.TextMarshaler
			*T : encoding.TextUnmarshaler
			 T : fmt.Stringer
			
		
			func LocalDateOf(t time.Time) LocalDate
			func ParseLocalDate(s string) (LocalDate, error)
			func LocalDate.AddDays(n int) LocalDate
		
			func LocalDate.After(d2 LocalDate) bool
			func LocalDate.Before(d2 LocalDate) bool
			func LocalDate.DaysSince(s LocalDate) (days int)


	
		A LocalDateTime represents a date and time.

		This type does not include location information, and therefore does not
		describe a unique moment in time.

		
			Date LocalDate
			Time LocalTime
		
			
				After reports whether dt1 occurs after dt2.

			
				Before reports whether dt1 occurs before dt2.

			
				In returns the time corresponding to the LocalDateTime in the given location.

				If the time is missing or ambigous at the location, In returns the same
				result as time.LocalDate. For example, if loc is America/Indiana/Vincennes, then
				both
				    time.LocalDate(1955, time.May, 1, 0, 30, 0, 0, loc)
				and
				    civil.LocalDateTime{
				        civil.LocalDate{Year: 1955, Month: time.May, Day: 1}},
				        civil.LocalTime{Minute: 30}}.In(loc)
				return 23:30:00 on April 30, 1955.

				In panics if loc is nil.

			
				IsValid reports whether the datetime is valid.

			
				MarshalText implements the encoding.TextMarshaler interface.
				The output is the result of dt.String().

			
				String returns the date in the format described in ParseLocalDate.

			
				UnmarshalText implements the encoding.TextUnmarshaler interface.
				The datetime is expected to be a string in a format accepted by ParseLocalDateTime

		
			 T : encoding.TextMarshaler
			*T : encoding.TextUnmarshaler
			 T : fmt.Stringer
			
		
			func LocalDateTimeOf(t time.Time) LocalDateTime
			func ParseLocalDateTime(s string) (LocalDateTime, error)
		
			func LocalDateTime.After(dt2 LocalDateTime) bool
			func LocalDateTime.Before(dt2 LocalDateTime) bool


	
		A LocalTime represents a time with nanosecond precision.

		This type does not include location information, and therefore does not
		describe a unique moment in time.

		This type exists to represent the TIME type in storage-based APIs like BigQuery.
		Most operations on Times are unlikely to be meaningful. Prefer the LocalDateTime type.

		
			
				// The hour of the day in 24-hour format; range [0-23]

			
				// The minute of the hour; range [0-59]

			
				// The nanosecond of the second; range [0-999999999]

			
				// The second of the minute; range [0-59]

		
			
				IsValid reports whether the time is valid.

			
				MarshalText implements the encoding.TextMarshaler interface.
				The output is the result of t.String().

			
				String returns the date in the format described in ParseLocalTime. If Nanoseconds
				is zero, no fractional part will be generated. Otherwise, the result will
				end with a fractional part consisting of a decimal point and nine digits.

			
				UnmarshalText implements the encoding.TextUnmarshaler interface.
				The time is expected to be a string in a format accepted by ParseLocalTime.

		
			 T : encoding.TextMarshaler
			*T : encoding.TextUnmarshaler
			 T : fmt.Stringer
			
		
			func LocalTimeOf(t time.Time) LocalTime
			func ParseLocalTime(s string) (LocalTime, error)


	
		Marshaler is the interface implemented by types that
		can marshal themselves into valid TOML.

		
			( T) MarshalTOML() ([]byte, error)


	

		
			func ValueStringRepresentation(v interface{}, commented string, indent string, ord MarshalOrder, arraysOneElementPerLine bool) (string, error)
			func (*Encoder).Order(ord MarshalOrder) *Encoder
			
		
			const OrderAlphabetical
			const OrderPreserve


	
		Position of a document element within a TOML document.

		Line and Col are both 1-indexed positions for the element's line number and
		column number, respectively.  Values of zero or less will cause Invalid(),
		to return true.

		
			
				// column within the line

			
				// line within the document

		
			
				Invalid returns whether or not the position is valid (i.e. with negative or
				null values)

			
				String representation of the position.
				Displays 1-indexed line and column numbers.

		
			 T : fmt.Stringer
			
		
			func (*PubTOMLValue).Position() Position
			func (*Tree).GetPosition(key string) Position
			func (*Tree).GetPositionPath(keys []string) Position
			func (*Tree).Position() Position
		
			func (*PubTOMLValue).SetPosition(p Position)
			func (*Tree).SetPositionPath(keys []string, pos Position)
			


	
		PubTOMLValue wrapping tomlValue in order to access all properties from outside.

		
			
		
			(*T) Comment() string
			(*T) Commented() bool
			(*T) Multiline() bool
			(*T) Position() Position
			(*T) SetComment(s string)
			(*T) SetCommented(c bool)
			(*T) SetMultiline(m bool)
			(*T) SetPosition(p Position)
			(*T) SetValue(v interface{})
			(*T) Value() interface{}


	
		PubTree wrapping Tree in order to access all properties from outside.


	
		SetOptions arguments are supplied to the SetWithOptions and SetPathWithOptions functions to modify marshalling behaviour.
		The default values within the struct are valid default options.

		
			Comment string
			Commented bool
			Literal bool
			Multiline bool
		
			func (*Tree).SetPathWithOptions(keys []string, opts SetOptions, value interface{})
			func (*Tree).SetWithOptions(key string, opts SetOptions, value interface{})


	
		Tree is the result of the parsing of a TOML file.

		
			
		
			(*T) Comment() string
			(*T) Commented() bool
			
				Delete removes a key from the tree.
				Key is a dot-separated path (e.g. a.b.c).

			
				DeletePath removes a key from the tree.
				Keys is an array of path elements (e.g. {"a","b","c"}).

			
				Get the value at key in the Tree.
				Key is a dot-separated path (e.g. a.b.c) without single/double quoted strings.
				If you need to retrieve non-bare keys, use GetPath.
				Returns nil if the path does not exist in the tree.
				If keys is of length zero, the current tree is returned.

			
				GetArray returns the value at key in the Tree.
				It returns []string, []int64, etc type if key has homogeneous lists
				Key is a dot-separated path (e.g. a.b.c) without single/double quoted strings.
				Returns nil if the path does not exist in the tree.
				If keys is of length zero, the current tree is returned.

			
				GetArrayPath returns the element in the tree indicated by 'keys'.
				If keys is of length zero, the current tree is returned.

			
				GetDefault works like Get but with a default value

			
				GetPath returns the element in the tree indicated by 'keys'.
				If keys is of length zero, the current tree is returned.

			
				GetPosition returns the position of the given key.

			
				GetPositionPath returns the element in the tree indicated by 'keys'.
				If keys is of length zero, the current tree is returned.

			
				Has returns a boolean indicating if the given key exists.

			
				HasPath returns true if the given path of keys exists, false otherwise.

			(*T) Inline() bool
			
				Keys returns the keys of the toplevel tree (does not recurse).

			
				Marshal returns the TOML encoding of Tree.
				See Marshal() documentation for types mapping table.

			
				Position returns the position of the tree.

			
				Set an element in the tree.
				Key is a dot-separated path (e.g. a.b.c).
				Creates all necessary intermediate trees, if needed.

			(*T) SetComment(c string)
			(*T) SetCommented(c bool)
			(*T) SetInline(i bool)
			
				SetPath sets an element in the tree.
				Keys is an array of path elements (e.g. {"a","b","c"}).
				Creates all necessary intermediate trees, if needed.

			
				SetPathWithComment is the same as SetPath, but allows you to provide comment
				information to the key, that will be reused by Marshal().

			
				SetPathWithOptions is the same as SetPath, but allows you to provide
				formatting instructions to the key, that will be reused by Marshal().

			
				SetPositionPath sets the position of element in the tree indicated by 'keys'.
				If keys is of length zero, the current tree position is set.

			(*T) SetValues(v map[string]interface{})
			
				SetWithComment is the same as Set, but allows you to provide comment
				information to the key, that will be reused by Marshal().

			
				SetWithOptions is the same as Set, but allows you to provide formatting
				instructions to the key, that will be used by Marshal().

			
				String generates a human-readable representation of the current tree.
				Alias of ToString. Present to implement the fmt.Stringer interface.

			
				ToMap recursively generates a representation of the tree using Go built-in structures.
				The following types are used:

					* bool
					* float64
					* int64
					* string
					* uint64
					* time.Time
					* map[string]interface{} (where interface{} is any of this list)
					* []interface{} (where interface{} is any of this list)

			
				ToTomlString generates a human-readable representation of the current tree.
				Output spans multiple lines, and is suitable for ingest by a TOML parser.
				If the conversion cannot be performed, ToString returns a non-nil error.

			
				Unmarshal attempts to unmarshal the Tree into a Go struct pointed by v.
				Neither Unmarshaler interfaces nor UnmarshalTOML functions are supported for
				sub-structs, and only definite types can be unmarshaled.

			(*T) Values() map[string]interface{}
			
				WriteTo encode the Tree as Toml and writes it to the writer w.
				Returns the number of bytes written in case of success, or an error if anything happened.

			
		
			*T : github.com/golang/protobuf/proto.Marshaler
			*T : fmt.Stringer
			*T : io.WriterTo
			
		
			func Load(content string) (tree *Tree, err error)
			func LoadBytes(b []byte) (tree *Tree, err error)
			func LoadFile(path string) (tree *Tree, err error)
			func LoadReader(reader io.Reader) (tree *Tree, err error)
			func TreeFromMap(m map[string]interface{}) (*Tree, error)
			
		
			


	
		Unmarshaler is the interface implemented by types that
		can unmarshal a TOML description of themselves.

		
			( T) UnmarshalTOML(interface{}) error


	


Package-Level Functions (total 77, in which 16 are exported)


	
		Load creates a Tree from a string.


	
		LoadBytes creates a Tree from a []byte.


	
		LoadFile creates a Tree from a file.


	
		LoadReader creates a Tree from any io.Reader.


	
		LocalDateOf returns the LocalDate in which a time occurs in that time's location.


	
		LocalDateTimeOf returns the LocalDateTime in which a time occurs in that time's location.


	
		LocalTimeOf returns the LocalTime representing the time of day in which a time occurs
		in that time's location. It ignores the date.


	
		Marshal returns the TOML encoding of v.  Behavior is similar to the Go json
		encoder, except that there is no concept of a Marshaler interface or MarshalTOML
		function for sub-structs, and currently only definite types can be marshaled
		(i.e. no `interface{}`).

		The following struct annotations are supported:

		  toml:"Field"      Overrides the field's name to output.
		  omitempty         When set, empty values and groups are not emitted.
		  comment:"comment" Emits a # comment on the same line. This supports new lines.
		  commented:"true"  Emits the value as commented.

		Note that pointers are automatically assigned the "omitempty" option, as TOML
		explicitly does not handle null values (saying instead the label should be
		dropped).

		Tree structural types and corresponding marshal types:

		  *Tree                            (*)struct, (*)map[string]interface{}
		  []*Tree                          (*)[](*)struct, (*)[](*)map[string]interface{}
		  []interface{} (as interface{})   (*)[]primitive, (*)[]([]interface{})
		  interface{}                      (*)primitive

		Tree primitive types and corresponding marshal types:

		  uint64     uint, uint8-uint64, pointers to same
		  int64      int, int8-uint64, pointers to same
		  float64    float32, float64, pointers to same
		  string     string, pointers to same
		  bool       bool, pointers to same
		  time.LocalTime  time.LocalTime{}, pointers to same

		For additional flexibility, use the Encoder API.


	
		NewDecoder returns a new decoder that reads from r.


	
		NewEncoder returns a new encoder that writes to w.


	
		ParseLocalDate parses a string in RFC3339 full-date format and returns the date value it represents.


	
		ParseLocalDateTime parses a string and returns the LocalDateTime it represents.
		ParseLocalDateTime accepts a variant of the RFC3339 date-time format that omits
		the time offset but includes an optional fractional time, as described in
		ParseLocalTime. Informally, the accepted format is
		    YYYY-MM-DDTHH:MM:SS[.FFFFFFFFF]
		where the 'T' may be a lower-case 't'.


	
		ParseLocalTime parses a string and returns the time value it represents.
		ParseLocalTime accepts an extended form of the RFC3339 partial-time format. After
		the HH:MM:SS part of the string, an optional fractional part may appear,
		consisting of a decimal point followed by one to nine decimal digits.
		(RFC3339 admits only one digit after the decimal point).


	
		TreeFromMap initializes a new Tree object using the given map.


	
		Unmarshal parses the TOML-encoded data and stores the result in the value
		pointed to by v. Behavior is similar to the Go json encoder, except that there
		is no concept of an Unmarshaler interface or UnmarshalTOML function for
		sub-structs, and currently only definite types can be unmarshaled to (i.e. no
		`interface{}`).

		The following struct annotations are supported:

		  toml:"Field" Overrides the field's name to map to.
		  default:"foo" Provides a default value.

		For default values, only fields of the following types are supported:
		  * string
		  * bool
		  * int
		  * int64
		  * float64

		See Marshal() documentation for types mapping table.


	
		ValueStringRepresentation transforms an interface{} value into its toml string representation.


	



Package-Level Constants (total 44, in which 2 are exported)


	
		Sort fields alphabetically.


	
		Preserve the order the fields are encountered. For example, the order of fields in
		a struct.