Module: UsingYAML

Defined in:
lib/using_yaml.rb,
lib/using_yaml/hash.rb,
lib/using_yaml/array.rb

Overview

UsingYAML provides convenient class extensions which make it easy to interact with YAML-storage of settings files by defining accessors which allow one to talk to the files as if they were fully implemented classes.

Each of these files will be automagically enhanced to provide save and clean methods of talking to your YAML files without needing to worry about checking for nil’s, re-serializing or long-winded hash access.

This module also provides some static access to make it easy to enable/disable options such as squelching error messages (in production) and tracking where instances should load their files from.

See using_yaml for usage information.

Defined Under Namespace

Modules: ClassMethods, InstanceMethods

Constant Summary collapse

NilExt = 
Module.new do
  define_method(:method_missing) do |*args|
    self
  end
end
NilClass = 
nil.extend(NilExt)

Class Method Summary collapse

Class Method Details

.add_array_extensions(array, pathname) ⇒ Object

Calls add_extensions on all children. Also defines a save method iff this is a top-level UsingYAML object (see below for details).



4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
 
# File 'lib/using_yaml/array.rb', line 4

def self.add_array_extensions(array, pathname)
  # Iterate over the items
  array.each do |item|
    # Recursively continue to extend.
    UsingYAML.add_extensions(item)
  end
  
  # Load in the extensions for this instance
  array.instance_eval "    def save\n      # Serialise using +to_yaml+\n      File.open(\"\#{pathname}\", 'w') do |f|\n        f.puts self.to_yaml\n      end\n    end\n  RUBY\n\n  array\nend\n"

.add_extensions(object, pathname = nil) ⇒ Object

Extends the incoming Array/Hash with magic which makes it possible to save and (in the case of Hashes) use methods instead of []-access.



36
37
38
39
40
41
42
43
44
45
46
47
 
# File 'lib/using_yaml.rb', line 36

def add_extensions(object, pathname = nil)
  case object
  when Array
    add_array_extensions(object, pathname)
  when Hash
    add_hash_extensions(object, pathname)
  when ::NilClass
    UsingYAML::NilClass
  end
        
  object
end

.add_hash_extensions(hash, pathname) ⇒ Object

Calls add_extensions on all children. Also defines a save method iff this is a top-level UsingYAML object (see below for details).



4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/using_yaml/hash.rb', line 4

def self.add_hash_extensions(hash, pathname)
  # Recursively continue to extend.
  hash.each_pair do |key, value|
    UsingYAML.add_extensions(value)
  end

  hash.instance_eval "    def method_missing(*args)\n      name = args.shift.to_s\n\n      if args.empty?\n        value = send(:[], name)\n        value.nil? ? UsingYAML::NilClass : value\n      elsif args.size == 1 && name =~ /(.+)=/\n        # This is an \"alias\" turning self.key= into self[key]=\n        # Also extends the incoming value so that it behaves\n        # consistently with the other key-value pairs.\n        key   = $1\n        value = args.first\n    \n        # Save the value in the hashtable\n        send(:[]=, key, UsingYAML.add_extensions(value))\n        value\n      else\n        super(name, args)\n      end\n    end\n  RUBY\n\n  # Define a save method if a pathname was supplied (only happens\n  # on the top-level object - that is, example.foo will have a\n  # +save+, but example.foo.bar will not).\n  if pathname\n    hash.instance_eval <<-RUBY\n      def save \n        # Serialise using +to_yaml+\n        File.open(\"\#{pathname}\", 'w') do |f|\n          f.puts self.to_yaml\n        end\n      end\n    RUBY\n  end\n  \n  hash\nend\n"

.included(base) ⇒ Object 



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

def self.included(base)
  base.extend UsingYAML::ClassMethods
end

.path(klass) ⇒ Object

Returns the path where the given class will load from. See using_yaml_path for information on how to override this on a per-instance basis.



52
53
54
 
# File 'lib/using_yaml.rb', line 52

def path(klass)
  return @@path[klass] if defined?(@@path)
end

.path=(args) ⇒ Object

Sets the the path where the given class will load from. See using_yaml_path for information on how to override this on a per-instance basis.



59
60
61
 
# File 'lib/using_yaml.rb', line 59

def path=(args)
  (@@path ||= {})[args.first] = args.last
end

.squelch! ⇒ Object

Because of the “safety” UsingYAML provides, it is easy for typos to creep in, which might result in unexpected nil’s. UsingYAML therefore is verbose in warning about these potential errors.

This method disables those warnings, which is useful in a production environment or if you are sure you aren’t making mistakes.



69
70
71
 
# File 'lib/using_yaml.rb', line 69

def squelch!
  @@squelched = true
end

.squelched? ⇒ Boolean

Returns true if UsingYAML will warn about potential typos (or similar) which might otherwise be masked.

Returns:

  • (Boolean) 


75
76
77
 
# File 'lib/using_yaml.rb', line 75

def squelched?
  defined?(@@squelched) && @@squelched
end

.unsquelch! ⇒ Object

Opposite of squelch!



80
81
82
 
# File 'lib/using_yaml.rb', line 80

def unsquelch!
  @@squelched = false
end