It didn’t take me long to realize that I could turn this into a framework where I could turn any Markdown file into a tutorial exactly like this one. So with surprisingly little work I modified the scripts to work with any markdown file and the html automatically generated from the standard Markdown.pl script.

I called this markdownorial. Laugh all you want at the name, but I still think the concept is very cool. I’ll probably be using this more and more to automatically generate and format a pretty cool looking tutorial from a single markdown file. The start to finish time for a project like this has instantly dropped to just the raw content part, no design or coding needed!

Advantages include:

• Writing Markdown is very fast and efficient.

• Time is spent writing the content. Not messing with design,

• Table of Contents is automatically built for you.

• Useful permalinks are automatically generated. Very useful when passing around links.

• Clean user interface that focuses entirely on the content but the Table of Contents is always available!

• Git Repository means if I update the design its just a `git pull` away to get the update.

Right now the tutorials shows up elegantly in all standards compliant browsers. Safari/Webkit and Chrome display it perfectly. Opera has some very minor Unicode issues but displays everything perfectly. Firefox has some separate Unicode issues and if you don’t have the latest version it has some working but slow animation. Overall, its entirely usable for people using decent browsers.

Let me know what you think. Feel free to use it and improve it. Its all up on Github.

This tutorial covers the basics of .htaccess, Apache’s Per Directory Configuration Files. Fortunately, with the basics out of the way, I can move on to the cooler features such as GZip encoding and mod_rewrite for the next article.

Also the examples can be viewed here:
http://bogojoker.com/htaccess/part1/

And the examples can be downloaded here:
http://bogojoker.com/htaccess/part1_examples.zip

Enjoy!

I’m not going to go over HTTP Headers. thats already been done. Instead I’m going to focus on debugging and working with them a little bit. I’m going to assume you have already the general concepts.

The Problem

I wanted to add pagination to the skreemr shell. So you could run a search, then get the next page of results, etc. So a little experimentation with skreemr in my browser produced the following URLs:

http://skreemr.com/results.jsp?q=test

http://skreemr.com/results.jsp?q=test&l=10&s=10

http://skreemr.com/results.jsp?q=test&l=10&s=20

A simple pattern! “q” is the query string, “l” is the number per page, “s” is the number to start at, indexed from 0. So that last URL would produce results 21-30. This all worked well in my browsers, but it wasn’t working in Ruby:

require 'open-uri'

# Grab the pages and read the content
str1 = open( 'http://skreemr.com/results.jsp?q=test'      ).read  # 1-10
str2 = open( 'http://skreemr.com/results.jsp?q=test&s=10' ).read  # 11-20

#=> Should print false... but its printing true!
puts str1==str2

What this was saying was that the content being returned from both of those urls is EXACTLY the same. That couldn’t be… could it?

More Investigation

At this point I thought it was a problem in Ruby. I figured Ruby was doing some caching in the background that I was going to have to disable or work around. (I now know this is not true, but that was my first guess). To test that hypothesis I turned to my trusty friend curl and checked to see if that showed the proper behavior:

shell> curl 'http://skreemr.com/results.jsp?q=test'      -o 1.html
shell> curl 'http://skreemr.com/results.jsp?q=test&s=10' -o 2.html
shell> diff -q -s 1.html 2.html
Files 1.html and 2.html are identical

What!?! That stunned me. Curl was getting the exact same results as Ruby. I took a look at the html files, and indeed 2.html, which should have contained results 11-20 held 1-10. I opened both urls in my browser… they showed the correct results. Something weird was happening!

Take A Step Back

At this point you’ve got to know what is happening. Curl and Ruby (using Ruby’s Net:HTTP under the hood) are just making a simple GET request. Both my browsers Safari and Firefox are sending far more then just a GET request. They are sending a bunch of other headers. Lets take a look at what Firebug says Firefox sent:

Thats a mighty long list of headers! Its entirely possible that one of those might be influencing the server. Onto the drama!

Time to Act – Literally

The only difference between what curl sent in its request and what Firefox was sending is that header information and possibly any information contained in those cookies (unlikely in this case). So lets make curl act as if it is Firefox by send the same headers with curl! I took a quick peek at my curl reference for the proper switches/formatting and I was ready:

shell> curl 'http://skreemr.com/results.jsp?q=test' -o 1.html
shell> curl 'http://skreemr.com/results.jsp?q=test&s=10'            \
            -H 'Host: skreemr.com'                                  \
            -H 'User-Agent: Mozilla/5.0 (...) Firefox/3.0.6'        \
            -H 'Accept: text/html,application/xml;q=0.9,*/*;q=0.8'  \
            -H 'Accept-Language: en-us,en;q=0.5'                    \
            -H 'Accept-Encoding: gzip,deflate'                      \
            -H 'Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7'     \
            -H 'Keep-Alive: 300'                                    \
            -H 'Connection: keep-alive'                             \
            -H 'Cache-Control: max-age=0'                           \
            -o 2.html
shell> diff -q -s 1.html 2.html
Files 1.html and 2.html differ

Jackpot! Some subset of those headers is indeed fixing my problem, because now it properly fetched the second page of results! Translating that back into Ruby works as well:

require 'open-uri'

# Headers
HEADERS = {
  'Host'            => 'skreemr.com',
  'User-Agent'      => 'Mozilla/5.0 (...) Firefox/3.0.6',
  'Accept'          => 'text/html,application/xml;q=0.9,*/*;q=0.8',
  'Accept-Language' => 'en-us,en;q=0.5',
  'Accept-Encoding' => 'gzip,deflate',
  'Accept-Charset'  => 'ISO-8859-1,utf-8;q=0.7,*;q=0.7',
  'Keep-Alive'      => '300',
  'Connection'      => 'keep-alive',
  'Cache-Control'   => 'max-age=0'
}

# Get the Pages
str1 = open( 'http://skreemr.com/results.jsp?q=test', HEADERS ).read
str2 = open( 'http://skreemr.com/results.jsp?q=test&s=10', HEADERS ).read

# Correctly Prints false
puts str1==str2

Problem Solved

Sure, we have a solution but its not pretty. How much is really needed? Finding that out is just a matter of eliminating the headers that do nothing. Remove one, test, remove another, test, remove another test… As long as it still works after you’ve removed an individual header you know that header wasn’t needed. It took me a few minutes but I narrowed it down to just a single header:

MAGIC = { 'Accept-Language' => 'en-us' }

This was a rather unique problem. It is rare for me to have to dip down to the HTTP Headers to see what is actually happening for such a high level problem. However, as this problem shows, its important to know what is going on under the hood. If I didn’t know about headers, I would not have been able to solve it.
]]> http://blog.bogojoker.com/2009/03/debugging-http-headers/feed/ 2 http://blog.bogojoker.com/2008/11/rdoc-introduction/ http://blog.bogojoker.com/2008/11/rdoc-introduction/#comments Sun, 30 Nov 2008 05:05:43 +0000 Joseph Pecoraro http://blog.bogojoker.com/?p=148 Automatically generating documentation from source code has been available as far back as 1993. Its so common now that its expected to be available in any mainstream programming languages. I’ve seen it most commonly in Object Oriented languages offering nicely formatted descriptions of classs and their public methods/attributes.

Consistency is Nice

The main advantage I see with automatically generated documentation is that it is consistent. Take Javadocs for instance. They are all the same. When a developer wants to work with a Java library, they expect Javadocs. Why? Because they are familiar with them. They can easily navigate them and quickly find whatever it is that they are looking for. Documentation in any other way would require wasting time learning how to use/navigate it searching for what you want to know.

RDoc is Ruby’s documentation generator. You see RDoc generated documentation all over the place in Ruby. See YAML, Hpricot, or even core classes like Array.

So, I felt if I want to continue using Ruby I should at least learn how its handled. It turns out that its easier then I thought. I’m a huge fan of Markdown syntax and RDoc turns out to be pretty close to that. So, here is what I think is all you need to know to handle producing some simple, yet thorough, documentation for a class.

RDoc Resources

Start by updating your rdoc. The latest version at the time of writing is 2.2.1. The gem provides you with the rdoc and ri tools so that you can both generate and display documentation from the command line. Here is how you can install them:

shell> sudo gem install rdoc

The best online resources I found were not surprisingly:

• RDoc’s documentation itself – an RDoc on RDoc… actually its RDoc’s classes but its overview is helpful.
• An Older Writeup by Dave Thomas – has a similar example
• Markdown Syntax – Very similar to what is used in RDoc comments

Structure

Here is a basic example that shows the structure of the RDoc as it describes a File, Class, Attributes, and Methods. The placement of the comments is important. RDoc comments are always on top of what they are documenting:

# Documentation for the file itself
# There should be a blank line between this and any class
# definition to separate the documentation about the file
# and the class.  If there is no space then the entire text
# is used for both the file and the class, no different.

# Documentation for the class itself.
# This will appear at the top of the page specific to this
# class, before any other content.
class Dice

  # Documentation for an attribute
  # To documentation each attribute you must make individual
  # calls to attr_accessor, attr_reader, and attr_writer.
  # Appears next to the attribute name in the attrs section
  attr_accessor :sides

  # Documentation for the constructor
  # Corresponds to the `new` method
  def initialize(sides)
    @sides = sides
  end

  # Documentation for a method
  def roll(times)
    Array.new(times).map { 1+rand(@sides) }
  end

  # Documentation for a method
  def beat(num)
    roll(1).first > num
  end

end

Running `rdoc` on that file creates this documentation.

Style

Rich documentation makes the important parts stand out. It makes use of HTML’s expressive power and enables lists, headers, links, bold/italics, code, and other presentation helpers. I’ll now document the Dice class and add some style and realistic content.

# == sample.rb
# This file contains the Dice class definition and it runs
# some simple test code on a 16 sided dice.  A 20 dice
# roll fight again the COMPUTER who always rolls 10s!

#
# Multi-sided dice class.  The number of sides is determined
# in the constructor, or later on by accessing the _sides_
# attribute.
#
# == Summary
#
# A #single_roll returns a single integer from 1 to the
# number of sides, _inclusive_.  However, if you want to
# roll multiple times you can can use the #roll method,
# specifying the number of rolls you want, and you will
# get an Array with the values of all the rolls!
#
# == Example
#
#    dice = Dice.new(8)   # An eight sided dice
#    four = dice.roll(4)  # An Array containing 4 rolls
#    sum  = four.inject(0) { |mem,i| mem+i } # Sum of rolls
#
# == Contact
#
# Author::  Joseph Pecoraro (mailto:joepeck02@gmail.com)
# Website:: http://blog.bogojoker.com
# Date::    Saturday November 29, 2008
#
class Dice

  # Number of sides on the dice
  attr_accessor :sides

  # Create a dice with `sides` of dice.
  # Defaults to 6.
  def initialize(sides=6)
    @sides = sides
  end

  # Returns an array of size `times` containing
  # a group of dice rolls.
  def roll(times)
    Array.new(times).map { single_roll }
  end

  # Returns the value of a single dice roll.  The
  # values are from 1 to @sides _inclusive_.
  def single_roll
    1+rand(@sides)
  end

  # A single roll challenge:
  # * makes a single_roll
  # * returns true if the roll was strictly greater
  #   then the given number
  # * returns false otherwise
  def beat(num)
    single_roll > num
  end

end

# Note that this is a constant, which is special
# and it is documented like a Class Attribute.
# This is in the RDoc generated documentation for
# the file.
COMPUTER = 10

# Note that these comments, for generic code
# are not in the RDoc generated documentation.
dice = Dice.new(16)
winCount = loseCount = 0
20.times do
  if dice.beat(COMPUTER)
    winCount += 1
  else
    loseCount += 1
  end
end

# Output
puts "You won #{winCount} times and lost #{loseCount} times!"
puts "Muhahah.  Try again later!!"           if winCount < loseCount
puts "Well Played.  I'll get you next time." if winCount > loseCount
puts "What a match!  Boy that was fun."      if winCount == loseCount

That generates this documentation.

Specifics

There are some subtle points that make this documentation format nicely. I’ll point them out and explain them. Most of this is straight from the above resources, however some of it I could not find documented anywhere.

• The file documentation links to the Dice class. Furthermore the Class documentation links down to the single_roll and roll methods. This is because:
  

  Names of classes, source files, and any method names containing an underscore or preceded by a hash character are automatically hyperlinked from comment text to their description.

  1. sample.rb was a filename and so it was automatically linked.
  2. Dice was the name of a class and so it was automatically linked.
  3. single_roll had an underscore and happened to be a method name so it was automatically linked in a few places.
  4. #roll had a hash character signifying that it should be linked.
• Sections begin with a “=” or a “==”. I prefer to use double, because it stands out more in the source code. Technically a single “=” becomes a level 1 header, and a double becomes a level 2 header. However, they both display the same.
• URIs like http://blog.bogojoker.com and mailto:email are automatically turned into links and formatted nicely.
• Bold, Italics, and Typewriter Text can be quickly formated much like Markdown:
  

  _italic_ or <em>italic</em>
  *bold* or <b>bold</b>
  +typewriter+ or <tt>typewriter</tt>

• Code is displayed if each line
• Tabular Labeled List, like the Contact information, are formatted like:
  

  label:: description 1
  label2:: both descriptions will line up

• Formatting source code is like Markdown. The code that you want formatted must be indented with a few spaces. As long as the indention is maintained the text will display as source code in the HTML documentation.
• Formatting lists is again like Markdown. Just use *’s or -’s and they will turn into bullet points. For numbered lists just use numbers followed by a dot and they will be formatted automatically.

Final Notes on `rdoc` itself

When I created the final documentation above I used a few of rdoc’s command line switches to customize the output. What I actually used was:

shell> rdoc --title="Dice Documentation" --line-numbers --tab-width=2

The title switch changed the <title> for the documentation page, and the other two deal with formatting the htmlized source code that RDoc shows when you click on the function name to view the source in the documentation. There are plenty of command line switches. To view the full list do:

shell> rdoc --help

A few useful switches are “–ri” to create ri documentation so you can access your classes from the command line. Also you can output to several formats. For instance you can make a PDF using “–format=texinfo” then using `texi2pdf` on the texinfo file. The PDF doesn’t look that bad, here is my example as a PDF.

NOTE: Finding the generators was tricky. I had to check out the rdoc source code and find the different generators. If anyone knows an easier way to check what generators are available, please let me know.

I hope this helps some people using RDoc for their classes. Enjoy.

My Visual Guide to AtomPub

Now keep in mind that I wrote that only a few weeks after learning it. The process of writing that guide forced myself to study it in greater detail than normal, actually run tests, and produce realistic output and examples. I know its not perfect (I’d probably be slaughtered for my definition of REST) but over time I’ll be happy to improve and update it. I think the design really improves the content making it readable, fun, and useful to refer to.

I’m linking to it now because I’ve done a number of projects like this (my Unix Tutorial) because I like sites that are strictly focused on one thing and do that one thing very well. I’ll probably spend a little bit of time on remainder of my break from school by cleaning up these small “brain dump” websites. I wanted to make sure they were mentioned and linked to from my blog. Clearly they will be of no use to anyone if they are never linked to!

I decided to include a small `curl` reference on my AtomPub guide. This is because its a very nice tool when working with HTTP requests and an overall generally useful shell program. I think people might find the curl reference useful.

I hope you enjoy this. I’ll be linking to these occasionally as they grow.

All of the basic examples:

1. put the string “one two three” into a variable
2. then use a regular expression and a native function to the language to
3. transform the original variable’s value to the new string “one 2 three”

Click Here For the Basic Examples

str = "one two three"
str.gsub!(/two/, "2");

$str = "one two three";
$str =~ s/two/2/;

import re
str = "one two three"
str = re.sub(r"two", "2", str)

str = "one two three";
str = str.replace(/two/, "2");

public class RegexTest {
  public static void main(String[] args) {
    String str = "one two three";
    str = str.replaceAll("two", "2");
  }
}

If you have gotten to this point you may have done something wrong...

Now you may recognize that in the above examples that regular expressions where not even needed. All we did was find and replace a string and that simple task can be done without regular expressions! So here is a more advanced example without the training wheels.

In the advanced examples:

1. the string “a1b2c3″ [may not need to be stored in a variable] is
2. manipulated by a [globally replacing] regular expression
3. resulting in “a11b22c33″ [where all numbers, but not letters, are duplicated]
4. which is stored in a variable

Click Here To Toggle the Advanced Examples

result = 'a1b2c3'.gsub( /(\d)/, '\1\1' )

$result = 'a1b2c3';
$result =~ s/(\d)/\1\1/g;

import re
result = re.sub(r'(\d)', '\\1\\1', 'a1b2c3')

var result = 'a1b2c3'.replace( /(\d)/g, "$1$1" );

public class RegexTest {
  public static void main(String args[]) {
    String str = "a1b2c3";
    String result = str.replaceAll("(\\d)", "$1$1");
  }
}

I hope this helped answer your questions on regular expressions. In case I whet your appetite on Regular Expressions I can point you to my Introductory Article on Regular Expressions and my command line utility rr that allows you to run Ruby regular expression find and replace commands on files, standard input, and even piped input.

The most basic solution was creating a procedure (also known as functions and methods), which would run the repetitive code. Every point where where one would encounter a situation where he/she would need the code they would call the procedure (with parameters if necessary) and the procedure would run the code. This had a number of advantages for the programmers.

1. The amount of code could be greatly reduced.
2. The procedures/functions could be modular by using parameters
3. Changes would only need to be made in one place, greatly enhancing maintainability

In terms of web development you will encounter programming situations in PHP and javascript where you will need to use the aforementioned method of creating procedures and functions but what about HTML/XHTML?

Repetition across HTML documents is obvious. For starters, each document will have a head and a body. Quite possibly there will be a footer within the body. More then likely the header and footer for each document will be almost exactly the same. First time programmers will see this as an excellent copy-and-paste opportunity but from an experienced perspective you can see that this is just code repetition. The copy-and-paste technique will work but will almost surely cost you more work in the future.

Imagine this common situation, you have a website with 20 separate HTML documents each with the same CSS include files and the same footer <div> which displays contact information and links. Something along the lines of a header:

<head>
  <title>My Site - Homepage</title>
  <link rel="stylesheet" type="text/css" src="general.css" />
  <script type="text/javascript" src="scripts.js" />
</head>

And a footer:

<div id="footer">
  <p>&copy; 2006-2007 My Site</p>
  <p>
     <a href="index.html">Home</a> |
     <a href="contact.html">Contact</a>
  </p>
</div>

Now imagine that you have to make a change. You might want to change the name of the css or javascript file, add a javascript file to include, change the years in the footer or change one of the link locations or names. To make any of these single changes you would have to go and manually edit all 20 pages. This is the worst possible situation and it can be easily avoided. The concept is using a template, and including repetitive code, which has the same three advantages above.

Templates are not possible solely with HTML. That is unless you are using frames in which you have little to no control and horrible cross browser computability. Don’t even try frames. Template driven websites can be created very easily with server-side programming languages (PHP/ASP) or even just using a sophisticated web server like Apache using a concept called Service Side Includes (SSI). The idea is that such a fundamental concept in both programming and design should be easy to implement, and templates are considered a major concept.

There are really only two steps needed to make this happen. First put the section of html that you want included from all of your main documents into a single file. Common extensions are .inc for include, but the extension does not matter. The above case is a nice example, you could put the footer into its own file, footer.inc. Many frameworks have an entire folder devoted to included files, often named includes/ in the root directory. This is a good idea and makes it easy to use an absolute path inside any html document on the web server to the include files.

Finally you now need to include the file from you main html documents. Here is the php way to include that file:

<?php include ‘/includes/footer.inc’; ?>

And the SSI method which looks a lot like an html comment (You may need to look into turning on SSI functionality on your webserver first, here is a resource):

<!–#include virtual=”‘/includes/footer.inc’” –>

With the correct include statement above the contents of your include file will be placed at that position in the HTML document. This is all done on the server, so the final product delivered to the client’s browser (the person visiting your website) will not be any different from the original.

There are differences between the PHP and SSI includes. Without question the PHP includes are more powerful but I’ll give a brief description of each. The SSI’s only go one level deep. This means that if you include a file, you will not be able to include another file from within the included file. SSI is meant to allow for very basic templating without a full blown server side programming language like PHP.

With PHP there are endless possibilities. The included files can contain php code. In actuality, when you include a file in PHP the contents of the file are run as if they are php code. So any php tags will be properly executed. Even the variables outside of the include are directly accessible because they are considered on the same scope as the included code.

There are a few ways you could put the above header a php include. Here is a very straightforward approach. First the PHP file to be include. I will call it ‘header.php’ because that is a clear indicator to me later that the file contains php code. Notice the php tag and variable:

<head>
  <title>My Site - <?php echo $pageTitle; ?></title>
  <link rel="stylesheet" type="text/css" src="general.css" />
  <script type="text/javascript" src="scripts.js" />
</head>

The original php file that would set the variable before the include like so:

<?php
$pageTitle = 'Homepage';
include '/includes/header.php';
?>

This would work just fine. It is a very loose form of templates. The programmer is forced to keep track of the variables that are all floating around in the global scope. Another approach would be to make a collection of functions, like an API. Take this example:

<?php
/*
  Function to print out the <head> for each of my webpages.
  @param   $title   To go inside the <title>
*/
function printHead($title = 'My Site') {
?>

<head>
  <title><?php echo $title; ?></title>
  <link rel="stylesheet" type="text/css" src="general.css" />
  <script type="text/javascript" src="scripts.js" />
</head>

<?php
}
?>

Clearly a little more structured approach. You would have to include this file to make the function available, but everything from there is straightforward. Just call the function and pass the appropriate title as a parameter to the function:

<?php
include '/includes/commonFunctions.php';
printHead('My Site - Homepage');
?>

Templates are a fundamental part of good programming. Common uses are the header, footer, and menu’s for websites. Very little variation is needed across a website for these portions, so consolidating all of the code into a single file is immensely helpful. I just want to make sure that you learn about it soon and not like I did. The hard way.

Introduction to Server Side Includes – Apache’s very own HowTo. A good start.

Setup More SSI Setup Information – Some Troubleshooting and Methods to get SSI working on Apache

PHP Include Function – Documentation and Comments on the include function. Will be helpful to PHP developers.

I have read a number of tutorials and I find the best are the ones that include you, the reader, in them. You are participating in the tutorial. Often there is a story, or some creative aspect that brings you into the tutorial. You are learning in an entertaining way. For first timers this can make all the difference.

My tutorial also gives tips and tricks for using the terminal. They are the kind of tricks that make using the console much easier, but they are the tricks that you often don’t know unless someone shows you. I hope that my tutorial at least gives insight to newer Unix/Linux users as they take the leap into a new realm.

Please take a look and offer your feedback to help me improve the tutorial. I now present my Unix Tutorial.

I would like to point out that the tutorial happened to be a college project that I recently decided to turn into a reality. I have been and will be refurnishing the tutorial with improvements (sIFR), more rich content, while still maintaining my original goals and objectives.

Inspiration: A rather stimulating Ruby tutorial that wraps you inside a rather creative story, with “synergy and cartoon foxes.”

• Regular Expressions

• Templates and Includes

• XML Parsing

I will only touch light on these subjects in the hope that you will continue research on them if you have a desire to improve your skills. Once learning each of these, your understanding of web programming will be greatly improved, your code may become cleaner and more concise, and most importantly you will have more fun programming! Today’s article will focus on Regular Expressions, commonly refered to as regex.

Regular Expressions – Regex

This will not be an article teaching regular expressions (I may refer to them as ‘regex’). I would rather this be a stimulus for you to learn regular expressions if you are currently in the dark, and afterwards I may provide you with a few sources to help you learn regular expressions. You don’t need to really understand the regex that I show you in this article, nor will I really explain them to you. You may even be able to decipher what the regex means on your own. Keep in mind that I am showing you uses of regular expressions, their powerful and simplicity, as a means to entice you to learn them yourself. You will not regret it.

Regular expressions are a language in their own. At first glance, a regex may appear complex, but they are in fact very straightforward and they have many uses for web programmers. Regex provide pattern matching for strings. A common use is searching a string for something, if that something exists then execute some code. Or the reverse, if the pattern is not found then execute some code. One such example is input validation.

Lets say you have a simple contact form, which asks for a user’s phone number and email address. Those are common form elements and should be checked for valid input so you can be sure users are not putting deliberately fake input or perhaps a simple typo in their phone number. Regex can ensure that the users input is not only valid, but that it is also in the correct format that you specify, making your work easier.

Lets make a simple PHP example, with hardcoded values, and the phone number format we want is ###-###-####.

<?php
$str = '555-555-555a';
$regex = '/^d{3}-d{3}-d{4}$/';
if (preg_match($regex, $str))
  echo 'This is a valid phone number.';
else
  echo 'Bad phone number.';
?>

The regex is located between the forward slashes. / here /. I am also using a PHP function preg_match( regex, string the regex works on ). For those interested, here is the documentation on preg_match from php.net. Copy, Paste, Save, and Run this example and you should see that the result is that 555-555-555a is indeed a bad phone number! The reason, you probably determined, was that ‘a’ is not a number! The preg_match() function applies the regex on the string and finds that the string is not in the correct format (described above). Powerful, simple, and fast! To see the script in action with a working phone number change $str to any valid phone number, here is an example:

$str = ’123-456-7890′;

With one simple string we force all input to be exactly how we want it! To show how flexible regex can be, we can extend the regular expression to allow for a phone number in either: ###-###-### format, ######### format, or (###) ###-#### format! All at the same time like so: /^(\d{3}-\d{3}-\d{4})|\d{10}|(\(\d{3}\) \d{3}-\d{4})$/

Now lets take a look at an email address. An email address to be valid should look something like: example@domain.com. It may even be as complex as: alpha.123@crazy.com, but lets just have a regex to allow for a simple email address. Here goes:

<?php
$email = 'example@domain.net';
if (preg_match('/^[a-z0-9_-]+@([_a-z0-9-]+.)+(com|net)$/i', $email))
  echo 'Valid Email ending in .com or .net';
else
  echo 'Bad email address!';
?>

The regular expression allows for only a simple email address. It only allows email address ending in .com or .net, but that can easily be extended. I think you can see how powerful this is! Only allow valid formatted email address will prevent problems down the line if you ever have to email this person using a script. At least the email will be correctly formatted, at least your script won’t crash prematurely due to a formatting error, but instead the worst that could happen was the email is sent but no one ever receives it!

The simplicity of regex in form validation is unparalleled. How would you ensure that the user put in a valid phone number?!? Would you individually check each character in the string? Make sure that the first character is a number, the second, the third, then a dash, number, number, … A pain to do manually, regular expressions are just a single string which can do all of the work.

Soon I will provide another use of regular expression, search and replace! There are countless uses but I will cover topics you will surely have to deal with as web programmers, and by learning regular expressions you will see a new world of possibilities. It would be best if you started to learn the basics of regular expressions and so I will provide you with some links.

Overview – A Brief but Very Accurate Overview of Regular Expressions.

Regular-Expressions.info – Regex Tutorial, Examples and Reference – Regexp Patterns
This is the website I highly recommend that you start at.

Regular expression – Wikipedia, the free encyclopedia
Wikipedia is always a great resource for programming questions.

Regular Expressions Cheat Sheet – Cheat Sheets – ILoveJackDaniels.com
If ever you need a cheat sheet, be it PHP, Ruby on Rails, or CSS, get it here!