How to use the remote REPL of PycaWM
------------------------------------

1) Introduction

The remoteREPL gives access to a python shell where you can inspect or modify the window manager.

To use the REPL, you must add the `RemoteREPL' plugin to PycaWM, and use the `pycarepl' program to connect to the REPL.

The `pycarepl' program is stored in the directory `utils' of your PycaWM's installation path. (The installation path is `/usr/lib/python$(version)/site-packages/pycawm' if you have not modified the Makefile.)

2) Technical details

The REPL is a window manager plugin. The REPL client (i.e. `pycarepl') communicates with the plugin via a Unix socket. When the client connects to the REPL, the window manager creates a new thread for this client. The REPL uses the `code.py' default module of Python.

3) User guide

First, add the plugin to your configuration file:

"wm.add_plugin(RemoteREPL)"

Note: the `RemoteREPL' class must be imported before using it. Add this line at the top of the configuration file: "from pycawm.plugins import RemoteREPL"

Next, launch the window manager.

Then, execute the `pycarepl' program. If no REPL was found, the program will print an error message.

`pycarepl' can take some options as parameters. To show these options, use the `pycarepl -h' command.

If no error was reported to you, you should now be inside a python shell. This shell has completion support, so you can press [Tab] to have your variables completed.

You can now access your PycaWM running instance. To do that, look for the instance name in your configuration file:

"wm = PycaWM(nb_desktops=3)"

Here, the instance name is `wm'.
You can now play with your window manager inside this shell:
>>> len(wm.desktops)
3 # there are 3 desktops (as in the configuration file)
>>> len(wm.clients)
2 # and 2 clients
>>> for c in wm.clients: print c.name
Calculator # we have got an xcalc
user@host: ~/prog # and an xterm
>>> wm.clients[0].close() # close the xcalc
>>> len(wm.clients)
1 # only one remaining client

There are locking mechanisms in the REPL, so the REPL will work flawlessly with the Xlib functions.

You can do almost anything you like in the REPL: add new plugins, new shortcuts, modidy the window manager functions by using the hook system, ...
