Sputnik: LuaUsers:DecoratorsAndDocstrings

## Pattern: Decorators, Annotators and Docstrings

At times we want to associate some metadata with an object, such as the documentation or type information on the object.  It may be possible to store this in a field inside the object, thereby modifying the implementation of the object, but that may be something to avoid, especially if the object belongs to someone else (information hiding).  In fact, it might not be possible to modify the object if the object is a function or a read-only table.

One solution is basically to create a global table that maps objects (as keys) to their annotations (as values).  By definition, objects have unique identities and therefore can serve as unique keys in a table.  In this way, the objects themselves are not modified.  This interferes a bit with garbage collection since the global table holds references to the objects, but we can use a "weak table" in Lua for this purpose (see the book _Programming in Lua_ in [[LuaUsers:LuaBooks]]).

Here's a way to apply docstrings[(c)](http://en.wikipedia.org/wiki/Docstring) to Lua objects.

local docstrings = setmetatable({}, {__mode = "kv"})
    
    function document(str)
      return function(obj) docstrings[obj] = str; return obj end
    end
    
    function help(obj)
      print(docstrings[obj])
    end
    
    document[[Print the documentation for a given object]](help)
    document[[Add a string as documentation for an object]](document)
    
    f = document[[Print a hello message]](
      function()
        print("hello")
      end
    )
    f()
    help(f)
 
Note: garbage collection can fail if the annotation is an object that refers back to the object it annotates (see [[LuaUsers:GarbageCollectingWeakTables]]).

A somewhat similar pattern is applied in Perl "inside out objects".

This pattern can be applied to other situations in which you wish to apply metadata to objects without making any change to those objects.  
These include function decorators as used in Python [(a)](http://www.python.org/dev/peps/pep-0318/) [(b)](http://www.ddj.com/184406073).

The following alternative syntax for applying function decorators to functions could be preferable:

random =
      docstring[[Compute random number.]] ..
      typecheck("number", '->', "number") ..
      function(n)
        return math.random(n)
      end

The function decorators can be implemented basically in this way:

mt = {__concat =
      function(a,f)
        return function(...)
          print("decorator", table.concat(a, ","), ...)
          return f(...)
        end
      end
    }
    
    function typecheck(...)
      return setmetatable({...}, mt)
    end
    
    function docstring(...)
      return setmetatable({...}, mt)
    end
 
The use of an operator (`..`) here between the function decorator and the function avoids the parenthesis around the function and makes chaining decorators nicer.  We want this operator to have right associativity, so the only choices for this operator are `..` and `^`.

See also LuaTypeChecking for specific use of decorators for expressing function parameter and return types.

--DavidManura, 2007-02

This page is based on [http://lua-users.org/wiki/DecoratorsAndDocstrings](http://lua-users.org/wiki/DecoratorsAndDocstrings).

Page Name (for URL)

Don't put anything here

Page Title

Breadcrumb Text

Page Content

Advanced Fields

About This Edit