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