Module: NestedText

Defined in:
lib/nestedtext.rb,
lib/nestedtext/encode.rb,
lib/nestedtext/decode.rb,
lib/nestedtext/encode_helpers.rb,
lib/nestedtext/error.rb,
lib/nestedtext/version.rb

Overview

NestedText

A ruby library for the human friendly data format NestedText (https://nestedtext.org/).

Provided is support for decoding a NestedText file or string to Ruby data structures, as well as encoding Ruby objects to a NestedText file or string. Furthermore there is support for serialization and deserialization of custom classes.

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

Defined Under Namespace

Modules: ToNTMixin Classes: Error

Constant Summary collapse

VERSION =

The version of this library.

'4.5.0'

Class Method Summary collapse

Class Method Details

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

Encode a Ruby object to a NestedText string.

Parameters:

  • obj (Object) —

    The object to encode to NestedText.

  • io (IO) (defaults to: nil) —

    Additionally write the output to this IO object. The caller is responsible for that the IO is closed after the call to this method. The file willl end with a newline.

  • indentation (Integer) (defaults to: 4) —

    The indentation of nested levels to use.

  • strict (Boolean) (defaults to: false) —

    If strict mode should be used.

Returns:

  • (String, nil) —

    A String containing NestedText data, or nil when obj is represented as empty.

Raises:

  • (NestedText::Error) —

    if anything went wrong.

  • Whatever the io can raise, if supplied.



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, "\n")
    io.fsync
  end
  dumper.dump obj
end

.dump_file(obj, filename, **kwargs) ⇒ String?

Encode a Ruby object to a NestedText file.

Apart from filename, this method behaves exactly like dump.

Parameters:

  • filename (String) —

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

  • obj (Object) —

    The object to encode to NestedText.

  • io (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. The file willl end with a newline.

  • indentation (Integer) —

    The indentation of nested levels to use.

  • strict (Boolean) —

    If strict mode should be used.

Returns:

  • (String, nil) —

    A String containing NestedText data, or nil when obj is represented as empty.

Raises:

  • (IOError) —

    on issues opening the filename for writing in text mode.

  • (NestedText::Error) —

    if anything went wrong.

  • Whatever the io can raise, if supplied.



41
42
43
44
45
46
47
 
# File 'lib/nestedtext/encode.rb', line 41

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

  File.open(filename, '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.

Parameters:

  • ntstring (String) —

    The string containing NestedText to be decoded.

  • top_class (String) (defaults to: Object) —

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

  • strict (Boolean) (defaults to: false) —

    If strict mode should be used.

Returns:

  • (Object, nil) —

    The parsed object.

Raises:



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

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?

Decode a NestedText stored in a given file.

Parameters:

  • filename (String) —

    The file path to read NestedText to decode from.

  • top_class (String) (defaults to: Object) —

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

  • strict (Boolean) (defaults to: false) —

    If strict mode should be used.

Returns:

  • (Object, nil) —

    The parsed object.

Raises:

  • (NestedText::Error) —

    if anything went wrong.

  • (IOError) —

    on issue opening filename for reading in text mode.



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

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, 'rt') do |file|
    Parser.new(file, top_class, strict: strict).parse
  end
end