records 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a634c1c166a9375df4d42da8a5b0c4e0fe63a0c7
-  data.tar.gz: aedd9d2c2d0ba064d6fd7292dc6456bd35981c74
+  metadata.gz: 13d06e265fb13c8800ea2c98f699a839bef77a8e
+  data.tar.gz: 530dcd1156f9e7146bb3ff157db9159f4aa8d72d
 SHA512:
-  metadata.gz: 36b9c96f91005b5b94ba48ef22d6e7f73fa3276206c03c3238d27a6377241434d16a16225b00b95c68844f93327b1000be8b47cc44c907f35200dd5c23780437
-  data.tar.gz: a13e7eabfc946b8a3db5c3a070d6bb1df9579de67c5be4cb78e1fb5165bcb2014d51641f7c0e6a5a9157d9e1974f00cf1887728edb0d12baa4b23253a48bc101
+  metadata.gz: eafaa2aa7bdcb10b0d4138337e11157d5afc035569d4829c81dadac1f1e20a2c08801f8811208f0e9108c3b531a1d0af436ac2aea49a56fc9c21821406c703ea
+  data.tar.gz: e7ae023c0bf8dbdf08b85472e7eb64145973e4a79662d8b4c03c51ce2e4179066613f67e0291acf40062c5df98afe263c4d3052b84d5a34b64ddcf86d0f0ee2d

data/Manifest.txt

@@ -4,6 +4,7 @@ Manifest.txt
 README.md
 Rakefile
 lib/records.rb
+lib/records/record.rb
 lib/records/version.rb
 test/helper.rb
 test/test_account.rb

data/README.md

@@ -1,7 +1,7 @@
 
 # Records - Frozen / Immutable Structs with Copy on Updates
 
-records gem / library - frozen / immutable (frozen) structs with copy on updates
+records gem / library - frozen / immutable structs with copy on updates
 
 
 * home  :: [github.com/s6ruby/records](https://github.com/s6ruby/records)
@@ -12,7 +12,94 @@ records gem / library - frozen / immutable (frozen) structs with copy on updates
 
 ## Usage
 
-To be done
+Use `Record.new` like `Struct.new` to build / create a new frozen / immutable
+record class. Example:
+
+``` ruby
+
+Record.new( :Account,
+              balance:    Integer,
+              allowances: Hash )
+
+# -or-
+
+Record.new :Account,
+              balance:    Integer,
+              allowances: Hash
+
+# -or-
+
+Record.new :Account, { balance:    Integer,
+                       allowances: Hash }
+
+# -or-
+
+class Account < Record::Base
+  field :balance,    Integer
+  field :allowances, Hash
+end
+```
+
+
+And use the new record class like:
+
+``` ruby
+account1a  = Account.new( 1, {} )
+account1a.frozen?            #=> true
+account1a.values.frozen?     #=> true
+account1a.balance            #=> 1
+account1a.allowances         #=> {}
+account1a.values             #=> [1, {}]
+
+Account.keys                 #=> [:balance, :allowances]
+Account.fields               #=> [<Field @key=:balance, @index=0, @type=Integer>,
+                             #    <Field @key=:allowances, @index=1, @type=Hash>]
+Account.index( :balance )    #=> 0
+Account.index( :allowances ) #=> 1
+```
+
+Note: The `update` method (or the `<<` alias)
+ALWAYS returns a new record.
+
+``` ruby
+account1a.update( balance: 20 )     #=> [20, {}]
+account1a.update( balance: 30 )     #=> [30, {}]
+account1a.update( { balance: 30 } ) #=> [30, {}]
+
+account1a << { balance: 20 }        #=> [20, {}]
+account1a << { balance: 30 }        #=> [30, {}]
+
+account1b = account1a.update( balance: 40, allowances: { 'Alice': 20 } )
+account1b.balance                   #=> 40
+account1b.allowances                #=> { 'Alice': 20 }
+account1b.values                    #=> [40, { 'Alice': 20 } ]
+# ...
+```
+
+And so on and so forth.
+
+
+## Bonus - Record Update Language Syntax Pragmas - `{...}` and `={...}`
+
+Using the Record Update Pragma. Lets you
+
+``` ruby
+account1a {... balance: 20 }     #=> [20, {}]
+account1a {... balance: 30 }     #=> [30, {}]
+
+account1a = {... balance: 40, allowances: { 'Alice': 20 }}
+```
+
+turn into:
+
+``` ruby
+account1a.update( balance: 20 )     #=> [20, {}]
+account1a.update( balance: 30 )     #=> [30, {}]
+
+account1a = account1a.update( balance: 40, allowances: { 'Alice': 20 } )
+```
+
+See [Language Syntax Pragmas - Let's Evolve Ruby by Experimenting in a Pragma(tic) Way](https://github.com/s6ruby/pragmas) for more.
 
 
 ## License

data/Rakefile

@@ -5,7 +5,7 @@ Hoe.spec 'records' do
 
   self.version = Records::VERSION
 
-  self.summary = "records gem / library - frozen / immutable (frozen) structs with copy on updates"
+  self.summary = "records - frozen / immutable structs with copy on updates"
   self.description = summary
 
   self.urls    = ['https://github.com/s6ruby/records']

data/lib/records.rb

@@ -4,7 +4,7 @@ require 'pp'
 
 ## our own code
 require 'records/version'    # note: let version always go first
-
+require 'records/record'
 
 
 

data/lib/records/record.rb

@@ -0,0 +1,132 @@
+# encoding: utf-8
+
+
+
+class Record
+
+class Type; end
+Types = Type   # note Types is an alias for Type
+
+
+
+class Field
+  attr_reader :key, :type
+  attr_reader :index       ## note: zero-based position index (0,1,2,3,...)
+
+  def initialize( key, index, type )
+    @key    = key.to_sym  ## note: always symbol-ify (to_sym) key
+    @index  = index
+    @type   = type
+  end
+end  # class Field
+
+
+
+class Base < Record
+
+  def self.fields   ## note: use class instance variable (@fields and NOT @@fields)!!!! (derived classes get its own copy!!!)
+    @fields ||= []
+  end
+
+  def self.keys
+    @keys ||= fields.map {|field| field.key }.freeze
+  end
+
+  def self.index( key )   ## indef of key (0,1,2,etc.)
+    ## note: returns nil now for unknown keys
+    ##   use/raise IndexError or something - why? why not?
+    @index_by_key ||= Hash[ keys.zip( (0...fields.size).to_a ) ].freeze
+    @index_by_key[key]
+  end
+
+
+
+  def self.field( key, type )
+    index = fields.size  ## auto-calc num(ber) / position index - always gets added at the end
+    field = Field.new( key, index, type )
+    fields << field
+
+    define_field( field )  ## auto-add getter,setter,parse/typecast
+  end
+
+  def self.define_field( field )
+    key    = field.key   ## note: always assumes a "cleaned-up" (symbol) name
+    index  = field.index
+
+    define_method( key ) do
+      instance_variable_get( "@values" )[index]
+    end
+  end
+
+  ## note: "skip" overloaded new Record.new (and use old_new version)
+  def self.new( *args ) old_new( *args ); end
+
+
+
+  attr_reader :values
+
+  def initialize( *args )
+    #####
+    ##  todo/fix: add allow keyword init too
+    ###  note:
+    ###  if init( 1, {} )  assumes last {} is a kwargs!!!!!
+    ##                     and NOT a "plain" arg in args!!!
+
+    ## puts "[#{self.class.name}] Record::Base.initialize:"
+    ## pp args
+
+    ##
+    ##  fix/todo: check that number of args are equal fields.size !!!
+    ##            check types too :-)
+
+    @values = args
+    @values.freeze
+    self.freeze     ## freeze self too - why? why not?
+    self
+  end
+
+
+  def update( **kwargs )
+    new_values = @values.dup   ## note: use dup NOT clone (will "undo" frozen state?)
+    kwargs.each do |key,value|
+        index = self.class.index( key )
+        new_values[ index ] = value
+    end
+    self.class.new( *new_values )
+  end
+
+  ## "convenience" shortcut for update e.g.
+  ##    << { balance: 5 }
+  ##         equals
+  ##    .update( balance: 5 )
+  def <<( hash )  update( hash ); end
+
+
+  ###
+  ##  note: compare by value for now (and NOT object id)
+  def ==(other)
+    if other.instance_of?( self.class )
+      values == other.values
+    else
+      false
+    end
+  end
+  alias_method :eql?, :==
+
+end # class Base
+
+
+  def self.build_class( class_name, **attributes )
+    klass = Class.new( Base )
+    attributes.each do |key, type|
+       klass.field( key, type )
+    end
+
+    Type.const_set( class_name, klass )   ## returns klass (plus sets global constant class name)
+  end
+
+  class << self
+    alias_method :old_new, :new       # note: store "old" orginal version of new
+    alias_method :new,     :build_class    # replace original version with create
+  end
+end # class Record

data/lib/records/version.rb

@@ -8,9 +8,9 @@
 
 module Records
 
-  MAJOR = 0
+  MAJOR = 1
   MINOR = 0
-  PATCH = 1
+  PATCH = 0
   VERSION = [MAJOR,MINOR,PATCH].join('.')
 
   def self.version

data/test/test_account.rb

@@ -10,4 +10,111 @@ require 'helper'
 
 class TestAccount < MiniTest::Test
 
+  Record.build_class( :Account,
+                      balance:    Integer,
+                      allowances: Hash )
+  Account = Record::Type::Account
+
+
+  Record.new( :Account2,
+                 balance:    Integer,
+                 allowances: Hash )
+  Account2 = Record::Type::Account2
+
+
+  class Account3 < Record::Base
+    field :balance,    Integer
+    field :allowances, Hash
+  end
+
+
+
+  def test_account
+    pp Record::Type::Account
+    pp Account.ancestors
+
+    puts "Record::Type.constants:"
+    pp Record::Type.constants
+
+    account1a  = Account.new( 1, {} )
+    assert_equal Account.new( 1, {} ), account1a
+    assert_equal true,     account1a.frozen?
+    assert_equal true,     account1a.values.frozen?
+    assert_equal 1,        account1a.balance
+    assert_equal Hash({}), account1a.allowances
+
+
+    assert_equal Account.new( 20, {} ), account1a.update( balance: 20 )
+    assert_equal Account.new( 30, {} ), account1a.update( balance: 30 )
+    assert_equal Account.new( 30, {} ), account1a.update( { balance: 30 } )
+
+    assert_equal Account.new( 20, {} ), account1a << { balance: 20 }
+    assert_equal Account.new( 30, {} ), account1a << { balance: 30 }
+    assert_equal Account.new( 30, {} ), account1a << Hash( { balance: 30 } )
+  end
+
+
+  def test_account2
+    pp Record::Type::Account2
+    pp Account2.ancestors
+
+    puts "Record::Type.constants:"
+    pp Record::Type.constants
+
+    assert_equal [:balance, :allowances], Account2.keys
+    # assert_equal [Record::Field.new( :balance,    0, Integer),
+    #              Record::Field.new( :allowances, 1, Hash )
+    #             ], Account2.fields
+
+    assert_equal 0, Account2.index( :balance )
+    assert_equal 1, Account2.index( :allowances )
+
+    account1a  = Account2.new( 1, {} )
+    assert_equal Account2.new( 1, {} ), account1a
+    assert_equal [1, {}],               account1a.values
+
+    assert_equal Account2.new( 20, {} ), account1a.update( balance: 20 )
+    assert_equal Account2.new( 30, {} ), account1a.update( balance: 30 )
+    assert_equal [20, {}],               account1a.update( balance: 20 ).values
+    assert_equal [30, {}],               account1a.update( balance: 30 ).values
+
+
+    account1b =  account1a.update( balance: 10, allowances: { '0xaa': 20 } )
+    assert_equal Account2.new( 10, { '0xaa': 20 } ), account1b
+    assert_equal Hash({ '0xaa': 20 }),               account1b.allowances
+  end
+
+
+  def test_account3
+    pp Account3
+    pp Account3.ancestors
+
+    puts "Record::Type.constants:"
+    pp Record::Type.constants
+
+    account1a  = Account3.new( 1, {} )
+    assert_equal Account3.new( 1, {} ), account1a
+    assert_equal true, account1a.is_a?( Record )
+    assert_equal true, account1a.is_a?( Record::Base )
+
+
+    assert_equal Account3.new( 20, {} ), account1a.update( balance: 20 )
+    assert_equal Account3.new( 30, {} ), account1a.update( balance: 30 )
+    assert_equal [30, {}],               account1a.update( balance: 30 ).values
+
+    account1b =  account1a.update( balance: 10 )
+    assert_equal Account3.new( 10, {} ), account1b
+    assert_equal 10,                      account1b.balance
+    assert_equal Hash({}),                account1b.allowances
+    assert_equal [10, {}],                account1b.values
+
+    account1b =  account1a.update( balance: 10, allowances: { '0xaa': 20 } )
+    assert_equal Hash({'0xaa': 20 }),      account1b.allowances
+    assert_equal [10, {'0xaa': 20 }],      account1b.values
+
+    account2 = Account3.new( 2, {} )
+    assert_equal Account3.new( 2, {} ), account2
+    assert_equal [2, {}], account2.values
+  end
+
 end  # class TestAccount

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: records
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Gerald Bauer
@@ -38,8 +38,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.16'
-description: records gem / library - frozen / immutable (frozen) structs with copy
-  on updates
+description: records - frozen / immutable structs with copy on updates
 email: wwwmake@googlegroups.com
 executables: []
 extensions: []
@@ -55,6 +54,7 @@ files:
 - README.md
 - Rakefile
 - lib/records.rb
+- lib/records/record.rb
 - lib/records/version.rb
 - test/helper.rb
 - test/test_account.rb
@@ -83,6 +83,5 @@ rubyforge_project:
 rubygems_version: 2.5.2
 signing_key: 
 specification_version: 4
-summary: records gem / library - frozen / immutable (frozen) structs with copy on
-  updates
+summary: records - frozen / immutable structs with copy on updates
 test_files: []