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