View source for LDT/User Area/Debugger/ValueDisplay

This document introduces the concept of custom inspectors which allows you to plug your own logic to decode children properties debugging.

This document is a tutorial, it just introduces concepts and best practices. For details about used functions, see the [http://git.eclipse.org/c/koneki/org.eclipse.koneki.ldt.git/tree/libraries/luadbgpclient/debugger/introspection.lua?id=1.1_RC1 <code>debugger.introspection</code>] API documentation.

There are two main uses cases:

* Enumerate properties of userdata object (which debugger cannot inspect at all out of the box)
* Customize debugging of tables to hide internal fields and reduce noise

The provided API tries to be as simple as possible by hiding most debugger &lt;=&gt; IDE communication logic such as recursion limit, pagination, … However it is not yet considerated as final and may change without notice.

{{tip| If it is about ''LuaJIT'' cdata, you might have a look at our [[Koneki/LDT/Developer_Area/User_Guides/User_Guide_1.1#Improve_cdata_display|cdata display module]].}}

= Inspector modules =

The inspectors are module distinct from the debugger and must be registered in order to be active. It can be done before or after starting debugging.

For simplicity, inspector modules should register themselves into debugger core and do not return anything. So attaching a module is simply a <code>require</code> or <code>dofile</code> call. This violates the ''no global side effects'' policy of Lua modules, but for debugging purposes, I think we can live with that :)

= Probing objects =

First, we need to know what object we want to inspect. For this, two distinct modes are available.

== Metatable matching ==

This matching mode works by associating an inspector function to a given metatable. It requires you to know in advance what metatables are expected (for example, all your ''Car'' objects share the same metatable).

For this we simply add our inspector function to <code>debugger.introspection.inspectors</code> table with the metatable as key. Your module should look like:

<source lang="lua">    local introspection = require 'debugger.introspection'
    local function my_inspector(name, value, parent, fullname)
      -- my inspection logic
    end
    
    introspection.inspectors[my_metatable] = my_inspector</source>

== Generic probe ==

Some libraries use a lot of different metatables or create them on-the-fly. In this situation, it can became tricky to list all possible metatables for a given object family.

To handle such cases, you can add a probe function that will be called for any value (table or userdata) when a specific metatable inspector cannot be found.

As you can imagine, this method is munch slower than previous one so do not abuse this feature by attaching many such probes or making expensive processing on them.

Generic probes are added to debugger with <code>debugger.introspection.add_probe</code> function. A typical module should look like:

<source lang="lua">    local introspection = require 'debugger.introspection'
    local function my_inspector(name, value, parent, fullname)
      if is_my_object(value)
        -- my inspection logic
      end
      return nil -- unknown object
    end
    
    introspection.add_probe(my_inspector)</source>

= Inspection logic =

Now we’re able to detect values to inspect, let’s generate our properties. This what inspector functions do.

These functions generate properties that will be sent to IDE with the <code>debugger.introspection.property</code> function. They are called with a value to inspect and must generate a debugger property for it (and possibly its children for complex data structures).

Like we saw in previous part, inspector functions always takes 4 parameters and their return values are defined too.

These arguments are:

* '''name''' is the property name that appear on the ''name'' column of debugger view. This name is usually given by parent object (that is the inspector that called your inspector)
* '''value''' is the actual value to inspect
* '''parent''' is the parent property of the value (a debugger data structure, not <code>value</code>’s parent !)
* '''fullname''' this is the expression that will be evaluated by the debugger to get <code>value</code> again (either to query its children or to set it).

== Generating properties ==

The main task of the inspector is to call <code>debugger.introspection.property</code> to generate a property corresponding to <code>value</code>. This function will check if the value should be sent to IDE, depending on this, it returns:

* A ''Property'' object if the property have be sent to IDE, in this case you can inspect children properties (if any) and return that object to caller
* <code>nil</code> if value will not be sent to IDE (too deep recursion for instance). In this case, you should not try to inspect children and return a <code>nil</code> value immediately.

The inspector that is used for most primitive types is simply:

<source lang="lua">    local function default_inspector(name, value, parent, fullname)
      return introspection.property(name, type(value), tostring(value), parent, fullname)
    end</source>

== Inspecting children properties ==

Now let’s inspect more complex types with child properties. This is done by either by calling <code>debugger.introspection.property</code> more than once if you want to fully handle children inspection or by calling <code>debugger.introspection.inspect</code> to dispatch an arbitrary value to appropriate inspector.

As you can imagine, the <code>parent</code> of these sub-properties is the object returned by <code>debugger.introspection.property</code>. For <code>fullname</code> (the expression used to retrieve the value in future calls), you can use <code>debugger.introspection.make_fullname</code> to generate a valid Lua expression However, this method works only if your property can be accessed by index.

If the value is retrieved by some other way (like calling a <code>get_my_prop</code> function) there is currently no supported way to handle it, see ''Limitations'' section).

Let’s show an example with a ''Car'' that have ''x'', ''y'', ''z'' and ''speed'' properties that we want to expose and some internal ''id'' that we will use only for string representation:

<source lang="lua">    local function car_inspector(name, value, parent, fullname)
      local prop = introspection.property(name, 'Car', 'Car #' .. value.id, parent, fullname)
      -- do not inspect children if the parent is not generated
      if not prop then return nil end
      
      -- use regular introspection for x,y,z
      introspection.inspect('x', value.x, prop, introspection.make_fullname(fullname, 'x'))
      introspection.inspect('y', value.y, prop, introspection.make_fullname(fullname, 'y'))
      introspection.inspect('z', value.z, prop, introspection.make_fullname(fullname, 'z'))
      
      -- generate directly speed property
      introspection.property('speed', 'Speed', tostring(value.speed), prop, introspection.make_fullname(fullname, 'speed'))
      
      return prop
    end</source>

= Samples =

Write a module for a debugger can be tricky, that is why we thought samples could help. We will continue on the ''car'' use case. Here the idea is to provide debugger display modules for the following code.

<source lang="lua">
  local C = {}
  local mt = {
    __index = function(self, key)
      return self[string.format('_%s',key or '')] or 'Nameless'
    end
  }
  local id = 1
  function C.newcar(name)
    local car = { _id = id , _name = name , _type = 'Car' }
    id = id + 1
    setmetatable(car, mt)
    return car
  end
  
  return C
</source>
<center><small>car.lua</small></center>

<source lang="lua">
  if os.getenv('DEBUG_MODE') then
    require 'carintrospection'
  end
  
  local car = require 'car'
  local c = car.newcar('Chevrolet')
  print ( c.name )

</source>
<center><small>main.lua</small></center>

== Metatable matching ==

Some insight about writing a ''metatable matching'' display module. This is the ''faster'' method as it is call only when adequate.

<source lang="lua">
  local introspection = require 'debugger.introspection'
  
  local function car_inspector(name, value, parent, fullname)
    local carlabel = string.format('%s (car:%d)', value.name, value.id)
    local property = introspection.property(name, 'Car', carlabel, parent, fullname)
    -- Inspect children
    introspection.inspect('id', tostring(value.id), property, introspection.make_fullname(fullname, 'id'))
    introspection.inspect('name', value.name, property, introspection.make_fullname(fullname, 'name'))
    return property
  end
  
  local car = require 'car'
  local mt  = getmetatable(car.newcar('Debugger inspector'))
  if mt then
    introspection.inspectors[ mt ] = car_inspector
  end
</source>

== Generic probe ==

Here is a ''generic probe'' display module for given sample. This method is applicable to a wider range of use cases. Use it with caution, as it call for each value displayed by the debugger.

<source lang="lua">
  local introspection = require 'debugger.introspection'

  local function carprobe(name, value, parent, fullname)

    if value._type ~= 'Car' then
      return nil
    end

    local carlabel = string.format('%s (car:%d)', value.name, value.id)
    local property = introspection.property(name, 'Car', carlabel, parent, fullname)
    -- Inspect children
    introspection.inspect('id', tostring(value.id), property, introspection.make_fullname(fullname, 'id'))
    introspection.inspect('name', value.name, property, introspection.make_fullname(fullname, 'name'))
    return property
  end

  introspection.add_probe( carprobe )
</source>

= Limitations =

As we’ve seen before, the debugger engine is currently unable to use anything else than indexation to retrieve values or set values after inspection phase, so you will be able to use this feature only if your userdata (or table) implements <code>__index</code> metamethod correctly.

For setting data, the debugger makes basically <code>dostring(fullname .. ' = ' .. newvalue)</code> in a sandboxed environment. So, <code>__newindex</code> metamethod must be implemented if you want to modify data.