Merge pull request #24 from B-CDD/change/rename-halted-to-terminal

Change/Rename halted concept to terminal

CHANGELOG.md

@@ -1,27 +1,28 @@
 - [\[Unreleased\]](#unreleased)
+  - [Changed](#changed)
 - [\[0.10.0\] - 2023-12-31](#0100---2023-12-31)
   - [Added](#added)
 - [\[0.9.1\] - 2023-12-12](#091---2023-12-12)
-  - [Changed](#changed)
+  - [Changed](#changed-1)
   - [Fixed](#fixed)
 - [\[0.9.0\] - 2023-12-12](#090---2023-12-12)
   - [Added](#added-1)
-  - [Changed](#changed-1)
+  - [Changed](#changed-2)
 - [\[0.8.0\] - 2023-12-11](#080---2023-12-11)
   - [Added](#added-2)
-  - [Changed](#changed-2)
+  - [Changed](#changed-3)
   - [Removed](#removed)
 - [\[0.7.0\] - 2023-10-27](#070---2023-10-27)
   - [Added](#added-3)
-  - [Changed](#changed-3)
+  - [Changed](#changed-4)
 - [\[0.6.0\] - 2023-10-11](#060---2023-10-11)
   - [Added](#added-4)
-  - [Changed](#changed-4)
+  - [Changed](#changed-5)
 - [\[0.5.0\] - 2023-10-09](#050---2023-10-09)
   - [Added](#added-5)
 - [\[0.4.0\] - 2023-09-28](#040---2023-09-28)
   - [Added](#added-6)
-  - [Changed](#changed-5)
+  - [Changed](#changed-6)
   - [Removed](#removed-1)
 - [\[0.3.0\] - 2023-09-26](#030---2023-09-26)
   - [Added](#added-7)
@@ -33,6 +34,14 @@
 
 ## [Unreleased]
 
+### Changed
+
+- **(BREAKING)** Rename halted concept to terminal. Failures are terminal by default, but you can make a success terminal by enabling the `:continue` addon.
+
+- **(BREAKING)** Rename `BCDD::Result::Context::Success#and_expose` halted keyword argument to `terminal`.
+
+- **(BREAKING)** Rename `BCDD::Result#halted?` to `BCDD::Result#terminal?`.
+
 ## [0.10.0] - 2023-12-31
 
 ### Added
@@ -45,7 +54,7 @@
 
 ### Changed
 
-- **(BREAKING)** Make `BCDD::Result::Context::Success#and_expose()` to produce a halted success by default. You can turn this off by passing `halted: false`.
+- **(BREAKING)** Make `BCDD::Result::Context::Success#and_expose()` to produce a terminal success by default. You can turn this off by passing `halted: false`.
 
 ### Fixed
 

README.md

@@ -920,9 +920,9 @@ The `BCDD::Result.mixin` also accepts the `config:` argument. It is a hash that
 
 **continue**
 
-This addon will create the `Continue(value)` method and change the `Success()` behavior to halt the step chain.
+This addon will create the `Continue(value)` method and change the `Success()` behavior to terminate the step chain.
 
-So, if you want to advance to the next step, you must use `Continue(value)` instead of `Success(type, value)`. Otherwise, the step chain will be halted.
+So, if you want to advance to the next step, you must use `Continue(value)` instead of `Success(type, value)`. Otherwise, the step chain will be terminated.
 
 ```ruby
 module Divide
@@ -1571,7 +1571,7 @@ Divide.new.call(10, 5)
 #<BCDD::Result::Context::Success type=:ok value={:number=>2, :number1=>10, :number2=>5}>
 ```
 
-> PS: The `#and_expose` produces a halted success by default. This means the next step will not be executed even if you call `#and_then` after `#and_expose`. To change this behavior, you can pass `halted: false` to `#and_expose`.
+> PS: The `#and_expose` produces a terminal success by default. This means the next step will not be executed even if you call `#and_then` after `#and_expose`. To change this behavior, you can pass `terminal: false` to `#and_expose`.
 
 <p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
 
@@ -1680,9 +1680,9 @@ The `BCDD::Result::Context.mixin` and `BCDD::Result::Context::Expectations.mixin
 
 **Continue**
 
-The `BCDD::Result::Context.mixin(config: { addon: { continue: true } })` or `BCDD::Result::Context::Expectations.mixin(config: { addon: { continue: true } })` creates the `Continue(value)` method and change the `Success()` behavior to halt the step chain.
+The `BCDD::Result::Context.mixin(config: { addon: { continue: true } })` or `BCDD::Result::Context::Expectations.mixin(config: { addon: { continue: true } })` creates the `Continue(value)` method and change the `Success()` behavior to terminate the step chain.
 
-So, if you want to advance to the next step, you must use `Continue(**value)` instead of `Success(type, **value)`. Otherwise, the step chain will be halted.
+So, if you want to advance to the next step, you must use `Continue(**value)` instead of `Success(type, **value)`. Otherwise, the step chain will be terminated.
 
 Let's use a mix of `BCDD::Result::Context` features to see in action with this add-on:
 

lib/bcdd/result.rb

@@ -16,7 +16,7 @@
 class BCDD::Result
   attr_accessor :unknown, :transitions
 
-  attr_reader :subject, :data, :type_checker, :halted
+  attr_reader :subject, :data, :type_checker, :terminal
 
   protected :subject
 
@@ -32,12 +32,12 @@ def self.configuration
     config.freeze
   end
 
-  def initialize(type:, value:, subject: nil, expectations: nil, halted: nil)
+  def initialize(type:, value:, subject: nil, expectations: nil, terminal: nil)
     data = Data.new(kind, type, value)
 
     @type_checker = Contract.evaluate(data, expectations)
     @subject = subject
-    @halted = halted || kind == :failure
+    @terminal = terminal || kind == :failure
     @data = data
 
     self.unknown = true
@@ -46,8 +46,8 @@ def initialize(type:, value:, subject: nil, expectations: nil, halted: nil)
     Transitions.tracking.record(self)
   end
 
-  def halted?
-    halted
+  def terminal?
+    terminal
   end
 
   def type
@@ -89,7 +89,7 @@ def on_unknown
   end
 
   def and_then(method_name = nil, context = nil, &block)
-    return self if halted?
+    return self if terminal?
 
     method_name && block and raise ::ArgumentError, 'method_name and block are mutually exclusive'
 

lib/bcdd/result/context.rb

@@ -15,7 +15,7 @@ def self.Failure(type, **value)
       Failure.new(type: type, value: value)
     end
 
-    def initialize(type:, value:, subject: nil, expectations: nil, halted: nil)
+    def initialize(type:, value:, subject: nil, expectations: nil, terminal: nil)
       value.is_a?(::Hash) or raise ::ArgumentError, 'value must be a Hash'
 
       @acc = {}

lib/bcdd/result/context/mixin.rb

@@ -13,15 +13,15 @@ def Failure(type, **value)
         _ResultAs(Failure, type, value)
       end
 
-      private def _ResultAs(kind_class, type, value, halted: nil)
-        kind_class.new(type: type, value: value, subject: self, halted: halted)
+      private def _ResultAs(kind_class, type, value, terminal: nil)
+        kind_class.new(type: type, value: value, subject: self, terminal: terminal)
       end
     end
 
     module Addons
       module Continuable
         def Success(type, **value)
-          _ResultAs(Success, type, value, halted: true)
+          _ResultAs(Success, type, value, terminal: true)
         end
 
         private def Continue(**value)

lib/bcdd/result/context/success.rb

@@ -3,13 +3,13 @@
 class BCDD::Result::Context::Success < BCDD::Result::Context
   include ::BCDD::Result::Success::Methods
 
-  def and_expose(type, keys, halted: true)
+  def and_expose(type, keys, terminal: true)
     unless keys.is_a?(::Array) && !keys.empty? && keys.all?(::Symbol)
       raise ::ArgumentError, 'keys must be an Array of Symbols'
     end
 
     exposed_value = acc.merge(value).slice(*keys)
 
-    self.class.new(type: type, value: exposed_value, subject: subject, halted: halted)
+    self.class.new(type: type, value: exposed_value, subject: subject, terminal: terminal)
   end
 end

lib/bcdd/result/expectations.rb

@@ -38,8 +38,8 @@ def self.new(...)
 
     private_class_method :mixin!, :mixin_module, :result_factory_without_expectations
 
-    def initialize(subject: nil, contract: nil, halted: nil, **options)
-      @halted = halted
+    def initialize(subject: nil, contract: nil, terminal: nil, **options)
+      @terminal = terminal
 
       @subject = subject
 
@@ -60,16 +60,16 @@ def Failure(type, value = nil)
       _ResultAs(Failure, type, value)
     end
 
-    def with(subject:, halted: nil)
-      self.class.new(subject: subject, halted: halted, contract: contract)
+    def with(subject:, terminal: nil)
+      self.class.new(subject: subject, terminal: terminal, contract: contract)
     end
 
     private
 
     def _ResultAs(kind_class, type, value)
-      kind_class.new(type: type, value: value, subject: subject, expectations: contract, halted: halted)
+      kind_class.new(type: type, value: value, subject: subject, expectations: contract, terminal: terminal)
     end
 
-    attr_reader :subject, :halted, :contract
+    attr_reader :subject, :terminal, :contract
   end
 end

lib/bcdd/result/expectations/mixin.rb

@@ -24,14 +24,14 @@ def Failure(...)
 
       FACTORY = <<~RUBY
         private def _Result
-          @_Result ||= Result.with(subject: self, halted: %<halted>s)
+          @_Result ||= Result.with(subject: self, terminal: %<terminal>s)
         end
       RUBY
 
       def self.to_eval(addons)
-        halted = addons.key?(:continue) ? 'true' : 'nil'
+        terminal = addons.key?(:continue) ? 'true' : 'nil'
 
-        "#{BASE}\n#{format(FACTORY, halted: halted)}"
+        "#{BASE}\n#{format(FACTORY, terminal: terminal)}"
       end
     end
 

lib/bcdd/result/mixin.rb

@@ -20,15 +20,15 @@ def Failure(type, value = nil)
         _ResultAs(Failure, type, value)
       end
 
-      private def _ResultAs(kind_class, type, value, halted: nil)
-        kind_class.new(type: type, value: value, subject: self, halted: halted)
+      private def _ResultAs(kind_class, type, value, terminal: nil)
+        kind_class.new(type: type, value: value, subject: self, terminal: terminal)
       end
     end
 
     module Addons
       module Continuable
         def Success(type, value = nil)
-          _ResultAs(Success, type, value, halted: true)
+          _ResultAs(Success, type, value, terminal: true)
         end
 
         private def Continue(value)

sig/bcdd/result.rbs

@@ -5,7 +5,7 @@ class BCDD::Result
 
   attr_reader data: BCDD::Result::Data
   attr_reader subject: untyped
-  attr_reader halted: bool
+  attr_reader terminal: bool
   attr_reader transitions: Hash[Symbol, untyped]
 
   def self.config: -> BCDD::Result::Config
@@ -16,13 +16,13 @@ class BCDD::Result
     value: untyped,
     ?subject: untyped,
     ?expectations: BCDD::Result::Contract::Evaluator,
-    ?halted: bool
+    ?terminal: bool
   ) -> void
 
   def type: -> Symbol
   def value: -> untyped
 
-  def halted?: -> bool
+  def terminal?: -> bool
   def success?: (?Symbol type) -> bool
   def failure?: (?Symbol type) -> bool
 

sig/bcdd/result/context.rbs

@@ -10,7 +10,7 @@ class BCDD::Result::Context < BCDD::Result
     value: untyped,
     ?subject: untyped,
     ?expectations: BCDD::Result::Contract::Evaluator,
-    ?halted: bool
+    ?terminal: bool
   ) -> void
 
   def and_then: (?Symbol, **untyped) ?{ (Hash[Symbol, untyped]) -> untyped } -> BCDD::Result::Context
@@ -27,7 +27,7 @@ class BCDD::Result::Context
   class Success < BCDD::Result::Context
     include BCDD::Result::Success::Methods
 
-    def and_expose: (Symbol, Array[Symbol], halted: bool) -> BCDD::Result::Context::Success
+    def and_expose: (Symbol, Array[Symbol], terminal: bool) -> BCDD::Result::Context::Success
   end
 
   def self.Success: (Symbol, **untyped) -> BCDD::Result::Context::Success
@@ -54,7 +54,7 @@ class BCDD::Result::Context
 
       private
 
-      def _ResultAs: (singleton(BCDD::Result::Context), Symbol, untyped, ?halted: bool) -> untyped
+      def _ResultAs: (singleton(BCDD::Result::Context), Symbol, untyped, ?terminal: bool) -> untyped
     end
 
     module Addons

sig/bcdd/result/expectations.rbs

@@ -18,14 +18,14 @@ class BCDD::Result::Expectations
   def self.new: (
     ?subject: untyped,
     ?contract: BCDD::Result::Contract::Evaluator,
-    ?halted: bool,
+    ?terminal: bool,
     **untyped
   ) -> (BCDD::Result::Expectations | untyped)
 
   def initialize: (
     ?subject: untyped,
     ?contract: BCDD::Result::Contract::Evaluator,
-    ?halted: bool,
+    ?terminal: bool,
     **untyped
   ) -> void
 
@@ -40,7 +40,7 @@ class BCDD::Result::Expectations
 
   attr_reader subject: untyped
   attr_reader contract: BCDD::Result::Contract::Evaluator
-  attr_reader halted: bool
+  attr_reader terminal: bool
 end
 
 module BCDD::Result::Expectations::Mixin

sig/bcdd/result/mixin.rbs

@@ -11,7 +11,7 @@ class BCDD::Result
 
       private
 
-      def _ResultAs: (singleton(BCDD::Result), Symbol, untyped, ?halted: bool) -> untyped
+      def _ResultAs: (singleton(BCDD::Result), Symbol, untyped, ?terminal: bool) -> untyped
     end
 
     module Addons