class Sycl::Array

A Sycl::Array is like an Array, but creating one from an array blesses any child Array or Hash objects into Sycl::Array or Sycl::Hash objects. All the normal Array methods are supported, and automatically promote any inputs into Sycl equivalents. The following example illustrates this:

h = { 'a' => { 'b' => 'Hello, world!' } }
a = Sycl::Array.new
a << h

puts a.first.a.b   # outputs 'Hello, world!'

A Sycl::Array supports YAML preprocessing and postprocessing, and having individual nodes marked as being rendered in inline style. YAML output is always sorted, unless individual nodes are marked as being rendered unsorted.

a = Sycl::Array.from_array %w{bravo delta charlie alpha}
a.render_inline!
a.yaml_preprocessor { |x| x.each { |e| e.capitalize! } }
a.yaml_postprocessor { |yaml| yaml.sub(/\A---\s+/, '') }

puts a.first    # outputs 'bravo'
puts a.to_yaml  # outputs '[Alpha, Bravo, Charlie, Delta]'

Public Class Methods

default_sorting=(sort) click to toggle source

Set Default Array Sorting. In some cases we want to instantiate all sycl objects with sorting defaulted to either true or false.

Example:

Sycl::Array.default_sorting = false
# File lib/sycl.rb, line 170
def self.default_sorting=(sort)
  @@default_sorting = sort
end
load_file(filename) click to toggle source

Like Sycl::load_file(), a shortcut method to create a Sycl::Array from loading and parsing YAML from a file.

# File lib/sycl.rb, line 149
def self.load_file(filename)
  Sycl::Array.from_array YAML::load_file filename
end

Public Instance Methods

render_inline!() click to toggle source

Make this array, and its children, rendered in inline/flow style. The default is to render arrays in block (multi-line) style.

Example:

a = Sycl::Array::from_array %w{one two}
a.yaml_postprocessor { |yaml| yaml.sub(/\A---\s+/, '') }

puts a.to_yaml  # output: "- one\n- two"
a.render_inline!
puts a.to_yaml  # output: '[one, two]'
# File lib/sycl.rb, line 267
def render_inline!
  @yaml_style = :inline
end
render_sorted!() click to toggle source

Sort this array when it is rendered as YAML. Useful when the default_sorting has been set to false and arrays should be sorted.

# File lib/sycl.rb, line 302
def render_sorted!
  @render_sorted = true
end
render_unsorted!() click to toggle source

Do not sort this array when it is rendered as YAML. Usually we want elements sorted so that diffs are human-readable, however, there are certain cases where array ordering is significant (for example, a sorted list of queues).

# File lib/sycl.rb, line 295
def render_unsorted!
  @render_sorted = false
end
render_values_inline!() click to toggle source

Keep rendering this array in block (multi-line) style, but, make this array's children rendered in inline/flow style.

Example:

a = Sycl::Array::from_array ['one', {'two' => ['three']}]
a.yaml_postprocessor { |yaml| yaml.sub(/\A---\s+/, '') }

a.render_values_inline!
puts a.to_yaml  # output: "- one\n- two: [three]"
a.render_inline!
puts a.to_yaml  # output: '[one, {two: [three]}]'
# File lib/sycl.rb, line 284
def render_values_inline!
  self.each do |e|
    e.render_inline! if e.respond_to?(:render_inline!)
  end
end
to_yaml(opts = {}) click to toggle source

Render this object as YAML. Before rendering, run the object through any yaml_preprocessor() code block. After rendering, filter the YAML text through any yaml_postprocessor() code block.

Nodes marked with render_inline!() or render_values_inline!() will be output in flow/inline style, all hashes and arrays will be sorted, and we set a long line width to more or less support line wrap under the Psych library.

Calls superclass method
# File lib/sycl.rb, line 370
def to_yaml(opts = {})
  yaml_preprocess!
  if defined?(YAML::ENGINE) && YAML::ENGINE.yamler == 'psych'
    opts ||= {}
    opts[:line_width] ||= 999999  # Psych doesn't let you disable line wrap
    yaml = super
  else
    yaml = YAML::quick_emit(self, opts) do |out|
      if @render_sorted
        out.seq(nil, @yaml_style || to_yaml_style) do |seq|
          sort.each { |e| seq.add(e) }
        end
      else
        out.seq(nil, @yaml_style || to_yaml_style) do |seq|
          each { |e| seq.add(e) }
        end
      end
    end
  end
  yaml_postprocess yaml
end
yaml_postprocessor(&block) click to toggle source

Set a postprocessor hook which runs after YML is dumped, for example, via to_yaml() or Sycl::dump(). The hook is a block that gets the YAML text string as an argument, and returns a new, possibly different, YAML text string.

A common example use case is to suppress the initial document separator, which is just visual noise when humans are viewing or editing a single YAML file:

a.yaml_postprocessor { |yaml| yaml.sub(/\A---\s+/, '') }

Your conventions might also prohibit trailing whitespace, which at least the Syck library will tack on the end of YAML hash keys:

a.yaml_postprocessor { |yaml| yaml.gsub(/:\s+$/, '') }
# File lib/sycl.rb, line 333
def yaml_postprocessor(&block)
  @yaml_postprocessor = block if block_given?
end
yaml_preprocessor(&block) click to toggle source

Set a preprocessor hook which runs before each time YAML is dumped, for example, via to_yaml() or Sycl::dump(). The hook is a block that gets the object itself as an argument. The hook can then set render_inline!() or similar style arguments, prune nil or empty leaf values from hashes, or do whatever other styling needs to be done before a Sycl object is rendered as YAML.

# File lib/sycl.rb, line 313
def yaml_preprocessor(&block)
  @yaml_preprocessor = block if block_given?
end