In the first part of this tutorial we looked at reading a document from CouchDB and keeping our markup separate from our code using Haml templates. We arrived at the point where we clicked on a link, but nothing happened. Today we are going to put that right with some very simple routing.

The URL Module

The basis of all routing is the URL. Fortunately, Node has some basic functions which handle reading the URL so we can then decide what the user is actually trying to do.

First, we want to make sure we have included the URL module.

var sys = require('sys'),
fs = require('fs'),
http = require('http'),
url = require('url');

The next step is to extrapolate the path name from the URL that the user has visited:

var url_parts = url.parse(req.url);
sys.puts(url_parts.pathname);

Now, when I go to http://127.0.0.1:8000/create in Chromium, the system output is as follows:
/create
/favicon.ico

As you can see I have to deal with /create but also /favicon.ico – unfortunately I don’t have one. We’ll deal with that later by using a 404 error.

The pages we want to be dealing with are as follows:

• /
• create
• /edit

For simplicity’s sake we’ll put them into a switch statement:

switch(url_parts.pathname) {
case '/':
sys.puts("display root");
break;
case '/create':
sys.puts("display create");
break;
case '/edit':
sys.puts("display edit");
break;
default:
sys.puts("oh dear, 404");
}

If you test this out you should see the relevant text displayed in the standard output.

Tidy up Existing Code

Now we have a basic router telling us that it has detected which page the user wants to display, but is then displaying the default page regardless. To correct this we need to put our existing code within a function and then call that function in the relevant part of the switch statement.

So, create a new (sub) function called display_root() in the main bulk of the http.createServer() function, expecting a url, a server request object and aserver response object as parameters:

function display_root(url, req, res) {
...
}

Within the body of the function, you want to insert the main bulk of the application that we wrote last time. I have included the complete code at the bottom of this tutorial, and all code is of course on GitHub.

Now call this function within the switch statement:

display_root(url_parts.pathname, req, res);

Handling Missing Pages

As said, Chromium is looking for a favicon.ico file, but currently this application doesn’t have one. As such it needs to be able to handle missing files gracefully, with the correct 404 response.

Create a new function within the main bulk of the http.createServer() function:

function display_404(url, req, res) {
res.writeHead(404, {'Content-Type': 'text/html'});
res.write("<h1>404 Not Found</h1>");
res.end("The page you were looking for: "+url+" can not be found");
}

Notice that we have specified the header to be 404.

Now you can call this from within the switch:

display_404(url_parts.pathname, req, res);

You can test it out by going to http://127.0.0.1:8000/qwerty
You should see:

404 Not Found
The page you were looking for: /qwerty can not be found

We could use a Haml template to move the content out of the code, but for the purposes of this tutorial it will suffice.

The Form

Now we want to generate a “Create” page – which will be a form allowing us to enter a list name and 1-5 items. (Note: I have changed from 10 items to 5 for no other reason that I am lazy, and don’t particularly want 10 things on my list, also it keeps the code a bit more clean!)

First, create the Haml template that will be used. We’ll keep this very simple for now. The key part is the form generation. After some trial and error, this mark-up seemed to work:

%form(action=url method="post")
      :each i in [0,1,2,3,4]
        %p %label Item
           %input(type="text" name="item[]")
      %p
        %input(type="submit" value="Create List")

You may want to read up on Haml here: http://haml-lang.com

The function for displaying the page is as follows:

    function display_create(url, req, res) {
	res.writeHead(200, {'Content-Type': 'text/html'});
	fs.readFile('./templates/create.haml', function(e, c) {
	    var data = {
		title: "Create New List",
		message: "Please enter up to 5 things to remember",
		url: url
	    };
	    var html = haml.render(c.toString(), {locals: data});
	    res.end(html);
	});
    }

Now if you fill in the items and submit, the page simply refreshes itelf. We need to get hold of the posted form data and do something useful with it.

This will be what we’ll focus on next time.

Tutorial Recap Part 2

In part 2 of the Node JS tutorial, we started to explore some very basic routing techniques. A number of dedicated routing modules have sprung up, of two of which are listed here:

• Tim Caswell’s node-router
• Tom Hughes-Croucher’s node-routing
• Find more on the Node Modules wiki page

Complete Code

var sys = require('sys'),
    fs = require('fs'),
    http = require('http'),
    url = require('url');
 
// Node-CouchDB: http://github.com/felixge/node-couchdb
var couchdb = require('./libs/node-couchdb/lib/couchdb'),
    client = couchdb.createClient(5984, 'localhost'),
    db = client.db('erdnodeflips');
 
// Haml-js: http://github.com/creationix/haml-js
var haml = require('./libs/haml-js/lib/haml');
 
var doc_id = '2d36f401bc4b82c9160e1a4ea936aba3';
 
http.createServer(function (req, res) {
    var url_parts = url.parse(req.url);
 
    switch(url_parts.pathname) {
    case '/':
	display_root(url_parts.pathname, req, res);
	break;
    case '/create':
	display_create(url_parts.pathname, req, res);
	break;
    case '/edit':
	sys.puts("display edit");
	break;
    default:
	display_404(url_parts.pathname, req, res);
    }
    return;
 
    /**
     * Display the document root
     **/
    function display_root(url, req, res) {
	res.writeHead(200, {'Content-Type': 'text/html'});
	db.getDoc(doc_id, function(error, doc) {
	    if(error) {
		fs.readFile('./templates/no-doc.haml', function(e, c) {
		    var data = {
			title: "No Document Found",
			message: "No document could be found",
			link: "/create",
			link_text: "Create a new document"
		    };
		    var html = haml.render(c.toString(), {locals: data});
		    res.end(html);
		});
	    }
	    else {
		fs.readFile('./templates/doc.haml', function(e, c) {
		    var data = {
			title: "Erdnodeflip document: "+doc.name,
			message: "Your Erdnusflip document was found!",
			items: doc.items,
		    };
		    var html = haml.render(c.toString(), {locals: data});
		    res.end(html);
		});
	    }
	});
    }
 
    /**
     * Display the list creat page
     **/
    function display_create(url, req, res) {
	res.writeHead(200, {'Content-Type': 'text/html'});
	fs.readFile('./templates/create.haml', function(e, c) {
	    var data = {
		title: "Create New List",
		message: "Please enter up to 5 things to remember",
		url: url
	    };
	    var html = haml.render(c.toString(), {locals: data});
	    res.end(html);
	});
    }
 
    /**
     * Display the 404 page for content that can't be found
     **/
    function display_404(url, req, res) {
	res.writeHead(404, {'Content-Type': 'text/html'});
	res.write("
<h1>404 Not Found</h1>
");
	res.end("
 
The page you were looking for: "+url+" can not be found");
    }
}).listen(8000);
sys.puts('Server running at http://127.0.0.1:8000/');

1. To list a number of items
2. To remove an item from the list
3. To add an item to the list

Obviously, before getting cracking with this tutorial I had to think up a name for this “killer app” of the Node world.

So I give you ErdNodeFlips! In honour of erdnussflips – the strangely addictive Wotsit type things that taste of peanut butter and stick to the top of your mouth. Yum! (OMG – they even have their own Facebook page!)

All code is available on GitHub.

Directory Structure and Libraries

The first step is to create a directory structure for the application and bring in the relevant libraries. We need two directories underneath the top-level application root: templates (which will hold the haml files) and libs (which will contain 3rd party libraries). We are going to grab two libraries off GitHub:

• Felix Geisendörfer’s node-couchdb – this is what we’ll be using to interact with the Couch database
• Tim Caswell’s haml-js – this is our haml template engine

$ cd /
$ mkdir {libs,templates}
$ cd libs
$ git clone git://github.com/felixge/node-couchdb.git
$ git clone http://github.com/creationix/haml-js.git
$ cd ../

Basic Web Server

Now we can get started. Open up a new file called main.js in your favourite editor. Now, just to make sure that everything is working at this early stage you can copy and paste the http server example from the nodejs.org front page and run that.

http.createServer(function (req, res) {
  setTimeout(function () {
    res.writeHead(200, {'Content-Type': 'text/plain'});
    res.end('Hello World\n');
  }, 2000);
}).listen(8000);

$ node ./main.js

Navigate to http://127.0.0.1:8000/ and after 2 seconds you should see “Hello World” appear. If you see this, all is working. We have the (very basic) base of our application.

Talk to the Database

Once we know that our basic setup is working, we can try and interact with the database. Before we can do this, however, we actually need to create the database and add an record – or document.

CouchDB comes with a nifty little utility called Futon. We’ll use this to quickly create our database and add a document.

• Go to http://localhost:5984/_utils/
• Create a new database: erdnodeflips
• Create a new document
• Add Field – name it name
• Double click on the value for name, enter “Don’t forget” (including the quotes)
• Add another field – name it items
• Double click on the value for items enter: ["item 1", "item 2", "item 3"] (including quotes and square brackets)
• Click on Save Document – copy the _id value
• Navigate to: http://localhost:5984/erdnodeflips/[value of "_id"] to see something like: {”_id”:”2d36f401bc4b82c9160e1a4ea936aba3″,”_rev”:”2-3b9f738a50ff9928348ce32b0eb807b2″,”items”:["item 1","item 2","item 3"],”name”:”Rob’s List”}

To read this within node we simply need to know the _id of the document. Save this as a var for now:

var doc_id = ‘2d36f401bc4b82c9160e1a4ea936aba3′;

and replace the setTimeout function with the following:

db.getDoc(doc_id, function(error, doc) {
	if(error) {
	    res.write(JSON.stringify(error));
	}
	else {
	    res.write('Fetched my new doc from couch:');
	    res.write(JSON.stringify(doc));
	}
     res.end("-= Fin =-");
    });

This is pretty simple, and should be relatively straight forward to read. Essentially the code tries to get the document identified by doc_id, invoking a function when done: db.getDoc(doc_id, function(error, doc){});

The function that is invoked has 2 arguments, one containing the error (if any) and the second containing the actual document returned (if any).

Within this function we can then deal with the two arguments as needed. If there is an error, we output that to the browser, if no error and a doc is returned, output that instead.

Finally, we end the server response: res.end(”-= Fin =-”);. Note, we must end the server response within the callback of the getDoc() function. Due to the event driven, asynchronous nature of Node, if we end the response after that function then the server response will more than likely be closed before getDoc() has had a chance to write the additional server responses.

So the code now looks like this:

var sys = require('sys'),
    fs = require('fs'),
    http = require('http');
 
// Node-CouchDB: http://github.com/felixge/node-couchdb
var couchdb = require('./libs/node-couchdb/lib/couchdb'),
    client = couchdb.createClient(5984, 'localhost'),
    db = client.db('erdnodeflips');
 
// Haml-js: http://github.com/creationix/haml-js
var haml = require('./libs/haml-js/lib/haml');
 
var doc_id = '2d36f401bc4b82c9160e1a4ea936aba3';
 
http.createServer(function (req, res) {
    res.writeHead(200, {'Content-Type': 'text/html'});
    db.getDoc(doc_id, function(error, doc) {
	if(error) {
	    res.write(JSON.stringify(error));
	}
	else {
	    res.write('Fetched my new doc from couch:');
	    res.write(JSON.stringify(doc));
	}
     res.end("-= Fin =-");
    });
 
}).listen(8000);
sys.puts('Server running at http://127.0.0.1:8000/');

Generate Nicer Output

If you run the above code, you should get something along the lines of:

Fetched my new doc from couch:{”_id”:”2d36f401bc4b82c9160e1a4ea936aba3″,”_rev”:”2-3b9f738a50ff9928348ce32b0eb807b2″,”items”:["item 1","item 2","item 3"],”name”:”Rob’s List”}-= Fin =-

So it works, but it doesn’t look very good.

First, lets create a Haml template that we can use to output something better.

!!! Strict
%html(lang="en")
  %head
    %title&= title
  %body
    %h1&= title
    %p&= message
    :if items.length === 0
      %p There are no items to remember
    :if items.length > 0
      %ul
        :each item in items
          %li&=

I’m not going to go into great depth. You can find more information on Haml at the Haml homepage and also have a look at Tim’s excellent tutorial on his Haml-js library.

Essentially, this template is going to build an XHTML strict page that will have a title, a message and then should loop through the items in the list. To get this displayed, we then need to open up the template file, render it and then output it as a server response. The code to do that is:

fs.readFile('./templates/doc.haml', function(e, c) {
		var data = {
		    title: "Erdnodeflip document: "+doc.name,
		    message: "Your Erdnusflip document was found!",
		    items: doc.items,
		};
		var html = haml.render(c.toString(), {locals: data});
		res.end(html);
	    });

Notice that I am simply ending the response with the generated HTML. Again, it is worth keeping an eye on exactly where the response is being ended otherwise you might find you are trying to add to a conversation that has already ended.

We can do the same for the “document not found” route:

!!! Strict
%html(lang="en")
  %head
    %title&= title
  %body
    %h1&= title
    %p&= message
    %p %a{href: link}&= link_text

fs.readFile('./templates/no-doc.haml', function(e, c) {
		var data = {
		    title: "No Document Found",
		    message: "No document could be found",
		    link: "/create",
		    link_text: "Create a new document"
		};
		var html = haml.render(c.toString(), {locals: data});
		res.end(html);

Quick Recap for this Tutorial

In this tutorial we’ve only scratched the surface of what can be done. However, in a relatively short space of time we have our Node web server communicating with a CouchDB database and displaying some valid strict XHTML. Not bad for one sitting!

To recap, our code now looks like this:

var sys = require('sys'),
    fs = require('fs'),
    http = require('http');
 
// Node-CouchDB: http://github.com/felixge/node-couchdb
var couchdb = require('./libs/node-couchdb/lib/couchdb'),
    client = couchdb.createClient(5984, 'localhost'),
    db = client.db('erdnodeflips');
 
// Haml-js: http://github.com/creationix/haml-js
var haml = require('./libs/haml-js/lib/haml');
 
var doc_id = '2d36f401bc4b82c9160e1a4ea936aba3';
 
http.createServer(function (req, res) {
    res.writeHead(200, {'Content-Type': 'text/html'});
    db.getDoc(doc_id, function(error, doc) {
	if(error) {
	    fs.readFile('./templates/no-doc.haml', function(e, c) {
		var data = {
		    title: "No Document Found",
		    message: "No document could be found",
		    link: "/create",
		    link_text: "Create a new document"
		};
		var html = haml.render(c.toString(), {locals: data});
		res.end(html);
	    });
	}
	else {
	    fs.readFile('./templates/doc.haml', function(e, c) {
		var data = {
		    title: "Erdnodeflip document: "+doc.name,
		    message: "Your Erdnusflip document was found!",
		    items: doc.items,
		};
		var html = haml.render(c.toString(), {locals: data});
		res.end(html);
	    });
	}
    });
 
}).listen(8000);
sys.puts('Server running at http://127.0.0.1:8000/');

The exciting thing here is that we’ve thrown in a link! However, if you click on it, it will simply reload the page.

Being able to handle this kind of basic page navigation and actually adding stuff to the database is for next time.

Feedback always welcome. You can find all the code on my GitHub pages.

Valuable Node resources:

• The official Node JS site
• The Node Github page
• How To Node – a great place for tutorials and other tips
• Node Blogs – which appears to be down at the moment, but again is very useful
• NodeJS Google Group – keep your finger on the pulse

For example, one thing that has been bugging me is to validate a URL the user must type in the initial http://. But why? Can the validation not just assume that if, for example, www.robsearles.com is typed in, that the user actually meant http://www.robsearles.com?

Well, after a quick read of the documentation and a hack around this little irritant is now gone. It’s all down to addMethod() which lets you add a custom validation method. Lets create one called complete_url().

jQuery.validator.addMethod("complete_url", function(val, elem) {
    // will contain our validation code
}, 'You must enter a valid URL');

A quick word about return values. If the method returns true, everything is considered OK. However, if false is returned then validation is assumed to have failed.

Our new method needs to do three things:

1. If no url, don’t do anything
2. Check that the user had entered http:// in their URL, if not, add it in for them.
3. Check that the URL is now valid. For this I just used the source for the original url validation method.

Lets translate this into some code:

jQuery.validator.addMethod("complete_url", function(val, elem) {
    // if no url, don't do anything
    if (val.length == 0) { return true; }
 
    // if user has not entered http:// https:// or ftp:// assume they mean http://
    if(!/^(https?|ftp):\/\//i.test(val)) {
        val = 'http://'+val; // set both the value
        $(elem).val(val); // also update the form element
    }
    // now check if valid url
    // http://docs.jquery.com/Plugins/Validation/Methods/url
    // contributed by Scott Gonzalez: http://projects.scottsplayground.com/iri/
    return /^(https?|ftp):\/\/(((([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(%[\da-f]{2})|[!\$&'\(\)\*\+,;=]|:)*@)?(((\d|[1-9]\d|1\d\d|2[0-4]\d|25[0-5])\.(\d|[1-9]\d|1\d\d|2[0-4]\d|25[0-5])\.(\d|[1-9]\d|1\d\d|2[0-4]\d|25[0-5])\.(\d|[1-9]\d|1\d\d|2[0-4]\d|25[0-5]))|((([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])*([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])))\.)+(([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])*([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])))\.?)(:\d*)?)(\/((([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(%[\da-f]{2})|[!\$&'\(\)\*\+,;=]|:|@)+(\/(([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(%[\da-f]{2})|[!\$&'\(\)\*\+,;=]|:|@)*)*)?)?(\?((([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(%[\da-f]{2})|[!\$&'\(\)\*\+,;=]|:|@)|[\uE000-\uF8FF]|\/|\?)*)?(\#((([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(%[\da-f]{2})|[!\$&'\(\)\*\+,;=]|:|@)|\/|\?)*)?$/i.test(val);
});

Validating the form with this new method is very straight forward:

$("#form1").validate({
    rules: {
        url: "complete_url"
    }
});

Feel free to use/copy/modify as you see fit. If you do use it, why not let me know, or drop me a trackback?

Have fun

Other jQuery Specific Posts

• IE 7 indexOf() Replacement
• Fixed – jQuery DatePicker not working in Thickbox
• jQuery: Link override with search box

Some of my most used shell commands are using SVN, such as add, revert etc. However, I couldn’t find anywhere to just add/revert the current file I am working on. Fortunately there is Stack Overflow! Someone with a very similar issue to me has had a couple of good answers, which I have “borrowed” and now adding files to my SVN repository is really easy.

First, add the following to your .emacs file

(define-key minibuffer-local-map [f3]
(lambda() (interactive) (insert (buffer-file-name (nth 1 (buffer-list))))))

Now either open up Emacs, or reload your .emacs file:

M-x load-file RET ~/.emacs RET

Now, when you are working on a new file you can easily add it to SVN with the following command:

M-! svn add F3 RET

Nice!

Why Arch?

There are three main reasons I’ve picked Arch over Ubuntu, or even Debian.

1. I really like the idea of Arch’s rolling release system. My laptop is currently running Jaunty and in order to get the latest packages I would have to upgrade to Karmic. With Arch this is less of an issue.
2. As mentioned in my initial post, the base system should be small, quick and light. With Arch you can pick and choose exactly what you want at installation time, keeping it bloat free.
3. Finally, Arch will be something new to play with!

After downloading and burning a Net Install ISO I followed the excellent installation guide in the Arch Wiki.

Installation was relatively painless, the only two slight issues being:

I chose Auto prepare for partitioning, but I didn’t really know what filesystem to choose. Eventually I opted for Ext4, with so far, no ill effects.

During Boot Device Selection, again I wasn’t really sure what to do, but after some Googling I found this page, whose advice I followed, but just pressing enter.

I restarted and was greeted with a shell prompt. I quickly pinged Google and my network was still up and running through the ethernet on DHCP.

The next step up a non-root user and X. Again, the Arch documentation is excellent.

Setting up X was relatively simple. I originally decided to not opt for hotplugging, which was a mistake because I only have a USB keyboard and mouse, neither of which I could use in X (muppet of the day award goes to me). After turning off the machine and setting up hotplugging, all was fine!

I have been using the Awesome window manager for about a month now. Awesome is a tiling window manager which is heavily geared towards being keyboard friendly, and as it’s name suggests, it is pretty awesome.

Unlike Jaunty, installing the latest stable version of Awesome was a breeze, I simply ran:

# pacman -S awesome

and edited my ~/.xinitrc file adding:

exec awesome

at the bottom. When I started X again, Awesome was there without any problem.

Sound was equally as simple to install, which was a nice surprise.

So my base system is now setup, with my window manager of choice in place and sound ready and waiting for my music collection. And all this running under 100MB of RAM!

After my first foray into the world of Arch I’m pretty impressed. Pacman is very straight forward to use, after a bit of tweaking here and there it has just worked.

Next time, file management tools.

After freshly installing Karmic (the desktop version looks very nice btw) on a new VirtualBox image and then updating with the latest, er, updates I was ready to begin.

The entire installation procedure is very simple, once all dependencies are met.

Firstly you must edit your sources list to include the DotDeb package repository and the old Jaunty security packages to meet dependencies.

$ sudo nano /etc/apt/sources.list

# php5.3
deb http://php53.dotdeb.org stable all
deb-src http://php53.dotdeb.org stable all
deb http://security.ubuntu.com/ubuntu jaunty-security main

Now update and upgrade Ubuntu

$ sudo apt-get update
$ sudo apt-get upgrade

You may find that you get the following warning:

WARNING: The following packages cannot be authenticated!
libevent-1.4-2
Install these packages without verification [y/N]?

I just answered Y and continued as normal

Once successfully upgraded then you can install Apache, MySQL and PHP as normal, feel free to cater the installation line to your tastes.

$ sudo aptitude install libicu38 apache2 apache2-mpm-prefork mysql-client-5.1 mysql-server-5.1 php5 php5-cli php5-mysql libapache2-mod-php5

You will get a warning about untrusted packages being installed but this simply means that the PHP5.3 stuff is not signed, so I typed in “yes” and carried on.

Robmorin commented in my Jaunty post that he had issues when installing PHP MCrypt. The answer can be found within the DotDeb comments

After you have installed everything you need to, test it out, either command line:

$ php -v
PHP 5.3.2-0.dotdeb.1 with Suhosin-Patch (cli) (built: Mar  9 2010 10:14:53)
Copyright (c) 1997-2009 The PHP Group
Zend Engine v2.3.0, Copyright (c) 1998-2010 Zend Technologies with Suhosin v0.9.29, Copyright (c) 2007, by SektionEins GmbH

Or by using phpinfo() page within your Apache installation:

$ sudo nano /var/www/info.php

<?PHP
phpinfo();
?>

then fire up http://localhost/info.php and at the top of the page you should see something along the lines of
PHP Version 5.3.2-0.dotdeb.1

Note: if your browser asks if you want to download info.php, simply restart Apache and try again:

$ sudo /etc/init.d/apache2 restart

All done. Not quite as simple as on Jaunty, but still better than compiling the source!

Post Script: Before starting this post, I did a quick search looking for tutorials to see if the work had already been done, but couldn’t find anything on installing PHP5.3 on Karmic. As there wasn’t anything I decided to continue with my tutorial and I ended up struggling for an hour or so with the dependency issues. Typically, after I had figured it out for myself, whilst searching for another dependency issue I found this post on the JMOZ blog about installing PH5.3 on Karmic Koala.  No idea why it’s not in Google, but either way, damn, I could have saved myself an hour or so!

In our team we have a mixture of Linux and Mac users, and we are constantly editing the same files. One of the most irritating things is when a file is saved with Mac line endings instead of Unix line endings (displaying as ^M in Emacs). This happens very rarely, but on the occasion it does I can quickly convert back using the following commands on my Linux box:

$ tr '\r' '\n' < file-in-question.txt > tmp.file
$ mv tmp.file file-in-question.txt

Works perfectly

If you want to find more about the tr (Translate) program, visit the man page.

We need to initially define our flags:

define('BASE', 0); // binary 00000000
define('F1', 1);   // binary 00000001
define('F2', 2);   // binary 00000010
define('F3', 4);   // binary 00000100

To start with we have no flags set, so if we set F1 using the following:

$f1_set = BASE + F1; // $f1_set = 1
echo "F1 set = $f1_set\n";

All is well and good, $f1_set = 1 as expected.

However, what if we set F1 again?

$f1_set_twice = $f1_set + F1; // $f1_set_twice = 2 !!! wrong !!!
echo "F1 set twice = $f1_set_twice\n";

As you can see, if we set F1 twice, it effectively “unsets” F1 and sets F2. Not what we were after.

So why is this? Well, it’s kind of obvious and I was being a bit of a muppet for not spotting it yesterday. The reason is pretty simple: 1 + 1 = 2. (I told you it was obvious!)

Clearly this is not what we want, but how can we solve this? By using the bitwise OR. If we change the statements slightly as follows:

$f1_or_set = BASE | F1; // $f1_or_set = 1
echo "F1 OR set = $f1_or_set\n";
 
$f1_or_set_twice = $f1_or_set | F1; // $f1_or_set_twice = 1 - huzzah!
echo "F1 OR set twice = $f1_or_set_twice\n";

As far as “unsetting” the flags if we use my original method we fall (again) into trouble.

$f1_and_f3 = BASE | F1 | F3; // $f1_and_f3 = 5;
$unset_f3 = $f1_and_f3 - F3; // $unset_f3 = 1
echo "Unset F3 = $unset_f3\n";
 
$unset_f1 = $f1_and_f3 - F1; // $unset_f1 = 4;
echo "Unset F1 = $unset_f1\n";

Now, if we try to “unset” F1 twice, we arrive at the problem.

$unset_f1 = $f1_and_f3 - F1; // $unset_f1 = 3;
echo "Unset F1 = $unset_f1\n";

Unsetting F1 twice here effectively turns off F3 and sets F1 and F2 – completely wrong!

Instead, if we use the &~ binary operator mentioned in Jesper’s comment all works as expected. (note: I can’t find mention of this operator in the PHP docs, please someone help me out)

$f1_and_f3 = BASE | F1 | F3; // $f1_and_f3 = 5;
$unset_f3 = $f1_and_f3 &~ F3; // $unset_f3 = 1
echo "Unset F3 = $unset_f3\n";
 
$unset_f1 = $f1_and_f3 &~ F1; // $unset_f1 = 4;
echo "Unset F1 = $unset_f1\n";

Even if we try to “unset” a flag twice, it still has the same results:

$unset_f1 = $f1_and_f3 &~ F1; // $unset_f1 = 4;
echo "Unset F1 = $unset_f1\n";
 
$unset_f1_twice = $unset_f1 &~ F1; // $unset_f1_twice = 4;
echo "Unset F1 twice = $unset_f1_twice\n";

Also in Jesper’s comment and original post was the use of the left shift operator: <<. After playing around with this it seems very simple to use, as follows:

$f1 = 1;    // 00000001
$f2 = 1<<1; // 00000010
$f3 = 1<<2; // 00000100
$f4 = 1<<3; // 00001000

Or to put it another way:

$f1 = 1;      // 00000001
$f2 = $f1<<1; // 00000010
$f3 = $f2<<1; // 00000100
$f4 = $f3<<1; // 00001000

After all this I think I am a little closer to understanding Bitwise operations, hopefully! Tomorrow I’ll have a crack at testing to see if a flag is turned on or not. Until then…

I have always wondered what the point of Bitwise Operators were,to me they seem to belong to a distant past. However, after reading a couple of great blog posts I have at last an understanding of how they can be put to use, and have started playing around with them a bit (ba dum!).

Jesper Noehr has written about using bitwise operators for a flexible permissions scheme within Python  and Jonathan Snook has taken the bitwise concept further creating a great calendar app in Javascript. After reading these I thought I better dive in, and an opportunity came along yesterday when I had to code a flagging system within PHP.

For the benefit of this post I have greatly simplified the problem but hopefully it should be enough to get an understanding and allow you to get started with playing around with bits.

The problem is as follows. I have a number of items and each item has 3 different flags associated with it. We’ll call these flags F1, F2 and F3. A single item can have none, some or all flags set, and needs to have the ability to turn each flag on or off independently. The “base” state for each item is that no flags are set.

Each flag is a boolean, on or off, or to put it another way, 1 or 0. This translates perfectly into binary numerals. If we visualise this with a number of examples:

No flags switched on

Just F1 switched on

Just F2 switched on

Just F3 switched on

F1 and F3 switched on

The reason we have translated the binary number for just F1 switched on to 001 and not 100 is because from a text point of view, we read F1, F2 then F3 from left to right, but from a numeric point of view we read numbers right to left, i.e. 1s then 10s then 100s then 1000s etc.

From the above examples, we can see that if F1 is already switched on, we can easily switch on F3 as well by simply turning on the F3 bit. We accomplish this by simply adding the F3 bit:
Base + F1 + F3 = 0 + 1 + 100 = 000 + 001 + 100  = 101

We can also remove flags, for example if we have F3 and F1 set, but then remove F1 we have:
101 – 001 = 101 – 1 = 100
But even though these are all ones and noughts we can translate these into decimal. PHP has a handy little utility function for this: decbin() [http://php.net/manual/en/function.decbin.php]

So now this makes it really easy to turn flags on an off.
In PHP it would be as follows:

define('BASE', 0);
define('F1', 1);
define('F2', 2);
define('F3', 4);
 
echo "No flags = ".BASE.":".decbin(BASE)."\n";
 
// switching flags on
$f1_on = BASE+F1;
echo "Turn on F1 = $f1_on:".decbin($f1_on)."\n";
 
$f2_on = $f1_on+F2;
echo "Turn on F2 = $f2_on:".decbin($f2_on)."\n";
 
$f3_on = $f2_on+F3;
echo "Turn on F3 = $f3_on:".decbin($f3_on)."\n";
 
// switching flags off
$f2_off = $f3_on-F2;
echo "Turn off F2 = $f2_off:".decbin($f2_off)."\n";
 
$f1_off = $f2_off-F1;
echo "Turn off F1 = $f1_off:".decbin($f1_off)."\n";

Save this as bits.php and then run it from the command line with:

$ php ./bits.php
No flags = 0:0
Turn on F1 = 1:1
Turn on F2 = 3:11
Turn on F3 = 7:111
Turn off F2 = 5:101
Turn off F1 = 4:100

All good so far, but now we need to see if a particular flag is switched on or off. I’ll publish that in my next blog post. So stay tuned.

The internet is great! Clearly it wasn’t just me having a problem, Guido Stevens was also suffering and posted a fix, which he himself found on another blog post by Chris Miller, which Chris in turn found on StokeBloke.com which had been found originally on a now dead post.

Not bad! Four people all having problems with the same thing and posting a fix for others to share. So I thought I’d join the chain, and write this blog post.

Oh yes, and the fix itself:

;; fix css mode
(require 'css-mode)
(setq cssm-indent-level 2)
(setq cssm-newline-before-closing-bracket t)
(setq cssm-indent-function #'cssm-c-style-indenter)
(setq cssm-mirror-mode t)