Using Lua scripts in conky: How does a lua script work

This tutorial has been written by mrpeachy and was posed on Crunchbang all credit goes to him. The tutorial was slightly adapted for conky 1.10 and onwards. The Lua syntax did not change between conky 1.9 and 1.10 so the scripts themselves are usable in both.

The tutorial could use a rewrite with proper punctuation and sometimes more explanation, if you feel like helping out please feel free to edit/expand this tutorial! Much appreciated.

The tutorial is friendly for people new to programming, besides this tutorial a good learning point are Lua scripts from other people.

Using Lua scripts in conky (Part 1)

How does a lua script work?

In conky there are several lua related settings and objects primarily for using lua script there are 2 settings:

lua_load
lua_draw_hook

these come in the conky.config={ ... } section.

lua_load is where you give conky the location of the script to use

eg. lua_load = '/home/username/scripts/script.lua'

so that one is pretty easy to understand the second line lua_draw_hook (can be lua_draw_hook_pre or lua_draw_hook_post) tells conky which function to run from the lua script that was loaded.

This takes a little more explanation.

---

A bare bones lua script for use in conky might look like this.

--this is a lua script for use in conky
require 'cairo'

function conky_main()
    if conky_window == nil then
        return
    end
    local cs = cairo_xlib_surface_create(conky_window.display,
                                         conky_window.drawable,
                                         conky_window.visual,
                                         conky_window.width,
                                         conky_window.height)
    cr = cairo_create(cs)
    local updates=tonumber(conky_parse('${updates}'))
    if updates>5 then
        print ("hello world")
    end
    cairo_destroy(cr)
    cairo_surface_destroy(cs)
    cr=nil
end

---

Line by line we have:

--this is a lua script for use in conky

Anything preceded by -- is a comment in lua.

You can write a longer comment section starting with --[[ and ending with ]] like so:

--[[ this is a comment
and it can span multiple
lines until you end it with ]]

---

Next we have

require 'cairo'

cairo is the name of the graphics library that lua will be using to get all those fancy graphics showing up in conky.

This line loads up that library and then

function conky_main()

This is our main function and the one we will set in the conkyrc for lua_draw_hook. If you open a lua script and not sure which function to set in conkyrc, look for conky_ in the function name.

---

The next a couple lines are standard setup lines and are ONLY required for the main function that will be called in the conkyrc:

    if conky_window == nil then
        return
    end
    local cs = cairo_xlib_surface_create(conky_window.display,
                                         conky_window.drawable,
                                         conky_window.visual,
                                         conky_window.width,
                                         conky_window.height)
    cr = cairo_create(cs)

This is creating the "surface" onto which the text and graphics will be drawn.

If you want the lua script to draw anything to conky you need these setup lines.

---

Then we have lines about conky updates:

    local updates=tonumber(conky_parse('${updates}'))
    if updates>5 then

These lines are only important if you plan on reading cpu% in the lua script, but its generally a good idea to have these lines anyway (one less thing to cause an error).

NOTE If you are not going to be using conky_parse("${cpu}") then by all means remove these lines BUT if you remove the line that says if updates>5 then you MUST also remove the matching end from lower down in the script.

The use of conky_parse (you can get the output of any conky object into lua this way):

cpu=conky_parse("${cpu}")
memory=conky_parse("${memperc}")
home_used=conky_parse("${fs_used /home}")

You can even use things like if_ objects from conky using conky_parse, which can be useful as switches:

internet=conky_parse("${if_up wlan0}1${else}0${endif}")

now internet will have a value of 1 or 0 depending on the outcome of if_up

NOTE The value of updates in the example script is the number of times that conky has updated as set by this line in your conkyrc

update_interval = 1,

It was set using conky_parse to read the conky object ${updates}, so if you have your interval set to 1 (i.e. every second), you are going to wait 5 seconds from the time conky starts to the time you see anything from lua if you are using the if updates>5 line.

If update_interval was 10, you would be waiting 60 seconds.

Clearly you don't want to wait that long to see your lua.

---

So next we have the body of the script, the stuff we want the lua script to do:

        print ("hello world")

The command "print ()" will not show anything up in conky, but will be printed in the terminal, so always run conky from the terminal when testing out a lua script!

print() can be a very useful way of finding error in the script if things aren't working.

---

Then we come to closing out the function

    cairo_destroy(cr)
    cairo_surface_destroy(cs)
    cr=nil

These lines do some clean up. One thing that lua can do is to eat up memory over time, and these lines help to avoid that.