Ana Nelson

A Rails Application Factory

2008-08-28T21:14:19+01:00

Please visit the website for source code downloads and syntax highlighting.

A Rails Application Factory

This is a post about creating fresh Rails applications quickly and maintaining them easily over time. The approach I take here could easily be applied outside of Rails to any software project.

My Philosophy of Friction

I like to think about productivity in terms of “friction”. My inner economist wants me to call this “marginal cost” but my inner consultant thinks “friction” will sell better. The principle I try to organize by is that things which you want yourself to do on a regular basis: exercise, eat well, churn out a shiny prototype in next to no time; should be quick and painless. You should try to reduce the friction between you and your desired outcomes. So, make it easy to eat well by stocking the kitchen with plenty of healthy, easy-to-prepare food. If you never go to the gym because there’s never any parking, or you have to make a tricky right turn to get into the car park (I live in Ireland, remember, where right turns are the tricky ones), this is friction and the more friction there is, the less likely you are to do something. Join a different gym, or make yourself consciously aware of the friction and make the decision to go to the gym anyway. Friction is nefarious since it works on our subconscious, sometimes just being aware of it can remove its influence, but staying aware of it is difficult.

Reducing friction for good things, and increasing friction for bad things (put those cookies on the TOP shelf), can be a simple and effective guideline for orienting your practices towards your goals. (But, please do remember that marginal thinking does not show you the entire picture. Somewhere you need to think about the sum of what you are doing, not just marginal increases or decreases. Friction is very useful as a short-term heuristic, though, and it’s also usually the right tool for predicting behaviour in other people, especially users of software. Check out Why We Buy by Paco Underhill, one of my all-time favourite books for its content and basically all about friction.)

So, this week I decided to reduce a few forms of friction in my programming life. To begin with, I wanted to improve my strategy for creating a fresh Rails application.

Creating A Fresh App

Of course, actually building a generic Rails application is very straightforward, you simply type:

1	rails example

and you will have a new directory called example which contains a skeleton Rails application. Very quickly, though, a skeleton Rails application isn’t going to be enough. Most developers will have a collection of plugins, rake tasks and other goodies which they want to install on every application. I head straight for rspec and active_scaffold. Also, I don’t have any use for public/index.html or the test/ directory so I will always delete these. The details don’t really matter, the point is that there is a series of repetitive tasks which we do whenever we set out to create a new Rails application.

My original approach to automating this was to write a shell script which went through the various steps for me:

# Usage: bash setup_rails projectname
rails $1
cd $1
ruby script/plugin install svn://rubyforge.org/var/svn/rspec/tags/CURRENT/rspec
ruby script/plugin install svn://rubyforge.org/var/svn/rspec/tags/CURRENT/rspec_on_rails
ruby script/generate rspec
ruby script/plugin install http://svn.caldersphere.net/svn/main/plugins/rspec_autotest
svn export http://activescaffold.googlecode.com/svn/trunk vendor/plugins/active_scaffold
svn export http://activescaffoldexport.googlecode.com/svn/trunk vendor/plugins/activescaffoldexport
svn export http://dev.agent.ie/svn/rails/generators/ajax_rspec_resource/ lib/generators/ajax_rspec_resource
ruby script/plugin install exception_notification

echo "About to drop and recreate development and test databases. Next password prompt is for mysql user password."
echo "drop database if exists $1_development;" | mysql -u root -p
echo "drop database if exists $1_test;" | mysql -u root -p
echo "create database $1_development;" | mysql -u root -p
echo "create database $1_test;" | mysql -u root -p

Wow, mysql and svn, that takes me back. ;-)

With this script, I could create a new Rails application in a few seconds and my favourite plugins would be installed and configured, databases would be set up and a custom generator installed and ready to go.

This was definitely better than nothing, but it had some problems. I would tend to have a spurt of starting a few new projects, and then there would be a lull of a few months where I was working on existing projects. By the time I went back to use this script again, things would have changed. Plugins would have moved or I would be using different ones. Or, I would forget I had written the script and find myself halfway through setting up an application manually before I remembered that, yes, I invented an easier way to do this once upon a time. But, the crucial flaw in the setup_rails.sh concept is that it does nothing to help you automate the maintenance of your Rails applications. I had automated the birth process, but not the much more onerous ongoing maintenance which is necessary for any piece of software with external dependencies.

So, finally, this morning I worked out a strategy which is going to solve all of these problems. There’s no script involved, just some really easy branching and merging using, in my case, the Bazaar version control system.

The strategy is:

create a skeleton Rails application configured just the way I like it named template-rails
each time I want to create a new Rails application, I bzr branch template-rails my_new_app. This creates a copy of the contents of template-rails in a new directory called my_new_app, and the my_new_app branch “remembers” that it originated from template-rails.
each time I upgrade a plugin, tweak a rake task, write a new spec helper or anything else that I want to share amongst more than one application, I make this change to template-rails and then bring the changes into each application by just typing bzr merge and, later, committing the changes.

So, this covers both creating and maintaining applications in one easy step. Because I interact with version control on a daily basis, I’m not going to forget what my setup is, whereas I might easily forget about a six-month-old shell script tucked away in some bin/ directory.

Bazaar Tricks

I’m sure you could do this with any version control system that has good (low-friction!) support for branching and merging. I happen to be partial to bazaar because, coming from subversion, it took me 5 minutes to learn the basics but I’m still discovering wonderful little features that make my life so much easier. Just this morning, for example, I learned that if you bzr rm --new --keep, bazaar will remove whichever files you have just accidentally added to your repository without deleting them, they just go back to being “unknown” files. This is GREAT when you add several directories without adding, say, ”.git” to your .bzrignore file. You can just undo the add, tell .bzr to ignore the pattern, then safely add just the files you want. When I use a plugin from github I git clone it and leave the git branch information intact. It doesn’t conflict with bzr and I can easily pull down changes.

A trick which is particularly useful for working with a template like I have been describing is described in Section 7.2.3 of the Bazaar user guide. While I would probably go into template-rails/ to pull down the latest version of a plugin, if I am editing something I have written myself like a rake task or a spec helper, chances are I’m going to be working on this and testing this in a live application. But, once I have upgraded or fixed the code, I probably want to bring this change back into my template so it can be shared with my other apps and any apps I create by branching this template in the future. Here is a nice little workflow assuming I start out in my example/ application directory:

cd ../template-rails
bzr merge --uncommitted example/
bzr diff
bzr commit . -m "Refactor matchers to derive description automatically from class name."
cd ../example
bzr merge
bzr commit . -m "Merged changes from template."

The merge --uncommitted example/ is just a fantastic little command which gets whatever changes you have made in the example/ branch but not yet committed (this does not know about “unknown” files, so if you create a new file you have to add it to the repository for it to show up here). So, you can happily develop and test in any of your branches and pulling the changes back to the template is a couple of quick commands away.

Sharing Code

A side effect of adopting a system like this is, because you have reduced the pain (or friction, or marginal cost) associated with sharing code between your applications, you are more likely to share code. You are more likely to write test helpers, custom rake tasks and your own plugins. Sharing code between your applications is a great way to improve it and the lessons you learn from testing your plugin on its 2nd Rails application will improve its performance and stability in the Rails application you originally developed it for. You are more likely to keep all your Rails applications running on an up-to-date version of Rails too.

I have mentioned Rails and some Rails-specific terminology quite a lot, but of course the idea of setting out a standard structure in a template and branching from this could be applied to very many situations. In fact, because Rails has a pretty good directory structure by default, I’m guessing I will feel the benefit of this approach much more in non-Rails project. For example, I am doing a lot of data analysis work using just DataMapper and a console, no web framework of any kind required, and I have started to work with a certain self-imposed project structure but now I am going to set up a template so that I don’t succumb to the temptation to re-invent this structure on every project.

One of the reasons I am pretty excited about sharing code between applications easily is that I have been developing some very fun tools over the past few weeks for rapid model prototyping in Rails using rspec and railroad. Stay tuned.

JRuby Wrapping For ANTLR

2008-06-27T18:33:55+01:00

Please visit the website for source code downloads and syntax highlighting.

JRuby Wrapping For ANTLR

I use ANTLR, a fantastic parser generator, for various parsing tasks and experimenting with DSLs¹. ANTLR is one of the tools that makes it possible to “write code that writes code”. Previously I wrote about capturing Java’s output and error streams in JRuby, and I used this trick to write a wrapping for ANTLR which makes it very easy to unit test grammars as well as to integrate ANTLR parsers into a Ruby class. I call it AntlrVelvet.

AntlrVelvet is just a Ruby module, so you need to require the file and then include the module in a class:

require 'antlr_velvet'

class Expr
  include AntlrVelvet  
end

And… that’s it. We now have a parser! By default, AntlrVelvet assumes you have given your class the same name as you gave your parser, in this case Expr. (You can easily override this.) ExprLexer.class and ExprParser.class need to be on the Java CLASSPATH somewhere, but if they’re in the same directory as antlr_velvet.rb this will be taken care of automatically.

Let’s take a quick look at Expr.g, the ANTLR grammar file, and see what super-powers we have given our Ruby class with these 4 lines of boilerplate.

// http://www.antlr.org/wiki/display/ANTLR3/Expression+evaluator
// [The "BSD licence"] Copyright (c) 2005-2008 Terence Parr All rights reserved.

grammar Expr;

@header {
import java.util.HashMap;
}

@members {
/** Map variable name to Integer object holding value */
HashMap memory = new HashMap();
}

prog:   stat+ ;
                
stat:   expr NEWLINE {System.out.println($expr.value);}
    |   ID '=' expr NEWLINE
        {memory.put($ID.text, new Integer($expr.value));}
    |   NEWLINE
    ;

expr returns [int value]
    :   e=multExpr {$value = $e.value;}
        (   '+' e=multExpr {$value += $e.value;}
        |   '-' e=multExpr {$value -= $e.value;}
        )*
    ;

multExpr returns [int value]
    :   e=atom {$value = $e.value;} ('*' e=atom {$value *= $e.value;})*
    ; 

atom returns [int value]
    :   INT {$value = Integer.parseInt($INT.text);}
    |   ID
        {
        Integer v = (Integer)memory.get($ID.text);
        if ( v!=null ) $value = v.intValue();
        else System.err.println("undefined variable "+$ID.text);
        }
    |   '(' expr ')' {$value = $expr.value;}
    ;

ID  :   ('a'..'z'|'A'..'Z')+ ;
INT :   '0'..'9'+ ;
NEWLINE:'\r'? '\n' ;
WS  :   (' '|'\t')+ {skip();} ;

Expr.g is taken directly from the ANTLR wiki, it is an expression evaluator. We can assign integer values to variables and perform simple arithmetic operations.

Let’s start feeding in some strings. If you have JRuby and ANTLR installed, you can download antlr_velvet_demo.rb etc. and play along.

AntlrVelvet has convenience methods for parsing files as well as strings. We’ll just parse strings. To initialize a new string parser, you do:

30	parser = Expr.string_parser("1 + 1")

parser is now all ready to parse, but the parsing hasn’t happened yet. Because AntlrVelvet is designed for unit testing, it doesn’t make any assumptions about how you want to parse. If you call parser.prog, it will parse according to the Expr grammar’s main prog rule. You might only want to test a part of your grammar, however, such as an atom or an expr. You can call any rule defined in your grammar, e.g. parser.atom, and the string you passed at initialization will be evaluated against that rule.

So, let’s try this now:

34	puts parser.prog

we get:

1	line 0:-1 missing NEWLINE at '<EOF>'

Oops. Okay, we tried comparing "1 + 1" to the prog rule and we got an error, because the prog rule expects to process one or more stat rules, each of which are newline-terminated. If we add a newline at the end:

41
42

parser = Expr.string_parser("1 + 1\n")
puts parser.prog

we get:

nil

nil? Honestly, how hard is 1 + 1 = 2? Okay, looking back at Expr.g I see that prog doesn’t actually return a value. Let’s try an expr since according to the grammar that should return an int.

46
47

parser = Expr.string_parser("1 + 1")
puts parser.expr

2! Excellent. After all this we can add 1 and 1.

Now, let’s take another look at stat, since that really does seem to be the main action. We don’t return anything, but we do write to System.out.println(). Remember AntlrVelvet captures Java’s output and error streams so it can look for parsing errors and raise an exception if it sees one. If you want to get at the contents of the output stream, you do this via the output method.

51
52
53

parser = Expr.string_parser("1 + 1\n")
parser.stat
puts parser.output.inspect

["2"]

So, we have an array with a 2 in it. This is because stat prints out expr.value every time it gets called. Now, let’s try calling prog again with some additional input.

parser = Expr.string_parser("
1 + 1
x = 1
y = 2
3*(x+y)
")
parser.prog
puts parser.output.inspect

1	["2", "9"]

The first “2” comes from 1 + 1. The lines x = 1 and y = 2 are of the form ID = expr NEWLINE, they are variable assignments rather than expr evaluations, so nothing is added to the output buffer, instead the parser executes the memory.put ... action. The final line is an expr which evaluates to 9 and so this is added to the output buffer. Note the extra newline at the end of our input, if this wasn’t there we would end up with an EOF error. (Of course you can easily write a grammar which doesn’t need a newline at the end if you want to.)

Let’s do one more example.

68	puts Expr.string_parser("1 + 2 * (3 + 4 * (5 + 6 * (7 + 8 * 9)))").expr

There’s some nice mutual recursion in Expr.g that lets it handle nested parentheses like this, go check it out if you haven’t seen it before.

Now, Expr.g doesn’t do anything mathematically that we couldn’t do in Ruby. What it does do is let us accept a string and only perform this calculation if the string conforms to our grammar. So, if, say, you were writing a web application and wanted to allow your users to perform arithmetic on your website, but for some reason you didn’t feel like doing this via² <%= eval(params[:arithmetic_expression]) %>, something like an ANTLR grammar might let you nicely sandbox and sanitize your user’s inputs. And, Expr.g might not be able to do anything all that fancy, but a more complex grammar might give you (and your untrustworthy users) some really interesting functionality.

So, to recap, Expr.string_parser returns an object of class Expr, a Ruby class. We can call any of the grammar’s rules as a method on that object and they will parse the string according to that rule, and the method will return a value if the rule returns a value.

After we have done the parsing, we can call parser.output to see what’s in the output buffer. This will either be an array of strings or nil. We can also call parser.parser or parser.lexer to return the ExprParser or ExprLexer, the actual ANTLR objects which do the parsing. Remember Expr is just our wrapper class. We can even call parser.token_stream. And, since this is JRuby, we can have some introspection fun with these objects:

93	puts java_methods(parser.parser.methods)

already_parsed_rule
atom
backtracking_level
begin_resync
consume_until
display_recognition_error
emit_error_message
end_resync
equals
expr
grammar_file_name
hash_code
input
java_class
java_object
match
match_any
memoize
mismatch_is_missing_token
mismatch_is_unwanted_token
mult_expr
notify
notify_all
number_of_syntax_errors
prog
recover
recover_from_mismatched_set
report_error
reset
rule_invocation_stack
rule_memoization_cache_size
source_name
stat
synchronized
to_java_object
to_string
to_strings
token_names
token_stream
trace_in
trace_out
wait

97	puts java_methods(parser.token_stream.methods)

consume
discard_off_channel_tokens
discard_token_type
equals
get
hash_code
index
java_class
java_object
la
lt
mark
notify
notify_all
release
reset
rewind
seek
size
source_name
synchronized
to_java_object
to_string
token_source
tokens
wait

101	puts java_methods(parser.lexer.methods)

already_parsed_rule
backtracking_level
begin_resync
char_error_display
char_index
char_position_in_line
char_stream
consume_until
display_recognition_error
emit
emit_error_message
end_resync
equals
grammar_file_name
hash_code
java_class
java_object
line
m_id
m_int
m_newline
m_t__10
m_t__11
m_t__12
m_t__13
m_t__8
m_t__9
m_tokens
m_ws
match
match_any
match_range
memoize
mismatch_is_missing_token
mismatch_is_unwanted_token
next_token
notify
notify_all
number_of_syntax_errors
recover
recover_from_mismatched_set
report_error
reset
rule_invocation_stack
rule_memoization_cache_size
skip
source_name
synchronized
text
to_java_object
to_string
to_strings
token_names
trace_in
trace_out
wait

So, here we have the internals of ANTLR laid out. You can see the values of any of these methods. Play with them. Use them for testing. Go into an interactive jirb session and follow the lexing and parsing step-by-step until you know exactly how the grammar does its thing.

By the way, AntlrVelvet uses method_missing to pass method calls like prog and stat on to the embedded ExprParser object, but you could also explicitly define any of these methods and call the ExprParser yourself. This can be useful if you want to do some Ruby post-processing or perhaps debugging. If you do this, you will need to invoke AntlrVelvet’s capture_java_streams yourself if you don’t want Java writing to your console. And remember, in JRuby Java’s System.out and Ruby’s $stdout are totally independent of each other. So if you have Ruby’s $stdout redirected to a logfile, Java’s System.out will still write to the console unless it, too, has been redirected.

class Expr
  def atom
    puts "Your atom is " + @parser.atom.to_s
  end
end

Expr.string_parser("99").atom

1	Your atom is 99

On to testing! I’m just using Ruby’s Test::Unit for now. To begin with, I define some custom assertions and convenience methods:

  def assert_nothing_left(parser)
    assert(parser.token_stream.index == parser.token_stream.size)
  end

  def assert_something_left(parser)
    assert(parser.token_stream.index < parser.token_stream.size)
  end

  def assert_valid_input(method, input_string)
    assert_nothing_raised do
      parser = Expr.string_parser(input_string)
      parser.send(method)
      assert_nothing_left(parser)
    end
  end

  def assert_too_much_input(method, input_string)
    parser = Expr.string_parser(input_string)
    parser.send(method)
    assert_something_left(parser)
  end

  def assert_invalid_input(method, input_string)
    assert_raise(AntlrError) { Expr.string_parser(input_string).send(method) }
  end

  def parsed_value(method, input_string)
    Expr.string_parser(input_string).send(method)
  end

  def parser_output(method, input_string)
    parser = Expr.string_parser(input_string)
    parser.send(method)
    parser.output
  end

To recap the examples from earlier in test form:

  
  def test_prog_without_newline
    assert_invalid_input(:prog, "1 + 1")
  end

  def test_prog_with_newline
    assert_valid_input(:prog, "1 + 1\n")
  end

  def test_expr
    assert_equal 2, parsed_value(:expr, "1 + 1")
  end

  def test_stat_output
    assert_equal ["2"], parser_output(:stat, "1 + 1\n")
  end

  def test_prog_output
    str = "
     1 + 1
     x = 1
     y = 2
     3*(x+y)
     "

     assert_equal ["2", "9"], parser_output(:prog, str)
   end

   def test_nasty_expr
    assert_equal 3839, parsed_value(:expr, "1 + 2 * (3 + 4 * (5 + 6 * (7 + 8 * 9)))")
   end

The assert_valid_input, assert_invalid_input and assert_too_much_input just take a symbol and an input string for the parser. assert_invalid_input expects the parsing to throw an AntlrError, meaning that ANTLR wrote something to Java’s System.err. This is used when you want to make sure that the input string is illegal for the rule in question, either too short or containing illegal characters or sequences. assert_too_much_input means that the input is acceptable, but after processing there’s something left over. In order for assert_valid_input to pass, ANTLR must not find any errors and the input string must be entirely consumed.

parsed_value and parser_output also take a symbol and an input string as arguments. They parse the string and return the grammar rule’s return value or the text written to System.out respectively. Then you can write assertions for what the value or output should be, as shown. assert_nothing_left and assert_something_left are mostly for internal use, you have to initialize and run a parser yourself before passing the parser in to these functions, but of course you can call these directly if you want to.

I use ANTLR’s Java target because, as of this writing, the Ruby target for ANTLRv3 isn’t complete enough to be practical. Even though I’m not a fan of Java, I have to say that I really don’t mind the little bit of it I have to write in a ANTLR grammar. If you are a Ruby programmer, don’t let a bit of Java scare you away from the possibilities that ANTLR opens up. And, if you are a Java programmer, I hope this has demonstrated that JRuby can be a useful complement to Java, giving you a fantastic scripting language and testing environment for development, even if it doesn’t play any role in your final product.

As usual, all the source code is available for download from the sidebar. If you have any difficulty running any of the files, please let me know in the comments.

¹ However, if you want to write a syndicated advice column protocol then you might want a more state-machine-oriented tool like Ragel.

² Joke!! I’m KIDDING people!! You really think I would put something so unsafe in my code? Of course I meant <%=h eval(params[:arithmetic_expression]) %>.

In Touch With .htaccess

2008-06-20T12:17:01+01:00

Please visit the website for source code downloads and syntax highlighting.

In Touch With .htaccess

(I’m actually not sure why I have named this post that, but it has stuck in my brain and refuses to budge. Also I seem to have a four-word title thing going on since moving to Webby, so I’m going with it for now.)

One of the many, many things I am loving about Webby is getting to play with .htaccess files. They are such brilliant little utilities to have at your disposal. I actually still find it a novelty to upload files and directories to a server and then see those pages in my web browser, and getting to do fun tricks with .htaccess is just icing on a very yummy cake. I’m not going anti-web-framework or anything, really I’m not, but it sure is refreshing to get back to basics.

.htaccess vs. Sitewide Config

According to Apache, you should avoid using .htaccess files as much as possible and instead put your instructions into the main server configuration file. They have some good arguments, but I think .htaccess files make a lot more sense for the uses I’m describing. (Of course, it’s a moot point since I am on shared hosting and don’t have access to my main server configuration file.)

I like .htaccess files since they are utterly immediate. You put them right where you need their functionality. Your 5 lines of code aren’t lost in a 4,000 line conf file in some directory you can never find. You can see it, change it, version it. You won’t forget that it’s there. If you delete the directory, you delete the configuration along with it. It will always be deployed, automatically, at the same time as the rest of your site. It’s a perfect fit with Webby.

Redirects

I set up my first .htaccess file to do some permanent redirects. I made a big mistake with my old blog. I displayed the full text of articles on lots of pages throughout the site, like tag pages and monthly and yearly archive pages, but I didn’t put NOINDEX tags on these pages. So, search engines had no way of knowing which was the actual permanent location of the blog post content, and which was just a /tagged/with/buzzword page. Unfortunately, in many cases the tag page ended up being much more prominent on Google than the actual blog post. I’m guessing this was because I was silly enough to put tag clouds in my sidebar, so these /tagged/with pages had lots of internal links pointing to them, hence they looked more important.

I have now decided that tags are a total waste of time anyway. Nobody needs tags to find your content. That’s what search is for. Google knows how to semantically parse your content much better than you do. It will find the important words. If you really want to have tags on your blog then go bookmark all your blog posts in del.icio.us. Or, better yet, go and see what other people have tagged your posts with. Those are the tags that really matter anyway, the ones your readers assign.

Getting back to the point, if you have any of your content duplicated anywhere on your site, then NOINDEX tags are your friend. Only let the search engines see 1 copy of your content. Everyone will be much happier that way. Since I didn’t do this, and I still get (relatively) plenty of inward traffic to some of these /tagged/with pages, the first .htaccess file I set up was along these lines:

1
2
3

Redirect 301 /tagged/with/pictobrowser http://ananelson.com/said/on/2007/12/17/screencasts-are-so-2005
Redirect 301 /tagged/with/skitch http://ananelson.com/said/on/2007/12/17/screencasts-are-so-2005
Redirect 301 /tagged/with/loldocs http://ananelson.com/said/on/2007/12/17/screencasts-are-so-2005

This is the sort of thing I probably would put into a sitewide conf file if I had access to it. They are redirects which can be safely forgotten about, I’ll probably take them out eventually but they won’t do any harm if they stay there indefinitely. I redirected the more popular tag pages directly to the blog posts they refer to, then I added a catch-all to redirect any other pages to the list of all my old blog posts:

7	RedirectMatch 303 ^/tagged http://ananelson.com/said/on

As with any regular expression based scenario, make sure catch-alls go AFTER everything else that their pattern might match.

By the way, you can increase the verbosity of Apache mod_rewrite logging temporarily to help you debug RedirectMatch statements. Comes in handy if you are trying to figure out how to do fancy regular expression redirects. (But don’t leave it on a high setting unless you are impressed by the size of really large log files.)

Custom Directory Listings

I have a /tmp directory which I am experimenting with at the moment. It’s, well, a place for me to dump temporary files. I knew, of course, that Apache will simply display the contents of a directory unless you tell it not to. I didn’t know until yesterday that you can customize the way it does this. You can even add your own stylesheets so that the directory contents list looks like the rest of your site. So, of course I had to play with this! I have a .htaccess file in /tmp which says:

10
11
12

IndexOptions +SuppressHTMLPreamble +IgnoreCase NameWidth=*
HeaderName apache-index-header.html
ReadmeName apache-index-footer.html

The +SuppressHTMLPreamble lets you define our own HTML headers (and therefore stylesheets), otherwise you are stuck with HTML 3! You specify a file HeaderName which should include opening <html> and <body> tags, and then a file called ReadmeName which should include the closing </body> and </html> tags. Apache will stick your directory contents in the middle.

Restricting Access

Another obvious use for .htaccess files is to restrict access to places you don’t want people to go. Sometimes, you just don’t want a directory’s contents to be listed but the items in that directory still need to be accessible. I have a /bin directory which contains some files, like the comment submission form, which need to be accessible, but I don’t really want people snooping in my /bin directory. (Not for security, just aesthetics.) So, there’s a .htaccess file in there with Options -Indexes. I have some other directories which contain files that are only going to be used via the file system on the server. These I can restrict access to completely with deny from all. It’s convenient for me to deploy these files using Webby, and with deny from all they are neatly hidden.

Drafts in Webby

A nice way to work on drafts of blog posts in Webby is to add a .htaccess file to the directory containing your post with a deny from all statement in it. (I put each post in its own directory with the post in an index.html file.) In this way the blog post is invisible on your website, so you can continue to deploy your site as normal, but locally Webby’s built in heel server will ignore .htaccess files so you will be able to see the drafts yourself when you autobuild. You need to combine this with some way to prevent the blog post from being mentioned in your RSS feed or on your archive pages. I stick index: false in the metadata until I am ready to publish (see this thread on the Webby mailing list) and I comment out the created at timestamp. In fact I do this in my blog template so blog posts are “unpublished” by default.

#####
# Uncomment created_at time,
# delete index: false
# and delete the .htaccess file
# when ready to post this article.
created_at: # <%= Time.now.to_y %>
index: false
#####

Those of you who got a feedful of lorem from me last night will, no doubt, appreciate this precaution. Sorry about that, and props to Fintan who took the time to reply in Latin.

You put the feed where?

When I was setting up my new atom feed I noticed that WordPress put the old feed at http://ananelson.com/feed/. A directory. Seriously, mod_rewrite has a lot to answer for. .htaccess to the rescue, though. I was able to solve this by creating a directory feed/ and putting

15	DirectoryIndex blog.xml

so that requests for /feed/ fetch the blog.xml file. But please, this is just wrong, update your subscriptions to the new feed.

Mime Trouble

You may have noticed the source code files in the sidebar. They will get an explanatory post of their own soon. There is lovely pygments syntax highlighting¹ in my blog posts, but in the sidebar I want people to be able to click and just view the full plain source in their browsers. (If you would rather download that’s what the .tgz is for.) Unfortunately some file extensions won’t display in the browser, they will download and try to open themselves with really bizarre applications. QuickTime for Ragel files?

But, as you may have guessed, this can be fixed with a .htaccess file! All we need to do is:

18
19
20

AddType text/plain .sh
AddType text/plain .rl
AddType text/plain .php

For whichever file extensions we want. I put this .htaccess file in my blog/ directory so it only affects subdirectories of that and I can have working files with these extensions elsewhere in my site.

Right, that’s all. I’m going off to play with mod_expires now.

¹ As used by GitHub. Yes, that’s right, they use a syntax highlighter written in Python.

Beware POST Request Redirects

2008-06-18T18:09:02+01:00

Please visit the website for source code downloads and syntax highlighting.

Beware POST Request Redirects

You probably know that you should choose either example.com or www.example.com for your website, but allowing both of these effectively means that you are splitting your search engine ranking in two (if you care about such things). I use Dreamhost and they make it very easy to redirect all traffic to one or the other of these. They do this using a 301 (permanent) redirect. For example, if you type curl http://www.ananelson.com, you will see:

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<HTML><HEAD>
<TITLE>301 Moved Permanently</TITLE>
</HEAD><BODY>
<H1>Moved Permanently</H1>
The document has moved <A HREF="http://ananelson.com/">here</A>.<P>
</BODY></HTML>

You can easily set this up yourself in your Apache config or a .htaccess file.

Now, something I’ve managed to do twice in the last week is to POST a form to the www-version of my domain, which then was redirected to the non-www version. When this happens, all the POST data is lost! (See the Apache documentation.) So, remember, when creating a form set its action URL to whichever is the preferred variant of your domain name so that no redirect takes place.