rung 0.0.1.pre.alpha → 0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a7cd0b72e47764f703e416e708f76644255e53df
-  data.tar.gz: 7887c8167710d0c089c792ca25c53a79b2fe053a
+  metadata.gz: de22a1e77fdae3c25ffd7813dfd6ffa2059d636a
+  data.tar.gz: dd81b258d16d75fa76d68cf2a72875c9c595db8f
 SHA512:
-  metadata.gz: 15ad2faba325fe974e782ac1941255e0ab80b2dddf269d77892d30a0ebb4a99e67844978b5dbc5dc7ad8c3ec97cd222e2e80ca3536ea6d9e2753ba4a1ee9f8e3
-  data.tar.gz: bb56850efb181213e11bae971feea9f659408f668598d1994bde7be06eba32010b2cd9603eb490c5b4c5640c13976ec7318ae03404b5511029d5cda924072248
+  metadata.gz: 2230826da27de68cc4d14a6678ce25fbc8a931e518df1931ad3fa5f5099d8e541ee53a0a1f244b14381bff623d03769d0e6a183611f9f0b59c9ea5259ad41b85
+  data.tar.gz: 5f2a503861595ecd5aa133ea523214fb2d5be738521b440fa27b1270d6a1ae422b13ef9b0fa078e2ed0b08a60ea42211dfad3f59652c4ccf6f4e4d5477fbc3db

data/.circleci/config.yml

@@ -0,0 +1,72 @@
+version: 2
+jobs:
+  build:
+    docker:
+      - image: circleci/ruby:2.4.1
+    steps:
+      - checkout
+      - run: bundle install
+      - run: bundle exec rspec
+      - run: bundle exec cucumber
+      - run: bundle exec rubocop
+
+      - run: mkdir workspace
+      - run: bundle exec cucumber -f json -o workspace/cucumber.json
+      - persist_to_workspace:
+          root: workspace
+          paths:
+            - cucumber.json
+
+  build_docs:
+    docker:
+      - image: circleci/openjdk:11-jdk-browsers
+    steps:
+      - checkout
+      - attach_workspace:
+          at: /tmp/workspace
+      - run: wget https://bintray.com/artifact/download/rmpestano/cukedoctor/com/github/cukedoctor/cukedoctor-main/1.2.1/cukedoctor-main-1.2.1.jar
+      - run: mkdir /tmp/workspace/generated_doc
+      - run: java -jar cukedoctor-main-1.2.1.jar -f html5 -p /tmp/workspace/cucumber.json -o /tmp/workspace/generated_doc/index -hideSummarySection -t "Rung Documentation" -hideStepTime -hideScenarioKeyword -hideFeaturesSection
+      - persist_to_workspace:
+          root: /tmp/workspace/
+          paths:
+            - generated_doc
+
+  deploy_docs:
+    docker:
+      - image: node:8.10.0
+    steps:
+      - checkout
+      - attach_workspace:
+          at: workspace
+      - run:
+          name: Install and configure dependencies
+          command: |
+            npm install -g --silent gh-pages@2.0.1
+            git config user.email "circle-ci@jedrychowski.org"
+            git config user.name "ci-build"
+      - add_ssh_keys:
+          fingerprints:
+            - "32:c9:81:d7:bf:fb:82:c1:48:eb:fc:a8:98:f8:48:7e"
+      - run:
+          name: Deploy docs to gh-pages branch
+          command: gh-pages --dist workspace/generated_doc/ --message "[skip ci] Doc update"
+
+workflows:
+  version: 2
+
+  btd:
+    jobs:
+      - build
+      - build_docs:
+          requires:
+            - build
+          filters:
+            branches:
+              only: master
+      - deploy_docs:
+          requires:
+            - build_docs
+          filters:
+            branches:
+              only: master

data/.config/cucumber.yml

@@ -0,0 +1 @@
+default: --format progress

data/.gitignore

@@ -0,0 +1,3 @@
+tmp
+generated_doc/
+.yardoc

data/.rspec

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

data/.rubocop.yml

@@ -0,0 +1,22 @@
+AllCops:
+  TargetRubyVersion: 2.3
+  Exclude:
+    - spec/integration/*
+    - rung.gemspec
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*.rb'
+
+Layout/AlignParameters:
+  EnforcedStyle: with_fixed_indentation
+
+Metrics/LineLength:
+  IgnoredPatterns:
+    - ^\s*it \'

data/Gemfile

@@ -1,7 +1,11 @@
-source "https://rubygems.org"
+source 'https://rubygems.org'
 
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
 # Specify your gem's dependencies in rung.gemspec
 gemspec
 gem 'pry'
+
+gem 'asciidoctor'
+gem 'rubocop'
+gem 'yard'

data/Gemfile.lock

@@ -1,11 +1,13 @@
 PATH
   remote: .
   specs:
-    rung (0.0.1.pre.alpha)
+    rung (0.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    asciidoctor (1.5.8)
+    ast (2.4.0)
     backports (3.11.4)
     builder (3.2.3)
     coderay (1.1.2)
@@ -27,12 +29,18 @@ GEM
     cucumber-wire (0.0.1)
     diff-lcs (1.3)
     gherkin (5.1.0)
+    jaro_winkler (1.5.2)
     method_source (0.9.2)
     multi_json (1.13.1)
     multi_test (0.1.2)
+    parallel (1.13.0)
+    parser (2.6.0.0)
+      ast (~> 2.4.0)
+    powerpack (0.1.2)
     pry (0.12.2)
       coderay (~> 1.1.0)
       method_source (~> 0.9.0)
+    rainbow (3.0.0)
     rake (10.5.0)
     rspec (3.8.0)
       rspec-core (~> 3.8.0)
@@ -47,17 +55,31 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.8.0)
     rspec-support (3.8.0)
+    rubocop (0.63.1)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.5, != 2.5.1.1)
+      powerpack (~> 0.1)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.4.0)
+    ruby-progressbar (1.10.0)
+    unicode-display_width (1.4.1)
+    yard (0.9.18)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
+  asciidoctor
   bundler (~> 1.16)
   cucumber (~> 3.1)
   pry
   rake (~> 10.0)
   rspec (~> 3.0)
+  rubocop
   rung!
+  yard
 
 BUNDLED WITH
    1.16.3

data/README.adoc

@@ -0,0 +1,111 @@
+:!hardbreaks:
+= Rung
+
+image:https://circleci.com/gh/gogiel/rung/tree/master.svg?style=svg["CircleCI", link="https://circleci.com/gh/gogiel/rung/tree/master"]
+https://codeclimate.com/github/gogiel/rung/maintainability[image:https://api.codeclimate.com/v1/badges/67ff3c0c392c368d0156/maintainability[Maintainability]]
+
+Rung is service object/business operation/Railway DSL.
+
+This is a lightweight, independent alternative to
+http://trailblazer.to/gems/operation[Trailblazer Operation]
+and
+https://github.com/dry-rb/dry-transaction[dry-transaction].
+
+== Installation
+
+Add this line to your application’s Gemfile:
+
+[source,ruby]
+----
+gem 'rung'
+----
+
+And then execute:
+
+....
+$ bundle
+....
+
+Or install it yourself as:
+
+....
+$ gem install rung
+....
+
+== Example Usage
+
+Example:
+
+[source,ruby]
+----
+class CreateOrder < Rung::Operation
+  step do |state|
+    state[:order_id] = "order-#{SecureRandom.uuid }"
+  end
+  step ValidateMagazineState
+  step :log_start
+
+  step WithBenchmark do
+    step CreateTemporaryOrder
+    step :place_order
+  end
+
+  step :log_success
+  failure :log_failure
+
+  def log_start(state)
+    state[:logger].log("Creating order #{state[:order_id]}")
+  end
+
+  def log_success(state)
+    state[:logger].log("Order #{state[:order_id]} created successfully")
+  end
+
+  def log_failure(state)
+    state[:logger].log("Order #{state[:order_id]} not created")
+  end
+
+  def place_order(state)
+    status = OrdersRepository.create(state[:order_id])
+
+    # Step return value is important.
+    # If step returns falsy value then the operation is considered as a failure.
+    status == :success
+  end
+end
+
+result = CreateOrder.call(logger: Rails.logger)
+if result.success?
+  print "Created order #{result[:order_id]}"
+end
+----
+
+== Docs
+
+Docs are available at https://gogiel.github.io/rung/.
+
+They are generated from Cucumber specifications using
+https://github.com/rmpestano/cukedoctor[Cukedoctor].
+
+Docs can be generated locally using `$ rake docker_generate_docs`. It requires Docker.
+
+== Development
+
+After checking out the repo, run `bundle` to install dependencies. Then,
+run `rake` 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`. To release a new version, update the version
+number in `version.rb`, and then run `bundle exec rake release`, which
+will create a git tag for the version, push git commits and tags, and
+push the `.gem` file to https://rubygems.org[rubygems.org].
+
+== Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/gogiel/rung.
+
+== License
+
+The gem is available as open source under the terms of the
+https://opensource.org/licenses/MIT[MIT License].

data/Rakefile

@@ -1,8 +1,23 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-require "cucumber/rake/task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'cucumber/rake/task'
+require 'rubocop/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
 Cucumber::Rake::Task.new(:cucumber)
+Cucumber::Rake::Task.new(
+  :cucumber_json, 'Generate Cucumber JSON in tmp/'
+) do |t|
+  t.cucumber_opts = %w[-f json -o tmp/cucumber.json]
+end
 
-task :default => [:spec, :cucumber]
+task default: %i[spec cucumber rubocop]
+
+desc 'Generate Cukedoctor docs in generated_doc/ using docker'
+task docker_generate_docs: [:cucumber_json] do
+  sh 'docker run -v "$PWD:/output" -w /output rmpestano/cukedoctor' \
+    ' -o generated_doc/index -f html5 -p tmp/cucumber.json' \
+    ' -t "Rung Documentation" -hideSummarySection  -hideStepTime' \
+    ' -hideScenarioKeyword -hideFeaturesSection'
+end

data/features/{steps_definition.feature → 010_operation.feature}

@@ -1,11 +1,34 @@
-Feature: steps_definition
-  There are multiple ways of defining steps.
-  Steps definition order is important as they are always executed in order.
+# order: 10
+Feature: Operation definition
+:!hardbreaks:
+Operation defines a business process that consists of multiple steps.
+
+For example when in e-commerce application new order is created then
+the system should update state of the warehouse, send an e-mail, create new waybill etc.
+
+To define Operation create a new class based on `Rung::Operation`.
+Inside it you can define steps using Rung DSL.
+Steps definition order is important as they are always executed in order.
+
+Steps can communicate with each other and the external world using State. When
+operation is called then new state object is created.
+State is shared between step executions and available as a result of operation.
+See link:#State[State chapter] to learn more.
+
+There are multiple ways of defining steps:
+
+* using a block
+* Symbol with a method name
+* using object that responds to `.call`
+
+Each method can be used with a an argument (state) or with no arguments.
+
+TIP: Using block notation is not advised. It's made primarily for debugging.
 
   Scenario: Steps can be defined as a Ruby block
     Given definition
     """ruby
-    class Operation < Rung::Base
+    class Operation < Rung::Operation
       step do |state|
         state[:what] = "World"
       end
@@ -35,7 +58,7 @@ Feature: steps_definition
   Scenario: Steps can be defined as methods
     Given definition
     """ruby
-    class Operation < Rung::Base
+    class Operation < Rung::Operation
       step :set_what_state
       step :print_hello
       step "print_what"
@@ -94,7 +117,7 @@ Feature: steps_definition
 
     PrintBang = -> { print_to_output "!" }
 
-    class Operation < Rung::Base
+    class Operation < Rung::Operation
       step SetWhatState.new("World")
       step PrintHello
       step PrintWhat

data/features/{state.feature → 020_state.feature}

@@ -1,9 +1,18 @@
-Feature: state
+# order: 20
+Feature: State
+:!hardbreaks:
+State is a Hash object that is shared between step executions.
+
+It's used to share state between steps and communicate with external world.
+
+User can provide initial state when calling the operation. By default it's empty.
+
+State can be used as the operation output as it is accessible in the result object.
 
   Scenario: State is shared across step executions
     Given definition
     """ruby
-    class Operation < Rung::Base
+    class Operation < Rung::Operation
       step do |state|
         state[:what] = "World!"
       end
@@ -29,7 +38,7 @@ Feature: state
   Scenario: State is available in the result object
     Given definition
     """ruby
-    class Operation < Rung::Base
+    class Operation < Rung::Operation
       step do |state|
         state[:output_text] = "Hello "
       end
@@ -51,7 +60,7 @@ Feature: state
   Scenario: Initial state can be passed to call method
     Given definition
     """ruby
-    class Operation < Rung::Base
+    class Operation < Rung::Operation
       step do |state|
         state[:output_text] << "World!"
       end
@@ -65,3 +74,7 @@ Feature: state
     """
     @result[:output_text] == "Hello World!"
     """
+    And I can assure that
+    """
+    @result.to_h == { output_text: "Hello World!" }
+    """

data/features/{failure.feature → 030_failure.feature}

@@ -1,11 +1,26 @@
-Feature: failure
-  Operation call returns `Rung::Runner::Result` object that can be either a success or a failure.
-  Result has `success?` and `failure?` methods.
+# order: 30
+Feature: Success and failure
+:!hardbreaks:
+Rung gem is based on
+link:https://fsharpforfunandprofit.com/rop/[Railway oriented programming]
+idea. If you are not familiar with this concept I highly recommend
+watching link:https://vimeo.com/113707214[Scott Wlaschin's presentation] first.
+
+Value returned from step call is important. Successful step should
+return truthy value (anything other than `false` or `nil`).
+
+If step returns falsy value (`false` or `nil`) then
+the operation is marked as failed. All next steps are not executed.
+
+Result of the Operation call (`Rung::State` object)
+can be either a success or a failure.
+It can be checked using `State` has `success?` and `fail?`
+(with `failed?`, `failure?` aliases) methods.
 
   Scenario: When all steps return truthy value the result is a success
     Given definition
     """ruby
-    class Operation < Rung::Base
+    class Operation < Rung::Operation
       step do
         # do something...
         true
@@ -30,11 +45,19 @@ Feature: failure
     """
     @result.failure? == false
     """
+    And I can assure that `fail?` alias works
+    """
+    @result.fail? == false
+    """
+    And I can assure that `failed?` alias works
+    """
+    @result.failed? == false
+    """
 
   Scenario: When at least one step returns a falsy value then the result is a failure
     Given definition
     """ruby
-    class Operation < Rung::Base
+    class Operation < Rung::Operation
       step do
         # do something...
         true
@@ -63,7 +86,7 @@ Feature: failure
   Scenario: When a step fails then the next steps are not executed
     Given definition
     """ruby
-    class Operation < Rung::Base
+    class Operation < Rung::Operation
       step do
         print_to_output "Hello"
         true