diff --git a/CHANGELOG.md b/CHANGELOG.md index 5af89d7..1991a9f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,8 @@ The "Signs And Portents" Update +Added `Cuprum.initializer` to initialize dependencies and error messages. Call `Cuprum.initializer.call` in the entry point or initializers of your application to avoid missing error messages. + ### Results Added `Result.success` and `Result.failure`, which provide singleton results with respective `:success` and `:failure` statuses. diff --git a/Gemfile b/Gemfile index 0e1745c..491bbc1 100644 --- a/Gemfile +++ b/Gemfile @@ -23,6 +23,7 @@ end group :docs do gem 'jekyll', '~> 4.3' gem 'jekyll-theme-dinky', '~> 0.2' + gem 'logger', '~> 1.7' # Use Kramdown to parse GFM-dialect Markdown. gem 'kramdown-parser-gfm', '~> 1.1' diff --git a/docs/_constants/cuprum/error/type.yml b/docs/_constants/cuprum/error/type.yml index 1f2d277..74a9ded 100644 --- a/docs/_constants/cuprum/error/type.yml +++ b/docs/_constants/cuprum/error/type.yml @@ -6,7 +6,7 @@ short_description: Short string used to identify the type of error. value: "'cuprum.error'" data_path: cuprum/error/type description: |- - Primarily used for serialization. This value can be overriden by passing + Primarily used for serialization. This value can be overridden by passing in the :type parameter to the constructor. Subclasses of Cuprum::Error should define their own default TYPE constant. diff --git a/docs/_methods/cuprum/c-initializer.yml b/docs/_methods/cuprum/c-initializer.yml new file mode 100644 index 0000000..d4e5261 --- /dev/null +++ b/docs/_methods/cuprum/c-initializer.yml @@ -0,0 +1,14 @@ +--- +name: Cuprum.initializer +parent_path: cuprum +signature: initializer +slug: initializer +constructor: false +data_path: cuprum/c-initializer +returns: +- description: |- + the initializer + for the module. + type: + - name: SleepingKingStudios::Tools::Toolbox::Initializer +version: "*" diff --git a/docs/_methods/cuprum/error/i-as-json.yml b/docs/_methods/cuprum/error/i-as-json.yml index a195331..d6b6bdd 100644 --- a/docs/_methods/cuprum/error/i-as-json.yml +++ b/docs/_methods/cuprum/error/i-as-json.yml @@ -7,9 +7,9 @@ constructor: false data_path: cuprum/error/i-as-json description: |- By default, contains the #type and #message properties and an empty :data - Hash. This can be overriden in subclasses by overriding the private method - #as_json_data; this should always return a Hash with String keys and whose - values are basic objects or data structures of the same. + Hash. This can be overridden in subclasses by overriding the private + method #as_json_data; this should always return a Hash with String keys + and whose values are basic objects or data structures of the same. returns: - description: |- a serializable hash representation of the diff --git a/docs/_modules/cuprum.yml b/docs/_modules/cuprum.yml index eaf04f7..3d042a3 100644 --- a/docs/_modules/cuprum.yml +++ b/docs/_modules/cuprum.yml @@ -28,6 +28,13 @@ files: - lib/cuprum/parameter_validation.rb parent_path: '' short_description: Toolkit for implementing business logic as function objects. +class_attributes: +- name: initializer + read: true + write: false + path: cuprum/c-initializer + slug: initializer + inherited: false class_methods: - name: version path: cuprum/c-version diff --git a/docs/index.md b/docs/index.md index 2d982e5..d31fcb3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,6 +15,34 @@ This is the documentation for the [current development build](https://github.com - For the most recent release, see [Version 1.3]({{site.baseurl}}/versions/1.3). - For previous releases, see the [Versions]({{site.baseurl}}/versions) page. +## Getting Started + +Add the gem to your `Gemfile` or `gemspec`: + +```ruby +gem 'cuprum' +``` + +Require `Cuprum` in your code: + +```ruby +require 'cuprum' +``` + +To ensure that error message definitions are loaded, call the `Cuprum` initializer: + +- In the [initializer](./initializer) for your project: + + ```ruby + module Space + @initializer = SleepingKingStudios::Tools::Toolbox::Initializer.new do + Cuprum.initializer.call + end + end + ``` + +- Or, in the entry points of your application (such as a `bin` script or `spec_helper.rb`). + ## Reference Cuprum defines the following core components: diff --git a/lib/cuprum.rb b/lib/cuprum.rb index bea2881..71ec41d 100644 --- a/lib/cuprum.rb +++ b/lib/cuprum.rb @@ -1,5 +1,7 @@ # frozen_string_literal: true +require 'sleeping_king_studios/tools/toolbox/initializer' + # Toolkit for implementing business logic as function objects. module Cuprum autoload :Command, 'cuprum/command' @@ -16,7 +18,15 @@ module Cuprum autoload :ResultList, 'cuprum/result_list' autoload :Steps, 'cuprum/steps' + @initializer = SleepingKingStudios::Tools::Toolbox::Initializer.new do + SleepingKingStudios::Tools.initializer.call + end + class << self + # @return [SleepingKingStudios::Tools::Toolbox::Initializer] the initializer + # for the module. + attr_reader :initializer + # @return [String] the current version of the gem. def version VERSION diff --git a/lib/cuprum/error.rb b/lib/cuprum/error.rb index 0c97373..f4e5f1a 100644 --- a/lib/cuprum/error.rb +++ b/lib/cuprum/error.rb @@ -52,7 +52,7 @@ module Cuprum class Error # Short string used to identify the type of error. # - # Primarily used for serialization. This value can be overriden by passing + # Primarily used for serialization. This value can be overridden by passing # in the :type parameter to the constructor. # # Subclasses of Cuprum::Error should define their own default TYPE constant. @@ -86,9 +86,9 @@ def ==(other) # Generates a serializable representation of the error object. # # By default, contains the #type and #message properties and an empty :data - # Hash. This can be overriden in subclasses by overriding the private method - # #as_json_data; this should always return a Hash with String keys and whose - # values are basic objects or data structures of the same. + # Hash. This can be overridden in subclasses by overriding the private + # method #as_json_data; this should always return a Hash with String keys + # and whose values are basic objects or data structures of the same. # # @return [Hash] a serializable hash representation of the # error. diff --git a/spec/cuprum_spec.rb b/spec/cuprum_spec.rb index 276466b..f558ddb 100644 --- a/spec/cuprum_spec.rb +++ b/spec/cuprum_spec.rb @@ -11,7 +11,13 @@ end end - describe '::version' do + describe '.initializer' do + include_examples 'should define class reader', + :initializer, + -> { be_a(SleepingKingStudios::Tools::Toolbox::Initializer) } + end + + describe '.version' do it 'should define the reader' do expect(described_class) .to have_reader(:version) diff --git a/spec/spec_helper.rb b/spec/spec_helper.rb index a3354d4..244f7d9 100644 --- a/spec/spec_helper.rb +++ b/spec/spec_helper.rb @@ -1,18 +1,20 @@ # frozen_string_literal: true +require 'rspec/sleeping_king_studios/all' +require 'byebug' + unless ENV['COVERAGE'] == 'false' require 'simplecov' SimpleCov.start end -require 'rspec/sleeping_king_studios/all' -require 'byebug' +require 'cuprum' # Isolated namespace for defining spec-only or transient objects. module Spec; end -SleepingKingStudios::Tools.initializer.call +Cuprum.initializer.call require 'support/matrix'