Module: PerfectTOML

Defined in:
lib/perfect_toml.rb

Defined Under Namespace

Classes: Generator, LocalDate, LocalDateTime, LocalDateTimeBase, LocalTime, ParseError, Parser

Constant Summary collapse

VERSION = 
"0.9.0"

Class Method Summary collapse

Class Method Details

.generate(hash, **opts) ⇒ Object

call-seq:

generate(hash, sort_keys: false, use_literal_string: false, use_multiline_string: false, use_dot: false) -> String

Encode a Hash in TOML format.

PerfectTOML.generate({ key: 42 })
# output:
#   key = 42

The order of hashes are respected by default. If you want to sort them, you can use sort_keys keyword:

PerfectTOML.generate({ z: 1, a: 2 })
# output:
#   z = 1
#   a = 2

PerfectTOML.generate({ z: 1, a: 2 }, sort_keys: true)
# output:
#   a = 2
#   z = 1

By default, all strings are quoted by quotation marks. If use_literal_string keyword is specified as truthy, it prefers a literal string quoted by single quotes:

PerfectTOML.generate({ a: "foo" })
# output:
#   a = "foo"

PerfectTOML.generate({ a: "foo" }, use_literal_string: true)
# output:
#   a = 'foo'

Multiline strings are not used by default. If use_multiline_string keyword is specified as truthy, it uses a multiline string if the string contains a newline.

PerfectTOML.generate({ a: "foo\nbar" })
# output:
#   a = "foo\nbar"

PerfectTOML.generate({ a: "foo\nbar" }, use_multiline_string: true)
# output:
#   a = """
#   foo
#   bar"

By default, dotted keys are used only in a header. If use_dot keyword is specified as truthy, it uses a dotted key only when a subtree does not branch.

PerfectTOML.generate({ a: { b: { c: { d: 42 } } } })
# output:
#   [a.b.c]
#   d = 42

PerfectTOML.generate({ a: { b: { c: { d: 42 } } } }, use_dot: true)
# output:
#   a.b.c.d = 42



280
281
282
283
284
 
# File 'lib/perfect_toml.rb', line 280

def self.generate(hash, **opts)
  out = ""
  Generator.new(hash, out, **opts).generate
  out
end

.load_file(io, **opts) ⇒ Object

call-seq:

load_file(filename, symbolize_names: boolean) -> Object

Loads a TOML file.

# test.toml
#   key = 42
PerfectTOML.load_file("test.toml") #=> { "key" => 42 }

See PerfectTOML.parse for options.



213
214
215
216
217
 
# File 'lib/perfect_toml.rb', line 213

def self.load_file(io, **opts)
  io = File.open(io, encoding: "UTF-8") unless IO === io

  parse(io.read, **opts)
end

.parse(toml_src, **opts) ⇒ Object

call-seq:

parse(toml_src, symbolize_names: boolean) -> Object

Decodes a TOML string.

PerfectTOML.parse("key = 42")  #=> { "key" => 42 }

src = <<~END
  [foo]
  bar = "baz"
END
PerfectTOML.parse(src)  #=> { "foo" => { "bar" => "baz" } }

All keys in the Hash are String by default. If a keyword ‘symbolize_names` is specficied as truthy, all keys in the Hash will be Symbols.

PerfectTOML.parse("key = 42", symbolize_names: true)  #=> { :key => 42 }

src = <<~END
  [foo]
  bar = "baz"
END
PerfectTOML.parse(src, symbolize_names: true)  #=> { :key => { :bar => "baz" } }



198
199
200
 
# File 'lib/perfect_toml.rb', line 198

def self.parse(toml_src, **opts)
  Parser.new(toml_src, **opts).parse
end

.save_file(io, hash, **opts) ⇒ Object

call-seq:

save_file(filename, hash, symbolize_names: boolean) -> Object

Saves a Hash into a file in TOML format.

PerfectTOML.save_file("out.toml", { key: 42 })
# out.toml
#   key = 42

See PerfectTOML.generate for options.



297
298
299
300
301
302
 
# File 'lib/perfect_toml.rb', line 297

def self.save_file(io, hash, **opts)
  io = File.open(io, mode: "w", encoding: "UTF-8") unless IO === io
  Generator.new(hash, io, **opts).generate
ensure
  io.close
end