laminar 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3fb0486b2d99158c6fa192d237100a61bc9ae40e
+  data.tar.gz: 0755f031eee6dfaefbb64d9301c3e27327c6088f
+SHA512:
+  metadata.gz: 5d7f0f34420a061583f4744cf16bfa6a899c8ccf8bd2cb2b8aa24c269c487290632084fbce0dd74e6f2f6540b54f4e605e6731f37e89e6c6bee5a5176f0f55fc
+  data.tar.gz: 2fbbbef809c51fff94be71195e63fab67c8c93f9cb1ed0b96228e7dcc84e21a34572d31f4a48e18e6e23514686115a690f6d125581333626c7c1c93e1f2eb38a

data/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: Bug report
+about: Create a report to help us improve
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

data/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

data/.gitignore

@@ -0,0 +1,13 @@
+*.gem
+Gemfile.lock
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,13 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.3
+  - 2.4
+  - 2.5
+before_install: gem install bundler -v 1.16.5
+script:
+  - bundle exec rspec
+after_script:
+  - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Change Log
+
+## [Unreleased](https://github.com/rmlockerd/laminar/tree/HEAD)
+
+[Full Changelog](https://github.com/rmlockerd/laminar/compare/v0.2.0...HEAD)
+
+**Implemented enhancements:**
+
+- Before/after callbacks on individual flow steps [\#6](https://github.com/rmlockerd/laminar/issues/6)
+- Halt a flow without failure [\#5](https://github.com/rmlockerd/laminar/issues/5)
+- Add Travis configuration [\#3](https://github.com/rmlockerd/laminar/issues/3)
+- Add automated tests [\#2](https://github.com/rmlockerd/laminar/issues/2)
+- Add before/after particle callbacks [\#1](https://github.com/rmlockerd/laminar/issues/1)
+
+## [v0.2.0](https://github.com/rmlockerd/laminar/tree/v0.2.0) (2018-09-27)
+**Fixed bugs:**
+
+- .gemspec missing active\_support dependency [\#4](https://github.com/rmlockerd/laminar/issues/4)
+
+
+
+\* *This Change Log was automatically generated by [github_changelog_generator](https://github.com/skywinder/Github-Changelog-Generator)*

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at robertl@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in laminar.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Robert Lockerd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,362 @@
+# Laminar
+
+[![Build Status](https://travis-ci.org/rmlockerd/laminar.svg?branch=master)](https://travis-ci.org/rmlockerd/laminar)
+[![Maintainability](https://img.shields.io/codeclimate/maintainability/rmlockerd/laminar.svg)](https://codeclimate.com/github/rmlockerd/laminar)
+[![Test Coverage](https://img.shields.io/codeclimate/coverage-letter/rmlockerd/laminar.svg)](https://codeclimate.com/github/rmlockerd/laminar)
+
+A simple Chain-of-Responsibility/Interactor gem that helps MVC applications organise their business logic, keeping their models and controllers skinny and their logic easily testable. Individual chunks of business logic (called particles) can be easily composed into more complex chains called flows.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'laminar'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install laminar
+
+## Usage
+### 'Skinny' Controllers AND 'Skinny' Models
+
+Even if you are reasonably new to Model-View-Controller (MVC) frameworks, such as Ruby on Rails, you have likely encountered the advice to have 'skinny controllers, fat models'. 'Skinny' controllers (i.e., simple, small, single-responsibility) are indeed best, but pushing a lot of code into your models has its own issues, and it isn't in reality an either/or choice.
+
+Separating your business logic into single-purpose service objects (also sometimes called 'interactors' and several other names) helps keep your models and controllers skinny, and your code DRY and more easily testable.
+
+### Particles
+
+A particle is a PORO (Plain Old Ruby Object) that encapsulates a piece of your business logic. Keeping with the Single Responsibility Principle, a particle should preferably do only one thing.
+
+#### Defining a Particle
+A particle is a plain Ruby class that includes `Laminar::Particle` and defines a `call` method.
+
+```ruby
+class ChangeAddress
+  include Laminar::Particle
+
+  def call
+    // change address logic goes here
+  end
+end
+```
+
+#### Particle Context
+
+To invoke a particle, invoke the `.call` method on the particle's
+class object, passing a Hash of values that is the 'context' in which
+the particle runs.
+```ruby
+ChangeAddress.call(user: user, new_address: addr)
+```
+
+The invoked particle accesses its context within its `.call` method like  normal Hash:
+```ruby
+sku = context[:product_sku]
+```
+
+The particle can also add to or modify the context. The context is returned to the invoker, which can then access the modified context.
+
+```ruby
+// Particle
+class OpenTicket
+  include Laminar::Particle
+
+  def call
+    context[:status] = :pending
+  end
+end
+
+// Caller
+result = OpenTicket.call
+if result[:status] != :pending
+  ...
+end
+```
+
+#### Keyword Arguments
+
+You can also use keyword arguments particle's `.call` method:
+```ruby
+class ChangeAddress
+  include Laminar::Particle
+
+  def call(user:, new_address:)
+    // change address logic goes here
+  end
+end
+```
+
+When you declare keyword arguments, Laminar passes matching values
+from the context to your particle. This can make your particle more
+self-documenting and provides a simple `ArgumentError` exception if the
+calling context does not contain the minimum information required for the
+particle to function.
+
+The `.call` implementation always has access to the full context via
+`context` whether or not you declare keyword arguments.
+
+#### Particle Success / Failure
+Particles have a simple mechanism for flagging success and
+failure. To signal failure, simply call `.fail!` on the context.
+```ruby
+context.fail!
+```
+
+There are also convenience methods for checking success/failure:
+```ruby
+context.success? # => true by default
+context.failed? # => false
+
+context.fail!
+
+context.halted? # => true
+context.failed? # => true
+context.success? # => false
+```
+
+The `.fail!` method accepts a hash that is merged into the context,
+making it convenient to attach error information:
+```ruby
+context.fail!(error: 'The user is allergic to bananas!')
+```
+
+Use the `.halt!` class method to immediately stop a particle without marking it as a failure.
+
+```ruby
+context.halt!
+
+context.halted? # => true
+context.success? # => true
+context.failed? # => false
+```
+
+The `.halt!` accepts a context hash similar to `.fail!`.
+
+#### Callbacks
+
+Particles can specify one or more callbacks to execute immediately before or after the invocation of its `#call`.
+
+```ruby
+class Foo
+  include Laminar::Flow
+
+  before :setup  # method symbol
+  before { ... } # block
+
+  after :teardown  # method symbol
+  after { ... } # block
+```
+Callbacks execute in the order they are specified when there are multiple of the same kind.
+
+### Flows
+
+A flow is a chained sequence of particles, creating a simple workflow.
+Each step (particle) contributes to an overall outcome through a shared
+context. Simple branching and looping is supported via conditional
+logic.
+
+A flow includes `Laminar::Flow`, which provides a DSL for specifying
+the particles to execute. The most basic flow is a simple set of steps executed sequentially.
+
+```ruby
+class FillCavity
+  include Laminar::Flow
+
+  flow do
+    step :numb_mouth
+    step :drill_cavity
+    step :apply_amalgam
+  end
+end
+```
+
+A step label must be a symbol that identifies a Particle. By default,
+the Flow assumes the step label is the implementation class name (i.e.,
+`:numb_mouth` -> `NumbMouth`).
+You can use the `class:` directive to specify an alternate class
+name. Very useful when your particles
+are organised into modules.
+```ruby
+class FillCavity
+  include Laminar::Flow
+
+  flow do
+    step :numb_mouth
+    step :drill_cavity, class: 'Dentist::Drill'
+    step :apply_amalgam
+  end
+end
+```
+
+#### Invoking a Flow
+Flows behave exactly like Particles in terms of execution. To start
+a Flow, call `.call` on the Flow class, passing a Hash of context:
+
+```ruby
+// Flow
+class FillCavity
+  include Laminar::Flow
+
+  flow do
+    step :numb_mouth
+    step :drill_cavity, class: 'Dentist::Drill'
+    step :apply_amalgam
+  end
+end
+
+// Caller
+result = FillCavity.call(patient: patient, tooth_number: tooth)
+```
+
+A Flow returns the context as it stands after the final step in the
+Flow ends. Because Flows behave exactly like Particles, they can be
+nested as steps inside other flows without issue:
+
+```ruby
+class FillCavity
+  include Laminar::Flow
+
+  flow do
+    step :check_equipment # Flow
+    ...
+  end
+end
+
+class CheckEquipment
+  include Laminar::Flow
+
+  flow do
+    ...
+  end
+end
+```
+
+#### Flow Branching
+Ordinarily particle execution is sequential in the order specified.
+However, you can optionally branch to a different label with `branch`.
+```ruby
+  flow do
+    step :do_something do
+      branch :final_step      
+    end
+    step :another_step # skipped
+    step :final_step
+  end
+```
+
+You can use the special symbol :endflow to jump terminate the flow
+(skipping all remaining steps).
+
+```ruby
+  flow do
+    step :do_something do
+      branch :endflow
+    end
+    step :another_step # skipped
+    step :final_step # skipped
+  end
+```
+
+#### Conditional Branching
+
+Branches can be made conditional with the `if:` and `unless:`
+directives.
+
+```ruby
+  flow do
+    step :first do
+      branch :last_step, if: :done_early?      
+    end
+    step :then_me
+    step :do_something
+    step :last_step
+  end
+```
+
+The target of `if:` or `unless:` is a symbol naming a method on the invoking Flow.
+
+```ruby
+  flow do
+    step :first do
+      branch :last_step, if: :done_early?      
+    end
+    ...
+  end
+
+  def done_early?
+    !context[:finished].nil? && context[:finished] == true
+  end
+```
+
+A step can have multiple branch directives; the flow will take the first
+branch that it finds that satisfies its specified condition (if any). If
+no condition is satisfied, execution drops to the next step.
+
+```ruby
+  flow do
+   step :first do
+     branch :last_step, if: :condition1?
+     branch :do_something, if: :condition2?
+   end
+   step :then_me # executed if neither condition1 nor condition2
+   step :do_something
+   step :last_step
+  end
+```
+
+#### Flow Callbacks
+
+A flow can specify callback(s) to run before/after every step:
+
+```ruby
+class MyFlow
+  include Laminar::Flow
+
+  before_each :thing, :thing2  # method
+  before_each { ... } # block
+
+  after_each :thing, :thing2  # method
+  after_each { ... } # block
+```
+
+The order of execution for callbacks in a flow looks like:
+
+```
+flow's before
+  flow's before_each
+    step1's before
+      <step1 invoked>
+    step1's after
+  flow's after_each
+flow's after
+```
+
+#### Testing Particles and Flows
+
+TODO
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/rmlockerd/laminar. This project is intended to be a
+safe, welcoming space for collaboration, and contributors are expected to
+adhere to the [Contributor Covenant](http://contributor-covenant.org) code
+of conduct.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Laminar project’s codebases, issue trackers,
+chat rooms and mailing lists is expected to follow the
+[code of conduct]
+(https://github.com/rmlockerd/laminar/blob/master/CODE_OF_CONDUCT.md).