accessible_data

AccessibleData

The goal of AccessibleData is to allow for an expressive mechanism for referencing data by making that data a "first class citizen" of the structure that it applies to.

Installation

To get the latest stable release, add this line to your application's Gemfile:

gem 'accessible_data'

And then include it in your bundle:

$ bundle

You can also install AccessibleData just as you would any other gem:

$ gem install accessible_data

Usage

Consider a data source like this:

numbers:
  integers:
    one: 1

letters:
  vowels: "a, e, i, o, u"

This would be a YAML file. AccessibleData lets you refer to the data in this file via how it is structured by turning the keys into referenceable elements. There are a couple of ways to handle all of this.

AccessibleData Sources

You can create an AccessibleData class like this:

TestData = AccessibleData.sources do |source|
  source.data_load "data/sample_data.yml"
end

Here you assign the result of calling the sources action and you can pass a block where you load or merge data sources.

You can check the data you have available by either of the following approaches:

puts TestData.to_h
puts TestData.accessible_data

Given the data from the YAML file, you would end up with this:

{"numbers"=>{"integers"=>{"one"=>1}}, "letters"=>{"vowels"=>"a, e, i, o, u"}}

When you load data into your class like this, accessor methods are defined on the class and recursively through the loaded data for each key. In the example data shown, the keys are "numbers" and "letters". This means you can easily walk through your data:

puts TestData.numbers
puts TestData.numbers.integers
puts TestData.numbers.integers.one
puts TestData.letters
puts TestData.letters.vowels

The result of this would be:

{"integers"=>{"one"=>1}}
{"one"=>1}
1
{"vowels"=>"a, e, i, o, u"}
a, e, i, o, u

Data Loading

The data_load method loads data into your class, wiping out any previously loaded data. So you don't want to do multiple data_load statements. You have to provide a data source to the data_load call. A data source can be a string and that string should represent a file path to an existing YAML file to be loaded. An error will be throw if the file cannot be found.

TestData.data_load('data/sample_data.yml')

Here you can specify any path that you want, relative to the working directory of the running script.

If you want to shorten that, you can use a symbol. This approach requires that data is your default directory. Here's an example:

TestData.data_load(:sample_data)

The given symbol represents the name of a .yml file located in the data directory.

You can also load up a specific hash as opposed to a file:

TestData.data_load({ :names => ['Flash', 'Green Arrow', 'Firestorm'] })

The data loading mechanism also accepts an optional second parameter representing the name of a specific key within the data source from which data should be loaded.

TestData.data_load "data/sample_data.yml", "letters"

So here only the letters key and anything within it would be loaded from the sample_data.yml file.

Data Referencing

As you saw above, you can use the to_h or accessible_data methods to have all of the data loaded in your class returned to you as a hash.

Merging Data

Let's say you have another data source called another_sample_data.yml with this:

numbers:
  integers:
    two: 2

You could now do something like this:

TestData = AccessibleData.sources do |source|
  source.data_load "data/sample_data.yml"
  source.data_merge "data/another_sample_data.yml"
end

Given the data in those files, you would end up with this:

{"numbers"=>{"integers"=>{"one"=>1, "two"=>2}}, "letters"=>{"vowels"=>"a, e, i, o, u"}}

Now you could do something similar to the above with the merged data set:

puts TestData.numbers
puts TestData.numbers.integers
puts TestData.numbers.integers.one
puts TestData.numbers.integers.two
puts TestData.letters
puts TestData.letters.vowels

You would end up with:

{"integers"=>{"one"=>1, "two"=>2}}
{"one"=>1, "two"=>2}
1
2
{"vowels"=>"a, e, i, o, u"}
a, e, i, o, u

So notice how the similar data got merged together (for "numbers") and you still end up with all data ("numbers" and "letters").

You can also merge specific data without referring to a file. For example:

TestData = AccessibleData.sources do |source|
  source.data_load "data/sample_data.yml"
  source.data_merge "data/another_sample_data.yml"
  source.data_merge test: 'xyzzy'
end

puts TestData.test

Here you can reference the previous data as before but now you are also merging in a specific set of data and that last statement would show you:

xyzzy

So what you are seeing here is that the data_merge method is somewhat equivalent to data_load with the exception that the data source is merged. This means entries with duplicate keys are overwritten with previously loaded data. Also, you can pass a namespace to merge just as you did during loading:

TestData.data_merge "data/sample_data.yml", "letters"

AccessibleData Mixin

You can potentially make the above approach a bit easier to by having your class include AccessibleData, rather than calling sources directly. For example:

class TestData
  include AccessibleData

  data_load "data/sample_data.yml"
  data_merge "data/another_sample_data.yml"
  data_merge test: 'xyzzy'
end

puts TestData.accessible_data

A key thing to note here is that the data is a first class citizen of the class, not of instances of the class. You can reference data from an object, however, by doing something like this:

class TestData
  include AccessibleData

  data_load "data/sample_data.yml"
  data_merge "data/another_sample_data.yml"
  data_merge test: 'xyzzy'

  def action
    puts self.class.accessible_data
  end
end

data = TestData.new
data.action

Getting and Setting Data

Consider the following:

class TestData
  include AccessibleData
end

TestData.data_load({
  :superheroes => {
    :green_lantern => {
      :secret_identity => [
        { name: 'Hal Jordan' },
        { name: 'John Stewart '},
        { name: 'Guy Gardner' }
      ]
    }
  }
})

You can reference the data as such:

puts TestData.superheroes.green_lantern.secret_identity[0].name
puts TestData.superheroes[:green_lantern].secret_identity[0].name
puts TestData.superheroes.green_lantern

That will get you:

Hal Jordan
Hal Jordan
{:secret_identity=>[{:name=>"Hal Jordan"}, {:name=>"Kyle Rayner"}, {:name=>"Guy Gardner"}]}

You can also set the data by referencing an index directly:

TestData[:superheroes].green_lantern.secret_identity[1].name = 'Kyle Rayner'

What this is showing you is the reference via a [] method. This gets data from your class and will return nil if the key does not exist. That can make this method useful for assigning default values in the absence of a key, as such:

villain = TestData[:supervillain] || 'Parallax'

You can also use a []= method.

TestData[:supervillain] = 'Parallax'
puts TestData.supervillain

Caveat on Accessors

Consider the following:

class TestData
  include AccessibleData
end

TestData.data_load({})

TestData[:hal_jordan] = "Green Lantern"  # []=
puts TestData[:hal_jordan]               # []
puts TestData.hal_jordan

You can see how the key is referenced. In both cases you will get a value of "Green Lantern" returned. The comments show you which methods on AccessibleData are being called. Notice that the "hal_jordan" key is being created on the fly. Now consider this:

class TestData
  include AccessibleData
end

TestData.data_load({ hal_jordan: { :superhero => 'Green Lantern' } })
puts TestData.hal_jordan
puts TestData.hal_jordan.superhero

TestData.hal_jordan[:evil] = 'Parallax'
puts TestData.hal_jordan[:evil] # WORKS
puts TestData.hal_jordan.evil   # DOES NOT WORK

Notice the comments here. The reason the last statement does not work is because the when the [:evil] key and value is established above, this does not call []= on AccessibleData but rather the standard mechanism for insertion into a hash provided by Ruby. This means the accessors that AccessibleData provides are not created. So this is where you would want to use data_merge to bring in data.

ERB Processing

AccessibleData will process files with Embedded Ruby. For example, you could have a data source like this:

numbers:
  integers:
    one: 1
    four: <%= 2 + 2 %>

This would be referenced by AccessibleData as such:

{"numbers"=>{"integers"=>{"one"=>1, "four"=>4}}}

Notice how the keyword "four" shows the calculated value.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec:all to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment. To install this gem onto your local machine, run bundle exec rake install.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/jeffnyman/accessible_data. The testing ecosystem of Ruby is very large and this project is intended to be a welcoming arena for collaboration on yet another testing tool. As such, contributors are very much welcome but are expected to adhere to the Contributor Covenant code of conduct.

To contribute to AccessibleData:

1. Fork the project.
2. Create your feature branch. (git checkout -b my-new-feature)
3. Commit your changes. (git commit -am 'new feature')
4. Push the branch. (git push origin my-new-feature)
5. Create a new pull request.

Author

• Jeff Nyman

License

AccessibleData is distributed under the MIT license. See the LICENSE file for details.