Programming in Lua

The library libipelua implements Lua bindings for many classes in Ipelib. The bindings are available in Lua ipelets, as well as in Lua scripts executed using the ipescript program.

These pages document the Lua bindings to Ipelib:

- Lua bindings for geometric objects
- Lua bindings for objects and attributes
- Lua bindings for Document, Page, and StyleSheet

When writing Ipelets in Lua, you have access to additional methods provided by the Ipe program itself:

- Lua bindings for Ipe
- Lua bindings for dialogs and menus

# Examples

Here is a Lua script that reads an Ipe document and then recenters each page on the paper. You can run this script as "ipescript recenter".

    -- recenter.lua
    -- center objects on each page of the document

    if #argv ~= 2 then
      io.stderr:write("Usage: ipescript recenter <inputfile> <outputfile>\n")
      return
    end

    inname = argv[1]
    outname = argv[2]

    doc = assert(ipe.Document(inname))

    -- make sure we have size information for text
    assert(doc:runLatex())

    layout = doc:sheets():find("layout")
    fs = layout.framesize

    for i,p in doc:pages() do
      box = ipe.Rect()
      for j = 1,#p do
        box:add(p:bbox(j))
      end
      nx = (fs.x - box:width()) / 2
      ny = (fs.y - box:height()) / 2
      trans = ipe.Vector(nx, ny) - box:bottomLeft()
      m = ipe.Translation(trans)
      for j = 1,#p do
        p:transform(j, m)
      end
    end
    doc:save(outname)

The following script prints out all the gradients defined in a document:

    -- -*- lua -*-

    function printTable(t, indent)
      for k in pairs(t) do
        local v = t[k]
        if type(v) == "table" then
          print(indent .. k .. ":")
          printTable(v, "  " .. indent)
        else
          print(indent .. k .. ": " .. tostring(v))
        end
      end
    end

    if #argv ~= 1 then
      io.stderr:write("Usage: ipescript show-gradients <ipe-document>\n")
      return
    end

    local figname = argv[1]
    local doc = assert(ipe.Document(figname))
    local s = doc:sheets()

    for _,w in ipairs(s:allNames("gradient")) do
      print("Gradient: ", w)
      local g = s:find("gradient", w)
      printTable(g, "  ")
    end

And here is a script that shows how to add a gradient to a document (the same technique works for tilings and effects):

    -- -*- lua -*-

    if #argv ~= 1 then
      io.stderr:write("Usage: ipescript add-gradient <ipe-document>\n")
      return
    end

    local figname = argv[1]
    local doc = assert(ipe.Document(figname))

    local sheet = [[<ipestyle>
    <gradient name="ball" type="radial" coords="-4 10 2 0 0 18">
     <stop offset="0" color="1 1 0"/>
     <stop offset="1" color="0 1 0"/>
    </gradient>
    </ipestyle>]]

    local ts = ipe.Sheet(nil, sheet)

    local s = doc:sheets()
    for i = 1,s:count() do
      print(s:sheet(i):name())
    end

    -- add the gradient to the sheet on top of the stack
    -- in general it is not a good idea to change the "basic" sheet,
    -- better verify if a custom sheet for gradients exists already
    -- and create it if not.
    s:sheet(1):addFrom(ts, "gradient", "ball")
    assert(doc:runLatex())
    doc:save(figname .. ".new.ipe")

For more examples, have a look at the scripts in your Ipe installation, such as add-style.lua or update-styles.lua.