Class NiceFFI::Struct
In: lib/nice-ffi/struct.rb
Parent: FFI::Struct

A class to be used as a baseclass where you would use FFI::Struct. It acts mostly like FFI::Struct, but with nice extra features and conveniences to make life easier:

  • Automatically defines read and write accessor methods (e.g. x, x=) for struct members when you call layout. (You can use hidden and read_only before or after calling layout to affect which members have accessors.)
  • Implements "smart" accessors for TypedPointer types, seamlessly wrapping those members so you don‘t even have to think about the fact they are pointers!
  • Implements a nicer new method which allows you to create a new struct and set its data in one shot by passing an Array, Hash, or another instance of the class (to copy data). You can also use it to wrap a FFI::Pointer like FFI::Struct can.
  • Implements to_ary and to_hash to dump the struct data.
  • Implements to_s and inspect for nice debugging output.
  • Adds ::typed_pointer convenience alias to create a TypedPointer for this klass.
  • Provides automatic memory management for Pointers if you define MyClass.release( pointer). (This can be disabled per-instance by providing {:autorelease => false} as an option to new).

Methods

hidden   hidden?   inspect   layout   new   read_only   read_only?   to_ary   to_bytes   to_hash   to_s   typed_pointer  

Included Modules

NiceFFI::AutoRelease

Public Class methods

Mark the given members as hidden, i.e. do not create accessors for them in layout, and do not print them out in to_s, etc. You can call this before or after calling layout, and can call it more than once if you like.

Note: They can still be read and written via #[] and #[]=, but will not have convenience accessors.

Note: This will remove the accessor methods (if they exist) for the members! So if you‘re defining your own custom accessors, do that after you have called this method.

Example:

  class SecretStruct < NiceStruct

    # You can use it before the layout...
    hidden( :hidden1 )

    layout( :visible1, :uint16,
            :visible2, :int,
            :hidden1,  :uint,
            :hidden2,  :pointer )

    # ... and/or after it.
    hidden( :hidden2 )

    # :hidden1 and :hidden2 are now both hidden.
  end

True if the member has been marked hidden, false otherwise.

Same syntax as FFI::Struct#layout, but also defines nice accessors for the attributes.

Example:

  class Rect < NiceStruct
    layout( :x, :int16,
            :y, :int16,
            :w, :uint16,
            :h, :uint16 )
  end

Create a new instance of the class, reading data from a Hash or Array of attributes, a bytestring of raw data, copying from another instance of the class, or wrapping (not copying!) a FFI::Pointer.

If val is an instance of FFI::Pointer and you have defined MyClass.release, the pointer will be passed to MyClass.release when the memory is no longer being used. Use MyClass.release to free the memory for the struct, as appropriate for your class. To disable autorelease for this instance, set {:autorelease => false} in options.

(Note: FFI::MemoryPointer and FFI::Buffer have built-in memory management, so MyClass.release is never called for them.)

Mark the given members as read-only, so they won‘t have write accessors.

Note: They can still be written via #[]=, but will not have convenience accessors.

Note: This will remove the writer method (if it exists) for the members! So if you‘re defining your own custom writer, do that after you have called this method.

Example:

  class SecretStruct < NiceStruct

    # You can use it before the layout...
    read_only( :readonly1 )

    layout( :visible1,  :uint16,
            :visible2,  :int,
            :readonly1, :uint,
            :readonly2, :pointer )

    # ... and/or after it.
    read_only( :readonly2 )

    # :readonly1 and :readonly2 are now both read-only.
  end

True if the member has been marked read_only, false otherwise.

Returns a NiceFFI::TypedPointer instance for this class. Equivalent to NiceFFI::TypedPointer.new( this_class, options )

Public Instance methods

inspect()

Alias for to_s

Dump this instance as an Array of its struct data. The array contains only the data, not the member names.

Note: the order of data in the array always matches the order of members given in layout.

Example:

  Rect.new( :x=>1, :y=>2, :w=>3, :h=>4 ).to_ary
  # => [1,2,3,4]

Dump this instance as a string of raw bytes of its struct data.

Dump this instance as a Hash containing {member => data} pairs for every member in the struct.

Example:

  Rect.new( :x=>1, :y=>2, :w=>3, :h=>4 ).to_hash
  # => {:h=>4, :w=>3, :x=>1, :y=>2}

[Validate]