Chapter 1
Introduction

Rumai is a Ruby interface to the wmii window manager.

What’s new? — history of project releases.
Source code — obtain via Git or browse online.
API reference — documentation for source code.
Project home — the Rumai project home page.

To get help or provide feedback, simply contact the author(s).

Features
Etymology
License
Credits
Related works

1.1 Features

Rumai is exciting because:

It excels at dynamic arrangement of clients, columns, views, and tags.
It provides an interactive shell for live entertainment and experimentation.
It provides a pure Ruby client for the 9P2000 protocol, upon which wmii’s IXP file-system interface is built.

1.2 Etymology

The word “wmii” is difficult to pronounce because it is an abbreviation, not an acronym. If we were to treat it as an acronym, the closest pronounciation would be, in my mind, something like “vim-eye”.

Since this is a Ruby library, I added a “roo” and worked it through:

vim-eye
roo-vim-eye
roovm-eye

And thus we get “Rumai”.

1.3 License

(the ISC license)

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

1.4 Credits

Rumai is made possible by contributions from users like you:

Christoph Blank
Michael Andrus
Simon Hafner

Chapter 2
Setup

Requirements
Installation
Package contents
Version numbers

2.1 Requirements

Your system needs the following software to run Rumai.

Software	Description	Notes
Ruby	Ruby language interpreter	Version 1.8.6, 1.8.7, 1.9.1 have been tested successfully.
RubyGems	Ruby packaging system	Version 1.3.5 or newer is required.
wmii	Window manager	Version 3.6 or newer is required.

2.2 Installation

You can install Rumai by running this command:

gem install rumai

To check whether the installation was sucessful, run this command:

rumai --version

If the installation was successful, you will see output like this:

project: Rumai
version: 3.2.0
release: 2009-11-17
website: http://snk.tuxfamily.org/lib/rumai/
install: /home/sun/src/rumai

If you do not see such output, you may ask the author(s) for help.

2.3 Package contents

You will see the following items inside Rumai’s installation directory, whose path you can determine by running this command:

rumai --version

bin/
- rumai — the main Rumai executable.
lib/
- rumai.rb — the main Rumai library.
- rumai/
  - ixp.rb - pure Ruby client for the 9P2000 protocol
doc/
- api/ — API reference documentation.
- index.erb — source of this user manual.
LICENSE — copyright notice and legal conditions.
CREDITS — attribution of project contributors.

2.4 Version numbers

Rumai releases are numbered in major.minor.patch form according to the RubyGems rational versioning policy, which can be summarized as follows:

What increased in the version number?	Is backward compatible?	Has new features?	Has bug fixes?
What increased in the version number?	The increase indicates that the release:
major	No	Yes	Yes
minor	Yes	Yes	Yes
patch	Yes	No	Yes

Chapter 3
Usage

Concepts
Command-line interface
Tutorial
Scripting your wmiirc

3.1 Concepts

Client

Any graphical program (a “window”) that is running in your X session.

Tag

An arbitrary label that can be associated with one or more clients.

View

A visualization of a particular tag. A “workspace”.

Area

A region inside a view. It can contain clients.

Managed area, column

An area whose clients cannot overlap each other.

Floating area

An area whose clients:

can overlap each other
float above clients in the managed areas

3.2 Command-line interface

When you run this command:

rumai --help

You will see this output:

Rumai - Ruby interface to the wmii window manager

This program is an interactive shell for Rumai.

Usage:

  rumai [Options]
  rumai [Options] -- Arguments

  Arguments:  Command-line options and arguments that should
              be passed to `irb`, the interactive Ruby shell.

Options:

      --manual, -m:   Show the user manual
  --locale, -l <s>:   Set preferred language
     --version, -v:   Print version and exit
        --help, -h:   Show this message

Interactive shell

When you run this command:

rumai

An IRB session will begin, showing you a command prompt like this:

irb(Rumai):001:0>

The irb(Rumai) token in the command prompt indicates that commands will be evaluated inside the Rumai module. As a result, you can omit the “Rumai” prefix from your commands if you wish.

For example, to get the current client object, you can type curr_client instead of having to type Rumai.curr_client at the prompt. Both commands achieve the same effect.

The next thing to note is that tab completion is enabled by default. So you can type part of a command and press the TAB key to see a list of possible completions.

3.3 Tutorial

Now that you know how to start the interactive shell, let us walk through a quick demonstration that highlights the main features of Rumai. You can follow along by copying & pasting the presented commands into the interactive shell.

Automated client arrangement
Multiple client grouping
Easy column manipulation
Easy client manipulation
Traversing the file system
Available commands

3.3.1 Automated client arrangement

Launch a few terminals so that we have something to work with:

colors = %w[ red green blue black orange brown gray navy gold ]
colors.each {|c| system "xterm -bg #{c} -title #{c} -e sh -c read &" }

Arrange all clients in a grid:

curr_view.arrange_in_grid

Arrange all clients in a diamond shape:

curr_view.arrange_in_diamond

Arrange all clients like LarsWM does:

curr_view.arrange_as_larswm

Close the terminals we launched earlier:

terms = curr_view.clients.select {|c| colors.include? c.label.read }
terms.each {|c| c.kill }

3.3.2 Multiple client grouping

Launch a few terminals so that we have something to work with:

colors = %w[ red green blue black orange brown gray navy gold ]
colors.each {|c| system "xterm -bg #{c} -title #{c} -e sh -c read &" }

Add the red, green, and blue terminals into the “grouping”:

terms = curr_view.clients.select {|c| %w[red green blue].include? c.label.read }
terms.each {|c| c.group }

You should now see a new button labelled as ”@” on the left-hand side of wmii’s bar, indicating that there is now a new view labelled ”@” in wmii. Let us inspect what clients this mysterious view contains:

v = View.new "@"
puts v.clients.map {|c| c.label.read }

Aha! The mysterious view contains the red, green, and blue clients we recently “grouped”. Thus, by adding a client to the “grouping”, we are simply tagging the client with the ”@” token.

Now that we have put some clients into the “grouping”, let us move all clients in the grouping to the floating area in the current view:

grouping.each {|c| c.send "toggle" }

Neat! Let us bring them back into the managed area:

grouping.each {|c| c.send "toggle" }

Close the terminals we launched earlier:

terms = curr_view.clients.select {|c| colors.include? c.label.read }
terms.each {|c| c.kill }

In summary, you can select multiple clients (by adding them to the “grouping”) and perform operations on them. This is useful when you want to do something with a group of clients but do not want to manually focus one, perform the action, focus the next one, and so on.

Another important aspect is that selected clients stay selected until they are unselected. This allows you to continue performing tasks on the selection without having to reselect the same clients after every operation.

3.3.3 Easy column manipulation

Launch a few terminals so that we have something to work with:

colors = %w[ red green blue black orange brown gray navy gold ]
colors.each {|c| system "xterm -bg #{c} -title #{c} -e sh -c read &" }

You can insert a group of clients to the top, bottom, or after the currently focused client of any column using Array-like methods.

Give each client its own column (one client per column):

curr_view.each_column {|c| c.length = 1 }

Put (at most) three clients in every column:

curr_view.each_column {|c| c.length = 3 }

Move the red, green, and blue clients into the floating area:

rgb = %w[red green blue]
terms = curr_view.clients.select {|c| rgb.include? c.label.read }
curr_view.areas[0].push terms

Slurp all floating clients into the last column:

list = curr_view.areas
a, b = list.first, list.last
b.concat a

Set the last column’s layout to stacking mode:

b.layout = 'stack'

Move the red, green, and blue clients to the top of the second column:

curr_view.areas[2].unshift terms

Move the red, green, and blue clients to the bottom of the third column:

curr_view.areas[3].push terms

Close the terminals we launched earlier:

terms = curr_view.clients.select {|c| colors.include? c.label.read }
terms.each {|c| c.kill }

3.3.4 Easy client manipulation

Launch a few terminals so that we have something to work with:

colors = %w[ red green blue black orange brown gray navy gold ]
colors.each {|c| system "xterm -bg #{c} -title #{c} -e sh -c read &" }

Obtain a reference to the red client:

red = curr_view.clients.find {|c| c.label.read == "red" }

Show the red client’s current tags:

red.tags

Add the “foo” and “bar” tags to the red client:

red.tag "foo", "bar"

Remove the “bar” tag from the red client:

red.untag "bar"

Do complex operations on the red client’s tags:

red.with_tags { concat %w[a b c]; push 'z'; delete 'c' }

Focus the next client after the red client:

red.next.focus
curr_client == red.next #=> true

Notice that by focusing a client, we make it the current client.

Focus the red client on a different view:

orig = curr_view
v = red.views.last
red.focus v

Return to the original view:

orig.focus

Send the red client to the last column:

red.send curr_view.areas.last

Close the terminals we launched earlier:

terms = curr_view.clients.select {|c| colors.include? c.label.read }
terms.each {|c| c.kill }

3.3.5 Traversing the file system

Show the root node of wmii’s IXP file system:

fs

Show the names of all files at the root level:

fs.entries

Show the parent of the root node:

fs.parent

Show the children of the root node:

fs.children

Navigate into to the /lbar/ directory:

n1 = fs.lbar
n2 = fs['lbar']
n1 == n2 #=> true
left_bar = n1

Notice that you can traverse the file system hierarchy by simply calling methods on node objects. Alternatively, you can traverse by specifying an arbitrary sub-path (relative path) using the [] operator on a node.

Create a new temporary button:

b = left_bar.rumai_example # path of new button
b.exist? #=> false
b.create
b.exist? #=> true

You should now see an empty button on the left-hand side of the wmii bar.

Color the button black-on-white and label it as “hello world”:

content = "#000000 #ffffff #000000 hello world"
b.write content
b.read == content #=> true

Remove the temporary button:

b.remove
b.exist? #=> false

3.3.6 Available commands

Refer to the Rumai module in the API documentation for a complete list of commands (method calls, really) and their documentation.

3.4 Scripting your wmiirc

One important application of Rumai is the support of Ruby-based wmiirc configuration files. For a solid example of such application, take a look at my personal wmiirc.

Chapter 4
History

Version 3.2.0 (2009-11-17)
Version 3.1.1 (2009-11-16)
Version 3.1.0 (2009-10-02)
Version 3.0.0 (2009-05-11)
Version 2.1.0 (2009-05-09)
Version 2.0.2 (2009-02-26)
Version 2.0.1 (2009-01-25)
Version 2.0.0 (2008-02-04)
Version 1.0.0 (2008-01-26)

4.1 Version 3.2.0 (2009-11-17)

This release adds a new automated view arrangement, simplifies the IXP transport layer, and cleans up the code and API documentation.

New features

Add Rumai::View#arrange_in_stacks automated view arrangement.
Convert :stack and :max arguments into wmii 3.9 syntax in Rumai::Area#layout=.

Bug fixes

Rewrote IXP transport layer (Rumai::IXP::Agent) to not use a background thread, according to the XCB cookie approach.

Housekeeping

Clean up some code and API docs.
Reduce amount of string concatenation in Struct#to_9p.

4.2 Version 3.1.1 (2009-11-16)

This release fixes bugs in automated view arrangements and updates the user manual.

Thank you

Nathan Neff reported the client ordering bug in automated view arrangements.

Bug fixes

The relative order of clients was not being preserved during view arrangements.
Focus on the current view was lost after automated view arrangement was applied if the current view was not the first view on which the initially focused (before the automated arrangement was applied) client appeared.

4.3 Version 3.1.0 (2009-10-02)

This release adds new methods, fixes some bugs, and revises the manual.

New features

Add Client#float methods to manipulate floating status.
Add Client#manage methods to manipulate managed status.
The Client#tags= method now accepts ’~’ and ’!’ tag prefixes.

Bug fixes

There is no View#move_focus method, only View#select.
Assertion failure in test suite because all files in /rbar (inside wmii’s IXP filesystem) contain an automatic color header when read.

Housekeeping

Use simpler Copyright reminder at the top of every file.
Open source is for fun, so be nice: speak of “related works” instead of “competitors”.

4.4 Version 3.0.0 (2009-05-11)

This release revises method names, adds new methods, and fixes a bug.

Incompatible changes

Rename #toggle_ methods to use ! suffix in their names.
Rename #float methods to #floating.
Rename View#floater method to View#floating_area.

New features

Add Client#stick methods to manipulate sticky status.
Add Client#fullscreen methods to manipulate fullscreen status.
Add Client#slay method which is a forceful version of #kill.
Add View#select method to move focus relatively inside a view.
Add Area::floating method for symmetry with Area::curr.
Add View#managed_area aliases for View#column methods.

Bug fixes

Fix error when unzooming clients from temporary view.
Fix code that launches temporary terminals in Tutorial.

Use the /bin/sh version of the read command for portability.

Housekeeping

Use Client#send instead of #swap in automated arrangements because it causes less traffic on /event/.
Add old release notes from blog to user manual.

4.5 Version 2.1.0 (2009-05-09)

This release improves client arrangement, fixes several bugs, and cleans up the code.

Thank you

Simon Hafner reported several bugs.
Michael Andrus verified bug fixes.

New features

Focus is now restored on the initially focused client after applying Automated client arrangements.
The push(), insert(), and unshift() instance methods of the Rumai::Area class now preserve the order of inserted clients.
The Rumai::View#arrange_in_grid() method now accepts 1 as a parameter. This invocation causes every column to contain at most 1 client.

Bug fixes

Fix error caused by focusing the top/bottom client in the destination area before sending new clients into that area.
Fix error when importing clients into an empty area.

Housekeeping

Use snake_case instead of camelCase for variable names.
Add copyright notice at the top of every file.
Plenty of code formatting and beautification.

4.6 Version 2.0.2 (2009-02-26)

This release fixes a connection bug.

Thank you

Simon Hafner reported and helped debug the $DISPLAY bug.

Bug fixes

wmii omits the fractional portion of $DISPLAY in its socket file path. Rumai was trying to connect with the entire $DISPLAY value (including the fractional portion) and thus could not find wmii’s socket file.

4.7 Version 2.0.1 (2009-01-25)

This release simplifies project administrivia using Inochi, improves the unit tests, and revises the user manual.

Bug fixes

The lib/rumai/ixp/message.rb library’s unit test would fail if /rbar/status did not already exist in wmii.

Housekeeping

Store IXP socket address in Rumai::IXP_SOCK_ADDR.
Added missing test cases for (TR)create and (TR)remove messages in the unit test for the lib/rumai/ixp/message.rb library.

4.8 Version 2.0.0 (2008-02-04)

This release adds support for wmii 3.6, improves the performance of the IXP library, and fixes some bugs.

Thank you

Christoph Blank tested Rumai 1.0.0 under wmii 3.6 and reported bugs.

Incompatible changes

wmii version 3.6 or newer is now required.
The Rumai::IXP::Agent::FidStream#read_partial method has been replaced by Rumai::IXP::Agent::FidStream#read(true) for efficiency.
- The Rumai::IXP::Agent::FidStream#write method no longer writes to the beginning of the stream. Instead, it writes to the current position in the stream.
- The Rumai::View#floating_area method has been renamed to Rumai::View#floater for brevity.

New features

Added several more methods (such as rewind, pos=, eof?, and so on) from Ruby’s IO class to the Rumai::IXP::Agent::FidStream class.
Added the Rumai::Client#kill method to simplify client termination.

Bug fixes

Fixed a race condition in Rumai::Agent#talk which would cause Rumai to hang when multiple threads used it.

4.9 Version 1.0.0 (2008-01-26)

This is the first release of Rumai, the evolution of wmii-irb, which lets you manipulate the wmii window manager through Ruby.

Happy birthday!

Resource	Origin	License
	Tango Icon Theme © 2005 Tango Desktop Project	Creative Commons Attribution-ShareAlike 2.5 License Agreement
	MediaWiki Monobook Skin © 2007 MediaWiki contributors	GNU General Public License, version 2

Rumai 3.2.0

Ruby interface to the wmii window manager

Suraj N. Kurapati

17 November 2009

Contents

Document

Chapter 1
Introduction

1.1 Features

1.2 Etymology

1.3 License

1.4 Credits

Chapter 2
Setup

2.1 Requirements

2.2 Installation

2.3 Package contents

2.4 Version numbers

Chapter 3
Usage

3.1 Concepts

3.2 Command-line interface

3.3 Tutorial

3.3.1 Automated client arrangement

3.3.2 Multiple client grouping

3.3.3 Easy column manipulation

3.3.4 Easy client manipulation

3.3.5 Traversing the file system

3.3.6 Available commands

3.4 Scripting your wmiirc

Chapter 4
History

4.1 Version 3.2.0 (2009-11-17)

4.2 Version 3.1.1 (2009-11-16)

4.3 Version 3.1.0 (2009-10-02)

4.4 Version 3.0.0 (2009-05-11)

4.5 Version 2.1.0 (2009-05-09)

4.6 Version 2.0.2 (2009-02-26)

4.7 Version 2.0.1 (2009-01-25)

4.8 Version 2.0.0 (2008-02-04)

4.9 Version 1.0.0 (2008-01-26)

Rumai 3.2.0

Ruby interface to the wmii window manager

Suraj N. Kurapati

17 November 2009

Contents

Document

Chapter 1 Introduction

1.1 Features

1.2 Etymology

1.3 License

1.4 Credits

1.5 Related works

Chapter 2 Setup

2.1 Requirements

2.2 Installation

2.3 Package contents

2.4 Version numbers

Chapter 3 Usage

3.1 Concepts

3.2 Command-line interface

3.3 Tutorial

3.3.1 Automated client arrangement

3.3.2 Multiple client grouping

3.3.3 Easy column manipulation

3.3.4 Easy client manipulation

3.3.5 Traversing the file system

3.3.6 Available commands

3.4 Scripting your wmiirc

Chapter 4 History

4.1 Version 3.2.0 (2009-11-17)

4.2 Version 3.1.1 (2009-11-16)

4.3 Version 3.1.0 (2009-10-02)

4.4 Version 3.0.0 (2009-05-11)

4.5 Version 2.1.0 (2009-05-09)

4.6 Version 2.0.2 (2009-02-26)

4.7 Version 2.0.1 (2009-01-25)

4.8 Version 2.0.0 (2008-02-04)

4.9 Version 1.0.0 (2008-01-26)

Chapter 1
Introduction

Chapter 2
Setup

Chapter 3
Usage

Chapter 4
History