Now that I’ve been using XMonad as my window manager on FreeBSD for a while, I find that when I have to work on Windows one of the more painful aspects thereof is, ironically, window management. I spend way too much time hunting for the right window or arranging windows so I can clearly see all the ones I need at once. Windows Vista and 7 have the ability to view windows side-by-side or stacked, but that’s not adequate to my needs and it virtually requires using the mouse. I desperately want an automatic tiling window manager like XMonad.

So, I created the next best thing: a command-line utility that will arrange all the windows in a tiled fashion, according to a pattern specified per monitor. In the download below you will find all the sources, plus in the Release subdirectory I’ve included an executable built with Visual Studio 2010.

For usage, type ’tile’ at a command prompt without arguments. But, to give you some examples:

tile 1 2

This tiles both the primary and second monitors using a column-based scheme, with no maximum of columns. Each display will be divided into the number of columns needed to hold all of the windows on that monitor.

tile 1:2r 2:3c

This tiles the primary monitor into 2 rows, with each row split as evenly as possible to accomodate all of the windows. Thus, if the primary window contains three windows, the first window will occupy the entire top row, and the second row will be split between the other two windows. On monitor #2, we’ll have three columns — so if we have five windows there, we’ll get one window in the first column and two windows stacked in each of the two remaining columns.

If you specify more rows or columns than there are windows on that monitor, it’s automatically reduced to the number of windows. Tile silently ignores most errors, such as specifying a monitor that doesn’t exist. Tile does not affect windows that are maximized or minimized. In order to be considered within a monitor, at least 10 pixels of the window in both directions must intersect the monitor’s rectangle.

As noted above, all parts of an argument except for the monitor number are optional. If omitted, the max defaults to 99, and row/column defaults to column.

So, now I can choose my optimal layout, put it in a little batch file named ‘t.bat’, and whenever I need my windows to snap into place I can just type ‘t’ at a command prompt.

I’ve used all sorts of email filters since my very first internet email account in the early 90s – and none of them have been quite right.  I’d like to be able to block anything about Viagra, but not when a friend or family member uses the word.  Pure Bayesian filters always seem to block something from someone I know, while letting a few of the real spam messages through.  But whitelists and blacklists suffer from a “which rule comes first” problem.

I recently moved to FreeBSD as my primary workstation OS, and I’m now reading my email with mutt, after delivery by getmail.  Getmail has a pretty easy configuration for inline filters, so I decided to create a rules engine for filtering messages the way I want to.  I decided to write it in Ruby, which naturally led to the creation of a simple EDSL in Ruby for manipulating email content and approving or rejecting an incoming message.  Since it’s intended for use with getmail, I decided to call it “getlessmail”.

By connecting the getlessmail.rb script (which you can download below) into getmail as an external filter, you can write a user-specific script in Ruby to specify your filtering rules, like so:

keep if from “mybestfriend@example.com”
spam if from “@example.com”
spam if subject “viagra|cialis”
spam if body “(?m:\bnude\b.*\bpics\b)”

With this ordering, mybestfriend@example.com is automatically approved, while anybody else from that domain is considered spam.  Likewise, mybestfriend can use viagra or cialis in the subject line, or “nude” followed by “pics” in the body, and it will still be approved – but not if from anyone else.

As you can see, the patterns are regular expression fragments.  These get sewn into larger expressions that isolate their intended context.  By default, they’re treated as case-insensitive and not multi-line – but you can turn any options on or off using the contextual options grouping supported by Ruby regexen (as I have with “(?m:)” in the last example entry above).  Patterns are always automatically parenthesized to avoid issues with operator precedence, so don’t add enclosing parentheses of your own unless you need them for other reasons.

But there’s more.  I’ve included methods for moving messages to folders automatically, and for manipulating message headers.  The folder operations assume that your mailboxes are stored as mbox files, so don’t use them if you’re using maildir format instead.

But that’s not all.  Since your rules script is interpreted as Ruby code, you can go crazy.  Log events, change the contents of the message, translate attachments, write your own Bayesian filter, or anything else you can do with Ruby.

I’ll probably extend the core functions at some point to deal more easily with multi-part messages.  My number one beef is the ms-tnef MIME format, which merely wraps attachments in a Microsoft-specific container.  There’s a tnef utility for unpacking that, so I should be able to strip out attachments in that format, pipe them to tnef, and then sew the resulting files back together in regular MIME multi-part.

See the README file for full documentation.  The download below is in tar.bz2 format, since it’s really only useful on Unix or Linux, where most tar implementations should be able to read it as is.

Recently, I replaced a defunct notebook that I use as my primary workstation.  Instead of Windows 7 I decided to go with FreeeBSD 8.0-release.  For my window manager I selected XMonad, because it’s lightweight, emphasizes productive use of the keyboard, and it’s highly configurable using Haskell.

Today I’ll give you a guided tour of my Xmonad configuration, which you can download below.  First, some screen shots.  Here’s my usual setup on the main workspace (click to enlarge):

The screen is divided using the golden ratio, with vim in the larger section and a shell prompt (tcsh) in the smaller one.  The shell prompt gives me a scrollable history of commands and their output, unlike issuing shell commands from within vim.  The bar across the top is xmobar — the configuration of which I’ll explain later.

Next, here’s my second workspace, dedicated to internet communications:

This workspace is divided 80/20 between my email client (mutt) and chat (pidgin).  To keep the contrast between window backgrounds from blinding me, I’ve implemented a dark gtk-2.0 theme (Khali) so that pidgin’s background is almost black.

The third workspace is devoted entirely to the web browser (firefox):

Workspace number 4 is where I bring up VirtualBox.  Here it’s shown running Windows 7:

VirtualBox’s main window is behind the full-screen virtual machine, but I can do Win+J or Win-K to swap to the main window (after RightCtrl to release the keyboard from Windows), or switch to a split layout with Win+Space.

XMonad offers five more workspaces that I haven’t dedicated to anything yet, but I can use them as the need arises.

Now let’s examine the configuration that makes this all possible.  Xmonad configuration starts with launching X11.  Here’s my .xinittrc:

   1: xsetroot -solid "#330005"

   2: xscreensaver -no-splash &

   3: uxterm &

   4: exec xmonad

I set the workspace background (which I only see when no windows are open) to a nice, dark wine color.  Then I start up xscreensaver and a unicode-capable xterm (thanks to Chad for the tip), and finally start up xmonad.  The configuration for uxterm is defined, rather simply, in .Xdefaults:

   1: UXTerm*background: grey3

   2: UXTerm*foreground: SpringGreen

   3: UXTerm*savelines: 512

Yes, I like the old school green on black – but not exactly green and not exactly black.  I also like to be able to scroll pretty far back.

xmonad.hs

Now let’s move on to the XMonad-specific stuff.  The primary configuration file for Xmonad is ~/.xmonad/xmonad.hs:

   1: import XMonad

   2: import XMonad.Actions.CycleWS

   3: import XMonad.Hooks.DynamicLog

   4: import XMonad.Hooks.ManageDocks

   5: import XMonad.Layout.NoBorders

   6: import XMonad.Layout.PerWorkspace

   7: import qualified XMonad.StackSet as W

   8: import XMonad.Util.EZConfig(additionalKeys)

   9: import XMonad.Util.Run(spawnPipe)

  10: import System.IO

  11: import Keys(myKeys)

  12:  

  13: main = do

  14:     xmproc <- spawnPipe "xmobar"

  15:     xmonad $ defaultConfig

  16:         { borderWidth        = 3

  17:         , normalBorderColor  = "#1e1c10"

  18:         , focusedBorderColor = "#5d0017"

  19:         , workspaces = ["1:main", "2:mail", "3:web", "4:vbox", "5", "6", "7", "8", "9"]

  20:         , layoutHook = avoidStruts $

  21:                         onWorkspace "2:mail" (mailLayout ||| Full) $

  22:                         onWorkspace "4:vbox" (Full ||| Mirror tiled) $

  23:                         smartBorders (tiled ||| Mirror tiled ||| Full )

  24:         , logHook = dynamicLogWithPP $ xmobarPP

  25:                         { ppOutput = hPutStrLn xmproc

  26:                         , ppTitle = xmobarColor "#cdcd57" "" . shorten 50

  27:                         , ppCurrent = xmobarColor "#cdcd57" ""

  28:                         , ppSep = " <fc=#3d3d07>|</fc> "

  29:                         }

  30:         , modMask = mod4Mask

  31:         , terminal = "uxterm"

  32:         , manageHook = myManageHook

  33:         } `additionalKeys` myKeys

  34:   where

  35:     mailLayout = Tall nmaster delta mailRatio

  36:     tiled       = Tall nmaster delta ratio

  37:  

  38:     -- default number of windows in the master pane

  39:     nmaster     = 1

  40:  

  41:     -- default propoertion of screen occupied by master pane

  42:     ratio       = toRational (2/(1+sqrt(5)::Double)) -- golden ratio

  43:     mailRatio  = 0.8                                 -- Pareto ratio, mutt:pidgin

  44:  

  45:     -- Percent of screen to increment by when resizing panes

  46:     delta       = 0.05

  47:  

  48:     -- How to handle various windows

  49:     myManageHook = composeAll

  50:         [ className =? "Firefox"        --> doF (W.shift "3:web")

  51:         , className =? "Gimp"           --> doFloat

  52:         , className =? "Gnubg"          --> doFloat

  53:         , title     =? "mutt"           --> doF (W.shift "2:mail")

  54:         , className =? "Pidgin"         --> doF (W.shift "2:mail")

  55:         , title     =? "qiv"            --> doFloat

  56:         , className =? "VirtualBox"     --> doF (W.shift "4:vbox")

  57:         , manageDocks

  58:         ] <+> manageHook defaultConfig

First, we import a bunch of stuff that we’ll need.  You may notice at the end of the imports section an import for Keys(myKeys).  It turns out you can modularize your XMonad configuration into multiple files, as long as you place them in ~/.xmonad/lib and name the module and the file the same thing.  So that import statement looks for ~/xmonad/lib/Keys.hs when recompiling your configuration.  That’s done with the shell command:

   1: xmonad --recompile

The “main” function in xmonad.hs defines XMonad’s configuration.  The first thing I do is open a pipe to xmobar, a text-based status bar that can populate part of its information from stdin.  That’s why I opened it on a pipe, so XMonad can send its status changes to xmobar.

Next, we apply overrides to the default configuration of XMonad.  I use a 3-pixel window border, because my 50-year-old eyes can’t easily see a 1-pixel line.  But the default light grey and bright red are too much, so I softened those colors.  I named all the workspaces (which is optional).  Even though I don’t have names for workspaces 5 through 9, I supplied their numbers as names (otherwise you don’t get them).  I should note that you aren’t required to put the number in the name, but since their keyboard shortcuts are mod-1 through mod-9, I elected to begin each name with its number.

The layoutHook overrides the layout options for windows.  The avoidStruts layout keeps windows from overlapping the xmobar window.  The onWorkspace option (imported in XMonad.Layout.PerWorkspace) selects a workspace-specific layout based on the name of the workspace.  On “2:mail”, I specify that there are two layouts that the user can cycle through (using mod-space):  a layout named mailLayout, or the built-in layout named Full (main window full-screen).  The mailLayout is defined later in the “where” clause as the Tall layout (split horizontally) with one main window, a sizing delta of 5%, and a split ratio of 80/20.

The next workspace-specific layout is for “4:vbox”, where we start in Full mode, but allow the user to switch to Mirror tiled, where Mirror is a built-in layout (vertically split, with main window on top), and tiled is defined below as a golden ratio split.

The final layout specified applies to all other workspaces, where we start out with a horizontal golden ratio split, and then cycle through the vertical split and full screen.

The logHook specifies how we’ll log status for xmobar.  The dynamicLogWithPP is a “pretty-print” formatter of dynamic status information, which we combine with a built-in configuration for xmobar, overriding the output to go to our pipe to xmobar (xmproc).  The active window title is shortened to 50 characters if needed, the color of the active workspace and window title are just a bit brighter than the other text on xmobar, and the separator between sections is overridden to | and colored like the rest of the separators on xmobar so it fits right in.  This produces the first three |-delimited sections on the status bar that you can see in the screen shots above.

I override modMask to mod4Mask, so wherever XMonad expects the mod key (Alt by default) I can use the Windows key instead.  This frees up Alt for other applications.

My terminal is uxterm, which is what XMonad will launch whenever I press mod-shift-enter.

Next comes the manageHook, which specifies how windows are managed.  Look down in the where clause to myManageHook, which specifies that any window with the className matching “Firefox” will be automatically shifted to workspace “3:web”.  “Gimp” and “Gnubg” will be allowed to float instead of being tiled.  The window titled “mutt” (we’ll see how that happens later) will be routed to workspace “2:mail”, along with windows of class “Pidgin”.  A window titled “qiv” (an image viewer) can float, and “VirtualBox” will go in workspace “4:vbox”.  Finally, we combine the built-in manageDocks and merge with the manageHook for defaultConfig.

The only other piece of this file is the key mapping.  I use the additionalKeys imported from XMonad.Util.EZConfig so I don’t have to respecify the entire key map, only what I want to add or override.  That comes from myKeys, which I imported from Keys.hs and looks like this:

   1: module Keys where

   2:   import XMonad

   3:   import XMonad.Actions.CycleWS

   4:  

   5:   -- additional key mappings

   6:   myKeys        =

   7:     [ ((0, xK_Print), spawn "scrot -q 100")                             -- capture screen

   8:     , ((controlMask, xK_Print), spawn "sleep 0.2; scrot -s -q 100")     -- choose window to capture

   9:     , ((mod4Mask, xK_a), spawn "usualapps")                             -- launch mutt, firefox, and pidgin

  10:     , ((mod4Mask, xK_f), spawn "/usr/local/lib/firefox3/firefox")       -- firefox

  11:     , ((mod4Mask, xK_p), spawn "exe=`dmenu_path | dmenu -nb '#1c1c0e' -nf '#7d7d37' -sb 'gold' -sf 'grey30'` && eval \"exec $exe\"") -- dmenu

  12:     , ((mod4Mask, xK_r), spawn "xmonad --recompile && xmonad --restart") -- refresh xmonad config

  13:     , ((mod4Mask, xK_t), spawn "uxterm")                                -- uxterm

  14:     , ((mod4Mask, xK_Right), nextWS)                                    -- next workspace

  15:     , ((mod4Mask, xK_Left), prevWS)                                     -- previous workspace

  16:     , ((mod4Mask, xK_F1), spawn "xmonad_keys.sh")                       -- key help (toggle)

  17:     , ((mod4Mask, xK_F9), spawn "xscreensaver-command -lock && xset dpms force off") -- lock workstation and turn off display

  18:     ]

This is pretty easy to decode, and I’ve added comments to describe each action.  But a couple of them bear explanation.

The shell script usualapps launches my usual applications if they aren’t launched already:

   1: #!/bin/sh

   2: if ! xwininfo -name "Pidgin" >/dev/null 2>/dev/null

   3: then

   4:   pidgin &

   5: sleep 2

   6: fi

   7: if ! xwininfo -name "Firefox" >/dev/null 2>/dev/null

   8: then

   9:   /usr/local/lib/firefox3/firefox &

  10: fi

  11: if ! xwininfo -name "mutt" >/dev/null 2>/dev/null

  12: then

  13:   uxterm -title "mutt" -e mutt &

  14: fi

I use xwininfo to see if each window can be located.  If not, I launch the associated application (pidgin, firefox, or mutt).  Mutt gets launched inside a uxterm for two reasons:  (1) it needs a console for I/O, and (2) I can name that window “mutt” for my manageHook to recognize it.  I launch Pidgin first and sleep 2 seconds, to make sure that xmonad lays it out before mutt.  That puts mutt into the main window by default.

The key help (mod4-F1) is provided by a shell script xmonad_keys.sh, which I adapted from this version.  Here’s mine:

   1: #!/bin/sh

   2: #

   3: # Toggles display of dzen window containing key mappings for xmonad

   4: #

   5: # Adapted from http://snipt.net/doitian/show-xmonad-key-bindings/

   6: #

   7: # Assumes that keys are defined in ~/.xmonad/lib/Keys.hs, one per line.

   8: #

   9:  

  10: if xwininfo -name "dzen slave"

  11: then

  12:   killall dzen2

  13: else

  14:   keysfile=~/.xmonad/lib/Keys.hs

  15:   fgColor="#0a0a05"

  16:   bgColor="#f6e6a7"

  17:   font="-*-fixed-*-*-*-*-10-*-*-*-*-*-*-*"

  18:  

  19:   (

  20:     echo "^fg($bgColor)^bg($fgColor) xmonad keys ^bg()^fg()"

  21:     xmonad_keys.rb $keysfile

  22:   ) | dzen2 -fg $fgColor -bg $bgColor -fn $font -x 624 -y 15 -l 11 -w 400 -p \

  23:   -e 'onstart=uncollapse,scrollhome,grabkeys;enterslave=grabkeys;entertitle=uncollapse,grabkeys;key_Escape=ungrabkeys,exit;key_Next=scrolldown;key_Prior=scrollup'

  24: fi

This script toggles the existence of a dzen2 window containing documentation of my additional key bindings, which I filter out of my Keys.hs file using a Ruby script:

   1: #!/usr/local/bin/ruby

   2: #

   3: # Key definitions must be specified one per line

   4: #

   5: $<.each do |line|

   6:   if (match = /\(\((.+?),\s*xK_(\w+)\),\s*(.+)\)\s*--\s*(.*)$/.match(line))

   7:     key = ((match[1] == '0') ? '' :

   8:         (match[1].gsub('Mask','').gsub(/ *\.\|\. */,'-') + '-')) +

   9:         match[2]

  10:     puts ' ' + key.ljust(24) + match[4]

  11:   end

  12: end

This script extracts the key combination and comment, then lines them up in two columns.  If you don’t want to document a key, just leave off the comment and the regex will fail to match.  Here’s what the final window looks like:

This window floats on the screen until you press mod4-F1 again, or Escape if it’s focused.

.xmobarrc

The configuration of xmobar (the status bar across the top), apart from the information that comes from xmonad itself, is defined in ~/.xmobarrc.  Here’s mine:

   1: Config { font = "-b&h-lucida-medium-r-normal-sans-10-100-75-75-p-58-iso8859-1"

   2:        , bgColor = "#1c1c0e"

   3:        , fgColor = "#7d7d37"

   4:        , position = Top

   5:        , lowerOnStart = False

   6:        , commands = [ Run Weather "KPWT" ["-t","<tempF>F","-L","40","-H","80","--high","red","--low","#3333FF"] 36000

   7:                     , Run Com "echo" ["$USER"] "username" 864000

   8:                     , Run Com "hostname" ["-s"] "hostname" 864000

   9:                     , Run Com "uname" ["-sr"] "os" 864000

  10:                     , Run Date "%a %b %_d" "date" 36000

  11:                     , Run Date "%H:%M:%S" "time" 10

  12:                     , Run Com "mem" ["-tm"] "memtot" 36000

  13:                     , Run Com "mem" ["-um"] "memused" 10

  14:                     , Run Com "mem" ["-p"] "mempct" 10

  15:                     , Run Com "loadavg" [] "loadavg" 10

  16:                     , Run Com "batt" [] "batt" 600

  17:                     , Run CommandReader "ledmon" "LED"

  18:                     , Run StdinReader

  19:                     ]

  20:        , sepChar = "'"

  21:        , alignSep = "}{"

  22:        , template = "'StdinReader' <fc=#3d3d07>|</fc> 'username' <fc=#3d3d07>|</fc> 'hostname' <fc=#3d3d07>|</fc> 'os' <fc=#3d3d07>|</fc> Mem 'memused'/'memtot'mb ('mempct'%) <fc=#3d3d07>|</fc> Load 'loadavg' <fc=#3d3d07>|</fc> Batt 'batt' <fc=#3d3d07>|</fc> <fc=#ffff00>'LED'</fc>}{'date' <fc=#3d3d07>|</fc> 'time' <fc=#3d3d07>|</fc> 'KPWT'"

  23:        }

I’ve used a proportional font so I can squeeze more text on the bar, and specified colors.  The bar is across the top, and starts life not lowered.  The “commands” member specifies what commands to run and how often to run them:

• Run Weather polls a NOAA station (id KPWT in Bremerton, WA in my case) for current weather conditions.  I’m just showing the temperature in Fahrenheit and coloring it blue if below 40, red if above 80, otherwise inheriting the foreground color of  the bar.  This updates once an hour (36000 tenths of a second).
• Run Com runs a shell command and captures its output.  The arguments are given in a list, followed by the alias to use in the template further down, as well as the interval.  So I get the username once a day (it won’t change without restarting X11 anyway), as well as the hostname and operating system (which won’t change without rebooting).
• Run Date gets date/time information and formats it.  I do this twice:  formatting the date as alias “date” once an hour, and the time as alias “time” once a second.
• The “mem”, “loadavg”, and “batt” commands execute shell scripts to return the memory usage, load averages, and battery information from sysctl.  I’ll go into those in more detail below.
• Run CommandReader launches a process that is expected to send status updates to stdout as they happen.  The ledmon utility is a little C program by John Goerzen that you can download here.  I had to change the Makefile a bit to work on FreeBSD – it wants libX11.so and libX11-xcb.so as inputs instead of –lX11.  This little utility monitors changes in the Caps Lock, Num Lock, and Scroll Lock keys and sends you a textual status update of their states.  For some reason, it doesn’t seem to detect Scroll Lock on FreeBSD, but the one I really care about is Caps Lock, so it serves my need.
• The final command, Run StdinReader, is what picks up the output from XMonad itself.

Now for the templating.  I’ve overridden the sepChar as a single quote, because I wanted to be able to use % as an output character.  Thus, in the template, single quotes are used to interpolate each of the aliases of the commands listed above.  The alignSep specifies a string that separates left-justified from right-justified text.  In the template, I use a | as a visual separator, and I color it a little bit dimmer than the text pieces.  You can also see that I apply a bright yellow to the ledmon output, to get my attention before I accidentally join all the lines in my vim session.

Surrogates for xmobar builtins

I think xmobar must have been developed for use under Linux, because some of the built-in commands rely on being able to access Linux-specific features, like /proc/stat for Run Mem.  FreeBSD doesn’t have /proc/stat, so I created some shell scripts to extract information from sysctl(8) instead.  These are all included in the download below.

• mem provides information on memory.  Use mem –h for usage.
• loadavg returns the load average statistics, stripping off the {} included in the sysctl output.
• batt returns the battery’s percent of full charge.  If charging or discharging, that’s also noted.

Nonfinal remarks

This configuration is certainly a work in progress, and I can’t help but fiddle with it.  So, I may be posting an update at some point in the future.  Please let me know if there’s anything I could do more easily, or any other suggestions you might have.

Yes, Richard, I did it – I created another problem for everyone.  I’ve implemented a regex parser for Synergy/DE.  And because it’s written in Synergy/DE (as opposed to say, a C DLL), it’s portable between any number of Unices, Linux, Windows, and even OpenVMS – as long as you’re running Synergy/DE version 9.1.5 or above.

It performs pretty well, too – mostly because I started with an excellent (if limited) deterministic algorithm from Amer Gerzic.  I must admit that extending this algorithm to track parenthesized sub-expressions was one of the greatest programming challenges I’ve faced in quite some time.  It forced me to make the engine not quite as deterministic (there can now be more than one active state for each potential start of a match), but I completely avoided back-tracking – so performance suffers very little.  I was also able to optimize for the case in which no sub-expressions were compiled.

The breakthrough occurred to me while I was waiting in the doctor’s office for a colonoscopy – during which they would administer the Milk of Amnesia to make me forget the procedure.  I was so worried that it would wash away my brilliant algorithm that I asked my wife for a piece of paper so I could jot down some notes.  Fortunately, though, the anesthetic seemed to have only a limited effect (I was awake throughout the procedure – ewwww) and I remembered everything about my algorithm afterwards.

The trick was to abstract the notion of inputs beyond just characters received.  My implementation includes a transition for entering and exiting a potential sub-expression.  Whenever we can move in such a direction, we create a fork in the road for our deterministic engine – but rather than trying them one at a time, we try them all at once.  Each character thereafter collects the new states for each path we’re on until they dead-end or reach an accepting state.

I used a similar approach for handling line anchors.  Character classes also have more abstract transitions than just the characters they include, which reduces the number of paths we have to maintain in the state table — though it can increase the number of paths we’re following simultaneously.

Any way, it works, it’s fast, and I’m happy.  You can find full documentation here, and download the sources below.

I also added “match” and “replace” methods to Var, created mappers MapMatched(regex) and MapReplace(regex, with), and added some more useful methods to ls – all of which are included below.  I haven’t documented these or updated the official downloads for Var and ls yet, because it will involve adding everything from Regex.

Speaking of which, I’m thinking of consolidating the downloads for all of my Synergy/DE version 9 stuff and organizing it into a single library with a single include file and a right proper makefile.  What do you Synergistas think of that plan?

OK, I’ve given you regexen, now go save the day.

UPDATE: now merged into synthesis library.

Synergy/DE developers often have a mix of applications, some of which use the Synergy/DE UI Toolkit, and others that don’t.  The UI Toolkit doesn’t always play well with others, especially when it comes to things like allocating file channels or windows – it wants to control those operations itself.  So for a generalized routine, it’s useful to know whether the UI Toolkit has been linked into the current application, and if so whether or not it has been started.

The code you can download below includes a function named “GotToolkit”:

result = %GotToolkit(start)

where

result is returned with one of the following values (defined in gottk.def):
D_NO_TOOLKIT – This application has not included the Toolkit
D_TOOLKIT_AVAILABLE – Toolkit available, but not yet started
D_TOOLKIT_STARTED – Toolkit has been started

start is an optional argument indicating whether to attempt to start Toolkit (defined in tools.def):
D_NO_START – Leave things as they are (assumed if not passed)
D_START – Start the Toolkit, but only if available
D_START_ANYWAY – Start the Toolkit, attaching to it if not available

If instructed to start the Toolkit, result is the result of that operation.  In any case, result represents the current state of affairs when the function returns.

Be sure to include gottk.def within the data division of any routine that uses %GotToolkiit – this include file not only defines the literals used in the interface, it also declares the function to have a ^val return type.

In order to make the Toolkit truly optional on Windows and *nix, you must link gottk in an ELB.  Otherwise, because of the way global data section initialization works in Synergy/DE, you’ll be forced to link in the Toolkit also – which means you could never get a D_NO_TOOLKIT return value.  You can put gottk in your own ELB, or use the one built by the enclosed example.

This function should work across all supported Synergy/DE platforms: Windows, *nix, and OpenVMS.

I’ve included some tests in testtk1.dbl, testtk2.dbl, and testtk3.dbl.  For correctly building and executing these tests, I’ve included bld.sh (a *nix shell script) and bld.bat (a Windows batch file).  The tests succeed if you get a STOP message for each program, without throwing any exceptions.

I’ve been casually studying Lisp for years now, and gathering a much better understanding of programming languages in the process.  I finished reading Paul Graham’s On Lisp earlier this year.  But the only way to truly grok a language is to use it to write something fairly complex.  Lisp is often stereotyped as being designed for highly abstract academic problems – and what could be more abstract and academic than writing an interpreter for Brainfuck?

While it may sound über-geekish to be able to say that my first real program in Lisp was an interpreter, I cheat a little bit here because Brainfuck is such a simple language to interpret (for a computer, anyway).  I also didn’t build in Brainfuck as an extension of Lisp the way most DSLs are written in Lisp – primarily because the comma and period characters are reserved for the Lisp compiler, and overloading the functions + and – wouldn’t be such a good idea, either.

So, you can feed my interpreter its code as a series of strings or as a list of symbols.  The string form is probably preferable, because the symbols have to be prefixed with ‘bf’ to avoid the collisions I mentioned above.

In the downloadable code below, brainfuck.lisp contains all of the functions for the Brainfuck interpreter, and bf.lisp is a command-line interface for it.  I developed it using CLISP, but it should be compatible with most Common Lisp implementations.  Usage:

clisp bf.lisp <bf-file>*

where <bf-file> is a file containing Brainfuck code.  If you supply more than one file, they are executed within the same machine as if they were one continuous file.

This brought me face-to-face with the problem of retrieving command-line arguments in Common Lisp, which isn’t standard across implementations.  I found a work-around for that in the Common Lisp Cookbook, but it didn’t handle CLISP.  After a little research, I was able to modify it to include support for CLISP:

(defun get-command-args ()
  (or
   #+SBCL *posix-argv*
   #+LISPWORKS system:*line-arguments-list*
   #+CMU extensions:*command-line-words*
   #+clisp EXT:*ARGS*
   nil))

If you want to call the Brainfuck machine from within Lisp, here are a few important functions:

(make-bf-machine) => bf-machine

(bf-add-string bf-machine code) => code-stream

(bf-add-list bf-machine code) => code-stream

(bf-step bf-machine) => current-cell-value

(bf-run bf-machine) => final-cell-value

(bf-current-instruction bf-machine) => current-instruction

The last one is important if you intend to step through a program, because it yields nil when there are no more instructions.

Since bf-add-list doesn’t validate the symbols it receives, it provides an opportunity for Lisp code injection.  You can pass it any symbol that represents a function that takes a bf-machine as its only argument.  For example, 'print might be handy for debugging.  The bf-add-string function doesn’t have the same facility/vulnerability, because it filters out non-Brainfuck characters.

Notes on the Brainfuck implementation

First, let me address each of the points in Daniel Cristofani’s Epistle to the Implementors:

1. Greetings back atcha, Daniel.
2. Duly perused.
3. This implementation treats EOL as a 10.  That was a freebie from using CLISP.
4. EOF on input leaves the current cell unchanged.
5. Non-Brainfuck characters are dutifully ignored.
6. I have not added any extensions to the language – nor have I implemented the “traditionally sanctioned” # and ! extensions.
7. This implementation provides a logically infinite array of cells – in both directions.  Thus, if you shift left from cell 0, you will receive a new cell 0 containing a zero, and all other cells are shifted to the right.  The maximum value that can be stored in any cell is dependent on the capacity of numbers in the version of Common Lisp – which appears to be 64-bit floating point.
8. It’s fascinating!

My implementation passes all of the tests that Daniel suggests, with the exception of being more lenient on:

• The two bounds-checking tests, which run forever (or presumably until memory is exhausted, but I didn’t have the patience for that).
• The two unmatched bracket tests.  When my implementation reaches the end of the code stream while hunting for a matching bracket, it just ends.

I also tested most of the programs that Daniel supplies.  I particularly like his Fibonacci generator, which is incredibly concise for a version that outputs successive values in ASCII.

Finally, since there’s no finer way to screw up your noggin than with alcohol, try the programs at 99 Bottles of Beer.

PHP, the language of myriad functions, devotes quite a few of those to the problem of sorting arrays.  One flavor of sort function useful in presenting data on web pages is natcasesort, which performs a case-insensitive, natural order sort.  However, even though natcasesort preserves key => value associations, you cannot use it to sort an array by its keys.  The sort order is determined by the value alone.

Consider the following:

   1: $array = array('wilma' => array('role' => 'wife', 'sex' => 'female', 'haircolor' => 'red'),

   2:                'fred' => array('role' => 'husband', 'sex' => 'male', 'haircolor' => 'black'),

   3:                'barney' => array('role' => 'neighbor', 'sex' => 'male', 'haircolor' => 'blond'),

   4:                'Betty' => array('role' => 'neighbor', 'sex' => 'female', 'haircolor' => 'black'),

   5:                'pebbles' => array('role' => 'child', 'sex' => 'female', 'haircolor' => 'red'),

   6:                'bam bam' => array('role' => 'neighbor\'s child', 'sex' => 'male', 'haircolor' => 'blond'));

   7:

   8: natcasesort($array);

   9:

  10: echo "<h3>using natcasesort</h3>";

  11: foreach($array as $name => $features) {

  12:   echo $name . "<br/>";

  13: }

Since natcasesort sorts on the value rather than the key, and the value in this case is another array, the sort order appears to be almost random:

pebbles

bam bam

Betty

barney

fred

wilma

To sort by the keys instead you can use ksort, but unfortunately it supports neither natural ordering nor case-insensitivity.  What you’d like here is a natcaseksort, but no such animal exists.

However, you can easily create one by combining two other functions:  uksort and strnatcasecmp.  The former performs a key sort using a supplied function taking two parameters (two key values) and returning <0, 0, or >0 to indicate their collational relationship.  The latter performs a case-insensitive, natural order string comparison, returning precisely those values.  Thus, the equivalent of the mythical natcaseksort is the following one-liner:

   1: uksort($array, 'strnatcasecmp');

which faithfully produces:

bam bam

barney

Betty

fred

pebbles

wilma

For once, the authors of PHP refrained from creating yet another sort function.  It just happened to be the one I needed.  But two functions that each Do One Thing Well fit together with surprisingly Unix-like elegance to do the job.

I’ve often found that one of the best ways to learn how to do things in a programming language is to attempt to write an interactive game.  My daughter got me hooked on Sudoku, and I thought to myself “this should be a pretty trivial algorithm to implement in JavaScript.”  I’ve been working on it a few minutes at a time in between other projects ever since.  This morning I finally put a lid on it.  You can download the code below, and you can see it in action and play it as often as you like.

The Game

This version of Sudoku presents the usual 9 x 9 grid which is divided into nine 3 x 3 regions.  The object of the game is to fill in the grid with numbers from 1 to 9, such that each row, column, and region contains one and only one instance of each number.  To get you started, each game provides a number of “givens” — cells that already have their value filled in, and which you cannot change (indicated by a gray background).  By default, this version randomly provides 36 givens — without any attempt to evenly distribute them across rows, columns, or regions.

When you enter a number in a cell, if the value conflicts with another cell in the same row, column, or region, then the background of both cells will be changed to red (unless the other cell is a given, in which case it remains gray).  If a cell has two or more conflicts, a darker shade of red is used, up to four conflicts — beyond which point the color remains the same.  If you try to enter a value in the cell other than the numbers 1 through 9, the cell is cleared.  You can also clear the cell by pressing “delete”.  When a cell is focused, the arrow keys can be used to navigate to the next cell in the specified direction, with wrap-around.  Tab and Shift-tab follow the browser’s defined behavior for navigating input controls — the cells are defined in column order within rows, followed by the buttons.

The “Hint” button provides another given, randomly choosing an empty cell to fill in.  If there are no empty cells remaining, an alert “Can’t fill in anything!” will be displayed.

The “Solve” button will reveal the entire puzzle.  Note that it may be possible to solve a Sudoku in more than one way for the given values, but this button reveals the solution that was generated when the puzzle was created.

The “New” button generates a new puzzle.

You can use your browser’s “Zoom” or “Text size” functions to resize the puzzle.

Browser-specific differences

This game was tested with the following browsers, and revealed a few minor issues where noted:

• Google Chrome 1.0.154.46
• Mozilla Firefox 3.0.6
• Safari 3.2.1
• Internet Explorer 7 & 8 – Sizing the browser small enough causes the cells to misalign.  Corners on the container aren’t rounded.
• Opera 9.25 – border width differences used to delineate the regions are not honored, and neither are the rounded corners on the container.
• Opera Mini Simulator- same issues as Opera.

I’ve attempted to make this game mobile-friendly, but of course it only works on platforms that support JavaScript and CSS.

Styling

All styling for this game has been separated out into the file sudoku.css.  You can modify this or provide your own stylesheet to change the effects for the following class names (note that more than one class name may be applied to an individual cell):

• sudoku – the container for the game (defined in sudoku.htm)
• sudokuButton – the control buttons
• sudokuCell – every cell in the puzzle
• sudokuGiven – a cell whose value is given
• sudokuCorrected – a cell whose value has been corrected by pressing the “Solve” button
• sudokuConflict0 – a cell whose value does not conflict with any other cells
• sudokuConflict1 – a cell whose value conflicts with one other cell
• sudokuConflict2 – a cell whose value conflicts with two other cells
• sudokuConflict3 – a cell whose value conflicts with three other cells
• sudokuConflict4 – a cell whose value conflicts with four or more cells
• sudokuRegionTop – a cell that is along the top edge of a region
• sudokuRegionBottom – a cell that is along the bottom edge of a region
• sudokuRegionLeft – a cell that is along the left edge of a region
• sudokuRegionRight – a cell that is along the right edge of a region
• info – the section that contains the link to this page

Using the code

This code has been designed to play well with others.  It introduces only one global symbol, the name of the Sudoku function.  However, it does use the jQuery framework (included in the download).

You can instantiate a Sudoku puzzle within any HTML element using the following code:

new Sudoku(elem, ngivens)

where elem is the DOM Element that will contain the puzzle, and ngivens is the optional number of givens to display (default = 36).

Algorithm

For every new puzzle, the script generates a completed solution and then randomly chooses the location of the givens to reveal.  The algorithm for generating the puzzle can probably be made more elegant, but it works.  The generatePuzzle() function is called recursively, beginning with the first cell and progressing to the last one.  At each cell, the numbers 1 through 9 are attempted in a random order until no conflicts are found and we successfully recurse through the rest of the puzzle.  Thus, if no solution can be found for a given combination up to this point, we backtrack through the recursion and try something else.  This could certainly be optimized — for instance, we could keep track of unused values within the current row and only try those.  But I’m not certain that the benefit of that optimization wouldn’t be offset by the additional array manipulation required.  Ideally, this is a problem for graph theory — perhaps one day I’ll attack it from that angle.

For checking conflicts, the script maintains arrays of arrays:  an array of rows, an array of columns, and an array of regions.  Each element of these arrays is an array of DOM elements:  the “input” element for each cell.  Each of those elements also has back-linked properties for its row, column, and region.  Thus, when the “onchange” event occurs for a cell, we can easily check it against the other cells that might conflict.

For more details, see the comments in the code.

UPDATED 2009-02-17 to add styling for cells corrected by “Solve”.  Also added readme.txt and license.txt.

In my consulting business, I often have to switch my attention between different projects.  Unless I keep good notes, it can be difficult to figure out at the end of the day how much time I spent on each one.  So I developed this little stopwatch application that you can download below.  It lets you create as many independent stopwatches as you want on a single page, then start and stop them as appropriate.

To keep track of what each clock represents, they each contain an edit field for a description.  And if you forgot to start the clock, you can adjust the time whenever it is stopped by typing over the clockface’s value.  When you restart it, whatever is in the clockface will be parsed.  If it contains a string that matches the pattern H:M:S, those values will be used to compute the initial time on the clock.  You’re not limited to 60 minutes/seconds or 24 hours either.  For instance, if you want to start with a value of 110 minutes, you can type either 0:110:0, or 1:50:0.  On the first update, the value will be converted into the usual time notation.

You can see a demo of this application, or feel free to use it at that URL as often as you like.  You can also embed a timeclock in any web page simply by including a reference to timeclock.js and executing the following JavaScript snippet:

new TimeClock(elem)

where elem is a DOM Element that is to be the parent element of the new clock.  You can style the clock in CSS using the classes that are applied to each of the clock’s elements:

.tc-timeclock /* the clock's outer box */
.tc-close  /* the 'X' box for closing the clock */
.tc-descr  /* the description edit field */
.tc-face   /* the clockface */
.tc-start  /* the Start button */
.tc-reset  /* the Reset button */

See timeclock.css for some examples.

Tested with Google Chrome 0.3.154.9, Mozilla Firefox 3.0.1, Opera 9.2.5, Safari 3.1.2, and Internet Explorer 7.

Here’s a Windows desktop version written in C#, if that suits your style better.

Last year I changed the theme on this blog and my other ones to make use of Matthew Levine’s Holy Grail approach to layout – or rather,  a simplified version of it, since I only need two columns.  My motivation for doing this was to render the content before the sidebar (for impatient and mobile users, as well as for SEO), yet have the fixed-width sidebar float on the right and leave the remaining space to the content.  Although simplified for two divs instead of three, wedging it into an existing style sheet was anything but simple.  I wrestled with padding and margins until I got it working for Firefox and IE7.  In Opera and Safari, the sidebar kept popping out below the content, and (with apologies to their users) I didn’t care enough about those browsers to spend any more time trying to remedy this mostly cosmetic issue.

Enter Chrome.  It’s such a fast browser that I decided to start using it as my default for a while.  Of course, it uses WebKit for rendering, same as Safari — so sure enough, my sites had the same bug, only you’d see it faster.  I decided it was time to do something about my problem.

One of the reasons why I never figured out what was going on in Opera or Safari is the dearth of web debugging tools available for those browsers.  Chrome adds a JavaScript console that also shows you the dimensions of the sections and what styles actually get applied to them.  Turns out, though, that confusion over CSS inheritance wasn’t my problem.

As usually happens when you can’t figure out a problem, I had more than one.  So tweaking one of those settings wouldn’t show me any difference.  But, by carefully progressing from the working model to my version, I was finally able to ferret out the buggers.

First, Matthew’s approach sets the main fluid (center) section to a width of 100%.  But my theme set the width of an outer box to 96%.  That apparently allowed WebKit (and Opera’s Presto engine) to extend the logical edge of the inner section outside the outer box, squeezing out the sidebar.  I removed that outer 96% setting and changed the inner one to 96%, letting the inner divs push the outer one out.

Second, it appears that WebKit and Presto count border widths in addition to the width specified for a section.  Those widths had to be added to the size of the padding for the container and the negative margin used by the sidebar, to prevent two pixels of borders from squeezing out a 200+ pixel sidebar.

The net result moves the sidebar a little to the left from where it was in Firefox before, but I can live with that.  Let me know if you spot any other Knights Who Say Ni!

The new object-oriented syntax for Synergy/DE version 9 is pretty closely modeled after C#, because Synergex plans to create a CLR version of the language and they don’t want the syntax supported on the various platforms to differ by much.

That means, of course, that when we hear “Multiple Inheritance” we are supposed to close our eyes and ears, hold up a cross, load up with silver bullets, and make it go away.

And it’s true that MI has probably caused more problems than it solves in languages that support it. Sometimes the “need” for MI is really a symptom that you should have used composition instead of inheritance (the object “has a” <whatever you’re deriving from> instead of “is a”).

But sometimes MI can be useful. There are abstractions that apply to an object itself that cut across normal inheritance lines. For instance, there are lots of classes that you could compare for equality in some manner more abstract than comparing the identity of the objects. So, you’d like to overload the ==, !=, >, <, >=, and <= operators with methods that compare the objects in some custom way specific to the class. But why write all of those methods for every class that needs them? If each class had one method to compare the objects and return a value indicating less than, equal, or greater than — then all the operator overload methods could call that method, and they’d be essentially identical for each class. If you could inherit that code from a common source, you’d save yourself a lot of typing — and possibly a lot of paste and modify errors.

This idea comes to me from Ruby, which has the concept of “mixin modules” — code that can be added to any class to extend its functionality, without regard for its inheritance hierarchy. It creates a form of MI without all the screaming.

The downloadable code below includes a module in Comparable.dbl. Don’t compile that module, but if you include it within a class definition it will define the comparison operator overloads for you. These methods assume that your class contains a “compare” method that it can call to determine the appropriate result for each operation. Because Synergy/DE is a statically typed language, you also have to give it the types to work with, via .defines. So, for instance, in Person.dbl we have:

class Person
.define COMPARE_CLASS Person
.include "Comparable"

This creates the op_Equality, op_Inequality, and related methods that call the compare method to compare Persons. How do you compare Persons? Why, by their likability, of course:

protected static method compare, int
in req obj1, @Person
in req obj2, @Person
proc
    using obj1.likability select
    (< obj2.likability), mreturn -1
    (> obj2.likability), mreturn 1
    endusing
    mreturn 0 ;==
endmethod

You might expect that the compare method will look pretty similar from class to class as well, so I also added the ability to generate the compare method automatically to compare a specific member (data or method). Just define COMPARE_MEMBER, as shown in SalesPerson.dbl:

.define COMPARE_CLASS SalesPerson
.define COMPARE_MEMBER annual_sales ;Compare their annual sales
.include "Comparable"

It’s also possible to have different comparisons for mismatched operand types. Just define COMPARE_TYPE2 (and optionally COMPARE_MEMBER2), as when comparing a SalesPerson to a Person.

.define COMPARE_TYPE2 @Person
.undefine COMPARE_MEMBER ;Don't generate "compare"
.include "Comparable"
protected static method compare, int
in req obj1, @SalesPerson
in req obj2, @Person
proc
    mreturn -1 ;a SalesPerson is always less than a Person
endmethod

You may wonder why the second argument needs to have the “@” included in the definition, and why I called it COMPARE_TYPE2 instead of COMPARE_CLASS2. This is so you can define comparisons against primitive types like “int” or “string” as well.

The Programmer class in Programmer.dbl shows how the COMPARE_MEMBER definition can resolve to a member function:

.define COMPARE_CLASS Programmer
.define COMPARE_MEMBER geekQuotient()
.include "Comparable"

private method geekQuotient, decimal
proc
  begin
    data quotient, decimal
    quotient = (num_languages * num_languages) * years_coding
    if (ever_used_VB) quotient /= ^x(dead)
    mreturn quotient
  end
endmethod

See testComparable.dbl for examples of usage.

Naturally, you can use the same technique to create comparison operators for any class. As long as your comparison operators have complementary meaning (which I would recommend), you should never have to write your own overloads for them again.

You can expand on this idea to create other inheritable traits that cross inheritance boundaries. For instance, in Ruby, anything that acts vaguely like an array or collection includes “Enumerable” to get a whole host of useful methods.

So SalesPerson “is a” Person, but it also “is a” Comparable object. So is Programmer. Any other class into which you include Comparable also “is a” Comparable, without necessarily being a Person. We’ve achieved MI (Multiple Inheritance) via MI (MixIns), blurring the line between inheritance and composition.

UPDATED 4/28/2008 to add support for comparisons against primitive types, and to automatically undefine COMPARE_TYPE2 and COMPARE_MEMBER2 at the end of Comparable.dbl.

UPDATED 4/6/2009 to automatically generate operators for swapped operand types when COMPARE_TYPE2 is defined.  Thus, (myobj == 2) and (2 == myobj) will have identical results.  Note, however, that if the first operand’s class defines a suitable operator, that one has precedence.

One of the more useful features found in many scripting languages is the concept of an associative array.  It goes by the name of a hash in Perl and Ruby, or a dictionary in Python.  A hash lets you associate key values with data, and later retrieve a datum using its key — often via a syntax similar to an array element reference.  On this lazy Sunday morning it occurred to me that Synergy/DE could benefit from such a facility.

The downloadable code below contains a Hash class that acts as an array of untyped objects with an alphanumeric index.  You can control the case-sensitivity of the key by setting the CaseSensitive property (which defaults to false) before adding the first item.  Because this uses the new Synergy class syntax, it requires at least version 9 of Synergy/DE.

Usage:

myhash = new Hash()
myhash['key'] = anyobject
anyobject = myhash['key']

If a key is not found, then ^null is returned.  Thus, to clear an item, just set its entry to ^null.  This hash does not reclaim any array entries, so it will eventually grow to the size of all keys that have ever been used to store a value.

As you can see in the code, the class uses an internal ArrayList to store the object references, and associates the keys with array indices using the built-in Symbol Table functions in Synergy/DE.  If the Symbol Table API could take objects as associated data then we wouldn’t need this class at all — but it doesn’t.  The Symbol Table API can only take primitive types for data, so we have to introduce this extra layer of reference in order to support objects.

Synergy/DE’s static typing gets in our way in usage as well.  Because the elements are typed as System.Object, client code must cast any returned element to the type expected.  If a primitive type is to be stored in the hash, then it must be cast as an object in order to box it.  Even though you can store a hash as an element of a hash to created nested arrays, you cannot dereference a nested element using a single statement, because you must first store the nested hash element into a variable of type Hash.  And we don’t get any benefit at all from static typing here.  Of course, you could create a derived class of Hash that expects and returns a specific object type.  That would better be a job for generics, which have not yet been implemented in Synergy/DE.  Personally, I’d like to suspend static typing altogether for a class like this, but that’s just the Ruby talking.

UPDATED 3/22/08: Added an iterator and Count property.

UPDATED 7/6/09: Changed the namespace to “ChipsTips”.

UPDATED 9/9/09: Corrected iterator to use base-zero indexing.

As an independent consultant who bills by the hour, I have to keep track of how much time I spend on projects for different clients.  When various emergencies arise, that can get pretty confusing to reconstruct at the end of the day.  I needed an easy way to monitor my time with just a few mouse clicks.  So a few years ago I created the simple stopwatch application that you can download below.  One click to start, another to stop.  You can enter a description, and previously entered descriptions are remembered in a dropdown.  You can run multiple instances to keep track of time for multiple clients.  At the end of the day, you’ve got a total for each.

I wrote this as a C# Windows application using Visual Studio 2003.  Converting it for VS 2005 introduced a challenge, because accessing a control from another thread (the timer’s) is now considered unsafe and throws an exception.  So as you’ll see in the SetText method, I adopted a work-around from the MSDN documentation.

Back when I wrote this application, the code seemed quite concise.  Now that I’m older and wiser and have been exposed to Ruby, I can’t get over how verbose it is.  I can’t help but think that to do the same thing in JavaScript would be pretty trivial.  Maybe I’ll give it a go one day.

UPDATE 11/10/2008:  Here’s the JavaScript version.

Tony Peak (aka Rirath) helped to identify an incompatibility with PHP version 4 in my WiPeD plugin for WordPress.  Now, if back-porting to version 4 had involved a major rewrite I would have said “Routta Ruck, Rirath” — but it turned out to be pretty easy.  I had used class constants for the values in the database fields to indicate types of entries, and class constants weren’t supported in PHP 4.  Luckily, there’s a simple replacement:  define.  So, if you want to debug WordPress on PHP 4, download version 1.2 below.

A few days ago I started reading Shelley Powers’ new book, Adding Ajax, a free copy of which Shelley generously sent me.  In the very first chapter, Shelley said something that helped me solve a nagging problem that I’ve had for months.

Readers of this blog and my other one may have noticed (and some of you have remarked) that when my sidebar length exceeded the content length, the sidebar overlapped the footer and extended into dark space.  How amateurish.  But I had spent way too many hours tweaking the HTML and CSS trying to remedy the situation, and had finally given up.  The thing is, I knew how to avoid this aberrant behavior, but not without either displaying the sidebar first or making the content section fixed-width.  What I wanted was to have the content size fluid, the sidebar size fixed, and to display the content before the sidebar (for the benefit of all readers, but especially those using a screen reader or mobile device).  So I used a large right margin on the content and applied an absolute position to the sidebar.  But with that arrangement, clear:both on the footer ignored the sidebar’s length.  For someone who cut their web teeth using tables (or dare I admit it, frames) for layout, it was enough to drive me crazy.

In Shelley’s book, she gives a very clean and simple example that applies float:left to the content and float:right to the sidebar, drawing the latter last and applying clear:both to the footer — which works fine, except that in that case a fluid content section will take up all the available space, forcing the sidebar to appear beneath it.  But Shelley hinted that this was possible with fluid layouts, and said something even more useful at the end of her example:

For additional reading on CSS layouts, search the web for “fluid fixed elastic CSS layouts”.

Now, I had previously googled until my googler was sore trying to find a solution to this problem, but I hadn’t used those exact search terms before.  Since I’m not interested in fixed or elastic layouts, I omitted those words and googled anew.  This led me to the Holy Grail of web design.  Matthew Levine explains a simple but unique approach to making fixed-width sidebars float either left or right of a fluid center section, with a footer below them all.  In brief:

1. Enclose all three sections within a container section, using position:relative and float:left to keep them from stacking vertically.
2. Apply padding to the left and right side of the container for the desired size of your sidebars.  This restricts the fluid center section to the remaining space.
3. Use negative margins on the sidebars, to move them back out over the container’s padding.
4. For the left section, specify the position.  The right section gets bumped out automatically by the size of the center section.
5. Use clear:both on the footer, to position it beneath all three sections.

Since I don’t have a left sidebar, I was able to do this even more simply:

1. Enclose the content and sidebar sections within a container section, using position:relative and float:left.
2. Apply padding to the right side of the container for the space to reserve for the sidebar.
3. Use a negative right margin on the sidebar.
4. Apply clear:both to the footer.

Naturally, this didn’t work the first time (when does it ever?) — I had issues with inherited padding, prematurely closed div’s, and other such nonsense that had accumulated like dust in my theme files over the course of many tweaks.  These were relatively easy to hunt down using the Web Developer toolbar for Firefox (which Shelley also recommends in her book), using the Display Block Size and Display Div Order options on the Information menu.  One issue that I suspect would have taken me much longer to hunt down had it not been for this feature was a conflict between div class names — my theme used “content” for the class of the main content section, and the Brian’s Threaded Comments plugin uses the same class name for the section that includes the contents of each comment.  So when I added float:left to ”.content”, the comments section went haywire.  That’s a good example of why, when writing a plugin, you shouldn’t use common class names or ids for elements it produces — you should always prefix them with something to make them unique, because you never know who else might be using that name as well.  To work around it, I just renamed my “content” class to “blogcontent”.

Over the years, I’ve learned CSS and Javascript on an “as needed” basis.  Shelley’s book seems well targeted for an audience of people like me, because it’s all about bringing existing sites forward to these newer approaches.  I’m sure that it will fill in some gaps for me — and that this won’t be the last solution that gets sparked from reading her pages.

So I was coding along one fine day, happily using my WiPeD debugger for WordPress, when I suddenly stumbled on a problem with it.  I was attempting to debug a function that was hooked to an action that was supposed to be triggered by the MetaWebLog API (‘save_post’, when posting from a blog authoring tool), and none of my debug messages were being displayed!  Suddenly the heel of my hand went *bonk* on my forehead — of course I couldn’t retrieve any messages from XMLRPC processing, because I was saving the messages in a session variable, and the client in that case is my authoring tool instead of my browser – so the sessions aren’t the same.  Duh, time to rethink.

The downloadable version below saves the debug messages to the database instead of to a session variable.  Obviously, that means that multiple users will mix their output in the log.  Of course, you’d expect to be debugging on a private site, but just in case I added an options page where you can exclude users based on their capabilities — with the default being ‘level_9′ (administrators only).  I also added options to allow you to customize when the debug log is displayed, as well as when it’s cleared.  Spin it up, and check out the Readme-WiPeD.txt file.

UPDATE: get the latest version here.

Speaking of the deficiencies of PHP, another one is the complete lack of built-in debugging capabilities.  Sure, you can find debuggers for PHP, if you’ve got the time and ability to configure them on your server.  I guess if I was really serious about PHP I’d have to get one of those, but so far I only use PHP for WordPress customization, so it hardly seems worth the effort.

Some people will tell you that you shouldn’t need a debugger.  That it’s a sign of lazy programming.  But PHP has so many pitfalls, and WordPress has so many actions and interactions between plugins and themes provided by so many different developers, that I think you’re excused if you need a little help figuring out just what the heck is going on in your code.

When writing a plugin or modifying a theme for WordPress, usually all I need to know is the order of events and the values in various variables.  Sometimes you can get away with inserting “echo” statements in your code — but sometimes you can’t, like when your code executes ahead of a “wp_head” action that wants to add headers.  Besides, randomly placed “echo” statements can easily get lost from view in the whirl of words and images that comprise your theme and content.

So, I developed a simple little plugin that collects debug statements and prints them out nicely above the footer of your theme, or below the admin footer, whichever gets executed first.  I call it WiPeD, for “WordPress Printf Debugger”.  Anywhere in your code, you can call WPD_print() and pass it whatever text you want to output.  The lines of text are aggregated in a session variable until they are output together (in separate divs, surrounded by a single containing div).  Thus you can use styling to set the messages off from the rest of your blog, if you desire.

Here’s an example, from a project I’m currently working on.  My plugin was producing no results, and I couldn’t figure out why.  So I added some calls to WPD_print():

Then, when I executed the code to trigger this action, here’s what I saw at the bottom of my page:

That tells me that I got into my function and passed the tests, but the post has no content at that point.  Now I just need to figure out why.

See the enclosed readme file for more details.  Have fun debugging your PHP!

UPDATE: get an updated version here.

Version 1.2 of the OPML Browser plugin for WordPress has just been released!  This version includes some significant upgrades, including:

1. You may now have up to 9 opml-browser widgets. When upgrading, the options from your existing opml-browser widget are copied to the first opml-browser widget.  Thanks to Mark Barnes for suggesting this enhancement.
2. The option to exclude your domain now ignores differences in case when comparing domain names.  Thanks to Tony Lindskog for finding that one.
3. You can now override the title for the OPML link by entering text into the “OPML title override” field.  I didn’t want mine to read “FeedDemon Subscriptions”, so I added that for myself.
4. Added the ability to embed the browser within a page or post using a special [ opml-browser ] element in the text.  See the readme.
5. Added a “Get this widget” link at the bottom of the widget.  Thanks to TDavid for suggesting that little bit of self-promotion.

Download version 1.2 via the button below.  Pinging back to all previous posts for those following comments.

UPDATE: More corrections here.

Several years ago, Gary Hart said something that has stuck with me ever since: “just because it’s messy doesn’t mean you don’t want to do it.”  We were discussing plans for driving throughout the UK while there on business — but time and again I find this principle applies to other situations as well.  Besides the obvious, um, recreational possibilities, I can think of many more: eating sloppy sandwiches, parenting, electing public officials, starting a relationship, and coding in PHP.

PHP powers a lot of the web, including such popular frameworks as WordPress, so you really need to have it in your programming portfolio.  But it’s a messy language.   I’m not just talking about the way that PHP tends to sprawl like semicolon-laden vines around your HTML, earning an alternative interpretation of “Page Hacked to Pasta”.  Nor am I referring (this time) to its sucky object model.  The language itself contains many little gotchas and “almost right”s that wait like snares for the feet of the unwary coder.

One I ran into yesterday (not for the first time) is PHP’s partial distinction between false and zero.  In PHP, false is boolean, and zero is numeric.  Fine and good.  But if you treat a zero value as a boolean expression, the zero gets converted to a boolean false.

This seems innocent and helpful enough until you get to a function like strpos, which returns the position of one string within another.  If the target is not found in the source, it returns boolean false.  So, to make sure that one string doesn’t contain another, you’d think you’d do something like this:

if (!strpos($source, $target))

But there’s a problem here.  If $target starts at the beginning of $source, strpos will return 0.  Because it’s in a conditional, that gets converted to boolean false, and the test passes.  So, you need to explicitly test for false instead, right?

if (strpos($source, $target) == false)

Wrong.  Because you’re comparing it against a boolean value, the zero still gets converted to a boolean false.  The only right way to do this is:

if (strpos($source, $target) === false)

The triple equal sign tells PHP to only evaluate to true if both operands have the same type and the same value, so no conversion takes place.  Granted, the PHP docs have a great big warning on strpos to this effect, but the net result is something less than intuitive coding.

Languages like Java and C# solve this problem by not allowing automatic conversion between numeric and boolean values.  That’s sort of like castrating the entire population to prevent birth defects.  So why doesn’t this create problems for other languages?

In Synergy/DE, indices start at 1, so the instr function returns zero for not found:

if (!instr(1,source, target))

Quite logical and linguistically elegant (except for having the starting index as the first parameter), but then you don’t get to have the secret handshake.

Even though Ruby uses a starting index of 0, it prevents confusion in routines like String#index by returning nil instead of a number for not found.  Zero is treated as an object — and thus is not false — while nil does evaluate to false.  Thus,

print "good" if ("abcde".index("a"))
print "bad" if ("abcde".index("f"))

prints “good”, even though the index of “a” within “abcde” is 0.  Why should 0 be false anyway?

In C and C++, indices start at 0, and 0 can be used as a stand-in for false (in fact, all falses are zero), yet I hardly ever make the mistake of “if (strpos(…))” in C.  Why?  Because the documented return value for “target not found” isn’t FALSE, it’s -1.  I immediately know that to test for this return value I must say:

if (strpos(source, target) < 0)

The significance of the result does not rely on a distinction between returned values that can be automatically converted from one to the other.  PHP, on the other hand, requires the programmer to explicitly prevent that conversion from happening.  Automatic conversions are supposed to be a convenience for the programmer, not a trap.

Maybe PHP stands for Purposely Hampers Programming.