Class: CShadow::Attribute

Inherits:
Object
  • Object
show all
Defined in:
lib/cgen/attribute.rb

Overview

This is the base class for all plug-in attribute classes used with the CShadow module. Each subclass provides information which CShadow uses to manage some of the housekeeping for the attribute:

  • declaration of the attribute in the shadow struct,

  • accessor code (which CShadow wraps in methods),

  • type conversion for the write accessor,

  • type checking for the write accessor,

  • the ‘mark’ function, if the attribute refers to Ruby objects,

  • the ‘free’ function, if the attribute refers to C data,

  • initialization (usually, this is left to the class’s #initialize method),

  • serialization methods for the attribute.(*)

(*) For Ruby versions before 1.7, requires a patch using the marshal.patch file (the patch is explained in marshal.txt).

The subclass hierarchy has two branches: ObjectAttribute and CNativeAttribute. The former is a reference to a Ruby object (in other words, a struct member of type VALUE). The latter has subclasses for various C data types, such as double and char *.

Adding new attribute classes

Each attribute class must define a class method called ‘match’ which returns true if the right hand side of the ‘:name => …’ expression is recognized as defining an attribute of the class. The class should have an initialize method to supply custom code for readers, writers, type checking, memory management, and serialization. (If serialization methods are omitted, the attribute will be ignored during dump/load.) The easiest way is to follow the examples. For many purposes, most of the work can be done by subclassing existing classes.

The dump and load methods require a bit of explanation. Each attribute provides code to dump and load itself in a very generic way. The dump code must operate on a ruby array called result. It must push one piece of ruby data (which may itself be an array, hash, etc.) onto this array. Similarly, the load code operates on a ruby array called from_array. It must shift one piece of ruby data from this array. (Probably it would have been more efficient to use LIFO rather than FIFO. Oh, well.)

To do:

  • Type checking and conversion should to to_str, to_ary, etc. first if

appropriate.

  • Consider changing ‘[Foo]’ to ‘shadow(Foo)’ and using [Foo, Bar, Baz],

Foo]*20, and [Foo .. Foo

to signify structs, fixed-length arrays, and

var-length arrays of (VALUE *) ?

  • More attribute classes: floats, unsigned, fixed length arrays, bitfields,

etc.

  • substructs?

  • Make classes more generic, so that there aren’t so many classes. (Factory

classes, like ArrayAttribute(PointerAttribute(:char)) ?)

  • Support for #freeze, #taint, etc.

Limitations:

  • IntAttribute: No attempt to handle Bignums.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(owner_class, var, match, persists = true) ⇒ Attribute

Returns a new instance of Attribute.



90
91
92
93
94
 
# File 'lib/cgen/attribute.rb', line 90

def initialize owner_class, var, match, persists = true
  @owner_class = owner_class
  @var, @match = var, match
  @persists = persists
end

Instance Attribute Details

#cdecl ⇒ Object (readonly)

Returns the value of attribute cdecl.



85
86
87
 
# File 'lib/cgen/attribute.rb', line 85

def cdecl
  @cdecl
end

#check ⇒ Object (readonly)

Returns the value of attribute check.



85
86
87
 
# File 'lib/cgen/attribute.rb', line 85

def check
  @check
end

#cvar ⇒ Object (readonly)

Returns the value of attribute cvar.



85
86
87
 
# File 'lib/cgen/attribute.rb', line 85

def cvar
  @cvar
end

#dump ⇒ Object (readonly)

Returns the value of attribute dump.



85
86
87
 
# File 'lib/cgen/attribute.rb', line 85

def dump
  @dump
end

#free ⇒ Object (readonly)

Returns the value of attribute free.



85
86
87
 
# File 'lib/cgen/attribute.rb', line 85

def free
  @free
end

#init ⇒ Object (readonly)

Returns the value of attribute init.



85
86
87
 
# File 'lib/cgen/attribute.rb', line 85

def init
  @init
end

#load ⇒ Object (readonly)

Returns the value of attribute load.



85
86
87
 
# File 'lib/cgen/attribute.rb', line 85

def load
  @load
end

#mark ⇒ Object (readonly)

Returns the value of attribute mark.



85
86
87
 
# File 'lib/cgen/attribute.rb', line 85

def mark
  @mark
end

#owner_class ⇒ Object (readonly)

Returns the value of attribute owner_class.



85
86
87
 
# File 'lib/cgen/attribute.rb', line 85

def owner_class
  @owner_class
end

#persists ⇒ Object (readonly)

Returns the value of attribute persists.



85
86
87
 
# File 'lib/cgen/attribute.rb', line 85

def persists
  @persists
end

#reader ⇒ Object (readonly)

Returns the value of attribute reader.



85
86
87
 
# File 'lib/cgen/attribute.rb', line 85

def reader
  @reader
end

#var ⇒ Object (readonly)

Returns the value of attribute var.



85
86
87
 
# File 'lib/cgen/attribute.rb', line 85

def var
  @var
end

#writer ⇒ Object (readonly)

Returns the value of attribute writer.



85
86
87
 
# File 'lib/cgen/attribute.rb', line 85

def writer
  @writer
end

Class Method Details

.inherited(subclass) ⇒ Object 



77
78
79
 
# File 'lib/cgen/attribute.rb', line 77

def Attribute.inherited subclass
  AttributeTypes << subclass
end

.match(decl) ⇒ Object 



81
82
83
 
# File 'lib/cgen/attribute.rb', line 81

def Attribute.match decl
  false
end

Instance Method Details

#inspect ⇒ Object 



96
97
98
 
# File 'lib/cgen/attribute.rb', line 96

def inspect
  %{<#{self.class} #{@cvar} => #{@cdecl.inspect}>}
end