striuct 0.0.11.1 → 0.1.7

data/History.rdoc

@@ -1,41 +1,134 @@
+=== 0.1.7 2012-1-26
+
+* add:
+  * default with Proc
+  * detail error message in Subclass.#[]=
+
+* fix
+  * class duplicating
+
+=== 0.1.6 2012-1-25
+
+* delete:
+  * import.rb
+
+* modify:
+  * Subclass.#define
+  * naming risks (add bad name "_foo")
+  * Conditions.#GENERICS (enum prior all? to each_value.all?)
+  * timing of check default value
+
+* add:
+  * detail error message in Subclass.#define
+
+* fix:
+  * inherited behavior
+
+=== 0.1.5 2012-1-17
+
+* add:
+  * #lock, #lock?
+  * some Specific Conditions
+
+* note:
+  multiple conditions for 'or', dupulicated for direct throw member macro
+  please use .#OR method in this case
+
+=== 0.1.4 2012-1-16
+
+* modify:
+  * trace logs
+  * naming risks(add bad name "to_foo")
+  * Subclass#unassign
+
+* add:
+  * Specific Conditions
+    (for Syntax Sugar of useful Functional Conditions)
+  * Subclass.#each_index
+  * Subclass.#valid?
+  * Subclass#clear_at, reset_at
+
+=== 0.1.3 2012-1-10
+
+* add:
+  * Subclass.#alias_member
+  * Subclass.#valid?
+  * Subclass#valid?
+
+=== 0.1.2 2012-1-9
+
+* modify:
+  * Subclass.#hash
+
+* add:
+  * Subclass.#to_yaml
+
+=== 0.1.1 2011-12-26
+
+* modify:
+  * Subclass.#sufficient?
+
+* add:
+  * Subclass.#empty?
+  * Subclass.#has_value? (value?)
+  * Subclass.#flatten
+  * Subclass.#select! (keep_if)
+  * Subclass.#select
+  * Subclass.#reject! (delete_if)
+  * Subclass.#reject
+  * Subclass.#assoc
+  * Subclass.#rassoc
+
+* fix
+  * Subclass.#sufficient?
+
+=== 0.1.0 2011-12-25
+
+* modify:
+  * Subclass.#define
+
+* add:
+  * Subclass.#[] (alias load_pairs)
+  * Subclass.#to_h
+
 === 0.0.11 2011-12-23
 
-* modify
-  * Subclass.cname?
+* modify:
+  * Subclass.#cname?
 
 * add:
   * inference checker
 
 === 0.0.10 2011-12-23
 
-* delete
-  * Subclass#lock, Subclass#unlock?
+* delete:
+  * Subclass.#lock, Subclass.#unlock?
 
-* modify
-  * Subclass#freeze
+* modify:
+  * Subclass.#freeze
   * has_condition? -> has_conditions?
-  * Subclass.lock, Subclass.lock? -> .close, .closed?
+  * Subclass.#lock, Subclass.#lock? -> .close, .closed?
 
 * add:
-  * Subclass.protect_level   # class macro
-  * Subclass#default?
+  * Subclass.#protect_level   # class macro
+  * Subclass.#default?
 
 === 0.0.9 2011-12-21
 
-* delete
+* delete:
   * Striuct.load_pairs
-  * Subclass.conditions
-  * Subclass.procedures
-  * Subclass.defaults
+  * Subclass.#conditions
+  * Subclass.#procedures
+  * Subclass.#defaults
 
 * add:
   * Striuct.define
-  * Subclass.lock
-  * Subclass.default_for
+  * Subclass.#lock
+  * Subclass.#default_for
 
 * fix:
-  * Subclass#inspect
-  * Subclass#to_s
+  * Subclass.#inspect
+  * Subclass.#to_s
 
 * note:
   * innner name changed "procedure" to "flavor"
@@ -43,30 +136,30 @@
 === 0.0.8 2011-12-18
 
 * modify:
-  * Subclass.define
-  * Subclass.accept?
+  * Subclass.#define
+  * Subclass.#accept?
   * functional checker's action:
     Proc: context to instance
     Method: === to call
 
 * add:
-  * Subclass.default
+  * Subclass.#default
 
 * fix:
-  * Subclass#values_at
+  * Subclass.#values_at
 
 === 0.0.7 2011-12-16
 
 * modify:
   * called macro's block to procedure 
-  * public to private Subclass#unlock
+  * public to private Subclass.#unlock
 
 * add:
-  * Subclass.define
-  * Subclass.accept?
-  * Subclass.restrict?
-  * Subclass#assign?
-  * Subclass#assign
+  * Subclass.#define
+  * Subclass.#accept?
+  * Subclass.#restrict?
+  * Subclass.#assign?
+  * Subclass.#assign
 
 * fix:
   * use clone method ( initialize_copy )
@@ -77,13 +170,13 @@
   * error type in some methods
 
 * add:
-  * Subclass.sufficent?
-  * Subclass.define
-  * Subclass#sufficent?
-  * Subclass#secure?
-  * Subclass#lock?
-  * Subclass#lock
-  * Subclass#unlock
+  * Subclass.#sufficent?
+  * Subclass.#define
+  * Subclass.#sufficent?
+  * Subclass.#secure?
+  * Subclass.#lock?
+  * Subclass.#lock
+  * Subclass.#unlock
 
 * fix:
   * typo
@@ -96,7 +189,7 @@
 
 === 0.0.4 2011-12-13
 
-* divide modules for subclass methods
+* divide modules for Subclass.#methods
 * modify return values for void methods
 
 === 0.0.3 2011-12-12

data/Manifest.txt

@@ -3,13 +3,28 @@ Manifest.txt
 README.rdoc
 README.ja.rdoc
 Rakefile
-example.rb
 lib/striuct.rb
-lib/striuct/core.rb
+lib/striuct/frame.rb
 lib/striuct/version.rb
-lib/striuct/classutil.rb
-lib/striuct/subclass.rb
-lib/striuct/subclass_eigen.rb
-lib/striuct/import.rb
+lib/striuct/abstract.rb
+lib/striuct/conditions.rb
+lib/striuct/subclassable/frame.rb
+lib/striuct/subclassable/classutil.rb
+lib/striuct/subclassable/basic.rb
+lib/striuct/subclassable/safety.rb
+lib/striuct/subclassable/handy.rb
+lib/striuct/subclassable/hashlike.rb
+lib/striuct/subclassable/yaml.rb
+lib/striuct/subclassable/inner.rb
+lib/striuct/subclassable/eigen/frame.rb
+lib/striuct/subclassable/eigen/basic.rb
+lib/striuct/subclassable/eigen/constructor.rb
+lib/striuct/subclassable/eigen/safety.rb
+lib/striuct/subclassable/eigen/handy.rb
+lib/striuct/subclassable/eigen/macro.rb
+lib/striuct/subclassable/eigen/inner.rb
 test/test_helper.rb
 test/test_striuct.rb
+example/example.rb
+example/benchmarks.rb
+example/see_trace.rb

data/README.ja.rdoc

@@ -6,79 +6,82 @@
 
 == DESCRIPTION
 
-Strict Struct の略です。そのまま StrictStruct でも使えます。
+Struct以上の手軽さで扱える、Structより堅いコンテナを目指しています。
 
-メンバ名チェックのかかるStructは、安心感という意味ではHashよりも好ましい事があるかと思います。
-でもそうやってStructを使うぐらいなわけだから、名前だけじゃなく参照先にもある程度の代入条件をかけたいと思う事が多くありませんか？
+メンバ名にチェックがかかる＆一つの新しいクラスとして扱えるStructは、場面によってはHashよりも好ましい事があるかと思います。
+でもそうやってStructを使うぐらいなわけだから、値の方にもある程度のチェックをかけたいと思う事が多くありませんか？
 
 RubyのStructを愛しつつも、こういった部分をなんとかしたいと感じている方へお勧めします。
 
 1. ノーガードで参照を付けられるのがおっかないときもある
 2. かといって、型チェックしか出来ないようじゃRubyのメリットが死ぬんではなかろうか
 3. メンバ名でフツーのメソッド名を上書きしかねないのもおっかない
-4. 最初に代入したオブジェクトのクラスで固定したい
-5. どうせなら、チェックだけじゃなくキャストなりもやらせたものを参照したい
+4. 最初に代入したオブジェクトのクラスで固定したい（これは無いか）
+5. どうせなら、チェックだけじゃなくキャストなりやらせたものを参照したい
 6. メンバによっては標準値も定義したい
+7. Hashとの親和性を高くしたい
+8. メンバ名にaliasかけたいけど、alias_methodだけだと添え字アクセス出来なくて歯がゆい
+9. 構造体クラスでも継承を使った上で、更にメンバ追加がしたい
 
 == FEATURES
 
 * メンバ毎に、参照条件を簡単に定義できます。
-* 型チェックではなく式チェックなので、動的言語の良さを殺しません
+* 型チェックではなく式チェックなので、動的型の良さを殺しません
 * Proc(lambda)やMethod等 を使うことで、さらに柔軟なチェックが可能です
-* どれか一つの構造体で最初に代入したオブジェクトのクラスで固定するようなメンバを作れます。
-* 参照前に、ちょっとした処理を加える事も可能です
-* 構造体としてのメンバ追加時、Rubyの既存メソッドと干渉しないかを指定レベル別にチェック可能です。
-* Structの心地よい操作感を残したまま機能追加をしています。
+* どれか一つの構造体で最初に代入したオブジェクトのクラスに沿うようなメンバを作れます。
+* 参照直前に、ちょっとした処理を加える事も可能です
+* 構造体としてのメンバ追加時、Rubyの既存メソッドと干渉しないかを指定レベル別にチェック出来ます。
+* 違和感のない継承利用
+* なるべくStructの心地よい操作感を残したまま機能追加をしています。
 * 既存クラスやメソッドの上書き等を（勝手には）しない、控えめな名前空間
-* pure-ruby
+* Pure Ruby
 
 == SYNOPSIS
 
 * setup
     require 'striuct'
 
-* Structには無い機能として、memberというクラスマクロを用意しました。
-  ここでの定義順通りにindexが振られます。
-  引数1にメンバ名、引数2以降に参照条件を渡して下さい。caseのwhen節と同じ感覚で使えます。
-  引数1のみの場合、Structのメンバと同様ノーチェックになります。
+* 2つの名前空間をお借りしますが、どっちも同じクラスを指します
+    Striuct
+    StrictStruct
+
+=== Struct+ "Safety"
+
+==== 基本的な使い方
+
+* memberというクラスマクロを使うことで構造体のメンバを定義できます。
+  引数2以降に、参照するための「条件」を渡して下さい。
+  何も条件を渡さなければ、Struct同様ノーチェックです。
     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
 
-    # これはOK
-    user = User.new 128381, 'Tokyo Japan', 20
+    # pass
+    user = User.new 128381, 20
 
-    # これもOK
+    # pass
     user.age = 30
-    user.name = 'taro yamada'
+    user[2] = 'taro yamada'
 
-    # これは駄目(例外 Striuct::ConditionError)
+    # fail
     user[:id] = 10.0
-    user[1] = 'Tokyo-to'
     user.age = 19
-    user.name = nil
+    user[2] = nil
 
- 
-* リンク貼る時どれだけ注意しても、その後参照先のオブジェクトがぶっ壊れる可能性は残りますよね。
-  これは致し方無いと思うので、チェックだけでも簡単にできるようにしています。
-    user.strict? #=> true
-    user.address.clear
-    user.strict? #=> false
 
-* 単純な例としてはこんな感じですが、更に細かいチェッカが必要であれば関数オブジェクトを使って下さい。
+* 更に柔軟なチェッカが必要であれば関数的なオブジェクトを使って下さい。
   この時Proc(lambda)を構造体インスタンスのコンテキストで評価する為、他のメンバと連携したチェックも簡単です。
     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
       db = DB.new
       
@@ -89,17 +92,17 @@ RubyのStructを愛しつつも、こういった部分をなんとかしたい
       db.characters = [monster, Character.new]
       
       # fail
-      db.monsters = [:dummy]
+      db.monsters = [:Character.new]
       
       # pass
       db.monsters = [monster]
     end
 
 * 構造体クラスのコンテキスト内だけで使える "inference" というメソッドの返り値を渡すと、
-  最初にどれか一つのインスタンスで参照したクラスが以降の参照条件となります。
+  最初に参照したオブジェクトのクラスが、以降全インスタンスでの参照条件となります。
     class FlexibleContainer < Striuct.new
       member :anything, inference
-      member :number, inference, Numeric
+      member :number, Numeric, inference
     end
 
     fc1, fc2 = FlexibleContainer.new, FlexibleContainer.new
@@ -122,8 +125,51 @@ RubyのStructを愛しつつも、こういった部分をなんとかしたい
     # fail
     fc2.number = 1
 
+==== 意図しない名前干渉は避ける
+
+* Structはこんな感じで、ノーガード上書き＆メソッド定義出来ない物も無警告で進みます(object_id, __id__ なんかもそうですね)
+    NoGuard = Struct.new :__send__, :'?  !'
+    noguard = NoGuard.new false
+    p noguard.__send__
+    p noguard.methods.include?(:'?  !') # lost!!
+
+* ということで、意図しない上書き等を防ぐために安全度を設定出来るようにしました。
+  標準値は上から2番目の「:prevent」です。
+    class SafetyNaming < Striuct.new
+      begin
+        member :__send__
+      rescue
+        p $!
+      end
+      
+      begin
+        member :'?  !'
+      rescue
+        p $!
+      end
+      
+      # ここで下げると、定義可能に
+      protect_level :struct
+      
+      member :__send__, :'?  !'
+    end
+
+==== この辺に関わる述語メソッド
+
+* valid? / acccept? / sufficient?   # そのメンバにその値が設定出来るか
+* conditionable?           # 条件式として受け入れ可能なオブジェクトか
+* inference?               # 定義時にinferenceを使った上で、一つも参照されていないか
+* restrict?                # そのメンバに参照条件がかけられているか
+* strict?                  # 今時点で全てのメンバが参照条件を満たしているか
+* secure?                  # インスタンスもクラスも変動することない状態で、インスタンスにfreezeがかかっているか
+* cname?                   # そのメンバ名は、今のprotect level下で望ましいものか
+
 
-* memberマクロへブロックを渡しておくと、チェック後一処理加えた値を代入可能です。
+=== Struct+ "Handy"
+
+==== Flavor
+
+* memberマクロへブロックを渡しておくと、チェック後一処理加えた値を参照可能です。
     class User2 < Striuct.new
       # 数字っぽければIntegerへ変換してから
       member :age, /\A\d+\z/, Numeric do |v|
@@ -142,8 +188,11 @@ RubyのStructを愛しつつも、こういった部分をなんとかしたい
     user2.age = '10' #=> 10(Fixnum)
     
     user2.name = 10 #=> :10(Symbol)
+    user2.name = Class #=> :Class(Symbol)
+
+==== Default
 
-* Structだと標準値は全て nil になってしまいますが、これもクラスマクロで定義できるようにしました。
+* defaultマクロを用いることで、メンバ毎に標準値を定義することが出来ます。
     class User3 < Striuct.new
       member  :lank, Fixnum
       default :lank, 3
@@ -153,44 +202,51 @@ RubyのStructを愛しつつも、こういった部分をなんとかしたい
     user3 = User3.new
     user3.lank #=> 3
 
-* 「意図的にnilを定義する」事もありますよね
-  初期nilとの判別用メソッドを追加しました。
-   
-   user3.name  #=> nil
-   user3.assign? :name #=> false
-   user3.name = nil
-   user3.assign? :name #=> true
+* 「意図的なnil」との区別を付けられます。
+    user3.name  #=> nil
+    user3.assign? :name #=> false
+    user3.name = nil
+    user3.assign? :name #=> true
 
-* Structはこんな感じで、ノーガード上書き＆メソッド定義出来ない物も無警告で進みます
-    NoGuard = Struct.new :__send__, :'?  !'
-    noguard = NoGuard.new false
-    p noguard.__send__
-    p noguard.methods.include?(:'?  !') # lost!!
+==== Alias
 
-* ということで、意図しない上書き等を防ぐために安全度を設定出来るようにしました。
-  標準値は上から2番目です。
-    class SafetyNaming < Striuct.new
-      begin
-        member :__send__
-      rescue
-        p $!
-      end
-      
-      begin
-        member :'?  !'
-      rescue
-        p $!
-      end
-      
-      # ここで下げると、定義可能に
-      protect_level :struct
-      
-      member :__send__, :'?  !'
+* メンバ名を付与出来ます。(標準Structだと、添字アクセス可能にしたりするのが面倒。)
+    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...)
 
-* Structの良さは無くしたくないですよね
-    Sth1 = Striuct.new :id, :last_name, :family_name, :address, :age
+==== Lock
 
+* (writing...)
+
+==== New Constructors
+
+* Subclass.define は、生成時から先オブジェクトを変える必要が無いケースで使います。
+  * ブロックパラメータに新しいインスタンスがわたり、またこれが返り値となります
+  * すべてのメンバがアサイン済みかをチェックします
+  * ブロックを抜ける直前に、全て問題ない値かチェックします(オプション指定可)
+  * ブロックを抜ける直前に、全てlockをかけます(オプション指定可)
+      user3 = User3.define do |r|
+        r.lank = 10
+        r.name = 'foo'
+      end
+
+* Subclass.[](load_pairs) は、HashなりHashっぽいものから作る時用です。
+  # Struct.[] の仕様とは異なります。
+    user3 = User3[lank:10, name: 'foo']
+
+=== Structの良さは活かしたまま
+
+* 基本的にはStruct使い(?)が余り違和感を感じ無いようにしたつもりです。
     Sth2 = Striuct.new do
       def my_special_method
       end
@@ -198,21 +254,24 @@ RubyのStructを愛しつつも、こういった部分をなんとかしたい
     
     Sth2.new.respond_to?(:my_special_method) #=> true
 
-* 混在利用させたい向きとかに、Structにも同じようなインターフェイスを用意できます。
-  逆に言うと、これを使わない限りは名前空間をあんまし汚しません。
-    require 'striuct/import'
+=== Hashとお近づきに
+
+* どちらかというとStructはHashよりArray寄りな感じを受けるのですが、個人的にHash的な動きをしてくれると嬉しい事の方が多く感じます。
+  ということで、やり過ぎない範囲でHashっぽく使えるように調整しています。
 
-* 他にも幾つか機能追加しています。
-  また、ここの例だと返り値や例外が見づらいと思うので、同梱の example.rb を動かしてみてください
+* Hashへの変換も一発です。
+    user3.to_h #=> {:lank=>3, :name=>nil}
 
-* 早わかり
-  https://github.com/kachick/striuct/wiki/EasyGuide
+== Note
+
+* 現状、このReadme含めてドキュメントは殆ど更新出来ていません。
+  0.2.0 までにはなんとかしたい
 
 == REQUIREMENTS
 
 === Ruby
-* 1.9.3
-* 1.9.2
+
+* Ruby 1.9.2 and later (tested 1.9.2, 1.9.3)
 
 == INSTALL