module NestedText

# NestedText A ruby library for the human friendly data format NestedText (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 {file:README.md} for documentation on Types, Strict Mode and Custom Classes.

Constants

CUSTOM_CLASS_KEY
TOP_LEVEL_TYPES
VERSION

The version of this library.

Public Class Methods

dump(obj, io: nil, indentation: 4, strict: false) click to toggle source

Encode a Ruby object to a NestedText string.

@param obj [Object] The object to encode to NestedText. @param 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.

@param indentation [Integer] The indentation of nested levels to use. @param strict [Boolean] If strict mode should be used.

@return [String, nil] A String containing NestedText data, or nil when obj is represented as empty. @raise [NestedText::Error] if anything went wrong. @raise Whatever the ‘io` can raise, if supplied.

# File lib/nestedtext/encode.rb, line 18
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) click to toggle source

Encode a Ruby object to a NestedText file.

Apart from ‘filename`, this method behaves exactly like dump.

@param (see dump) @param filename [String] The file path to write the NestedText result to. The conventional file extension is ‘.nt`.

@return (see dump) @raise (see dump) @raise [IOError] on issues opening the ‘filename` for writing in text mode.

# File lib/nestedtext/encode.rb, line 40
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) click to toggle source

Decode a NestedText string to Ruby objects.

@param ntstring [String] The string containing NestedText to be decoded. @param top_class [String] Force the top level returned object to be of this type.

Supported values are `Object`, `Array`, `Hash` and `String`.

@param strict [Boolean] If strict mode should be used.

@return [Object, nil] The parsed object. @raise [NestedText::Error] if anything went wrong.

# 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) click to toggle source

Decode a NestedText stored in a given file.

@param filename [String] The file path to read NestedText to decode from. @param top_class [String] Force the top level returned object to be of this type.

Supported values are `Object`, `Array`, `Hash` and `String`.

@param strict [Boolean] If strict mode should be used.

@return [Object, nil] The parsed object. @raise [NestedText::Error] if anything went wrong. @raise [IOError] on issue opening ‘filename` for reading in text mode.

# 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