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.1"

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


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

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.



230
231
232
233
234
 
# File 'lib/perfect_toml.rb', line 230

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

  parse(io.read, **opts)
end

.parse(toml_src, version: "1.0.0", symbolize_names: false) ⇒ Object

call-seq:

parse(toml_src, version: String, 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" } }

The keyword version specifies the TOML version to parse. Supported versions are "1.0.0" and "1.1.0" (which isn't released yet and may change). Defaults to "1.0.0", but the default will change in future releases.

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" } }


209
210
211
212
213
214
215
216
217
 
# File 'lib/perfect_toml.rb', line 209

def self.parse(toml_src, version: "1.0.0", symbolize_names: false)
  case version
  when "1.0", "1.0.0" then version = :TOML_1_0_0
  when "1.1", "1.1.0" then version = :TOML_1_1_0
  else
    raise ArgumentError, "unsupported TOML version: #{ version.inspect }"
  end
  Parser.new(toml_src, version, symbolize_names).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.



314
315
316
317
318
319
 
# File 'lib/perfect_toml.rb', line 314

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