data_reader 1.3.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 03ea2f3976b4b25953823cb6a13ef4df119c7267
-  data.tar.gz: 1254a6838cb0bbecd4736e7039db6541c75354d7
+  metadata.gz: da1a5b970137e4a0bca2ccdd9bd4749d4ebd514a
+  data.tar.gz: b0160d317b3318450c19c1ff88889e793d431b35
 SHA512:
-  metadata.gz: 2fd827774f7505783ff69cad7fa5a6eb5351c821cf33b77dfa629a1bfc722b8a45442f83dfbf11de5878553b19a3f1581fe0ae010bcb25527a8c2158cf6d099f
-  data.tar.gz: 5062f627830900e1cafd5b5c36020e0eb1d07f0f2bf782edf59cffd5c2582e3f3af3b94e684c515d739354e162b48cffcebd607a5990e4762c060174e6a8108b
+  metadata.gz: 5960e1519c33606f3d5443676e69753c4e81cc39a9c7297d72f34ba4533e10fe9504ec6c7ab70ab92352bd61c2f6edfa9ebe49dd7b6e2127f02f2cd6615eca9c
+  data.tar.gz: 6218d82a67cd08da8e5afa71521033779a0e4e527266f16b0c87f182a12de91da158a0a23940eb4375f8df6490e1999eafb3a7a920b6d961de5395a63e754079

data/.gitignore

@@ -1,40 +1,49 @@
-# Ruby-Specific
+# Ruby Generated
 
+/Gemfile.lock
 /.bundle/
 /.yardoc
-/Gemfile.lock
 /_yardoc/
-
-# Ouput-Specific
-
 /coverage/
 /doc/
 /pkg/
 /spec/reports/
+/spec/coverage/
 /tmp/
-*.log
-*.tmp
-*.swp
-*.bak
 
-# IDE-Specific
+# Generated Reports
+reports/
 
-.idea
-.settings
-.project
-.classpath
-*.iws
+# Rspec Failure Tracking
 
-# Windows-Specific
+.rspec_status
 
-Thumbs.db
+# IDE Files
 
-# Mac OS-Specific
-
-*.DS_Store
-._*
+.idea/
+*.iml
+*.iws
+*.ipr
+.vscode/
+.settings/
+.metadata
+.classpath
+.loadpath
+.buildpath
+.project
 
-# Linux-Specific
+# OS Files
 
-.directory
-.Trash-*
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+$RECYCLE.BIN/
+Desktop.ini
+*.tmp
+*.bak
+*.swp
+*~.nib

data/Gemfile

@@ -1,4 +1,5 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in data_reader.gemspec
+gem "coveralls", require: false
+
 gemspec

data/README.md

@@ -3,7 +3,7 @@
 [![Gem Version](https://badge.fury.io/rb/data_reader.svg)](http://badge.fury.io/rb/data_reader)
 [![License](http://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jeffnyman/data_reader/blob/master/LICENSE.md)
 
-The DataReader gem is used to provide a standard mechanism for providing a YAML data source and loading data from it. DataReader is mainly used as a support gem that can be included by other libraries that need this functionality.
+The DataReader gem is used to provide a standard mechanism for providing a YAML data path and loading data from it. DataReader is mainly used as a support gem that can be included by other libraries that need this functionality.
 
 ## Installation
 
@@ -33,6 +33,8 @@ $ gem install data_reader
 
 ## Usage
 
+The basic idea of DataReader is simple: you set a data path and DataReader will load data files from that path. But there are some nuances that it's worth discussing in this documentation.
+
 ### Including DataReader
 
 You can include the DataReader in a class or module.
@@ -47,7 +49,7 @@ end
 
 This will provide DataReader functionality on any instance of the class where DataReader is mixed in.
 
-DataReader does not set defaults for anything. It provides a `data_path` variable that you can set. It also provides a `data_source` variable that will be populated with the result of a file that gets loaded from any specified data path.
+DataReader does not set defaults for anything. It provides a `data_path` variable that you can set. It also provides a `data_contents` variable that will be populated with the result of a data file that gets loaded from any specified data path.
 
 ### Data Paths
 
@@ -55,60 +57,63 @@ Consider the following file and directory setup:
 
 ```
 project_dir\
-  config\
-    config.yml
-
-  data\
+  combined\
+    invalid.yml
+    conditions.yml
     stars.yml
 
-  env\
-    environments.yml
+  provision\
+    invalid.yml
+
+  stardates\
+    conditions.yml
 
-  test-data-reader.rb
+  warp\
+    stars.yml
 ```
 
-All the code shown below would go in the `test-data-reader.rb` file.
+This is in fact the structure that is provided as part of the `examples` directory with this repository.
 
-With the above class in place and the above directory structure, you could do this:
+Within the `project_dir` you could create a file called `script.rb` to see how DataReader works. Put the above class in place in that file and then add this:
 
 ```ruby
 test = Testing.new
 
 puts test.data_path
-puts test.data_source
+puts test.data_contents
 ```
 
-This would print nothing for either of those values, showing that they have no default values as just stated. You could now do this:
+This would print nothing for either of those values, showing that they have no default values. You could now do this:
 
 ```ruby
-test.data_path = 'data'
+test.data_path = 'warp'
 
 puts test.data_path
 ```
 
-Here you are setting the `data_path` to a directory called `data`. The `puts` statement after that simply confirms that this was set. That will now set the data path for DataReader. Here the "data path" indicates where DataReader will look for data files. Thus you could load any file that is in that directory:
+Here you are setting the `data_path` to a directory called `warp`. The `puts` statement after that simply confirms that this was set. This has now set the data path for DataReader. Here the "data path" indicates where DataReader will look for data files. Thus you could load any file that is in that directory:
 
 ```ruby
 test.load 'stars.yml'
 ```
 
-Loading causes the data from the file to be put into the data source. This can be referenced directly by the `data_source` attribute.
+Loading causes the data from the file to be put into a `data_contents` attribute.
 
 
 ```ruby
-puts test.data_source
+puts test.data_contents
 ```
 
-The `puts` call for the `data_source` will show you the contents of the YAML.
+The `puts` call for the `data_contents` will show you the contents of the `stars.yml` file.
 
-You could set the data source on the class instance if you wanted to:
+You could set the data contents on the class instance if you wanted to:
 
 ```ruby
 class Testing
   include DataReader
 
   def data
-    @data_source
+    @data_contents
   end
 end
 ```
@@ -119,49 +124,42 @@ Now you can access the data via:
 puts test.data
 ```
 
-The reason this might be useful is because the data source may change but this way you refer to it via one variable.
+The reason this might be useful is because the data contents may change, such as if you read different files at different times, but this way you refer to the relevant contents via one variable.
 
-### Data Path on Class
-
-You could have specified the `data_path` as a method of the class instead, like this:
+Note that you can change the data path on the fly if you need to. For example:
 
 ```ruby
-class Testing
-  include DataReader
+test.data_path = 'stardates'
 
-  def data_path
-    'data'
-  end
-end
+test.load 'conditions.yml'
 ```
 
-Then you don't have to set the path specifically on the instance. That being said, you generally don't want to have both in place. Meaning either have the `data_path` defined on the test class or on the instance, not both. To show why this is problematic, consider this:
+This would set the data path to the `stardates` directory and then the load file would grab the contents of the `conditions.yml` file.
+
+### Data Path on Class
+
+You could have specified the `data_path` as a method on the class instead, like this:
 
 ```ruby
 class Testing
   include DataReader
 
   def data_path
-    'data'
+    'provision'
   end
 end
-
-test = Testing.new
-
-test.data_path = 'combined'
-
-test.load 'stars.yml'
 ```
 
-Here I'm setting the `data_path` twice. This works because the data file `stars.yml` is in the `data`. But now try this:
+Then you don't have to set the path specifically as we've been doing.
+
+Note that if you are setting the `data_path` on the class, the idea is that you want this to be the data path. So it can't be reassigned. To see that, try the above and the have the script logic as such:
 
 ```ruby
-test.load 'config.yml'
+test.data_path = 'provision'
+test.load 'invalid.yml'
 ```
 
-That will fail. And that's because even though `config.yml` is in the `combined` directory, it's not in `data`. And that's what's being used here.
-
-The upshot is that if you define a `data_path` on the class, that's what will be used.
+This would lead to an error because while you have set the `data_path`, that will not override what has been set on the class. So the upshot is that if you define a `data_path` as a method on the class, that's what will be used even if you re-define the `data_path` on a specific instance of that class.
 
 ### Default Data Path
 
@@ -172,7 +170,7 @@ class Testing
   include DataReader
 
   def default_data_path
-    'data'
+    'provision'
   end
 end
 ```
@@ -182,57 +180,22 @@ Keep in mind that DataReader will always favor whatever it has stored in `data_p
 ```ruby
 test = Testing.new
 
-test.load 'stars.yml'
-puts test.data_source
-
-test.data_path = 'config'
-configs = test.load 'config.yml'
-puts test.data_source
+test.load 'invalid.yml'
+puts test.data_contents
 ```
 
-Here the first `load` call works by using the default path. Then a data path is set and a file loaded from that path. Once that data path has been set, the default data path is no longer going to be used. If you want to be able to revert to the default, you need to set the `data_path` to nil. For example, here's the same code as the preceding with a few additions at the end:
+This owuld work just fine. But if you were to set the data path, that overrides the default:
 
 ```ruby
-test = Testing.new
-
-test.load 'stars.yml'
-puts test.data_source
-
-test.data_path = 'config'
-configs = test.load 'config.yml'
-puts test.data_source
-
-test.data_path = nil
-
-test.load 'stars.yml'
-puts test.data_source
+test.data_path = 'warp'
+test.load 'invalid.yml'
 ```
 
-The second call to load the `stars.yml` file reverts to using the default data path.
+Here I've set the `data_path` but I'm still trying to load `invalid.yml` (which is in the `provision` directory). But the `data_path`, since it's set, overrides that. The upshot is that a specific data path overrides the default.
 
-Just to show how this can fail, consider the following:
+If you want to be able to revert to the default, you need to set the `data_path` to nil.
 
-```ruby
-class Testing
-  include DataReader
-
-  def default_data_path
-    'data'
-  end
-end
-
-test = Testing.new
-
-test.data_path = 'config'
-
-test.load 'stars.yml'
-```
-
-This would fail to load `stars.yml`. While `stars.yml` is in `data`, which is the default, you have set a specific data path here to `config`.
-
-The upshot is that a specific data path overrides the default.
-
-Note that named sections will currently cause a failure. So for example:
+### Note that named sections will currently cause a failure. So for example:
 
 ```yaml
 users: &users
@@ -245,39 +208,26 @@ This would fail to load based on the `&users` part.
 
 ### Multiple Data Files
 
-You can load multiple YAML files. The `load` method takes a list of comma separated names of files that are in that same directory. So if you were to place all the above example YAML files in one directory, you could do this:
+You can load multiple YAML files. The `load` method takes a list of comma separated names of files that are in that same directory. So if you were to place all the above example YAML files in one directory, such as the `combined` directory shown above, you could do this:
 
 ```ruby
-load 'config.yml, environments.yml, stars.yml'
-```
-
-When loading in multiple files, the `data_source` will hold the contents of all the files in the list.
-
-### Multiple Data Sources
-
-You don't have to use the `data_source` value. For example, you could do this:
+test.data_path = 'combined'
 
-```ruby
-configs = app.load 'config.yml'
-envs = app.load 'environments.yml'
+test.load 'stars.yml, conditions.yml, invalid.yml'
 ```
 
-In this case, the appropriate data would be stored in each variable. Do note that `data_source` will always contain the last data read by the `load` method. So in the above case, `data_source` would contain the contents of `environments.yml` even if you never intended to use that variable.
+When loading in multiple files, the `data_contents` will hold the contents of all the files in the list.
 
-### Setting a Data Pata
+### Multiple Data Sources
 
-You can, at any time, set a data path. When you do, any calls to `load` will use that data path. Consider this example:
+You don't have to use the `data_context` value. For example, you could do this:
 
 ```ruby
-app.data_path = 'config'
-configs = app.load 'config.yml'
-
-app.data_path = 'env'
-envs = app.load 'environments.yml'
+stars = test.load 'stars.yml'
+invalid = test.load 'invalid.yml'
 ```
 
-Do note that if you had defined a `data_path` method in your class, as shown above, that will always overridde a local instance setting as shown in the preceding code.
-
+In this case, the appropriate data would be stored in each variable. Do note that `data_context` will always contain the last data read by the `load` method. So in the above case, `data_context` would contain the contents of `invalid.yml` even if you never intended to use that variable.
 
 ### Parameterizing Data
 
@@ -300,11 +250,11 @@ config:
 Now let's say I loaded up this file and looked at the data source:
 
 ```ruby
-app.load 'config.yml'
-puts app.data_source
+test.load 'config.yml'
+puts test.data_contents
 ```
 
-Assuming the BROWSER environment variable was set, the `data_source` variable would look as follows:
+Assuming the BROWSER environment variable was set, the `data_contents` variable would look as follows:
 
 ```
 {
@@ -320,27 +270,40 @@ Assuming the BROWSER environment variable was set, the `data_source` variable wo
 
 ### Method Calls on Data
 
-The support for ERB allows for custom method calls. One that is included with DataReader is `include_data`, which can be used like this:
+The support for ERB allows for custom method calls. One that is included with DataReader is `include_data`. First consider the directory structure:
+
+```
+included\
+  included_nested.yml
+  included.yml
+  with_includes.yml
+  with_nested_includes.yml
+```
+
+In the `with_includes.yml` file, there is a line like this:
 
 ```yaml
-<%= include_data("config.yml") %>
+<%= include_data("included.yml") %>
 ```
 
-Say that this line was included in line was in the YAML `environment.yml` from the above structure and you did this:
+Now you can do this:
 
 ```ruby
-app.data_path = 'env'
-app.load 'environments.yml'
+test.data_path = 'included'
+
+test.load 'with_includes.yml'
 ```
 
-This will load up `environments.yml` and, because of the `include_data` call would attempt to load the file `config.yml`. Note, however, that DataReader will attempt to load this from the same location as `environments.yml`. You can absolute or relative paths as part of the call, as such:
+This will load up `with_includes.yml` and, because of the `include_data` call would attempt to load the file `included.yml`.
+
+In this case, the value of `data_contents` would contain both data sets, first the data from `with_includes.yml` and then the data from `included.yml`.
+
+Note, however, that DataReader will attempt to load this from the same location as `with_includes.yml`. You can absolute or relative paths as part of the call, as such:
 
 ```yaml
-<%= include_data("../config/config.yml") %>
+<%= include_data("../warp/stars.yml") %>
 ````
 
-In this case, the value of `data_source` would contain both data sets, first the data from `config.yml` and then the data from `environments.yml`.
-
 ### Extending DataReader
 
 You can also extend, rather than include, DataReader. This means you deal with the class rather than an instance of it. For example:

data/Rakefile

@@ -10,6 +10,7 @@ namespace :spec do
   desc 'Clean all generated reports'
   task :clean do
     system('rm -rf spec/reports')
+    system('rm -rf spec/coverage')
   end
 
   RSpec::Core::RakeTask.new(all: :clean) do |config|

data/examples/combined/conditions.yml

@@ -0,0 +1,6 @@
+stardate:
+  invalid:
+    conditions:
+      - only letters
+      - some letters
+      - less than four numbers

data/examples/combined/invalid.yml

@@ -0,0 +1,8 @@
+invalid:
+  provision:
+    activation-code:
+      - The activation code must be four numeric characters.
+    deactivation-code:
+      - The deactivation code must be four numeric characters.
+    countdown-value:
+      - The countdown value must be a whole number.

data/examples/combined/stars.yml

@@ -0,0 +1,9 @@
+alpha centauri:
+  warp factor: 1
+  velocity: 1
+  distance: 4.3
+
+epsilon eridani:
+  warp factor: 1
+  velocity: 1
+  distance: 10.5

data/examples/config.yml

@@ -0,0 +1,5 @@
+config:
+  current:
+    server: test
+    user: jeff_nyman
+    browser: <%= ENV['BROWSER'] %>

data/examples/included/included.yml

@@ -0,0 +1,2 @@
+included:
+  key: "value"

data/examples/included/included_nested.yml

@@ -0,0 +1,2 @@
+include_nested:
+  nested_key: "nested value"

data/examples/included/with_includes.yml

@@ -0,0 +1,4 @@
+<%= include_data("included.yml") %>
+
+xyzzy:
+  adventure: "crowther"

data/examples/included/with_nested_includes.yml

@@ -0,0 +1,10 @@
+<%= include_data("included.yml") %>
+
+_include_:
+  - included_nested.yml
+
+xyzzy:
+  adventure: "woods"
+
+  nested_key:
+    _include_: "../warp/stars.yml"

data/examples/provision/invalid.yml

@@ -0,0 +1,8 @@
+invalid:
+  provision:
+    activation-code:
+      - The activation code must be four numeric characters.
+    deactivation-code:
+      - The deactivation code must be four numeric characters.
+    countdown-value:
+      - The countdown value must be a whole number.

data/examples/stardates/conditions.yml

@@ -0,0 +1,6 @@
+stardate:
+  invalid:
+    conditions:
+      - only letters
+      - some letters
+      - less than four numbers

data/examples/warp/stars.yml

@@ -0,0 +1,9 @@
+alpha centauri:
+  warp factor: 1
+  velocity: 1
+  distance: 4.3
+
+epsilon eridani:
+  warp factor: 1
+  velocity: 1
+  distance: 10.5

data/lib/data_reader.rb

@@ -1,21 +1,26 @@
 require "data_reader/version"
+
 require "pathname"
 require "yaml"
 require "erb"
 
 module DataReader
+  # Sets the path to use when reading data files.
   def data_path=(path)
     @data_path = path
   end
 
+  # Returns the path that will be used to read data files.
   def data_path
     return @data_path if @data_path
-    return default_data_path if self.respond_to? :default_data_path
+    return default_data_path if respond_to? :default_data_path
+
     nil
   end
 
-  def data_source
-    return @data_source if @data_source
+  # Returns the contents that have been read in from a loaded file data file.
+  def data_contents
+    return @data_contents if @data_contents
 
     nil
   end
@@ -24,7 +29,7 @@ module DataReader
     files = file_list.include?(',') ? file_list.split(',') : [file_list]
     files = files.collect(&:strip)
 
-    @data_source = files.inject({}) do |all_data, file|
+    @data_contents = files.inject({}) do |all_data, file|
       data = include_key(::YAML.safe_load(include_data(file)))
       all_data.merge!(data) if data
     end

data/lib/data_reader/version.rb

@@ -1,3 +1,3 @@
 module DataReader
-  VERSION = "1.3.0".freeze
+  VERSION = "2.0.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: data_reader
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Jeff Nyman
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-09-17 00:00:00.000000000 Z
+date: 2019-09-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -91,7 +91,6 @@ files:
 - ".hound.yml"
 - ".rspec"
 - ".rubocop.yml"
-- ".travis.yml"
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.md
@@ -100,6 +99,17 @@ files:
 - bin/console
 - bin/setup
 - data_reader.gemspec
+- examples/combined/conditions.yml
+- examples/combined/invalid.yml
+- examples/combined/stars.yml
+- examples/config.yml
+- examples/included/included.yml
+- examples/included/included_nested.yml
+- examples/included/with_includes.yml
+- examples/included/with_nested_includes.yml
+- examples/provision/invalid.yml
+- examples/stardates/conditions.yml
+- examples/warp/stars.yml
 - lib/data_reader.rb
 - lib/data_reader/version.rb
 homepage: https://github.com/jeffnyman/data_reader
@@ -107,7 +117,7 @@ licenses:
 - MIT
 metadata: {}
 post_install_message: "\n(::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::)\n
-  \ DataReader 1.3.0 has been installed.\n(::) (::) (::) (::) (::) (::) (::) (::)
+  \ DataReader 2.0.0 has been installed.\n(::) (::) (::) (::) (::) (::) (::) (::)
   (::) (::) (::) (::)\n  "
 rdoc_options: []
 require_paths:

data/.travis.yml

@@ -1,5 +0,0 @@
-sudo: false
-language: ruby
-rvm:
-  - 2.3.1
-before_install: gem install bundler -v 1.13.3