add record

Author: geraldb

README.md

@@ -26,6 +26,11 @@ Gems:
 - [date-formatter](date-formatter) - date formatter by example; auto-builds the strftime format string from an example date
 
 
+<!-- break -->
+- [records](records) -  frozen / immutable structs with copy on updates
+
+
+
 <!-- break -->
 - [shell-lite](shell-lite) - run / execute shell commands
 

records/.gitignore

@@ -0,0 +1,35 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc

records/CHANGELOG.md

@@ -0,0 +1,3 @@
+### 0.0.1 / 2019-04-13
+
+* Everything is new. First release

records/Manifest.txt

@@ -0,0 +1,9 @@
+CHANGELOG.md
+Manifest.txt
+README.md
+Rakefile
+lib/records.rb
+lib/records/record.rb
+lib/records/version.rb
+test/helper.rb
+test/test_account.rb

records/README.md

@@ -0,0 +1,116 @@
+
+# Records - Frozen / Immutable 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)
+* bugs  :: [github.com/s6ruby/records/issues](https://github.com/s6ruby/records/issues)
+* gem   :: [rubygems.org/gems/records](https://rubygems.org/gems/records)
+* rdoc  :: [rubydoc.info/gems/records](http://rubydoc.info/gems/records)
+
+
+## Usage
+
+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
+account  = Account.new( 1, {} )
+account.frozen?            #=> true
+account.values.frozen?     #=> true
+account.balance            #=> 1
+account.allowances         #=> {}
+account.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
+account.update( balance: 20 )     #=> [20, {}]
+account.update( balance: 30 )     #=> [30, {}]
+account.update( { balance: 30 } ) #=> [30, {}]
+
+account << { balance: 20 }        #=> [20, {}]
+account << { balance: 30 }        #=> [30, {}]
+
+account = account.update( balance: 40, allowances: { 'Alice': 20 } )
+account.balance                   #=> 40
+account.allowances                #=> { 'Alice': 20 }
+account.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
+account {... balance: 20 }     #=> [20, {}]
+account {... balance: 30 }     #=> [30, {}]
+
+account = {... balance: 40, allowances: { 'Alice': 20 }}
+```
+
+turn into:
+
+``` ruby
+account.update( balance: 20 )     #=> [20, {}]
+account.update( balance: 30 )     #=> [30, {}]
+
+account = account.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
+
+![](https://publicdomainworks.github.io/buttons/zero88x31.png)
+
+The `records` scripts are dedicated to the public domain.
+Use it as you please with no restrictions whatsoever.
+
+
+## Questions? Comments?
+
+Send them along to the [wwwmake forum](http://groups.google.com/group/wwwmake).
+Thanks!

records/Rakefile

@@ -0,0 +1,29 @@
+require 'hoe'
+require './lib/records/version.rb'
+
+Hoe.spec 'records' do
+
+  self.version = Records::VERSION
+
+  self.summary = "records - frozen / immutable structs with copy on updates"
+  self.description = summary
+
+  self.urls    = ['https://github.com/s6ruby/records']
+
+  self.author  = 'Gerald Bauer'
+  self.email   = '[email protected]'
+
+  # switch extension to .markdown for gihub formatting
+  self.readme_file  = 'README.md'
+  self.history_file = 'CHANGELOG.md'
+
+  self.extra_deps = [
+  ]
+
+  self.licenses = ['Public Domain']
+
+  self.spec_extras = {
+    required_ruby_version: '>= 2.2.2'
+  }
+
+end

records/lib/records.rb

@@ -0,0 +1,11 @@
+# encoding: utf-8
+
+require 'pp'
+
+## our own code
+require 'records/version'    # note: let version always go first
+require 'records/record'
+
+
+
+puts Records.banner    ## say hello

records/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

records/lib/records/version.rb

@@ -0,0 +1,28 @@
+# encoding: utf-8
+
+
+###
+# note: do not "pollute" Record namespace / module
+#  use its own module
+
+
+module Records
+
+  MAJOR = 1
+  MINOR = 0
+  PATCH = 0
+  VERSION = [MAJOR,MINOR,PATCH].join('.')
+
+  def self.version
+    VERSION
+  end
+
+  def self.banner
+    "records/#{VERSION} on Ruby #{RUBY_VERSION} (#{RUBY_RELEASE_DATE}) [#{RUBY_PLATFORM}]"
+  end
+
+  def self.root
+    "#{File.expand_path( File.dirname(File.dirname(File.dirname(__FILE__))) )}"
+  end
+
+end # module Records

records/test/helper.rb

@@ -0,0 +1,8 @@
+## minitest setup
+
+require 'minitest/autorun'
+
+
+## our own code
+
+require 'records'