striuct 0.0.11.1 → 0.1.7

data/README.rdoc

@@ -6,56 +6,63 @@
 
 == DESCRIPTION
 
-Striuct means Strict Struct.
-Handy and safty than Ruby's Standard Struct.
+Striuct = (YetAnotherStruct << safety << useful)
 
 == FEATURES
-* Provides automated checking for your setters.
 * When you link a object, Striuct checks "They are valid objects?".
-  These checkers are not only Type Checker. They judge under your expressions.
-* when use "inference", member will be fixed first passed object's class
-* After check, you can add one-step before link a object (call "flavor" at here).
-* You will be set default-value, and we have different meanings between nil and default-value.
-* without undesirable naming for conflict, no-identifier, and more cases
-* Base API looks like Ruby's standard Struct
-* not taint your name-space(exclude striuct/import)
-* pure-ruby
+  These checkers don't depend only types(class).
+  
+  The safety is made from your expressions.
+* When use "inference", member will be fixed under class of first passed object.
+* It is without undesirable naming of conflict, no-identifier and some cases.
+* You can add a step just before link a object. (named "flavor" at here)
+* You can use default-value, and we have different meanings between nil and default-value.
+* It is easy to alias member name.
+* You can use inherite of structual class. 
+* Base API looks like Struct.
+* No taint your name-space.
+* Pure Ruby
 
 == SYNOPSIS
 
 * setup
     require 'striuct'
 
-* Macro "member" provides one of Struct+ interface.
-  It checks under conditions when change to link other.
+* use two namespace (same meanings)
+    Striuct
+    StrictStruct
+
+=== Struct+ "Safety"
+
+==== "member" macro
+
+* Use "member" and you get a accessor, it looks Struct with tester(validator)s. 
     class User < Striuct.new
-      member :id, Integer
-      member :address, /\A((\w+) ?)+\z/
-      member :age, (20..140)
-      member :name, /\A\w+\z/, /\A\w+ \w+\z/
+      member :id,   Integer
+      member :age,  (20..140)
+      member :name, OR(/\A\w+\z/, /\A\w+ \w+\z/)
     end
 
     # pass
-    user = User.new 128381, 'Tokyo Japan', 20
+    user = User.new 128381, 20
 
     # pass
     user.age = 30
-    user.name = 'taro yamada'
+    user[2] = 'foo bar'
 
     # fail
     user[:id] = 10.0
-    user[1] = 'Tokyo-to'
     user.age = 19
-    user.name = nil
+    user[2] = nil
 
-* more detail checker do you need, you can use functional object here.
+* Use functional object and you get a tester on upstairs.
     module Game
       class Character
       end
 
       class DB < Striuct.new
-        member :monsters, ->monsters{(monsters - characters).empty?}
-        member :characters, ->characters{characters.all?{|c|c.kind_of? Character}}
+        member :monsters,   ->list{(list - characters).empty?}
+        member :characters, GENERICS(Character)
       end
       
       monster = Character.new
@@ -68,16 +75,16 @@ Handy and safty than Ruby's Standard Struct.
       db.characters = [monster, Character.new]
       
       # fail
-      db.monsters = [:dummy]
+      db.monsters = [Character.new]
       
       # pass
       db.monsters = [monster]
     end
 
-* "inference", check under first passed object's class
+* Use "inference" and all instance test under class of first passed object.
     class FlexibleContainer < Striuct.new
       member :anything, inference
-      member :number, inference, Numeric
+      member :number, Numeric, inference
     end
 
     fc1, fc2 = FlexibleContainer.new, FlexibleContainer.new
@@ -100,7 +107,50 @@ Handy and safty than Ruby's Standard Struct.
     # fail
     fc2.number = 1
 
-* with flavor for type cast
+==== Protect from risks in naming members
+
+* Standard Struct dosen't check member-name. 
+    NoGuard = Struct.new :object_id, :'?  !'
+    noguard = NoGuard.new false
+    noguard.object_id #=> false
+    noguard.methods.include?(:'?  !') #=> false(lost!!)
+
+* Striuct provides safety levels for this. (default: :prevent)
+    class SafetyNaming < Striuct.new
+      begin
+        member :object_id
+      rescue
+        p $!
+      end
+      
+      begin
+        member :'?  !'
+      rescue
+        p $!
+      end
+      
+      # set lower
+      protect_level :struct
+      
+      member :object_id, :'?  !'
+    end
+
+==== Support utils
+
+* valid? / acccept? / sufficient?   # can set a argument to a member 
+* conditionable?           # can set a condition for any members
+* inference?               # inference member and no passed any object
+* restrict?                # has any conditions for a member
+* strict?                  # now, all members are passed any conditions
+* secure?                  # instance and class are fixed and strict 
+* cname?                   # can use member name under protect level
+
+=== Struct+ "Handy"
+
+==== Flavor
+
+* Block with member macro, it is called "flavor" at here.
+  Below cases for type cast.
     class User2 < Striuct.new
       member :age, /\A\d+\z/, Numeric do |arg|
         Integer arg
@@ -117,13 +167,11 @@ Handy and safty than Ruby's Standard Struct.
     user2.age = '10' #=> 10(Fixnum)
 
     user2.name = 10 #=> :10(Symbol)
+    user2.name = Class #=> :Class(Symbol)
 
-* but, linked objects are able to clash
-    user.strict? #=> true
-    user.address.clear
-    user.strict? #=> false
+==== Default
 
-* use default value
+* provides default value
     class User3 < Striuct.new
       member  :lank, Fixnum
       default :lank, 3
@@ -133,62 +181,71 @@ Handy and safty than Ruby's Standard Struct.
     user3 = User3.new
     user3.lank #=> 3
     
-* Standard Struct always define "nil is default". ...realy?
-   user3.name  #=> nil
-   user3.assign? :name #=> false
-   user3.name = nil
-   user3.assign? :name #=> true
-
-* Standard Struct no check member name. 
-    NoGuard = Struct.new :__send__, :'?  !'
-    noguard = NoGuard.new false
-    p noguard.__send__
-    p noguard.methods.include?(:'?  !') # lost!!
+* Standard Struct always define "nil is default". Realy?
+    user3.name  #=> nil
+    user3.assign? :name #=> false
+    user3.name = nil
+    user3.assign? :name #=> true
 
-* Striuct provides safety levels for naming.
-    class SafetyNaming < Striuct.new
-      begin
-        member :__send__
-      rescue
-        p $!
-      end
-      
-      begin
-        member :'?  !'
-      rescue
-        p $!
-      end
-      
-      protect_level :struct
-      
-      member :__send__, :'?  !'
+==== Alias
+
+* alias member name
+    class User3
+      alias_member :position, :lank
     end
+    
+    user3.lank.equal? user3.position #=> true
+    user3[:lank].equal? user3[:position] #=> true
+    user3[:position] = 4
+    user3.lank  #=> 4
+
+==== Inherit
+
+* (writing...)
+
+==== Lock
 
+* (writing...)
 
-* Of course, keeping Struct's good interface
-    Sth1 = Striuct.new :id, :last_name, :family_name, :address, :age
+==== New Constructors
 
-    Sth2 = Striuct.new do
+* Subclass.define reject floating object.
+  * block parameter is new instance
+  * except if no finished to assign each member
+  * returning object is tested strict(optional)
+  * returning object is locked(optional)
+      user3 = User3.define do |r|
+        r.lank = 10
+        r.name = 'foo'
+      end
+
+* Subclass.[](load_pairs) make from Hash and like Hash
+    user3 = User3[lank: 10, name: 'foo']
+
+=== Almost interfaces are keeping Struct has.
+
+    Sth1 = Striuct.new do
       def my_special_method
       end
     end
     
-    Sth2.new.respond_to?(:my_special_method) #=> true
+    Sth1.new.respond_to?(:my_special_method) #=> true
+
+=== HashLike
+
+* some interfaces import from Hash
 
-* Here, not taint your name-space. but enhancers are too, you can choose it.
-    require 'striuct/import'
+* easy cast to Hash
+    user3.to_h #=> {:lank=>3, :name=>nil}
 
-* run example.rb
 
-* EasyGuide (in Japanese)
-  https://github.com/kachick/striuct/wiki/EasyGuide
+== Note
 
+* Documents are poor
 
 == REQUIREMENTS
 
-=== Ruby
-* 1.9.3
-* 1.9.2
+* Ruby 1.9.2 and later (tested 1.9.2, 1.9.3)
 
 == INSTALL
 

data/Rakefile

@@ -1,5 +1,5 @@
 require 'rubygems'
-gem 'hoe', '>= 2.12.4'
+gem 'hoe', '~> 2.13.0'
 require 'hoe'
 require 'fileutils'
 
@@ -10,8 +10,10 @@ Hoe.plugin :newgem
 # Generate all the Rake tasks
 # Run 'rake -T' to see list of generated tasks (from gem root directory)
 $hoe = Hoe.spec 'striuct' do
-  self.developer 'Kenichi Kamiya', 'kachick1+ruby@gmail.com'
-  self.rubyforge_name       = self.name # TODO this is default value
+  developer 'Kenichi Kamiya', 'kachick1+ruby@gmail.com'
+  self.rubyforge_name       = self.name
+  require_ruby_version '>= 1.9.2'
+  dependency 'yard', '~> 0.7.4', :development
 end
 
 require 'newgem/tasks'

data/example/benchmarks.rb

@@ -0,0 +1,56 @@
+#/usr/bin/ruby -w
+
+require 'benchmark'
+require_relative '../lib/striuct'
+
+XStruct = Struct.new :any, :no_use1, :no_use2
+
+XStriuct = Striuct.define do
+  member :any
+  member :int, Integer
+  member :truthy, ->v{v}
+end
+
+xstruct = XStruct.new
+xstriuct = XStriuct.new
+
+TIMES = 100000
+OBJ = 123
+
+Benchmark.bm do |bm|
+  bm.report 'Struct(equal Noguard): Setter' do
+    TIMES.times do
+      xstruct.any = OBJ
+    end
+  end
+  
+  bm.report 'Struct: Reader' do
+    TIMES.times do
+      xstruct.any
+    end
+  end
+  
+  bm.report 'Striuct(when Noguard): Setter' do
+    TIMES.times do
+      xstriuct.any = OBJ
+    end
+  end
+
+  bm.report 'Striuct(guard under class): Setter' do
+    TIMES.times do
+      xstriuct.int = OBJ
+    end
+  end
+  
+  bm.report 'Striuct(guard under function)' do
+    TIMES.times do
+      xstriuct.truthy = OBJ
+    end
+  end
+  
+  bm.report 'Striuct: Reader' do
+    TIMES.times do
+      xstriuct.any
+    end
+  end
+end

data/{example.rb → example/example.rb}

@@ -1,27 +1,27 @@
 #/usr/bin/ruby -w
 
-require_relative 'lib/striuct'
+require_relative '../lib/striuct'
 
 def debug(message)
-  puts "line: #{caller[0].slice(/:(\w+)/, 1)}"
+  puts "line: #{caller.first.slice(/:(\w+)/, 1)}"
   puts message.inspect, '-' * 80
 end
 
-#* Macro "member" provides one of Struct+ interfaces for condtions and a flavor.
+
+# 1. Struct+ "Secure"
+
+# macro "member" provides to use condtions
 class User < Striuct.new
-  member :id, Integer
-  member :address, /\A((\w+) ?)+\z/
-  member :age, (20..140)
-  member :name, /\A\w+\z/, /\A\w+ \w+\z/
+  member :id,   Integer
+  member :age,  (20..140)
+  member :name, OR(/\A\w+\z/, /\A\w+ \w+\z/)
 end
 
-# pass
-user = User.new 128381, 'Tokyo Japan', 20
+user = User.new 128381, 20
 debug user
 
-# pass
 user.age = 30
-user.name = 'taro yamada'
+user[2] = 'taro yamada'
 debug user
 
 # fail (Exception  Striuct::ConditionError)
@@ -31,12 +31,6 @@ rescue
   debug $!
 end
 
-begin
-  user[1] = 'Tokyo-to'
-rescue
-  debug $!
-end
-
 begin
   user.age = 19
 rescue
@@ -44,25 +38,19 @@ rescue
 end
 
 begin
-  user.name = nil
+  user[2] = 'typo! name'
 rescue
   debug $!
 end
 
-#* but, linked objects are able to clash
-debug user
-debug user.strict?
-debug user
-debug user.strict?
-
-# more detail checker do you need, you can use functional object.
+# more detail checker do you need, use functional object
 module Game
   class Character
   end
 
   class DB < Striuct.new
-    member :monsters, ->monsters{(monsters - characters).empty?}
-    member :characters, ->characters{characters.all?{|c|c.kind_of? Character}}
+    member :monsters,   ->list{(list - characters).empty?}
+    member :characters, GENERICS(Character)
   end
   
   monster = Character.new
@@ -78,7 +66,7 @@ module Game
   debug db
   
   begin
-    db.monsters = [:dummy]
+    db.monsters = [Character.new]
   rescue
     debug $!
   end
@@ -87,10 +75,10 @@ module Game
   debug db
 end
 
-# "inference", check under first passed object's class
+# through "inference", and check under first passed object class
 class FlexibleContainer < Striuct.new
   member :anything, inference
-  member :number, inference, Numeric
+  member :number,   Numeric, inference
 end
 
 fc1, fc2 = FlexibleContainer.new, FlexibleContainer.new
@@ -127,15 +115,43 @@ rescue
   debug $!
 end
 
- 
-# with flavor for type cast
+# Standard Struct not check member name. 
+NoGuard = Struct.new :__send__, :'?  !'
+noguard = NoGuard.new false
+debug noguard.__send__
+debug noguard.methods.include?(:'?  !') # lost!!
+
+# Striuct provides safety levels for naming.
+class SafetyNaming < Striuct.new
+  begin
+    member :__send__
+  rescue
+    debug $!
+  end
+  
+  begin
+    member :'?  !'
+  rescue
+    debug $!
+  end
+  
+  # set lower
+  protect_level :struct
+  
+  member :__send__, :'?  !'
+end
+
+# 2. Struct+ "Handy"
+
+# to through block called "flavor"
+# below case for type cast
 class User2 < Striuct.new
   member :age, /\A\d+\z/, Numeric do |arg|
     Integer arg
   end
   
-  member :name, ->v{v.respond_to? :to_str} do |v|
-    v.to_str.to_sym
+  member :name, ->v{v.respond_to? :to_s} do |v|
+    v.to_s.to_sym
   end
 end
 
@@ -149,16 +165,13 @@ debug user2
 user2.age = '10'
 debug user2
 
-begin
-  user2.name = 10
-rescue
-  debug $!
-end
+user2.name = 10
+debug user2
+user2.name = Class
+debug user2
 
-user2.name = 's'
-debug user2.class
+# Default value
 
-# use default value
 class User3 < Striuct.new
   member  :lank, Fixnum
   default :lank, 3
@@ -174,41 +187,39 @@ debug user3.assign?(:name)
 user3.name = nil
 debug user3.assign?(:name)
 
-# Standard Struct no check member name. 
-NoGuard = Struct.new :__send__, :'?  !'
-noguard = NoGuard.new false
-debug noguard.__send__
-debug noguard.methods.include?(:'?  !') # lost!!
+# Alias
 
-# Striuct provides safety levels for naming.
-class SafetyNaming < Striuct.new
-  begin
-    member :__send__
-  rescue
-    debug $!
-  end
-  
-  begin
-    member :'?  !'
-  rescue
-    debug $!
-  end
-  
-  # set lower
-  protect_level :struct
-  
-  member :__send__, :'?  !'
+class User3
+  alias_member :position, :lank
+end
+
+debug user3.lank.equal?(user3.position)
+debug user3[:lank].equal?(user3[:position])
+user3[:position] = 4
+debug user3.lank
+
+# New Constructors
+
+# Subclass.define reject floating object
+# * except if no finished assign each members
+# * return object is frozen
+user3 = User3.define do |r|
+  r.lank = 10
+  r.name = 'foo'
 end
 
+debug user3
+
+# Subclass.load_pairs easy make from Hash and like Hash
+user3 = User3[lank:10, name: 'foo']
 
-# and keeping Struct's good interface
-Sth1 = Striuct.new :id, :last_name, :family_name, :address, :age
+debug user3
 
-debug Sth1.new
+# 3. Keeping Struct's good interface
 
-Sth2 = Striuct.new do
+Sth1 = Striuct.new do
   def my_special_method
   end
 end
 
-debug Sth2.new.respond_to?(:my_special_method)
+debug Sth1.new.respond_to?(:my_special_method)

data/example/see_trace.rb

@@ -0,0 +1,28 @@
+#/usr/bin/ruby -w
+
+require_relative '../lib/striuct'
+
+class User < Striuct.new
+  member :id,   Integer
+  member :age,  (20..140)
+end
+
+user = User.new
+
+begin
+  user[:id] = 10.0
+rescue
+  puts $!.backtrace
+end
+
+begin
+  user.age = 19
+rescue
+  puts $!.backtrace
+end
+
+puts '-' * 80
+
+$stdout.flush
+
+user.age = 19