Module: Philiprehberger::TomlKit

Defined in:
lib/philiprehberger/toml_kit.rb,
lib/philiprehberger/toml_kit.rb,
lib/philiprehberger/toml_kit/diff.rb,
lib/philiprehberger/toml_kit/query.rb,
lib/philiprehberger/toml_kit/merger.rb,
lib/philiprehberger/toml_kit/parser.rb,
lib/philiprehberger/toml_kit/schema.rb,
lib/philiprehberger/toml_kit/version.rb,
lib/philiprehberger/toml_kit/serializer.rb,
lib/philiprehberger/toml_kit/type_coercion.rb,
lib/philiprehberger/toml_kit/comment_document.rb

Defined Under Namespace

Modules: Diff, Query Classes: CommentDocument, CommentPreservingParser, CommentPreservingSerializer, Error, MergeConflictError, Merger, ParseError, Parser, Schema, SchemaError, Serializer, TypeCoercion

Constant Summary collapse

VERSION = 
'0.3.0'

Class Method Summary collapse

Class Method Details

.diff(left, right) ⇒ Array<Diff::Change>

Compare two TOML hashes and return differences.

Parameters:

  • left (Hash) —

    first document

  • right (Hash) —

    second document

Returns:



103
104
105
 
# File 'lib/philiprehberger/toml_kit.rb', line 103

def self.diff(left, right)
  Diff.diff(left, right)
end

.dump(hash) ⇒ String

Serialize a Ruby Hash into a TOML string.

Parameters:

  • hash (Hash) —

    data to serialize

Returns:

  • (String) —

    TOML formatted string



57
58
59
 
# File 'lib/philiprehberger/toml_kit.rb', line 57

def self.dump(hash)
  Serializer.new.serialize(hash)
end

.load(path) ⇒ Hash

Parse a TOML file into a Ruby Hash.

Parameters:

  • path (String) —

    path to a TOML file

Returns:

  • (Hash) —

    parsed result

Raises:

  • (ParseError) —

    if the file contents are not valid TOML

  • (Errno::ENOENT) —

    if the file does not exist



49
50
51
 
# File 'lib/philiprehberger/toml_kit.rb', line 49

def self.load(path)
  parse(File.read(path, encoding: 'utf-8'))
end

.merge(left, right, strategy: :override) ⇒ Hash

Deep merge two TOML hashes.

Parameters:

  • left (Hash) —

    base hash

  • right (Hash) —

    hash to merge in

  • strategy (Symbol) (defaults to: :override) —

    :override, :keep_existing, or :error_on_conflict

Returns:

  • (Hash) 


94
95
96
 
# File 'lib/philiprehberger/toml_kit.rb', line 94

def self.merge(left, right, strategy: :override)
  Merger.merge(left, right, strategy: strategy)
end

.parse(string) ⇒ Hash

Parse a TOML string into a Ruby Hash.

Parameters:

  • string (String) —

    TOML document

Returns:

  • (Hash) —

    parsed result

Raises:



28
29
30
 
# File 'lib/philiprehberger/toml_kit.rb', line 28

def self.parse(string)
  Parser.new.parse(string)
end

.parse_with_comments(string) ⇒ CommentDocument

Parse a TOML string preserving comments for round-trip editing.

Parameters:

  • string (String) —

    TOML document

Returns:



74
75
76
 
# File 'lib/philiprehberger/toml_kit.rb', line 74

def self.parse_with_comments(string)
  CommentDocument.parse(string)
end

.query(data, path, default: nil) ⇒ Object

Query a nested value using a dot-path.

Parameters:

  • data (Hash) —

    parsed TOML hash

  • path (String) —

    dot-separated path (e.g., “database.host”)

  • default (Object) (defaults to: nil) —

    fallback value

Returns:

  • (Object) 


84
85
86
 
# File 'lib/philiprehberger/toml_kit.rb', line 84

def self.query(data, path, default: nil)
  Query.get(data, path, default: default)
end

.save(hash, path) ⇒ void

This method returns an undefined value.

Write a Ruby Hash to a TOML file.

Parameters:

  • hash (Hash) —

    data to serialize

  • path (String) —

    output file path



66
67
68
 
# File 'lib/philiprehberger/toml_kit.rb', line 66

def self.save(hash, path)
  File.write(path, dump(hash), encoding: 'utf-8')
end

.valid?(string) ⇒ Boolean

Check whether a string parses as valid TOML without raising.

Parameters:

  • string (String) —

    TOML document

Returns:

  • (Boolean) —

    true if the string is valid TOML



36
37
38
39
40
41
 
# File 'lib/philiprehberger/toml_kit.rb', line 36

def self.valid?(string)
  parse(string)
  true
rescue ParseError
  false
end