[ANN] Winapi - a minimal but useful Windows API binding

[steve donovan <steve.j.donovan@...>]

Hi all,

There was a recent discussion about how nice it would be if the
'hundred or so' common Windows API functions were available as a
module. Well, this is not quite a hundred, but winapi provides a good
start [1].

 * Enumerating and accessing windows, including sending keys.
 * Enumerating processes and querying their program name, memory used, etc.
 * Reading and Writing to the Registry
 * Copying and moving files, and showing drive information.
 * Launching processes and opening documents.
 * Support for Windows named pipes (server and client).
 * Monitoring filesystem changes.

This release is intended to provide the basic tools for managing
Windows, usually through the console but it does work with GUI
applications. winapi.execute is useful and probably worth the price of
entry alone, because it does not do the dreaded flashing black box
when spawning processes; it returns both the return code and the
collected output, so also serves as an io.popen replacement for most
purposes.

Apart from just a quiet execute, it provides a fuller process
management API. For instance, this runs two Lua scripts in parallel:

require 'winapi'
local t = os.clock()
local P = {}
P[1] = winapi.spawn 'lua slow.lua'
P[1] = winapi.spawn 'lua slow.lua'
winapi.wait_for_processes(P,true)
print(os.clock() - t)

(This was only slightly slower than running one, so clearly my i3 is
effectively a two-processor machine)

These process objects also allow you to capture an interactive process
and both write to and read from it.

The support for monitoring native filesystem change events is useful,
and AFAIK not found elsewhere in Lua for Windows. (there is linotify
and LuaFAM for other systems)

A lot of the operations are non-blocking (e.g there is an async read)
and run in background threads.  Currently this is fire-and-forget, but
I'm thinking of making such functions return a thread object so that
they can be terminated and associated resources cleared. So this
release is likely to be fairly leaky for long-lived processes.

One criticism is that it's just ASCII, but I wanted to ask advice
about the best way to proceed. One approach is to work internally with
widechar strings, but assume that all Lua strings are UTF-8. If this
seems the best way forward, I'm happy to implement it.

The readme is available at [2], and the API documentation is at [3].
This was done using ldoc, which is my (still experimental)
documentation tool I've been using for Penlight.

For those who like to browse the source, winapi.c looks like it was
generated by a machine because it was (#line directives are a dead
giveaway). The real source is winapi.l.c and it was preprocessed using
LuaMacro in its new C mode.

A binary Lua-for-Windows compatible zip is at [4], and a source-only
zipball is at [5].  It builds happily with MSVC and mingw, both 32-bit
(Windows XP SP3) and 64-bit (Windows 7).

steve d.

[1] https://github.com/stevedonovan/winapi
[2] http://stevedonovan.github.com/winapi/
[3] http://stevedonovan.github.com/winapi/api.html
[4] http://stevedonovan.github.com/files/winapi-1.0-lfw.zip
[5] http://stevedonovan.github.com/files/winapi-1.0.zip