safestruct 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: aabbb2a559ec2421cc0ac43cdcfb0764c8f01633
-  data.tar.gz: 7c4aa56416aa26f67f06aa09260d0af12f28cf27
+  metadata.gz: 74b37cac746195871cc30eec8b8b54622958c6a5
+  data.tar.gz: 80def63037cd23ce8812529a4f208e1ebfbbab7a
 SHA512:
-  metadata.gz: 3b51b663bc4580a435e39d74ea015bc6e407dec307126de09fe818977de527ced949d4d58a2a04f27a10a25074e76fcc17f47139152782804177b28bf0cd5d20
-  data.tar.gz: 5285c818c0b4240f186bbc3f9c4221aa4cdf204ec20f0ac187da6b3b1d2a8a339fe5162802b9fabc8b09c80c2ce77e8a013bb3fb391074229dc978fb886024dd
+  metadata.gz: 508027ee5576e342154bc62d6d5b5e25cf2f829a075a7b942fc9a3af2bb2295f6e6d71eec58597b7de5c69106ecde9ee6fb1f8d0c503215ab7f15735afa01f62
+  data.tar.gz: a9172d32b881902e273bc54cb4e41875edb0c2dd40efd62ca19a07170e8cf01596457b31fa1c63fe244096c3a69b2ab9a280c93241656abedf99f1fd5eeb4c60

data/README.md

@@ -6,16 +6,197 @@ safestruct gem / library - safe data structures (array, hash, struct) - say good
 * bugs  :: [github.com/s6ruby/safestruct/issues](https://github.com/s6ruby/safestruct/issues)
 * gem   :: [rubygems.org/gems/safestruct](https://rubygems.org/gems/safestruct)
 * rdoc  :: [rubydoc.info/gems/safestruct](http://rubydoc.info/gems/safestruct)
-* forum :: [wwwmake](http://groups.google.com/group/wwwmake)
 
 
 ## Usage
 
-to be done
+[Safe Struct](#safe-struct)  •
+[Safe Array](#safe-array)  •
+[Safe Hash](#safe-hash)
+
+
+### Null / Nil - The Billion Dollar Mistake ++ Zero - The Billion Dollar Fix
+
+> I call it my billion-dollar mistake. It was the invention of the null reference in 1965.
+> At that time, I was designing the first comprehensive type system for references
+> in an object oriented language (ALGOL W).
+> My goal was to ensure that all use of references should be absolutely safe,
+> with checking performed automatically by the compiler.
+> But I couldn't resist the temptation to put in a null reference,
+> simply because it was so easy to implement.
+> This has led to innumerable errors, vulnerabilities, and system crashes,
+> which have probably caused a billion dollars of pain and damage in the last forty years.
+>
+> -- [Sir Tony Hoare](https://en.wikipedia.org/wiki/Tony_Hoare)
+
+
+Let's make the code safer and
+let's say goodbye to null / nil (and maybe).
+How can the code work without nil?
+
+
+Let's say hello to zero.
+The new rule for NO null/nil ever (again) is:
+
+**All variables - including structs, arrays and hash mappings -
+MUST ALWAYS get set (initialized) to ZERO (default) values.**
+
+What's zero?
+
+| Type           | Value                      |
+|----------------|----------------------------|
+| Integer        | `0`      or `Integer.zero` |
+| Bool           | `false`  or `Bool.zero`    |
+| String         | `''` or `String.zero`      |
+| Array          | `[]` or `Array.zero`       |
+| Hash           | `{}` or `Hash.zero`        |
+| Vote (Struct)  | `Vote.new( 0, false, 0, '0x0000')` or `Vote.zero`  |
+| Address        | `0x0000` or `Address.zero` or `Address(0)`         |
+| ...            |                                                    |
+
+
+### Safe Struct
+
+Let's you define (auto-build) new struct classes.
+Example:
+
+``` ruby
+Voter = SafeStruct.new( weight: 0, voted: false, vote: 0, delegate: '0x0000' )
+
+voter1 = Voter.new    # or Voter.new_zero
+voter1.weight      #=> 0
+voter1.voted?      #=> false
+voter1.vote        #=> 0
+voter1.delegate    #=> '0x0000'
+voter1.frozen?     #=> false
+
+voter1 == Voter.zero    #=> true
+
+voter1.delegate = '0x1111'
+voter1 == Voter.zero    #=> false
+
+voter2 = Voter.new( 0, false, 0, '0x0000')  
+
+voter2.voted    = true
+voter2.delegate = '0x2222'
+voter2 == Voter.zero     #=> false
+
+Voter.zero.frozen?       #=> true
+
+voter3 = Voter.new( 0 )  #=> ArgumentError - wrong number of arguments
+                         #     for Voter.new - 1 for 4
+```
+
+
+Note: You can use `Struct` as an alias for `SafeStruct`
+(in the `Safe` namespace / module context).
+
+
+### Safe Array
+
+Let's you define (auto-build) new (type safe) array classes.
+Example:
+
+``` ruby
+ArrayInteger = SafeArray.build_class( Integer )
+ary = ArrayInteger.new
+ary.size       #=> 0
+ary[0]         #=> IndexError
+ary.size = 2   #=> [0,0]
+ary[0]         #=> 0
+```
+
+or use the `Array.of` convenience shortcut:
+
+``` ruby
+ary = Array.of( Integer )
+ary.size       #=> 0
+ary[0]         #=> IndexError
+ary.size = 2   #=> [0, 0]
+ary[0]         #=> 0
+
+## or
+
+another_ary = Array.of( Bool )
+another_ary.size      #=> 0
+another_ary[0]        #=> IndexError
+another_ary.size = 2  #=> [false, false]
+another_ary[0]        #=> false
+
+## or
+
+another_ary = Array.of( Bool, 2 )
+another_ary.size      #=> 2
+another_ary[0]        #=> false
+```
+
+Yes, Safe Array works with structs (or nested arrays or hash mappings) too. Example:
+
+``` ruby
+ary = Array.of( Vote )
+
+ary[0]         #=> IndexError
+ary.size = 2   #=> [#<Vote @weight=0, @voted=false, @vote=0, @delegate='0x0000'>,
+               #    #<Vote @weight=0, @voted=false, @vote=0, @delegate='0x0000'>]
+ary[0]         #=> #<Vote @weight=0, @voted=false, @vote=0, @delegate='0x0000'>
+ary[0].voted?  #=> false
+```
+
+
+### Safe Hash
+
+Let's you define (auto-build) new (type safe) hash classes.
+Example:
+
+``` ruby
+Hash_X_Integer = SafeHash.build_class( String, Integer )
+hash = Hash_X_Integer.new
+
+hash['0x0000']  #=> 0
+```
+
+or use the `Hash.of` convenience shortcut:
+
+``` ruby
+hash = Hash.of( String => Integer )
+
+hash['0x0000']         #=> 0
+hash['0x0000'] += 42
+hash['0x0000']         #=> 42
+```
+
+Note: Safe Hash will ALWAYS return a value.
+If the key is missing in the hash mapping on lookup,
+the key gets auto-added with a zero value.
+Use `has_key?` or `key?` to check if a key is present.
+
+
+Yes, Safe Hash works with structs (or arrays or nested hash mappings) too. Example:
+
+``` ruby
+hash = Hash.of( String => Vote )
+
+hash['0x0000']                #=> #<Vote @weight=0, @voted=false, @vote=0, @delegate='0x0000'>
+hash['0x0000'].voted?         #=> false
+hash['0x0000'].voted = true
+hash['0x0000'].voted?         #=> true
+```
+
+
+
+
+## More "Real World" Safe Data Structures (Array, Hash, Struct) Samples
+
+- [The "Red Paper" about sruby](https://github.com/s6ruby/redpaper) - Small, Smart, Secure, Safe, Solid & Sound (S6) Ruby - The Ruby Programming Language for Contract / Transaction Scripts on the Blockchain World Computer - Yes, It's Just Ruby
+- [Programming Crypto Blockchain Contracts Step-by-Step Book / Guide](https://github.com/s6ruby/programming-cryptocontracts). Let's Start with Ponzi & Pyramid Schemes. Run Your Own Lotteries, Gambling Casinos and more on the Blockchain World Computer...
+- [Ruby Sample Contracts for the Universum Blockchain/World Computer Runtime](https://github.com/s6ruby/universum-contracts)
+
 
 
 ## License
 
+![](https://publicdomainworks.github.io/buttons/zero88x31.png)
+
 The `safestruct` scripts are dedicated to the public domain.
 Use it as you please with no restrictions whatsoever.
 

data/lib/safestruct.rb

@@ -28,7 +28,7 @@ end
 #####
 # add "beautiful" convenience helpers
 
-class Mapping
+class Hash
 
   def self.of( *args )
      ## e.g. gets passed in [{Address=>Integer}]
@@ -38,7 +38,7 @@ class Mapping
        arg = args[0].to_a   ## convert to array (for easier access)
        klass_key   = arg[0][0]
        klass_value = arg[0][1]
-       klass = SafeHash.build_class( klass_key, klass_value )
+       klass = Safe::SafeHash.build_class( klass_key, klass_value )
        klass.new
      else
        ## todo/fix: throw argument error/exception
@@ -52,17 +52,16 @@ class Array
   ## "typed" safe array "constructor"
   ## e.g.  Array.of( Address ) or Array.of( Money ) or Array.of( Proposal, size: 2 ) etc.
   def self.of( klass_value )
-    klass = SafeArray.build_class( klass_value )
+    klass = Safe::SafeArray.build_class( klass_value )
     klass.new  ## todo: add klass.new( **kwargs ) for size: 2 etc.
   end
 end
 
-
-############################
-# note: HACK redefine built in struct
-#  => warning: already initialized constant Struct
-OldStruct = Struct        ## save old struct class
-Struct    = SafeStruct
-
+module Safe
+  ############################
+  # note: HACK redefine built in struct in module Safe "context"
+  ClassicStruct = ::Struct        ## save old classic struct class
+  Struct        = SafeStruct
+end
 
 puts Safe.banner    ## say hello

data/lib/safestruct/safe_array.rb

@@ -1,5 +1,7 @@
 # encoding: utf-8
 
+module Safe
+
 class SafeArray
 
   ## e.g.
@@ -67,3 +69,4 @@ RUBY
   def size() @ary.size; end
   def length() size; end
 end # class SafeArray
+end # module Safe

data/lib/safestruct/safe_hash.rb

@@ -1,12 +1,13 @@
 # encoding: utf-8
 
+module Safe
 
 class SafeHash
 
   ## e.g.
-  ##  Mapping.of( Address => Money )
+  ##  Hash.of( Address => Money )
 
-  ##   note: need to create new class!! for every mapping
+  ##   note: need to create new class!! for every safe hash
   ##     make klass_key class and
   ##          klass_value class  into class instance variables
   ##     that can get used by zero
@@ -75,3 +76,4 @@ RUBY
   def size() @h.size; end
   def length() size; end
 end # class SafeHash
+end # module Safe

data/lib/safestruct/safe_struct.rb

@@ -1,5 +1,7 @@
 # encoding: utf-8
 
+module Safe
+
 class SafeStruct
 
 def self.build_class( **attributes )
@@ -36,11 +38,15 @@ def self.build_class( **attributes )
 
   ## add self.new too - note: call/forward to "old" orginal self.new of Event (base) class
   klass.define_singleton_method( :new ) do |*args|
-    if args.size != attributes.size
-      ## check for required args/params - all MUST be passed in!!!
-      raise ArgumentError.new( "[SafeStruct] wrong number of arguments for #{name}.new - #{args.size} for #{attributes.size}" )
+    if args.empty?  ## no args - use new_zero and set (initialize) all ivars to zero
+      new_zero
+    else
+      if args.size != attributes.size
+        ## check for required args/params - all MUST be passed in!!!
+        raise ArgumentError.new( "[SafeStruct] wrong number of arguments for #{name}.new - #{args.size} for #{attributes.size}" )
+      end
+      old_new( *args )
     end
-    old_new( *args )
   end
 
   klass.define_singleton_method( :new_zero ) do
@@ -77,3 +83,4 @@ def self.zero
   @zero ||= new_zero.freeze
 end
 end # class SafeStruct
+end # module Safe

data/lib/safestruct/version.rb

@@ -4,7 +4,7 @@
 module Safe
 
   MAJOR = 0
-  MINOR = 1
+  MINOR = 2
   PATCH = 0
   VERSION = [MAJOR,MINOR,PATCH].join('.')
 

data/test/test_array.rb

@@ -10,6 +10,8 @@ require 'helper'
 
 class TestArray < MiniTest::Test
 
+  include Safe
+
   Array_Integer = SafeArray.build_class( Integer )
   Array_Bool    = SafeArray.build_class( Bool )
 

data/test/test_hash.rb

@@ -10,6 +10,8 @@ require 'helper'
 
 class TestHash < MiniTest::Test
 
+  include Safe
+
   ## sig: [Integer, Bool, Integer, Address]
   Voter = SafeStruct.new( weight: 0, voted: false, vote: 0, delegate: '0x0000' )
 
@@ -30,8 +32,8 @@ def test_integer
   assert_equal 101,  h['0x1111']
   assert_equal 102,  h['0x2222']
 
-  ## check Mapping.of  (uses cached classes)
-  assert_equal Hash_X_Integer, Mapping.of( String => Integer ).class
+  ## check Hash.of  (uses cached classes)
+  assert_equal Hash_X_Integer, Hash.of( String => Integer ).class
 end
 
 
@@ -48,8 +50,8 @@ def test_bool
   assert_equal true,  h['0x1111']
   assert_equal true,  h['0x2222']
 
-  ## check Mapping.of  (uses cached classes)
-  assert_equal Hash_X_Bool, Mapping.of( String => Bool ).class
+  ## check Hash.of  (uses cached classes)
+  assert_equal Hash_X_Bool, Hash.of( String => Bool ).class
 end
 
 
@@ -69,8 +71,8 @@ def test_voter
   pp h['0x1111']
   pp h['0x2222']
 
-  ## check Mapping.of  (uses cached classes)
-  assert_equal Hash_X_Voter, Mapping.of( String => Voter ).class
+  ## check Hash.of  (uses cached classes)
+  assert_equal Hash_X_Voter, Hash.of( String => Voter ).class
 end
 
 

data/test/test_struct.rb

@@ -10,6 +10,8 @@ require 'helper'
 
 class TestStruct < MiniTest::Test
 
+include Safe
+
 ## sig: [Integer, Bool, Integer, Address]
 Voter = SafeStruct.new( weight: 0, voted: false, vote: 0, delegate: '0x0000' )
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: safestruct
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Gerald Bauer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-02-14 00:00:00.000000000 Z
+date: 2019-02-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rdoc