December 11, 2009

Write a TextMate Command to Order your CSS Properties

I like to have my css property lists ordered by string length (smallest to largest). Some my find it fussy but I feel they are easier to read when formatted this way. Looking at this stuff all day makes my eyes pretty tired and I'll do whatever I can to improve things.

TextMate has a great feature called Commands. These are essentially small programs you can write using common programming languages (I prefer php since it's the only one I know). You can invoke these commands using key shortcuts or tab triggers.

Since I spend a lot of time formatting my css, I wanted to make it an automated process that I could fire off using the key shortcut option+return.

Be careful not to use an existing key shortcut when choosing your own. TextMate is smart enough to not overwrite the previous shortcut but instead shows you a contextual menu of the choices bound to the shortcut. This slows down the workflow, adding more steps to get the end result.

Start by opening a new document and select Bundle Editor > Show Bundle Editor

With the Bundle Editor open, select New Command. This will create a new command in whatever bundle was currently selected.

I prefer to keep all my customizations in my own bundle. This makes it easy to keep the bundles current between my home and work machines. It also makes it easy to share with friends. To create your own bundle simply select the "New Bundle" menu item first. Then add a "New Command" to it.

Give the new command a descriptive title.

Next, select what input you'd like. This is what gets passed to your command from the document. Choose "Selected Text" with a fallback of "Scope". For the output, choose "Replace Selected Text". You can also use "Show as Tool Tip" while debugging. This simply pops up a yellow tool tip showing you the result.

TextMate tracks the location your cursor to determines it's scope. For instance, if you're in-between the enclosing braces in a css rule, TextMate will determine the scope as meta.property-list.css. You can check the scope of the current cursor location using the key shortcut shift+control+p.

We want to edit the order of a css property list so we'll need to use meta.property-list.css as our scope. This way, TextMate will pass us all the properties inside the enclosing braces, including the braces.

We also need to choose our activation method. We want a "Key Equivalent" for this so click inside the input field and press the key shortcut you'd like to use. The input field will record your actions and show the shortcut using the associated key icons.

To start using a specific language in your command you need to let TextMate know where to look. #!/usr/bin/php is the default path to the php executable on a mac running Snow Leopard.

Open the php declaration with <?php and start coding.

Make sure there is no empty lines between the php path and opening declaration. If there is, this will get returned to your document in the form of an unwanted newline character. This drove me batty until a helpful person replied to my question on the TextMate mailing list.

Here's the tricky part, getting the input parsed out from the STDIN (standard input) constant. I referred to this excellent explanation for help. To see other data to which you have access, use print_r($_ENV). This shows an array of goodies you can use in in your command.

[updated 12.13.09] - Allan Odgaard suggested using file_get_contents("php://stdin") instead of $fstat = fstat(STDIN); $stdin = fread(STDIN, $fstat['size']); The updated command can be downloaded using the same download link at the end of the article.

Here is the full commented code for the command.

#!/usr/bin/php
<?php

// Get the properties list
$stdin = file\_get\_contents("php://stdin");

// remove the enclosing brackets
$pattern = '/\\{(.\*)\\}/Us';
preg\_match($pattern, $stdin, $matches);

// Trim off the whitespace
$match = trim($matches\[1\], "\\n");

// Turn each line into a member of an array
$match = preg\_split('/\\n/', $match);

// Check the string length of each member.
function sort\_strlen($val\_1, $val\_2) {
       // initialize the return value to zero
       $retVal = 0;

       // compare lengths
       $firstVal = strlen($val\_1);
       $secondVal = strlen($val\_2);

       if($firstVal > $secondVal) {
               $retVal = 1;
       } else if($firstVal < $secondVal) {
               $retVal = -1;
       }

       return $retVal;
}

// Iterate through the array using the preceding function to organize the array.
uasort($match, "sort\_strlen");

// Wrap the finished product in braces.
$output = '{' . "\\n";
foreach($match as $line) {
	$output .= $line . "\\n";
}
$output .= '}';

echo($output);
?>

Now that I have added my command and if my cursor is located inside a properties list, I can invoke it using option+return.

Here is what my properties looks like before the command:

And after: