standard-procedure-signal 0.1.2.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62ddde59890dc0a13e2704932107e8b25bd33fabf5a48a2100a97cf7c3cbff10
-  data.tar.gz: 31233250f1bc23143b6ef40b40081cd0b31da06ced7b4a1cbc39ef5cf12d7fad
+  metadata.gz: 4f6832d51eb537fe7c3fb46ffeddf42c0cace64f77a2caae6499ee85688caf55
+  data.tar.gz: be9c55a822d3d053d176f57b51e21b7e0de1ad8a3817257b096ff9f6b228d82a
 SHA512:
-  metadata.gz: 0a7786dad91fcc094e1b98362c9644502e82a35aae9b09cc93abea6b82993e2487c6ba6be30519ae9f8581119bc359ae7b01e3231aaf56cd23d46c44ad6c5c7b
-  data.tar.gz: c14bc7e66a1f1ca678e2295c88bb9aba9503c8ebe7910606d5f85223b4edf2eca19008396cafde904f2010357c2d10a9a69f802a501ce0f1ec57753fcf3293ae
+  metadata.gz: bedb9d1523ce359dfafe85fff3865055f48aeb4e8def1e585ba63b7d75de1bdd62e8107b26b2e7277e997f1b7bbf1d5fb41c78f505a5af051e3ffd408afba3a7
+  data.tar.gz: dabbde43de2d4b1a62da7bb7b389a8dcb0b3c8c27136da3cc8f3a0b316fa5ddab4592c87cbb18cf36d3b7160b48fe58bcfc4e3889b747f5181feb33d5ed5fe17

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## [0.2.0] - 2023-09-14
+
+- Improved the API by extending the ruby Signal module
+
 ## [0.1.2] - 2023-09-13
 
 - Added the StandardProcedure namespace, as ::Signal is used by Ruby itself

data/README.md

@@ -15,20 +15,18 @@ Finally, we define an observer (our "name badge") that simply writes the display
 When we update the values stored in those various attributes, our "name badge" redraws itself when it has to but does nothing if it does not need to change.
 
 ```ruby
-include StandardProcedure::Signal
-
 # Define the basic attributes
-first_name = attribute.text "Alice"
-last_name = attribute.text "Aardvark"
-show_full_name = attribute.boolean true
+first_name = Signal.text_attribute "Alice"
+last_name = Signal.text_attribute "Aardvark"
+show_full_name = Signal.boolean_attribute true
 
 # Define the composite attribute
-display_name = compute do
+display_name = Signal.compute do
   show_full_name.get ?  "#{first_name.get} #{last_name.get}" : first_name.get
 end
 
 # Define the output that the end-user will see
-observe do
+Signal.observe do
   puts "My name is #{display_name.get}"
 end
 # => My name is Alice Aardvark
@@ -41,7 +39,7 @@ show_full_name.set true
 # => My name is Alice Anteater
 
 # Perform a batch update, with no notifications until the batch is completed
-update do
+Signal.update do
   first_name.set "Anthony"
   # no output
   show_full_name.set false
@@ -107,25 +105,23 @@ In addition, there is a concrete implementation of the StandardProcedure::Signal
 And `StandardProcedure::Signal.compute` allows you to build composite observables which depend on multiple other observables.
 
 ```ruby
-include StandardProcedure::Signal
-
-@my_object = attribute.new MyObject.new
-@my_text = attribute.text "The total is: "
-@a = attribute.integer 1
-@b = attribute.integer 2
-@sum = compute { @a.get + @b.get }
-observe do
+@my_object = Signal.attribute MyObject.new
+@my_text = Signal.text_attribute "The total is: "
+@a = Signal.integer_attribute 1
+@b = Signal.integer_attribute 2
+@sum = Signal.compute { @a.get + @b.get }
+Signal.observe do
   puts "#{@my_text.get} #{@sum.get}"
 end
 ```
 
-To access the values stored in a `attribute`, you can call `attribute#get`. This is aliased as both `attribute#read` and `attribute#call` (which means you can use the short-hand `@my_attribute.()` as well).
+To access the values stored in an attribute, you can call `StandardProcedure::Signal::Attribute#get`. This is aliased as both `StandardProcedure::Signal::Attribute#read` and `StandardProcedure::Signal::Attribute#call` (which means you can use the short-hand `@my_attribute.()` as well).  However, calling `StandardProcedure::Signal::Attribute#get` also incurs the overhead of setting up observers for the attribute, so if you just want to peek at the value without worrying about changes, you can call `StandardProcedure::Signal::Attribute#peek`.
 
-To place a value into an attribute you call `attribute#set`, aliased as `attribute#write`.
+To place a value into an attribute you call `StandardProcedure::Signal::Attribute#set`, aliased as `StandardProcedure::Signal::Attribute#write`.
 
 ### Extensions
 
-Because `StandardProcedure::Signal.observe` and `StandardProcedure::Signal::Attribute` are quite long names, you can just include the [StandardProcedure::Signal module](lib/standard_procedure/signal.rb) that you can include into your classes, to give you shortcuts.  
+Because `StandardProcedure::Signal.observe` and `StandardProcedure::Signal::Attribute` are quite long names, you can include the [StandardProcedure::Signal module](lib/standard_procedure/signal.rb) into your own classes.  And the module has also been extended into the standard Ruby [Signal](https://docs.ruby-lang.org/en/master/Module.html) so you can refer to them as `Signal.observe`, `Signal.compute` and so on.  
 
 ### Triggering updates
 
@@ -134,23 +130,19 @@ It's important to note that most observables only trigger updates when the `set`
 For example: 
 
 ```ruby
-include StandardProcedure::Signal
-
 # This will not trigger any updates
-@attribute = attribute.string "hello"
+@attribute = Signal.text_attribute "hello"
 @attribute.get.upcase!
 
 # This will trigger updates
-@attribute = attribute.string "hello"
+@attribute = Signal.text_attribute "hello"
 @attribute.set @attribute.get.upcase
 ```
 
 If necessary, you can manually trigger updates on an observable.  
 ```ruby
-include StandardProcedure::Signal
-
 # Manually trigger updates
-@attribute = attribute.string "hello"
+@attribute = Signal.text_attribute "hello"
 @attribute.get.upcase!
 @attribute.update_observers 
 ```
@@ -160,30 +152,28 @@ However, there are two mutable attributes that you can use - [attribute::Array](
 These are partial implementations of the ruby Array and Hash classes that are convenience wrappers when it comes to updates.  They implement Enumerable, so you can use `each`, `map` and your other favourites, plus they include a subset of the mutation methods to make it easier to manipulate the contents without repeatedly copying, changing and then setting your attributes contents.  
 
 ```ruby
-include StandardProcedure::Signal
-
 # Non-mutable array attribute 
 @array = [1, 2, 3]
-@attribute = attribute.new @array 
+@attribute = Signal.array_attribute @array 
 @new_array = @array.dup 
 @new_array.push 4
 @attribute.set @new_array
 
 # Mutable array attribute
 @array = [1, 2, 3]
-@attribute = attribute.array @array 
+@attribute = Signal.array_attribute @array 
 @attribute << 4
 
 # Non-mutable hash attribute 
 @hash = { key1: "value1", key2: "value2" }
-@attribute = attribute.new @hash 
+@attribute = Signal.attribute @hash 
 @new_hash = @hash.dup 
 @new_hash[:key3] = "value3"
 @attribute.set @new_hash
 
 # Mutable hash attribute
 @hash = { key1: "value1", key2: "value2" }
-@attribute = attribute.array @hash
+@attribute = Signal.array_attribute @hash
 @attribute[:key3] = "value3"
 ```
 

data/checksums/standard-procedure-signal-0.2.0.gem.sha512

@@ -0,0 +1 @@
+7ff644775dc25b8168b1ba28d3d0635846efe7aada24bcd95c4299a5e225856f3cd5448dc1d2577a89dd01638504cf9be151d83d2869da1b645fa56c6cee6523

data/lib/standard_procedure/signal/attribute.rb

@@ -22,8 +22,9 @@ module StandardProcedure
         set value
       end
 
+      TYPES = %i[text integer float date time boolean array hash].freeze
       class << self
-        %i[text integer float date time boolean array hash].each do |type|
+        TYPES.each do |type|
           class_name = "StandardProcedure::Signal::Attribute::#{type.to_s.capitalize}"
           define_method type do |value|
             const_get(class_name).new value

data/lib/standard_procedure/signal/observable.rb

@@ -31,6 +31,13 @@ module StandardProcedure
       alias_method :get, :call
       alias_method :read, :call
 
+      # Peek at the value of this signal without registering as an observer
+      #
+      # This is useful if you just want to access the value but don't care if it changes
+      def peek
+        @value
+      end
+
       # Set the value of this signal and notify any observers
       #
       # This method is aliased as `write` it can be used in whichever way makes most sense to you

data/lib/standard_procedure/signal/signal_extensions.rb

@@ -0,0 +1,3 @@
+module Signal
+  extend StandardProcedure::Signal
+end

data/lib/standard_procedure/signal/version.rb

@@ -2,6 +2,6 @@
 
 module StandardProcedure
   module Signal
-    VERSION = "0.1.2.1"
+    VERSION = "0.2.0"
   end
 end

data/lib/standard_procedure/signal.rb

@@ -7,6 +7,7 @@ module StandardProcedure
     require_relative "signal/observer"
     require_relative "signal/observable"
     require_relative "signal/attribute"
+    require_relative "signal/signal_extensions"
 
     # Build a "computed" attribute that automatically updates based upon its dependents
     #
@@ -21,8 +22,8 @@ module StandardProcedure
     #   "#{first_line.get}\n#{second_line.get}\n#{city.get}\n#{region.get}"
     # end
     def compute(&block)
-      StandardProcedure::Signal::Attribute.new(nil).tap do |attribute|
-        observe { attribute.set block.call }
+      attribute(nil).tap do |a|
+        observe { a.set block.call }
       end
     end
 
@@ -59,16 +60,29 @@ module StandardProcedure
       end
     end
 
-    # Build an attribute that signals its changes to dependents
-    # See StandardProcedure::Signal::Attribute for the different types available
+    # Shortcut method to build an attribute that signals its changes to dependents
+    #
+    # There are also helpers for the various types of Attribute - see StandardProcedure::Signal::Attribute::TYPES
     #
     # include StandardProcedure::Signal
-    # @name = attribute.text "Alice"
-    # @age = attribute.integer 23
-    # @colours = attribute.array %w[red green blue]
-    # @object = attribute.new @some_object
-    def attribute
-      StandardProcedure::Signal::Attribute
+    # @object = attribute @some_object
+    # @name = text_attribute "Alice"
+    # @age = integer_attribute 23
+    # @colours = array_attribute %w[red green blue]
+    def attribute value
+      StandardProcedure::Signal::Attribute.new value
+    end
+
+    class_eval do
+      StandardProcedure::Signal::Attribute::TYPES.each do |type|
+        define_method :"#{type}_attribute" do |value|
+          StandardProcedure::Signal::Attribute.send type, value
+        end
+      end
     end
   end
 end
+
+def Signal
+  StandardProcedure::Signal
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: standard-procedure-signal
 version: !ruby/object:Gem::Version
-  version: 0.1.2.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Rahoul Baruah
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-09-13 00:00:00.000000000 Z
+date: 2023-09-14 00:00:00.000000000 Z
 dependencies: []
 description: Observable attributes which adapt based upon their dependencies so we
   avoid unecessary updates
@@ -32,6 +32,7 @@ files:
 - checksums/standard-procedure-signal-0.1.1.gem.sha512
 - checksums/standard-procedure-signal-0.1.2.1.gem.sha512
 - checksums/standard-procedure-signal-0.1.2.gem.sha512
+- checksums/standard-procedure-signal-0.2.0.gem.sha512
 - lib/standard_procedure/signal.rb
 - lib/standard_procedure/signal/attribute.rb
 - lib/standard_procedure/signal/attribute/array.rb
@@ -46,6 +47,7 @@ files:
 - lib/standard_procedure/signal/manager.rb
 - lib/standard_procedure/signal/observable.rb
 - lib/standard_procedure/signal/observer.rb
+- lib/standard_procedure/signal/signal_extensions.rb
 - lib/standard_procedure/signal/version.rb
 - sig/standard/procedure/attribute.rbs
 homepage: https://theartandscienceofruby.com