cppobj

cppobj provides a high level interface for working with C++ objects. The goal is to allow intuitive manipulation of those objects through familiar syntax.

For example, here’s how to wrap an object named foo from the current scope, and print the value of its bar data member:

local foo = cppobj.new( 'foo' )
print( foo.bar )

Lua’s metatable feature is used to overload the indexing operation performed by foo.bar, in order to return a new cppobj for the bar data member, which is then stringified. Stringification is overloaded to return a dbgeng “view” of an object, i.e., the same string that the dbgeng COM API would return when asked to return an object as text. A native Lua value can be retrieved for fundamental types by using cppobj.value().

Due to this overloading of the indexing operation, and the fact that object methods in Lua are also implemented by overloading indexing, most of the functions that operate on cppobj objects are instead implemented as class functions that simply take the cppobj as a paramater.

Class Functions

Class functions are accessible through the global cppobj table. Many of them operate on a cppobj, and return information about the wrapped C++ object.

cppobj.new(expr) → cppobj

Creates a new cppobj, representing a C++ symbol.

Parameters:expr (string) – C++ expression that evaluates to a symbol
Returns:New cppobj representing the given symbol
cppobj.is_cppobj(value) → boolean

Checks whether the given Lua value is a cppobj.

Parameters:value – Lua value to check
Returns:True if value is a cppobj, otherwise false
cppobj.value(obj) → Lua value

For fundamental types (cppobj.kind() returns “base”, “enum”, or “pointer”), returns an object’s value as an appropriately typed Lua value.

For array types, (cppobj.kind() returns “array), returns the memory offset of the array.

For other types, returns nil.

Parameters:obj (cppobj) – Object whose value to return
cppobj.kind(obj) → string

Returns the “kind” of a C++ object. The kind will be one of the following values:

  • base: Fundamental type like bool, char, int, float, etc
  • enum: Enum value
  • pointer
  • array
  • class: Class instance
  • function
  • unknown: Some other, unrecognized kind
Parameters:obj (cppobj) – Object whose kind to return
cppobj.type(obj) → string

Returns an object’s type.

Parameters:obj (cppobj) – Object whose type to return
cppobj.name(obj) → string

Returns an object’s name, usually the variable or field name.

Parameters:obj (cppobj) – Object whose name to return
cppobj.long_name(obj) → string

Returns an object’s “long” name, which is a fully qualified expression that is valid for the current scope.

Parameters:obj (cppobj) – Object whose long name to return
cppobj.offset(obj) → integer

Returns an object’s memory offset in the debugging target’s memory.

Parameters:obj (cppobj) – Object whose offset to return
cppobj.size(obj) → integer

Returns an object’s size.

Parameters:obj (cppobj) – Object whose size to return
cppobj.type_id(obj) → integer

Returns an object’s type id. This id is used in various dbgeng COM API functions.

Parameters:obj (cppobj) – Object whose type id to return
cppobj.type_module(obj) → integer

Returns the base memory offset of the module that the object’s type is from. This is effectively an id for the module, and is used in various dbgeng COM API functions.

Parameters:obj (cppobj) – Object whose module to return
cppobj.address_of(obj) → cppobj

Returns a new cppobj representing a pointer to obj.

Parameters:obj (cppobj) – Object to create a pointer to
cppobj.dereference(obj) → cppobj

Given a cppobj representing a pointer, returns a new cppobj representing the pointee.

Parameters:obj (cppobj) – Object to dereference
cppobj.bases(obj) → array[ cppobj ]

Returns an array of cppobj objects that are the base class representations of obj.

Parameters:obj (cppobj) – Object whose base class representations to return
cppobj.members(obj) → array[ cppobj ]

Returns an array of cppobj objects that are the data members of obj.

Parameters:obj (cppobj) – Object whose data members to return

Overloaded Operators

Overloaded operators comprise the remainder of the interactions with and between cppobj objects.

cppobj.__index(name) → cppobj

The indexing operator (. or []) is overloaded to return a new cppobj representing a data member of the cppobj being indexed.

Assuming foo is a formerly created cppobj, the following retrieves its bar data member as a cppobj:

local bar = foo.bar
-- equivalent:
local bar = foo[ 'bar' ]
cppobj.__eq(cppobj) → boolean

The equality operator (==) is overloaded to test C++ objects for equality, according to the following rules:

  • arrays are treated as pointers
  • pointers, base, and enum types are compared as numbers
  • class types are considered equal if two objects represent the same type at the same memory offset

If the first operand is a cppobj, any other equality result will be false.

cppobj.__sub(cppobj) → number
cppobj.__sub(number) → cppobj or number

The subtraction operator (-) is overloaded to perform subtraction with C++ objects, according to the following rules:

  • if the 1st operand is a cppobj pointer or array, and the 2nd operand is:
    • cppobj pointer or array of the same type
      • result is the scaled distance between the two memory locations, scaled by the object size
    • cppobj base integral type
      • result is a new pointer, offset by the given scaled distance
    • Lua integer
      • result is a new pointer, offset by the given scaled distance
  • if the 1st operand is a cppobj base type or enum, and the 2nd operand is:
    • cppobj base type or enum or Lua number; result is the difference of the two operands
  • if the 1st operand is a Lua value, and the 2nd operand is:
    • cppobj base type or enum or Lua number; result is the difference of the two operands
  • otherwise, the result is nil