Module: RapidyamlRb

Defined in:
lib/rapidyaml_rb.rb,
lib/rapidyaml_rb/version.rb

Constant Summary collapse

ParseError =

Error and SyntaxError are defined in the C extension (Init_rapidyaml_rb). ParseError is kept as an alias for backward compatibility.

SyntaxError
DATE_RE =

Regex patterns for scalar coercion during load. Only applied when the corresponding class is in permitted_classes.

/\A(\d{4})-(\d{2})-(\d{2})\z/
DATETIME_RE = 
/\A\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?: ?(?:Z|[+-]\d{2}:?\d{2}))?\z/
VERSION = 
"0.1.0"

Class Method Summary collapse

Class Method Details

.dump(obj) ⇒ String

Serializes a Ruby object to a YAML string.

Parameters:

  • obj (Object) —

    Ruby object to serialize

Returns:

  • (String) —

    YAML representation

Raises:

  • (RapidyamlRb::Error) —

    if the object cannot be serialized



56
57
58
 
# File 'lib/rapidyaml_rb.rb', line 56

def dump(obj)
  Ext.emit(obj)
end

.dump_file(obj, path) ⇒ void

This method returns an undefined value.

Serializes a Ruby object to a YAML file.

Parameters:

  • obj (Object) —

    Ruby object to serialize

  • path (String) —

    destination file path

Raises:

  • (RapidyamlRb::Error) —

    if the object cannot be serialized



157
158
159
 
# File 'lib/rapidyaml_rb.rb', line 157

def dump_file(obj, path)
  File.write(path, dump(obj))
end

.dump_stream(*objects) ⇒ String

Serializes multiple Ruby objects into a multi-document YAML stream.

Parameters:

  • objects (Array<Object>) —

    Ruby objects to serialize

Returns:

  • (String) —

    YAML stream with one document per object

Raises:

  • (RapidyamlRb::Error) —

    if any object cannot be serialized



65
66
67
68
69
70
 
# File 'lib/rapidyaml_rb.rb', line 65

def dump_stream(*objects)
  objects.map { |obj|
    s = dump(obj)
    obj.is_a?(Hash) || obj.is_a?(Array) ? "---\n#{s}" : "--- #{s}"
  }.join
end

.libyaml_version ⇒ String

Returns the version string of the bundled rapidyaml C++ library. Psych exposes libyaml_version; this is the equivalent for rapidyaml.

Returns:

  • (String) —

    rapidyaml version, e.g. "0.13.0"



85
86
87
 
# File 'lib/rapidyaml_rb.rb', line 85

def libyaml_version
  Ext.ryml_version
end

.load(yaml, symbolize_names: false, permitted_classes: []) ⇒ Object

Parses a YAML string and returns the corresponding Ruby object.

Parameters:

  • yaml (String) —

    YAML-formatted string

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

    if true, hash keys are returned as symbols

  • permitted_classes (Array<Class>) (defaults to: []) —

    classes allowed for type coercion (supports Symbol, Date, Time)

Returns:

  • (Object) —

    parsed Ruby object

Raises:

  • (RapidyamlRb::SyntaxError) —

    if the YAML is invalid



33
34
35
36
37
 
# File 'lib/rapidyaml_rb.rb', line 33

def load(yaml, symbolize_names: false, permitted_classes: [])
  result = Ext.parse(yaml)
  result = coerce_scalars(result, permitted_classes) unless permitted_classes.empty?
  symbolize_names ? deep_symbolize_keys(result) : result
end

.load_file(path, symbolize_names: false, permitted_classes: []) ⇒ Object

Parses YAML from a file and returns the corresponding Ruby object.

Parameters:

  • path (String) —

    path to the YAML file

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

    if true, hash keys are returned as symbols

  • permitted_classes (Array<Class>) (defaults to: []) —

    classes allowed for type coercion

Returns:

  • (Object) —

    parsed Ruby object

Raises:

  • (RapidyamlRb::SyntaxError) —

    if the YAML is invalid

  • (Errno::ENOENT) —

    if the file does not exist



146
147
148
149
 
# File 'lib/rapidyaml_rb.rb', line 146

def load_file(path, symbolize_names: false, permitted_classes: [])
  load(File.read(path), symbolize_names: symbolize_names,
       permitted_classes: permitted_classes)
end

.load_stream(yaml, symbolize_names: false, permitted_classes: []) {|Object| ... } ⇒ Array?

Parses all YAML documents in a string and yields each as a Ruby object. If no block given, returns an array of all documents.

Parameters:

  • yaml (String) —

    YAML-formatted string (may contain multiple documents)

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

    if true, hash keys are returned as symbols

  • permitted_classes (Array<Class>) (defaults to: []) —

    classes allowed for type coercion

Yields:

  • (Object) —

    each parsed document

Returns:

  • (Array, nil) —

    array of documents if no block given



97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/rapidyaml_rb.rb', line 97

def load_stream(yaml, symbolize_names: false, permitted_classes: [], &block)
  result = Ext.parse_stream(yaml)
  docs = result.is_a?(Array) ? result : [result]
  docs = docs.map { |d| coerce_scalars(d, permitted_classes) } unless permitted_classes.empty?
  docs = docs.map { |d| deep_symbolize_keys(d) } if symbolize_names
  if block
    docs.each(&block)
    nil
  else
    docs
  end
end

.safe_dump(obj) ⇒ String

Equivalent to dump; rapidyaml does not serialize arbitrary Ruby objects, so there is no unsafe surface to restrict.

Parameters:

  • obj (Object) —

    Ruby object to serialize

Returns:

  • (String) —

    YAML representation



77
78
79
 
# File 'lib/rapidyaml_rb.rb', line 77

def safe_dump(obj)
  dump(obj)
end

.safe_load(yaml, symbolize_names: false, permitted_classes: []) ⇒ Object

Alias matching Psych.safe_load; rapidyaml does not execute arbitrary code, so this is equivalent to load for all practical purposes.

Parameters:

  • yaml (String) —

    YAML-formatted string

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

    if true, hash keys are returned as symbols

  • permitted_classes (Array<Class>) (defaults to: []) —

    classes allowed for type coercion

Returns:

  • (Object) —

    parsed Ruby object

Raises:

  • (RapidyamlRb::SyntaxError) —

    if the YAML is invalid



47
48
49
 
# File 'lib/rapidyaml_rb.rb', line 47

def safe_load(yaml, symbolize_names: false, permitted_classes: [])
  load(yaml, symbolize_names: symbolize_names, permitted_classes: permitted_classes)
end

.safe_load_stream(yaml, symbolize_names: false, permitted_classes: [], &block) ⇒ Object

See Also:



111
112
113
114
 
# File 'lib/rapidyaml_rb.rb', line 111

def safe_load_stream(yaml, symbolize_names: false, permitted_classes: [], &block)
  load_stream(yaml, symbolize_names: symbolize_names,
              permitted_classes: permitted_classes, &block)
end

.unsafe_load(yaml, symbolize_names: false, permitted_classes: []) ⇒ Object

Alias matching Psych.unsafe_load; rapidyaml never executes arbitrary Ruby object tags, so this is equivalent to load.

Parameters:

  • yaml (String) —

    YAML-formatted string

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

    if true, hash keys are returned as symbols

  • permitted_classes (Array<Class>) (defaults to: []) —

    classes allowed for type coercion

Returns:

  • (Object) —

    parsed Ruby object



123
124
125
 
# File 'lib/rapidyaml_rb.rb', line 123

def unsafe_load(yaml, symbolize_names: false, permitted_classes: [])
  load(yaml, symbolize_names: symbolize_names, permitted_classes: permitted_classes)
end

.unsafe_load_file(path, symbolize_names: false, permitted_classes: []) ⇒ Object

Alias matching Psych.unsafe_load_file; rapidyaml never executes arbitrary Ruby object tags, so this is equivalent to load_file.

Parameters:

  • path (String) —

    path to the YAML file

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

    if true, hash keys are returned as symbols

  • permitted_classes (Array<Class>) (defaults to: []) —

    classes allowed for type coercion

Returns:

  • (Object) —

    parsed Ruby object



134
135
136
 
# File 'lib/rapidyaml_rb.rb', line 134

def unsafe_load_file(path, symbolize_names: false, permitted_classes: [])
  load_file(path, symbolize_names: symbolize_names, permitted_classes: permitted_classes)
end