gogyou 0.2.2 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: ff192352d61629b6bcec6f1f4a3ce798c2cab5ff
4
- data.tar.gz: 244710ba81429d85608ed708424971d5c1bcd843
3
+ metadata.gz: 27a359613aa14229e1909aa2407b66a0453d32d0
4
+ data.tar.gz: a20b4c0a8daba874576b033294d052741d65a4f7
5
5
  SHA512:
6
- metadata.gz: b575790ca4b409310f7418dcc4e12220a9dfaeb511f4449756ad9997e83abf1c77953efa2d3dcc33c28e8b5fe92e0f71b66bb65ba296603054ab2639b85904eb
7
- data.tar.gz: 3cc09af86d7884cca95aa399c912d19963608399273d45dd96cfbedc239c136f718e87ce2d2a8c6918d5757a0e2ddded0d93ff94afe45840f894de9ded4f003c
6
+ metadata.gz: 6756d3ec51de9d0a2f8a7d806b8fcc019b6f4345c3312437f4c94d94e94a38c25154d9e510dfb12eb1416e61c3170a6dcdfcff92809b22efa628fe036c2baa70
7
+ data.tar.gz: ea1b5f3afd52b88b8f273f98794c36afd191ab2ba45235a8d0f8680c2de168937558ffb7e5c064c7c8288f50beb93fac1c1fd1cfbbfee43eee5f936df0ec1fcf
@@ -0,0 +1,51 @@
1
+ # gogyou の更新履歴
2
+
3
+ ## gogyou-0.2.3 (2015-5-17)
4
+
5
+ * short、int、long、long long のバイト数が環境ごとの値として取得するようになっていなかった問題を修正
6
+ * これらの型のバイト数 (sizeof) は Array#pack を用いてそれぞれ
7
+ "S" "I" "L" "Q" を与えて取得しており、目的のためには本来 "!"
8
+ を加える必要があります。
9
+ これまではそうなっていなかったため、これを修正しています。
10
+ * Gogyou::Accessor#inspect と Gogyou::Accessor#pretty\_print の改善
11
+ * これらのメソッドは各フィールドの値を表示するように変更しました。
12
+ * Gogyou::Accessor#size を Gogyou::Accessor#elementsize に変更
13
+ * Gogyou::Accessor#size メソッドを Gogyou::Accessor#elementsize
14
+ に名称変更しました。
15
+ * Gogyou::Accessor#size メソッドは Gogyou::Accessor#elementsize
16
+ の別名となりました。
17
+ * Gogyou::Struct / Gogyou::Union クラスの追加
18
+ * これらを親クラスとしたクラスを作成し、その中で ``struct`` / ``union``
19
+ することで構造体の構築が行える機能を追加しました。
20
+ * ``int24_t`` と ``int48_t`` 系列の型を削除
21
+ * ネイティブレベルでは存在しない (であろう) 以下の型を削除しました。
22
+
23
+ ``int24_t`` ``uint24_t`` ``int48_t`` ``uint48_t``
24
+ ``int24_swap`` ``uint24_swap`` ``int48_swap`` ``uint48_swap``
25
+ * ``int24_be`` ``int48_le`` などはこれまで通り利用できます。
26
+ * その他の修正
27
+
28
+ ## gogyou-0.2.2
29
+
30
+ * ``Gogyou.define_typeinfo`` を追加
31
+ * ``Gogyou.struct`` 内における、フィールド修飾子メソッド ``packed`` を追加
32
+ * ``Extensions::String::Mixin#setbinary`` の引数の受け方を変更
33
+ * その他微修正
34
+
35
+ ## gogyou-0.2.1
36
+
37
+ * ``Accessor::Array`` の ``#size`` と ``#bytesize`` が間違った値を返していた問題を修正
38
+ * ``Accessor#size`` が存在しなかった問題を修正
39
+ * その他微修正
40
+
41
+ ## gogyou-0.2
42
+
43
+ * バイナリデータに対する値の代入・取り出しとするために書き直し
44
+ * 共用体への対応を追加
45
+ * フィールド修飾子メソッド ``const`` を追加
46
+ * ``String`` と ``Integer`` に対するバイナリ操作メソッドを追加
47
+
48
+
49
+ ## gogyou-0.1
50
+
51
+ * 初版
File without changes
@@ -18,20 +18,21 @@ ruby 構文による、C 言語の構造体・共用体・多次元配列 (も
18
18
 
19
19
  ----
20
20
 
21
- * Product Name (名称): gogyou (ゴギョウ / 御形 / Gnaphalium affine)
22
- * Author (制作者): dearblue &lt;<dearblue@users.sourceforge.jp>&gt;
23
- * Distribute License (頒布ライセンス): 2-clause BSD License (二条項 BSD ライセンス)
24
- * Software Quarity (ソフトウェア品質): alpha
25
- * User (想定利用者): Rubyist
26
- * Release Number (リリースナンバー): 0.2
27
- * Memory Usage (使用メモリ量): 2 MB +
28
- * Installed Size (インストール容量): under 1 MB
29
- * Project Page: &lt;http://sourceforge.jp/projects/rutsubo/>
30
- * Support Ruby: ruby-2.0+ &lt;http://www.ruby-lang.org/>
21
+ * Product Name (名称): gogyou (ゴギョウ / 御形 / Gnaphalium affine)
22
+ * Author (制作者): dearblue &lt;dearblue@users.sourceforge.jp&gt;
23
+ * Distribute License (頒布ライセンス): 2-clause BSD License (二条項 BSD ライセンス)
24
+ * Software Quarity (ソフトウェア品質): alpha
25
+ * User (想定利用者): Rubyist
26
+ * Release Number (リリースナンバー): 0.2.3
27
+ * Memory Usage (使用メモリ量): 2 MB +
28
+ * Installed Size (インストール容量): under 1 MB
29
+ * Project Page: &lt;http://sourceforge.jp/projects/rutsubo/&gt;
30
+ * Support Ruby: ruby-2.0+ &lt;http://www.ruby-lang.org/&gt;
31
31
 
32
32
  ## Example
33
33
 
34
- ruby/ruby.h の struct RBasic と struct RObject を gogyou を用いて次のように記述出来ます:
34
+ ruby/ruby.h の ``struct RBasic````struct RObject`` を gogyou を用いて次のように記述出来ます
35
+ (ポインタの定義はできていないため、``uintptr_t`` で置き換えています):
35
36
 
36
37
  ```ruby:ruby
37
38
  require "gogyou"
@@ -45,12 +46,7 @@ module MyRuby
45
46
 
46
47
  RBasic = struct {
47
48
  VALUE :flags
48
- union {
49
- const VALUE :klass
50
- struct -> {
51
- VALUE :klass
52
- }, :force_modify
53
- }
49
+ const VALUE :klass
54
50
  }
55
51
 
56
52
  RObject = struct {
@@ -67,63 +63,83 @@ module MyRuby
67
63
  end
68
64
  ```
69
65
 
70
- `extend Gogyou` して呼ばれた `struct` は、構築した構造体の無名クラスを返します。
66
+ ``extend Gogyou`` して呼ばれた ``struct`` は、構築した構造体の無名クラスを返します。
71
67
 
72
68
  この無名クラスを定数に代入すれば、ruby の一般的なクラスと同様に扱うことが出来ます。
73
69
 
74
- `RObject` のインスタンスは次のように (C 言語のそれや、ruby の他のオブジェクトと相違無く) 扱うことが出来ます。
70
+ ``RObject`` のインスタンスは次のように (C 言語のそれや、ruby の他のオブジェクトと相違無く) 扱うことが出来ます。
71
+
72
+ また、ruby がもつ ``p`` メソッドや ``pp`` メソッドでわかりやすく表示されます (gogyou-0.2.3 にて追加)。
75
73
 
76
74
  ```ruby:ruby
77
75
  obj = MyRuby::RObject.new
78
- # or obj = MyRuby::RObject.new(File.read("sample.bin", MyRuby::RObject.size, mode: "rb"))
79
- obj.basic.flags = 0x12345678
80
- (obj.basic.klass = 0xaaaaaaaa) rescue p $! # => exception! klass field is immutable type
81
- obj.basic.force_modify.klass = 0xaaaaaaaa
76
+ # OR obj = MyRuby::RObject.bind("0123456789abcdef" * 2000) # given any string
77
+
78
+ obj.basic.flags = 1234567890
79
+ (obj.basic.klass = 0xaaaaaaaa) rescue p $! # => EXCEPTION! klass field is immutable
80
+
82
81
  obj.as.heap.numiv = 0x55555555
83
- p obj.as.ary[0] # => 0x55555555
84
- tmp = obj.as.heap
85
- tmp.ivptr = 0x44444444
86
- p obj.as.ary[1] # => 0x44444444
82
+ p obj.as.ary[0] # => 0x55555555 # same address as union field
87
83
 
88
- # 以下の結果は 64ビット環境によるものです
89
- p obj.bytesize # => 40
90
- p obj.to_buffer # => "xV4\x12\0\0\0\0\xaa\xaa\xaa\xaa\0\0\0\0UUUU\0\0\0\0DDDD\0\0\0\0\0\0\0\0\0\0\0\0"
84
+ obj.as.heap.ivptr = 1234567890
85
+ p obj.as.heap.ivptr # => 1234567890
86
+ tmp = obj.as.heap # get a middle field accessor
87
+ tmp.ivptr = 0x44444444
88
+ p obj.as.heap.ivptr # => 0x44444444
89
+
90
+ # following results are in little endian 64 bit enviroment
91
+ require "pp"
92
+
93
+ pp obj.bytesize # => 40
94
+ pp obj.to_buffer # => "xV4\x12\0\0\0\0\0\0\0\0\0\0\0\0UUUU\0\0\0\0DDDD\0\0\0\0\0\0\0\0\0\0\0\0"
95
+ pp obj # => #<MyRuby::RObject
96
+ # basic=
97
+ # #<MyRuby::RBasic
98
+ # flags=1234567890,
99
+ # klass=0>,
100
+ # as=
101
+ # {heap={numiv=1431655765, ivptr=1145324612, iv_index_tbl=0},
102
+ # ary=[1431655765, 1145324612, 0]}>
91
103
  ```
92
104
 
93
105
 
94
106
  ## About features (機能について)
95
107
 
96
- * Support A C-liked struct and union (with nested containers)
108
+ * Support A C-liked struct and union (with nested and anonimous containers)
97
109
 
98
- C に似た構造体・共用体に対応 (入れ子構造も可能)
110
+ C に似た構造体・共用体に対応 (無名の入れ子構造も可能)
99
111
 
100
112
  ``` ruby:ruby
101
- X = Gogyou.struct {
102
- int :a
103
- float :b
104
- double :c
105
- union {
106
- struct -> {
107
- float :x, y, z
108
- }, :d
109
- const struct -> {
110
- int :x, :y, :z
111
- }, :e
112
- }
113
- }
113
+ X = Gogyou.struct { # struct X {
114
+ int :a # int a;
115
+ float :b # float b;
116
+ double :c # double c;
117
+ union { # union {
118
+ struct -> { # struct {
119
+ float :x, :y, :z, :w # float x, y, z, w;
120
+ }, :d, 4 # } d[4];
121
+ const struct -> { # const struct {
122
+ int32_t :x, :y, :z, :w # int x, y, z, w;
123
+ }, :e, 4 # } e[4];
124
+ } # };
125
+ struct { # struct {
126
+ int :u, :v, :s, :t # int u, v, s, t;
127
+ } # };
128
+ } # };
114
129
  ```
115
130
 
116
- * Support multidimensional arrays
131
+ * Support multidimensional arrays
117
132
 
118
133
  多次元配列に対応
119
134
 
120
135
  ``` ruby:ruby
121
- Gogyou.struct {
122
- char :name, 64, 4 # => char name[64][4];
123
- }
136
+ X = Gogyou.struct { # struct X {
137
+ char :name, 64, 4 # char name[64][4];
138
+ char :a, :b, 16, :c, 4, 8, :d # char a, b[16], c[4][8], d; // mixed definition
139
+ } # };
124
140
  ```
125
141
 
126
- * Alias types by `typedef` (with array)
142
+ * Alias types by `typedef` (with array)
127
143
 
128
144
  `typedef` による型の別名定義 (配列も可能)
129
145
 
@@ -140,11 +156,11 @@ p obj.to_buffer # => "xV4\x12\0\0\0\0\xaa\xaa\xaa\xaa\0\0\0\0UUUU\0\0\0\0DDDD\0
140
156
  end
141
157
  ```
142
158
 
143
- * Support packed struct liked GCC ``__attribute__((packed))``
159
+ * Support packed struct liked GCC ``__attribute__((packed))``
144
160
 
145
161
  GCC の ``__attribute__((packed))`` に似た、パックされた構造体に対応
146
162
 
147
- C 言語での記述
163
+ by C:
148
164
 
149
165
  ``` c:c
150
166
  struct X
@@ -154,7 +170,7 @@ p obj.to_buffer # => "xV4\x12\0\0\0\0\xaa\xaa\xaa\xaa\0\0\0\0UUUU\0\0\0\0DDDD\0
154
170
  } __attribute__((packed));
155
171
  ```
156
172
 
157
- ruby による記述
173
+ by ruby:
158
174
 
159
175
  ``` ruby:ruby
160
176
  X = Gogyou.struct {
@@ -165,11 +181,11 @@ p obj.to_buffer # => "xV4\x12\0\0\0\0\xaa\xaa\xaa\xaa\0\0\0\0UUUU\0\0\0\0DDDD\0
165
181
  }
166
182
  ```
167
183
 
168
- * Appended bit operation for Integer
184
+ * Appended bit operation for Integer
169
185
 
170
186
  Integer に対する追加のビット操作
171
187
 
172
- * Appended binary operation for String
188
+ * Appended binary operation for String
173
189
 
174
190
  String に対する追加のバイナリ操作
175
191
 
@@ -182,24 +198,68 @@ p obj.to_buffer # => "xV4\x12\0\0\0\0\xaa\xaa\xaa\xaa\0\0\0\0UUUU\0\0\0\0DDDD\0
182
198
  require "gogyou"
183
199
  ```
184
200
 
185
- 次に、クラスやモジュールの中で `extend Gogyou` します。
201
+ 構造体(又は共用体)を定義する方法はいくつかあり、小さいながらもそれぞれに特徴が異なります。
186
202
 
187
- ```ruby:ruby
188
- module MyModule
189
- extend Gogyou
190
- end
191
- ```
203
+ 1. クラスやモジュールの中で ``extend Gogyou`` して、``struct`` (または ``union``) をブロック付きで呼び出し、その戻り値を定数に代入する
204
+
205
+ ```ruby:ruby
206
+ module MyModule
207
+ extend Gogyou
208
+
209
+ TypeA = struct {
210
+ int :a
211
+ }
212
+ end
213
+ ```
214
+
215
+ 特徴:
216
+
217
+ * MyModule の中で ``typedef`` を使うことが出来る
218
+ * extend したモジュール内で struct した型名を typedef することなく利用することが出来る
219
+
220
+ 2. Gogyou.struct (または Gogyou.union) をブロック付きで呼び出し、その戻り値を定数に代入する
221
+
222
+ ```ruby:ruby
223
+ TypeA = Gogyou.struct {
224
+ int :a
225
+ }
226
+ ```
227
+
228
+ 特徴:
229
+
230
+ * Gogyou モジュールを ``extend`` する必要がない
231
+ (``extend`` するためのモジュール/クラスが不要)
232
+
233
+ 3. Gogyou::Struct (または Gogyou::Union) を親クラスとしてクラスを定義し、その中で ``struct`` (または ``union``) をブロック付きで呼び出す
234
+ (gogyou-0.2.3 にて追加)
235
+
236
+ ```ruby:ruby
237
+ class TypeA < Gogyou::Struct
238
+ struct {
239
+ int :a
240
+ }
241
+ end
242
+ ```
243
+
244
+ 特徴:
245
+
246
+ * 構造体 (共用体) の定義とメソッド定義を同じ ``class`` ブロックの中で定義することが出来る
247
+ * Gogyou モジュールを ``extend`` する必要がない
248
+
249
+ 以下の利用例では、(1)の方法を元に説明しています。
192
250
 
193
251
  ### Define struct (構造体の定義)
194
252
 
195
- 構造体(もどき)を構築するには、`struct` をブロック付きで呼び出します。
253
+ クラスやモジュールの中で ``extend Gogyou`` してから ``struct`` をブロック付きで呼び出します。
196
254
 
197
- ***このブロックは struct 内部で生成されるオブジェクトが `instance_exec` するときにそのまま渡されます。self が切り替わることに注意して下さい。***
255
+ **このブロックは struct 内部で生成されるオブジェクトが instance\_exec するときにそのまま渡されます。*self が切り替わることに注意*して下さい。**
198
256
 
199
257
  フィールド名はシンボル (または文字列) で与えます。
200
258
 
201
259
  ```ruby:ruby
202
260
  module MyModule
261
+ extend Gogyou
262
+
203
263
  TypeA = struct {
204
264
  int :a
205
265
  }
@@ -217,6 +277,8 @@ end
217
277
 
218
278
  ```ruby:ruby
219
279
  module MyModule
280
+ extend Gogyou
281
+
220
282
  TypeA1 = struct {
221
283
  int :b, 4 # => C: int b[4];
222
284
  }
@@ -227,6 +289,8 @@ end
227
289
 
228
290
  ```ruby:ruby
229
291
  module MyModule
292
+ extend Gogyou
293
+
230
294
  TypeA2 = struct {
231
295
  int :c, 8, 4, 2 # => C: int c[8][4][2];
232
296
  }
@@ -237,6 +301,8 @@ end
237
301
 
238
302
  ```ruby:ruby
239
303
  module MyModule
304
+ extend Gogyou
305
+
240
306
  TypeA3 = struct {
241
307
  int :a, :b, 4, :c, 8, 4, 2 # => C: int a, b[4], c[8][4][2];
242
308
  }
@@ -254,6 +320,8 @@ struct の最初の引数にブロックを与えること以外は、先に述
254
320
 
255
321
  ```ruby:ruby
256
322
  module MyModule
323
+ extend Gogyou
324
+
257
325
  TypeB = struct { # struct TypeB {
258
326
  struct -> { # struct {
259
327
  int :a, :b # int a, b;
@@ -262,10 +330,16 @@ module MyModule
262
330
  end
263
331
  ```
264
332
 
265
- 最初の引数にブロックではなく、型情報を持つオブジェクトを与えることも出来ます。
333
+ 最初の引数にブロックではなく、型情報としてのオブジェクトを与えることも出来ます。
266
334
 
267
335
  ```ruby:ruby
268
336
  module MyModule
337
+ extend Gogyou
338
+
339
+ TypeA = struct {
340
+ int :a
341
+ }
342
+
269
343
  TypeC = struct { # struct TypeC {
270
344
  struct TypeA, :n, 2, 4, 8, :m # struct TypeA n[2][4][8], m;
271
345
  } # };
@@ -276,6 +350,8 @@ end
276
350
 
277
351
  ```ruby:ruby
278
352
  module MyModule
353
+ extend Gogyou
354
+
279
355
  TypeD = struct { # struct TypeD {
280
356
  struct { # struct {
281
357
  int :a, :b # int a, b;
@@ -286,13 +362,13 @@ end
286
362
 
287
363
  struct 内の struct の呼び出し方法を示します。union も同様に利用できます。
288
364
 
289
- * `struct { ... } -> nil`
290
- * `struct proc_object, field_name, *array_elements`
291
- * `struct user_type_info, field_name, *array_elements`
365
+ * `struct { ... } -> nil`
366
+ * `struct proc_object, field_name, *array_elements`
367
+ * `struct user_type_info, field_name, *array_elements`
292
368
 
293
- * `union { ... } -> nil`
294
- * `union proc_object, field_name, *array_elements`
295
- * `union user_type_info, field_name, *array_elements`
369
+ * `union { ... } -> nil`
370
+ * `union proc_object, field_name, *array_elements`
371
+ * `union user_type_info, field_name, *array_elements`
296
372
 
297
373
  引数なしのブロック付きで呼ぶと、無名構造体 (union であれば無名共用体) を定義します。
298
374
 
@@ -312,11 +388,11 @@ struct 内の struct の呼び出し方法を示します。union も同様に
312
388
 
313
389
  この型情報は次のメソッドを持ったあらゆるオブジェクト (クラスでもモジュールでも、インスタンスでも構いません) のことです。
314
390
 
315
- * `.bytesize`
316
- * `.bytealign`
317
- * `.extensible?`
318
- * `.aref(buffer, offset)`
319
- * `.aset(buffer, offset, data)`
391
+ * `.bytesize`
392
+ * `.bytealign`
393
+ * `.extensible?`
394
+ * `.aref(buffer, offset)`
395
+ * `.aset(buffer, offset, data)`
320
396
 
321
397
  例として、MD5 を定義する場合の型情報は次のようになります。
322
398
 
@@ -335,11 +411,11 @@ class MD5
335
411
  end
336
412
 
337
413
  def self.aref(buffer, offset)
338
- ... snip ...
414
+ _ _ _ SNIP _ _ _
339
415
  end
340
416
 
341
417
  def self.aset(buffer, offset, data)
342
- ... snip ...
418
+ _ _ _ SNIP _ _ _
343
419
  end
344
420
  end
345
421
  ```
@@ -348,11 +424,13 @@ end
348
424
 
349
425
  ``` ruby:ruby
350
426
  class MD5
351
- Gogyou.define_typeinfo(16, # bytesize
352
- 1, # bytealign
353
- false, # extensible?
354
- ->(buffer, offset) { ... snip ... }, # aref
355
- ->(buffer, offset, data) { ... snip ... }) # aset
427
+ Gogyou.define_typeinfo(
428
+ self,
429
+ 16, # bytesize
430
+ 1, # bytealign
431
+ false, # extensible?
432
+ ->(buffer, offset) { _ _ _ SNIP _ _ _ }, # aref
433
+ ->(buffer, offset, data) { _ _ _ SNIP _ _ _ }) # aset
356
434
  end
357
435
  ```
358
436
 
@@ -370,7 +448,8 @@ MD5 を定義する場合、16バイトなので `16` を返します。
370
448
 
371
449
  このメソッドはその型のアライメントサイズを正の整数値で返します。
372
450
 
373
- MD5 を定義する場合、内部表現は1バイトの塊なので `1` を返します (MD5 の実装によっては `4` だったり `8` だったり、はたまた `16` になるかもしれません)。
451
+ MD5 を定義する場合、内部表現は1バイトの塊なので `1` を返します
452
+ (MD5 の実装によっては `4` だったり `8` だったり、はたまた `16` になるかもしれません)。
374
453
 
375
454
  ### `.extensible?`
376
455
 
@@ -518,10 +597,7 @@ Z = Gogyou.struct {
518
597
 
519
598
  ## Demerit (短所)
520
599
 
521
- * Can't be handled pointer
522
-
523
- ポインタが扱えない
524
-
525
- * The cost is high for reference/asignment from/to fields
526
-
527
- フィールドに対する参照・代入のコストが高い
600
+ * Can't be handled pointer
601
+ (ポインタが扱えない)
602
+ * The cost is high for reference/asignment from/to fields
603
+ (フィールドに対する参照・代入のコストが高い)