Module: NestedText

Defined in:
lib/nestedtext.rb,
lib/nestedtext/error.rb,
lib/nestedtext/decode.rb,
lib/nestedtext/dumper.rb,
lib/nestedtext/encode.rb,
lib/nestedtext/parser.rb,
lib/nestedtext/version.rb,
lib/nestedtext/scanners.rb,
lib/nestedtext/constants.rb,
lib/nestedtext/encode_helpers.rb,
lib/nestedtext/errors_internal.rb,
lib/nestedtext/core_ext_internal.rb

Overview

NestedText

The main module in this library to use.

See README.md for documentation on Types, Strict Mode and Custom Classes.

Defined Under Namespace

Modules: NTEncodeMixin Classes: Error

Constant Summary collapse

VERSION =

The version of this library.

"3.0.0"

Class Method Summary collapse

Class Method Details

.dump(obj, io: nil, indentation: 4, strict: false) ⇒ Object

Encode a Ruby object to a NestedText string.

obj

The object to encode to NestedText.

io

Additionally write the output to this IO object. The caller is responsible for that the IO is closed after the call to this method.

indentation

The indentation of nested levels to use.

strict

If strict mode should be used. true or false. Default is false

Returns a String containing NestedText data.

Raises NestedText::Error if anything went wrong.

Raises whatever the passed io can raise.

Raises:



19
20
21
22
23
24
25
26
27
28
29
 
# File 'lib/nestedtext/encode.rb', line 19

def self.dump(obj, io: nil, indentation: 4, strict: false)
  raise Errors::DumpBadIOError, io unless io.nil? || io.respond_to?(:write) && io.respond_to?(:fsync)

  dumper = Dumper.new(indentation, strict)
  result = dumper.dump obj
  unless io.nil?
    io.write(result)
    io.fsync
  end
  dumper.dump obj
end

.dump_file(obj, filename, **kwargs) ⇒ Object

Encode a Ruby object to a NestedText file.

filename

The file path to write the NestedText result to. The conventional file extension is .nt.

Raises IOError on issues opening the filename for writing in text mode.

Apart from filename, this method behaves exactly like dump (taking same arguments, returning and raising the same values).

Raises:



38
39
40
41
42
43
44
 
# File 'lib/nestedtext/encode.rb', line 38

def self.dump_file(obj, filename, **kwargs)
  raise Errors::DumpFileBadPathError, filename unless filename.is_a? String

  File.open(filename, mode = "wt") do |file|
    dump(obj, io: file, **kwargs)
  end
end

.load(ntstring, top_class: Object, strict: false) ⇒ Object

Decode a NestedText string to Ruby objects.

ntstring

The string containing NestedText to be decoded.

top_class

Force the top level returned object to be of this type. Supported values are Object, Array, Hash and String. Default is Object.

strict

If strict mode should be used. true or false. Default is false

Returns the parsed object.

Raises NestedText::Error if anything went wrong.

Raises:



19
20
21
22
23
 
# File 'lib/nestedtext/decode.rb', line 19

def self.load(ntstring, top_class: Object, strict: false)
  raise Errors::WrongInputTypeError.new([String], ntstring) unless ntstring.nil? || ntstring.is_a?(String)

  Parser.new(StringIO.new(ntstring), top_class, strict: strict).parse
end

.load_file(filename, top_class: Object, strict: false) ⇒ Object

filename

The file path to read NestedText to decode from.

top_class

Force the top level returned object to be of this type. Supported values are Object, Array, Hash and String. Default is Object.

strict

If strict mode should be used. true or false. Default is false

Returns the parsed object.

Raises NestedText::Error if anything went wrong.

Raises IOError on issue opening filename for reading in text mode.

Raises:



36
37
38
39
40
41
42
43
 
# File 'lib/nestedtext/decode.rb', line 36

def self.load_file(filename, top_class: Object, strict: false)
  raise Errors::WrongInputTypeError.new([String], filename) unless !filename.nil? && filename.is_a?(String)

  # Open explicitly in text mode to detect \r as line ending.
  File.open(filename, mode = "rt") do |file|
    Parser.new(file, top_class, strict: strict).parse
  end
end