Decorator task syntax

[bmatsuo]

A part of #32

The existing task syntax is a little weird and not very flexible. A decorator based syntax would be a little weirder, but more flexible.

local task = require('lark.task')

foo = lark.task .. function()
    lark.run("foo.o")
    lark.exec('gcc', '-o', 'foo', 'foo.o')
end

mypatt = lark.pattern[[%.o$]] .. function(ctx)
    local name = task.get_name(ctx)
    local src = string.gsub(name, '%.o$', '.c')
    lark.exec('gcc', '-c', src)
end

Note that the "lark.task" module only needs to be imported to get the task names, patterns, and params. Simple named tasks do not need the underlying module to be imported. Furthermore, lark.task can be the loaded module if the module table is callable through a metatable.

So, the task.get_name(ctx) call could be changed to lark.task.get_name(ctx) and the require call could be removed. Alternatively "lark.task" could be loaded inside the mypatt task. But I think the form above is probably the simplest and preferred.

Migrating existing projects

Once project maintainers are familiar with the new "lark.task" module they should add the following lines to the main lark.lua file in their projects.

local task = require('lark.task')
lark.task = task.create

Edit (2016-04-30): The exact expressions were changed in 7a898ae. The old method is not directly incompatible with the now suggested way to do things. So any previous migrations should be OK. Although their code may not exactly match what is recommended now.

These expressions must be evaluated before any tasks are defined so it is not a good idea to put it in a file under lark_tasks/.

[bmatsuo]

I think this has to be delayed until v0.5.0. The "lark.task" module can be released in v0.4.0, which allows the lark_tasks/ files to be updated to use a new syntax (dependency due to travis-ci). At this point lark.task will be switched (breaking things =).

[bmatsuo]

It occurred to me that the proper way to prepare for this change within a project is to add one line to the ~top of lark.lua.

lark.task = require('task')

This is the core of the change that will take place at the switch to v0.5.0.

Edit (2016-04-30): This is not correct anymore. It was decided that lark.task alias task.create directly for documentation purposes.

[bmatsuo]

The note in README.md will stay through the v0.6.0-dev cycle to keep anyone who still needs to know informed.