good coders code, great reuse

Announcing my third e-book "Perl One-Liners Explained"

2012-02-02T05:34:44Z

Hello ladies and gentlemen! I'm happy to announce my 3rd e-book called "Perl One-Liners Explained." This book is based on the "Famous Perl One-Liners Explained" article series that I wrote over the last 3 years and that has been read over 500,000 times!

I went through all the one-liners in the article series, improved explanations, fixed mistakes and typos, added a bunch of new one-liners, added an introduction to Perl one-liners and a new chapter on Perl's special variables.

The e-book has 111 pages and it explains 130 unique one-liners. Many of one-liners are presented in several different ways so the total number of one-liners in the book is over 200.

The e-book is divided into the following chapters:

Preface.
1. Introduction to Perl One-Liners.
2. Spacing.
3. Numbering.
4. Calculations
5. String Creation and Array Creation.
6. Text Conversion and Substitution.
7. Selective Printing and Deleting of Lines.
8. Handy Regular Expressions.
9. perl1line.txt
Appendix A. Perl's Special Variables.
Index.

What are Perl One-Liners?

Perl one-liners are small and awesome Perl programs that fit in a single line of code and they do one thing really well. These things include changing line spacing, numbering lines, doing calculations, converting and substituting text, deleting and printing certain lines, parsing logs, editing files in-place, doing statistics, carrying out system administration tasks, updating a bunch of files at once, and many more.

Let's take a look at several practical examples that you can easily do with one-liners. All these examples and many more are explained in the e-book.

I have also made the first chapter of the book, Introduction to Perl One-Liners, freely available. Please download the e-book preview to read it.

Example 1: Replace a string in multiple files at once

perl -p -i.bak -e 's/Config/config/g' conf1 conf2 conf3

Suppose you have 3 configuration files, and you discover that you made a mistake and need to replace all occurrences of Config with config. This one-liner does just that. It executes the s/Config/config/g that replaces all occurrences of Config with config on all lines. And since you're smart about it, you always do -i.bak to make backup files in case something goes wrong.

I explain the -i, -p, and -e arguments in the e-book in great detail.

Example 2: Generate a random 8 character password

perl -le 'print map { ("a".."z")[rand 26] } 1..8'

This one-liner generates and prints a random 8 character password. It uses the list range operator .. operator to produce all strings from "a" to "z", which is the alphabet. Then a random letter is chosen by rand 26 and this operation is repeated 8 times.

Example 3: URL-escape a string

perl -MURI::Escape -lne 'print uri_escape($string)'

Here we use the URI::Escape module from CPAN. It exports the uri_escape function that does URL-escaping.

You can install this module from CPAN by running perl -MCPAN -e'install URI::Escape' on the command line.

I have this one-liner as an alias actually for both URL-escaping and unescaping URL-escaping as it's such a common thing to do:

urlescape () { perl -MURI::Escape -lne 'print uri_escape($_)' <<< "$1" }
urlunescape () { perl -MURI::Escape -lne 'print uri_unescape($_)' <<< "$1"; }

Then I can do this in the shell:

$ urlescape "http://www.catonmat.net"
http%3A%2F%2Fwww.catonmat.net

$ urlunescape http%3A%2F%2Fwww.catonmat.net
http://www.catonmat.net

Very useful!

Example 4: Print all lines from line 17 to line 30

perl -ne 'print if 17..30'

Here we use the binary flip-flop operator .. that becomes true when the input line number is 17, stays true while the line number is less than or equal to 30, and then becomes false. Combining the flip-flop operator with print if makes it print only lines 17-30.

Example 5: Remove all consecutive blank lines, leaving just one

perl -00pe0

I included this one-liner here in the examples just to show you how funny and obscure one-liners can get. This one-liner deletes all repeated blank lines from the input or from the given file. It does it by enabling the paragraph slurp mode through -00 command line argument, which reads the input paragraph-by-paragraph, rather than line-by-line, and prints the paragraphs. This way any number of blank lines between the paragraphs get ignored.

I explain this one-liner in more details in the e-book.

As I hope you can see, knowing how to write one-liners is very useful. It was one of my top priority tasks through the years to become very efficient in the shell. Literally every day when I'm programming, I have to do all kinds of data processing tasks, changing files, verifying output, doing quick calculations, parsing data, etc, and knowing Perl one-liners makes it really fast to get things done.

Now that I have written this e-book, you can become very efficient, too. Enjoy!

Book Preview

I prepared a free book preview that contains the first 13 pages of the book. It includes the table of contents, preface, introduction to Perl one-liners and the first page of the second chapter.

Perl One-Liners Explained. Book Preview.

Buy it now!

The price of the e-book is $9.95 and it can be purchased via PayPal:

After you have made the payment, my automated e-book processing system will send you the PDF e-book in a few minutes!

Tweet about my book!

Help me spread the word about my new book! I prepared a special link that you can use to tweet about it:

What's next?

I really love writing about programming and I have planned writing many more books. The next few are going to be a book on mastering vim, a practical guide on how to be anonymous on the web, and the catonmat book.

Enjoy!

Enjoy the book and don't forget to leave comments about it! Ask me anything you wish and I'll help you out.

Also if you're interested, take a look at my other two e-books. The 1st one is called "Awk One-Liners Explained" and the 2nd one is called "Sed One-Liners Explained" They're written in a similar style as this e-book and they teach practical Awk and Sed through many examples.

Finally, if you enjoy my writing, you can subscribe to my blog, follow me on Twitter or Google+.

How Browserling Works [art]

2012-01-29T23:19:54Z

Art by James Halliday.

1. We run the browsers on our servers.
2. You use the browsers from the graphical web console.
3. If the servers are full, you wait in the queue.

Try Browserling!

Node.js modules you should know about: procstreams

2012-01-24T17:49:17Z

Hello everyone! This is the 15th post in the node.js modules you should know about article series.

The first post was about dnode - the freestyle rpc library for node, the second was about optimist - the lightweight options parser for node, the third was about lazy - lazy lists for node, the fourth was about request - the swiss army knife of HTTP streaming, the fifth was about hashish - hash combinators library, the sixth was about read - easy reading from stdin, the seventh was about ntwitter - twitter api for node, the eighth was about socket.io that makes websockets and realtime possible in all browsers, the ninth was about redis - the best redis client API library for node, the tenth was on express - an insanely small and fast web framework for node, the eleventh was semver - a node module that takes care of versioning, the twelfth was cradle - a high-level, caching, CouchDB client for node, the thirteenth was jsonstream - streaming JSON parsing library, the fourteenth was about everyauth - a module for authenticating your webapp with facebook, twitter, etc.

Today I'm gonna introduce you to procstreams by Marco Rogers aka polotek. Procstreams is a little experiment with shell scripting in node. Here is an example:

var $p = require('procstreams');

$p('cat lines.txt').pipe('wc -l')
  .data(function(stdout, stderr) {
      console.log(stdout); // prints number of lines in the file lines.txt
  });

This example executes the shell command cat lines.txt, then pipes the output to wc -l, and then collects the output through a callback that prints the number of lines in lines.txt

Here is another example:

var $p = require('procstreams');

$p('mkdir foo')
  .and('cp file.txt foo/')
  .and('rm file.txt')
    .on('exit', function() {
      console.log('done');
    });

This example executes mkdir foo, and if that succeeds, it executes cp file.txt foo/, and if that succeeds, it executes rm file.txt. In shells scripting you'd write this as:

mkdir foo && cp file.txt foo/ && rm file.txt

The .and(...) is the same as && in the shell scripting.

Procstreams also support .or(...), which is || in the shell and .then(...), which is ; in the shell.

Here is an example:

var $p = require('procstreams');

$p('mkdir foo')
  .then('cp file.txt file2.txt')
  .or('echo "failed" > ~/notify')

This example mkdirs foo, then copies file.txt to file2.txt, if that fails, it echos "failed" to ~/notify. Shell equivalent:

mkdir foo; cp file.txt file2.txt || echo "failed" > ~/notify

See procstreams documentation on GitHub for full info on other thingies it supports.

You can install procstreams through npm as always:

npm install procstreams

Procstreams on GitHub: https://github.com/polotek/procstreams.

Sponsor this blog series!

Doing a node.js company and want your ad to appear in the series? The ad will go out to 14,000 rss subscribers, 7,000 email subscribers, and it will get viewed by thousands of my blog visitors! Email me and we'll set it up!

Enjoy!

If you love these articles, subscribe to my blog for more, follow me on Twitter to find about my adventures, and watch me produce code on GitHub!

Browserling has a new design!

2012-01-16T18:51:51Z

Awesome news everyone! We launched new design for Browserling! We also switched to Stripe for accepting payments and also added a bunch more browsers!

The new design is much cleaner, and everything is driven through ajax calls, we don't even use HTML templates anymore!

Here is a screenshot of Browserling with the new design:

Browserling is interactive cross-browser testing tool that allows you to see what your webpage looks like in Internet Explorer, Firefox, Chrome, Opera, and Safari.

Node.js modules you should know about: everyauth

2012-01-03T18:34:38Z

Hello everyone! This is the 14th post in the node.js modules you should know about article series.

Today I'm gonna introduce you to everyauth by Brian Noguchi. Everyauth is a connect middleware that allows you to setup authentication for your app via facebook, twitter, google, vimeo, tumblr, 4square, etc.

Here is a list of all the sites you can use to login into your app:

Everyauth supports a plenty of sites.

Everyauth supports OpenID, Google, Twitter, LinkedIn, Yahoo, Readability, Dropbox, Justin.tv, Vimeo, Tumblr, Facebook, Github, Instagram, Foursquare, Gowalla, 37signals, AngelList, Dwolla, Box.net.

Using it is as simple as setting up a middleware for connect:

var everyauth = require('everyauth');
var connect = require('connect');

var app = connect(everyauth.middleware());

And setting up config.json that contains secret keys from the sites you are going to be using for authentication:

module.exports = {
    fb: {
        appId: '111565172259433'
      , appSecret: '85f7e0a0cc804886180b887c1f04a3c1'
    },
    twit: {
        consumerKey: 'JLCGyLzuOK1BjnKPKGyQ'
      , consumerSecret: 'GNqKfPqtzOcsCtFbGTMqinoATHvBcy1nzCTimeA9M0'
    },
    github: {
        appId: '11932f2b6d05d2a5fa18'
      , appSecret: '2603d1bc663b74d6732500c1e9ad05b0f4013593'
    },
    // ...
};

Then you setup routes for logging in for each particular site you want to support (in this example facebook) and you're done:

var conf = require('./config.json');

var usersByFbId = {};

everyauth
  .facebook
    .appId(conf.fb.appId)
    .appSecret(conf.fb.appSecret)
    .findOrCreateUser(function (session, accessToken, accessTokenExtra, fbUserMetadata) {
      return usersByFbId[fbUserMetadata.id] ||
        (usersByFbId[fbUserMetadata.id] = addUser('facebook', fbUserMetadata));
    })
    .redirectPath('/');

You can install everyauth through npm as always:

npm install everyauth

EveryAuth on GitHub: https://github.com/bnoguchi/everyauth.

Sponsor this blog series!

Enjoy!

If you love these articles, subscribe to my blog for more, follow me on Twitter to find about my adventures, and watch me produce code on GitHub!

How to setup Stripe payments with node.js

2011-12-31T12:17:18Z

This is going to be a super quick tutorial on how to accept payments with Stripe payment processor and node.js. At Browserling we're moving to Stripe right this very moment so I thought I'd write this quick post. Stripe is the most incredible payment processor - it took me like 30 minutes to figure everything out. Everything is well documented and works like a charm!

First, you will need the node-stripe module. Install it through npm, as always:

npm install stripe

Next, you'll need to login into Stripe, and setup a plan:

Setting up a new Stripe plan.

Next, you'll need to find the test and live keys that are used in the payment code. They are located in Account Settings -> API Keys.

Stripe keys are located in Account Settings -> API keys.

Next, you'll need to include Stripe's JavaScript library in your HTML code:

<script type="text/javascript" src="https://js.stripe.com/v1/"></script>

Next, you'll need to setup an HTML form with card name, cvc, expiration date, amount (in cents!). You don't need to ask the name or address, that stuff is old school:

<div id="stripe-form">
  <form action="/plans/browserling_developer" method="POST" id="payment-form">
    <div class="form-row">
      <div class="cc-text">Card Number</div>
      <input type="text" size="30" autocomplete="off" class="card-number"/>
    </div>
    <div class="form-row">
      <div class="cc-text">CVC</div>
      <input type="text" size="4" autocomplete="off" class="card-cvc"/>
    </div>
    <div class="form-row">
      <div class="cc-text">Expiration (MM/YYYY)</div>
      <input type="text" size="2" class="card-expiry-month"/>
      <span> / </span>
      <input type="text" size="4" class="card-expiry-year"/>
    </div>
    <input type="hidden" name="amount" value="2000" id="cc-amount">
    <button type="submit" class="submit-button">Submit Payment</button>
  </form>
</div>
<div id="error" class="hidden"></div>
<div id="success" class="hidden">Thanks for signing up at Browserling!</div>

Next, you'll need to generate a token when the form gets submitted, and submit it to your node.js application, instead of submitting credit card number and other info:

var publicStripeApiKey = '...';
var publicStripeApiKeyTesting = '...';

Stripe.setPublishableKey(publicStripeApiKey);

function stripeResponseHandler (status, response) {
  if (response.error) {
    $('#error').text(response.error.message);
    $('#error').slideDown(300);
    $('#stripe-form .submit-button').removeAttr("disabled");
    return;
  }
  
  var form = $("#payment-form");
  form.append("<input type='hidden' name='stripeToken' value='" + response.id + "'/>");

  $.post(
    form.attr('action'),
    form.serialize(),
    function (status) {
      if (status != 'ok') {
        $('#error').text(status);
        $('#error').slideDown(300);
      }
      else {
        $('#error').hide();
        $('#success').slideDown(300);
      }
      $('.submit-button').removeAttr("disabled");
    }
  );
}

// http://stripe.com/docs/tutorials/forms
$("#payment-form").submit(function(event) {
  $('#error').hide();
  // disable the submit button to prevent repeated clicks
  $('.submit-button').attr("disabled", "disabled");

  var amount = $('#cc-amount').val(); // amount you want to charge in cents
  Stripe.createToken({
    number: $('.card-number').val(),
    cvc: $('.card-cvc').val(),
    exp_month: $('.card-expiry-month').val(),
    exp_year: $('.card-expiry-year').val()
  }, amount, stripeResponseHandler);

  // prevent the form from submitting with the default action
  return false;
});

Next, you need to setup a route handler in node.js web server for all your plan names. In this tutorial I'll handle just browserling_developer plan:

var express = require('express');

var stripeApiKey = "...";
var stripeApiKeyTesting = "..."
var stripe = require('stripe')(stripeApiKey);

app = express.createServer(express.bodyDecoder);

app.post("/plans/browserling_developer", function(req, res) {
  stripe.customers.create({
    card : req.body.stripeToken,
    email : "...", // customer's email (get it from db or session)
    plan : "browserling_developer"
  }, function (err, customer) {
    if (err) {
      var msg = customer.error.message || "unknown";
      res.send("Error while processing your payment: " + msg;
    }
    else {
      var id = customer.id;
      console.log('Success! Customer with Stripe ID ' + id + ' just signed up!');
      // save this customer to your database here!
      res.send('ok');
    }
  });
});

That's it! This simple node.js code handles POST requests to /plans/browserling_developer, and creates a new customer at Stripe. Notice that it uses req.body.stripeToken and doesn't even touch credit card info.

I have never worked with a payment processor which was easier to setup. It's a pure pleasure to use Stripe!

A Perl Regular Expression That Matches Prime Numbers

2011-12-26T16:23:24Z

perl -lne '(1x$_) =~ /^1?$|^(11+?)\1+$/ || print "$_ is prime"'

Can you figure out how it works? I give an explanation below, but try to figure it out yourself. Here is what happens when you run it:

$ perl -lne '(1x$_) =~ /^1?$|^(11+?)\1+$/ || print "$_ is prime"'
1
2
2 is prime
3
3 is prime
4
5
5 is prime
6
7
7 is prime
8
9
10
11
11 is prime

Here is how it works.

First, the number is converted in its unary representation by (1x$_). For example, the number 5 gets converted into 1x5, which is 11111 (1 repeated 5 times.)

Next, the unary string gets tested against the regular expression. If it matches, the number is a composite, otherwise it's a prime.

The regular expression works this way. It consists of two parts ^1?$ and ^(11+?)\1+$.

The first part matches number 1 and the empty string. Clearly, the empty string and number 1 are not prime numbers, therefore this regular expression matches, which indicates that they are not prime numbers.

The second part determines if two or more 1s repeatedly make up the whole number. If two or more 1s repeatedly make up the whole number, the regex matches, which means that the number is composite. Otherwise it's a prime.

Let's look at the second regex part on numbers 5 and 4.

The number 5 in unary representation is 11111. The (11+?) matches the first two ones 11. The back-reference \1 becomes 11 and the whole regex now becomes ^11(11)+$. It can't match five ones, therefore it fails. But since it used +?, it backtracks and matches the first three ones 111. The back-reference becomes 111 and the whole regex becomes ^111(111)+$. It doesn't match again. This repeats for 1111 and 11111, which also don't match, therefore the whole regex doesn't match and the number is a prime.

The number 4 in unary representation is 1111. The (11+?) matches the first two ones 11. The back-reference \1 becomes 11 and the regex becomes ^11(11)+$. It matches the original string, therefore the number is not a prime.

PS. I didn't invent this regular expression, it was invented in 1998 by Abigail.

Don't take this regular expression too seriously, it's actually neither a regular expression (as defined in automata theory), nor a way to check if a number is a prime. It's just an awesome thing that Perl can do. See this cool article called The Prime That Wasn't by Andrei Zmievski for a discussion about how this regex fails for larger numbers because of backtracking.

Also if you wish to learn more about Perl one-liners, check out my Perl One-Liners Explained article series and download the perl1line.txt file.

Node.js modules you should know about: jsonstream

2012-01-03T18:42:47Z

Hello everyone! This is the thirteenth post in the node.js modules you should know about article series.

This time I'll introduce you to a very awesome module called JSONStream. JSONStream is written by Dominic Tarr and it parses streaming JSON.

Here is an example. Suppose you have couchdb view like this:

{"total_rows":129,"offset":0,"rows":[
  { "id":"change1_0.6995461115147918"
  , "key":"change1_0.6995461115147918"
  , "value":{"rev":"1-e240bae28c7bb3667f02760f6398d508"}
  , "doc":{
      "_id":  "change1_0.6995461115147918"
    , "_rev": "1-e240bae28c7bb3667f02760f6398d508","hello":1}
  },
  { "id":"change2_0.6995461115147918"
  , "key":"change2_0.6995461115147918"
  , "value":{"rev":"1-13677d36b98c0c075145bb8975105153"}
  , "doc":{
      "_id":"change2_0.6995461115147918"
    , "_rev":"1-13677d36b98c0c075145bb8975105153"
    , "hello":2
    }
  },
  ...
]}

And you wish to only filter out doc values from the rows. You can do it easily with JSONStream this way:

var parser = JSONStream.parse(['rows', /./, 'doc']);

This creates a stream that parses out rows.*.doc.

Since it's a stream you have to feed it data and then have it output the data somewhere. You can do it very nicely and idiomatically in node this way:

req.pipe(parser).pipe(process.stdout);

Here is the output:

{
  _id: 'change1_0.6995461115147918',
  _rev: '1-e240bae28c7bb3667f02760f6398d508',
  hello: 1
}
{
  _id: 'change2_0.6995461115147918',
  _rev: '1-13677d36b98c0c075145bb8975105153',
  hello: 2
}

Where req is request to couchdb view and parser is the JSONStream parser, and it all gets piped to process.stdout. The output, as you can see, is only the rows.*.doc. That was a really easy way to parse a JSON stream without reading the whole JSON into memory.

You can install JSONStream through npm as always:

npm install JSONStream

JSONStream on GitHub: https://github.com/dominictarr/JSONStream.

Sponsor this blog series!

Enjoy!

If you love these articles, subscribe to my blog for more, follow me on Twitter to find about my adventures, and watch me produce code on GitHub!

Node.js modules you should know about: cradle

2012-01-03T18:44:50Z

Hello everyone! This is the twelfth post in the node.js modules you should know about article series.

Today I'll introduce you to cradle - a high-level, caching, CouchDB client for Node.js. Cradle is written by Alexis Sellier (cloudhead).

Cradle is somewhat higher-level than most other CouchDB clients, requiring a little less knowledge of CouchDB's REST API. Cradle also has built-in write-through caching, giving you an extra level of speed, and making document updates and deletion easier. Cradle was built from the love of CouchDB and Node.js, and tries to make the most out of this wonderful marriage of technologies.

Here is an example of how simple it's to use cradle:

var cradle = require('cradle');
var db = new(cradle.Connection)().database('starwars');

db.get('vader', function (err, doc) {
    doc.name; // 'Darth Vader'
    assert.equal(doc.force, 'dark');
});

db.save('skywalker', {
    force: 'light',
    name: 'Luke Skywalker'
}, function (err, res) {
    if (err) {
        // Handle error
    } else {
        // Handle success
    }
});

Cradle supports all the operations that you'd expect an API for CouchDB to support like creating a database:

var db = c.database('starwars');
db.create();

Checking if a db exists:

db.exists(function (err, exists) {
  if (err) {
    console.log('error', err);
  } else if (exists) {
    console.log('the force is with you.');
  } else {
    console.log('database does not exists.');
    db.create();
    /* populate design documents */
  }
});

Destroying a db:

db.destroy(cb);

Fetching a document:

db.get('vader', function (err, doc) {
    console.log(doc);
});

Querying a view:

db.view('characters/all', function (err, res) {
    res.forEach(function (row) {
        console.log(row.name + " is on the " +
            row.force + " side of the force.");
    });
});

Creating and updating documents:

db.save('vader', {
    name: 'darth', force: 'dark'
}, function (err, res) {
    // Handle response
});

Creating views:

db.save('_design/characters', {
    all: {
        map: function (doc) {
            if (doc.name) emit(doc.name, doc);
        }
    },
    darkside: {
        map: function (doc) {
            if (doc.name && doc.force == 'dark') {
                emit(null, doc);
            }
        }
    }
});

Deleting documents:

db.remove('luke', '1-94B6F82', function (err, res) {
    // Handle response
});

And it also supports streaming, changes api, and many other things. See the cradle documentation to learn more.

You can install cradle through npm as always:

npm install cradle

Cradle on GitHub: https://github.com/cloudhead/cradle.

Sponsor this blog series!

Enjoy!

If you love these articles, subscribe to my blog for more, follow me on Twitter to find about my adventures, and watch me produce code on GitHub!

Node.js modules you should know about: semver

2012-01-03T18:44:41Z

Hello everyone! This is the eleventh post in the node.js modules you should know about article series.

Today I'll introduce you to a module called semver. Semver is the semantic versioner. Semver is written by Isaac Z. Schlueter, the author of npm. Semver is used in npm to handle all the node.js module versioning problems.

Here is an example of what it does:

semver.valid('1.2.3') // true
semver.valid('a.b.c') // false
semver.clean('  =v1.2.3   ') // '1.2.3'
semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
semver.gt('1.2.3', '9.8.7')  // false
semver.lt('1.2.3', '9.8.7')  // true

The ordering of versions is done using the following algorithm - given two versions and asked to find the greater of the two:

If the majors are numerically different, then take the one with a bigger major number. For example, 2.3.4 > 1.3.4.
If the minors are numerically different, then take the one with the bigger minor number. For example, 2.3.4 > 2.2.4.
If the patches are numerically different, then take the one with the bigger patch number. For example, 2.3.4 > 2.3.3.
If only one of them has a build number, then take the one with the build number. For example, 2.3.4-0 > 2.3.4.
If they both have build numbers, and the build numbers are numerically different, then take the one with the bigger build number. For example, 2.3.4-10 > 2.3.4-9.
If only one of them has a tag, then take the one without the tag. For example, 2.3.4 > 2.3.4-beta.
If they both have tags, then take the one with the lexicographically larger tag. For example, 2.3.4-beta > 2.3.4-alpha.
At this point, they're equal.

Semver supports the following ranges and styles:

>1.2.3 means greater than a specific version.
<1.2.3 means less than a specific version.
1.2.3 - 2.3.4 means >=1.2.3 <=2.3.4.
~1.2.3 means >=1.2.3 <1.3.0.
~1.2 means >=1.2.0 <2.0.0.
~1 means >=1.0.0 <2.0.0.
1.2.x means >=1.2.0 <1.3.0.
1.x means >=1.0.0 <2.0.0.

Ranges can be joined with either a space (which implies "and") or a || (which implies "or").

Semver supports the following functions:

valid(v) - return the parsed version, or null if it's not valid.
inc(v, release) - return the version incremented by the release type (major, minor, patch, or build), or null if it's not valid.

Semver supports the following comparisons:

gt(v1, v2) - v1 > v2.
gte(v1, v2) - v1 >= v2.
lt(v1, v2) - v1 < v2.
lte(v1, v2) - v1 <= v2.
eq(v1, v2) - v1 == v2.
neq(v1, v2) - v1 != v2.
cmp(v1, comparator, v2) - pass in a comparison string, and it'll call the corresponding function above. "===" and "!==" do simple string comparison, but are included for completeness. Throws if an invalid comparison string is provided.
compare(v1, v2) - return 0 if v1 == v2, or 1 if v1 is greater, or -1 if v2 is greater. Sorts in ascending order if passed to Array.sort().
rcompare(v1, v2) - the reverse of compare. Sorts an array of versions in descending order when passed to Array.sort().

Semver supports the following range functions:

validRange(range) - Return the valid range or null if it's not valid.
satisfies(version, range) - return true if the version satisfies the range.
maxSatisfying(versions, range) - return the highest version in the list that satisfies the range, or null if none of them do.

You can install semver through npm as always:

npm install semver

Semver on GitHub: https://github.com/isaacs/node-semver.

Sponsor this blog series!

Enjoy!

If you love these articles, subscribe to my blog for more, follow me on Twitter to find about my adventures, and watch me produce code on GitHub!

Node.js modules you should know about: express

2012-01-03T18:44:32Z

Hello everyone! This is the tenth post in my new node.js modules you should know about article series.

Today I'm going to introduce you to express - an insanely fast and small server-side web development framework built on connect. Express is written by TJ Holowaychuk. TJ has written 85 node.js modules so far so expect many more of his modules in this series!

Check this out:

var express = require('express');

var app = express.createServer();

app.get('/', function(req, res){
    res.send('Hello World');
});

app.listen(3000);

This creates a web server that listens on port 3000 and handles the requests to /, returning Hello World string as a response.

Express has really powerful routing system. See this:

app.get('/user/:id', function(req, res){
    res.send('user ' + req.params.id);
});

This handles requests to /user/foo and automatically sets req.params.id to foo. You can also use regular expressions to handle routes.

If you want to handle POST requests, you have to make your app use bodyParser middleware. That can be done through app.use(express.bodyParser()). BodyParser basically parses the application/x-www-form-urlencoded and application/json request bodies and sets up req.body for you. For example:

app.use(express.bodyParser());

app.get('/', function(req, res){
    console.log(req.body.foo);
    res.send('ok');
});

This echos the body variables to console and sends back ok.

There are a bunch of different middlewares that you can use with express, such as:

app.use(express.logger(...));
app.use(express.cookieParser(...));
app.use(express.session(...));
app.use(express.static(...));
app.use(express.errorHandler(...));

The logger middleware handles logging of HTTP requests, cookieParser handles cookies, session handles HTTP sessions, static for static content, such as images, css and scripts, and errorHandler for handling exceptions and errors.

See the express documentation to learn more about middlewares.

Express also integrates with various templating engines. For example, my favorite templating language is jade (also written by TJ) and here is how you'd render a jade template with express:

app.get('/', function(req, res){
    res.render('index.jade', { title: 'My Site' });
});

Template filenames take the form <name>.<engine>, where <engine> is the name of the module that will be required. For example the template layout.ejs will tell express's view system to require('ejs'). The module being loaded must export the method exports.compile(str, options), and return a Function to comply with express.

Express features:

Robust routing.
Redirection helpers.
Dynamic view helpers.
Content negotiation.
Focus on high performance.
View rendering and partials support.
Environment based configuration.
Session based flash notifications.
High test coverage.
Executable for generating applications quickly.
Application level view options.

As well as:

Session support.
Cache API.
Mime helpers.
ETag support.
Persistent flash notifications.
Cookie support.
JSON-RPC.
Logging.

Also see this screencast on express by TJ:

For more examples see the examples directory in express source tree. Express also has awesome documentation.

You can install express through npm as always:

npm install express

Express on GitHub: https://github.com/visionmedia/express.

Sponsor this blog series!

Enjoy!

If you love these articles, subscribe to my blog for more, follow me on Twitter to find about my adventures, and watch me produce code on GitHub!

Node.js modules you should know about: redis

2012-01-03T18:44:23Z

Hello everyone! This is the ninth post in my new node.js modules you should know about article series.

Today I'm going to introduce you to node_redis - the best node.js Redis client API library. Redis node.js module is written by Matt Ranney.

This library is a complete Redis client for node.js. It supports all Redis commands, including many recently added commands like EVAL from experimental Redis server branches.

Here is an example of using redis library:

var redis = require("redis");
var client = redis.createClient();

client.on("error", function (err) {
    console.log("Error " + err);
});

client.set("string key", "string val", redis.print);
client.hset("hash key", "hashtest 1", "some value", redis.print);
client.hset(["hash key", "hashtest 2", "some other value"], redis.print);
client.hkeys("hash key", function (err, replies) {
    console.log(replies.length + " replies:");
    replies.forEach(function (reply, i) {
        console.log("    " + i + ": " + reply);
    });
    client.quit();
});

Here is the output when you run this example:

mjr:~/work/node_redis (master)$ node example.js
Reply: OK
Reply: 0
Reply: 0
2 replies:
    0: hashtest 1
    1: hashtest 2
mjr:~/work/node_redis (master)$

Each Redis command is exposed as a function on the client object. All functions take either an args Array plus optional callback Function or a variable number of individual arguments followed by an optional callback.

Here is an example of passing an array of arguments and a callback:

client.mset(["key 1", "val 1"], function (err, res) {});

Here is that same call in the second style:

client.mset("key 1", "val 1", function (err, res) {});

Note that in either form the callback is optional:

client.set("some key", "some val");
client.set(["some other key", "some val"]);

For a list of Redis commands, see Redis Command Reference.

The commands can be specified in uppercase or lowercase for convenience - client.get() is the same as client.GET().

You can install redis through npm as always:

npm install redis

Redis on GitHub: https://github.com/mranney/node_redis.

Pieter Noordhuis has written a binding to the official hiredis C library, which is non-blocking and fast. It's called hiredis-node. To use hiredis, do:

npm install hiredis redis

If hiredis is installed, node_redis will use it by default. Otherwise, a pure JavaScript parser will be used.

Sponsor this blog series!

Enjoy!

If you love these articles, subscribe to my blog for more, follow me on Twitter to find about my adventures, and watch me produce code on GitHub!

Node.js modules you should know about: socket.io

2012-01-03T18:44:16Z

Hello everyone! This is the eighth post in my new node.js modules you should know about article series.

This time I'll introduce you to socket.io. I bet that most all of you already know socket.io, however I had several people message me to do an article on socket.io, so here it is.

Socket.io makes websockets and realtime possible in all browsers. It also enhances websockets by providing built-in multiplexing, horizontal scalability, and automatic JSON encoding/decoding. Socket.io is written by Guillermo Rauch, who's the co-founder of LearnBoost.

Socket.io always chooses the best realtime communication method possible. Here is the list of all the communication methods it supports:

WebSocket
Adobe® Flash® Socket
AJAX long polling
AJAX multipart streaming
Forever Iframe
JSONP Polling

For example, if you're using Chrome, then socket.io will use websockets. If your browser doesn't support websockets, it will try to use flash sockets, then it will try long polling, etc.

Now let's look at a very basic socket.io example:

var io = require('socket.io');
var express = require('express');

var app = express.createServer()
var io = io.listen(app);

app.listen(80);

io.sockets.on('connection', function (socket) {
  socket.emit('news', { hello: 'world' });
  socket.on('my other event', function (data) {
    console.log(data);
  });
  socket.on('disconnect', function () {
    console.log('user disconnected');
  });
});

This example uses the awesome express node web framework (I'll blog about it soon) to setup a web server on port 80, and attaches socket.io to it.

Socket.io then listens for new connections and when a new connection from the browser is created, it emits news event that sends the { hello: 'world' } hash back to the browser.

It also setups a listener for my other event and it listens for disconnects. When the web application emits this event, socket.io calls the function (data) { console.log(data); } callback, that just prints the data to console. When the client disconnects, it logs this event to console also.

Here is the client side (in the web browser):

<script src="/socket.io/socket.io.js"></script>
<script>
  var socket = io.connect('http://localhost');
  socket.on('news', function (data) {
    console.log(data);
    socket.emit('my other event', { my: 'data' });
  });
</script>

First we include the socket.io.js script, and then we create a socket.io connection to http://localhost. Here socket.io chooses the best communication method that the browser supports. If it's Chrome then it will be websockets, then if you have flash, then it will try flash sockets, then long polling, then multipart streaming, then forever iframe method, and finally jsonp polling. Then we listen on news event and when we receive it, we emit my other event.

This way you can build all kinds of awesome realtime applications, such as web chat servers and web irc clients.

There are many other features that socket.io supports, such as namespaces, volatile messages, message confirmations and message broadcasting. See the documentation to learn all about this awesomeness!

You can install socket.io through npm as always:

npm install socket.io

Socket.io on GitHub: https://github.com/LearnBoost/socket.io.

Also take a look at dnode that allows to call functions over socket.io!

Sponsor this blog series!

Enjoy!

If you love these articles, subscribe to my blog for more, follow me on Twitter to find about my adventures, and watch me produce code on GitHub!

Node.js modules you should know about: ntwitter

2012-01-03T18:44:08Z

Hello everyone! This is the seventh post in my new node.js modules you should know about article series.

This time I'll introduce you to ntwitter - asynchronous Twitter REST, streaming and searching client API. This module is maintained by Charlie McConnell, aka AvianFlu. Ntwitter was actually created by technoweenie, but since then maintainers have changed several times.

To use it, you'll need to get the API keys. That can easily be done at dev.twitter.com. Just register a new App, and you'll get the keys.

Here is an example ntwitter app that tweets:

var twitter = require('ntwitter');

var twit = new twitter({
  consumer_key: 'Twitter',
  consumer_secret: 'API',
  access_token_key: 'keys',
  access_token_secret: 'go here'
});

twit
  .verifyCredentials(function (err, data) {
    if (err) {
      console.log("Error verifying credentials: " + err);
      process.exit(1);
    }
  })
  .updateStatus('Test tweet from ntwitter/' + twitter.VERSION,
    function (err, data) {
      if (err) console.log('Tweeting failed: ' + err);
      else console.log('Success!')
    }
  );

Here is how to search through ntwitter API:

var twitter = require('ntwitter');

var twit = new twitter({
  consumer_key: 'Twitter',
  consumer_secret: 'API',
  access_token_key: 'keys',
  access_token_secret: 'go here'
});

twit.search('nodejs OR #node', function(err, data) {
  if (err) {
    console.log('Twitter search failed!');
  }
  else {
    console.log('Search results:');
    console.dir(data);
  }
});

You can also use Twitter's streaming API:

var twitter = require('ntwitter');

var twit = new twitter({
  consumer_key: 'Twitter',
  consumer_secret: 'API',
  access_token_key: 'keys',
  access_token_secret: 'go here'
});

twit.stream('statuses/sample', function(stream) {
  stream.on('data', function (data) {
    console.log(data);
  });
});

Here is a list of all the possible statuses/* that you can stream from.

Note how you don't need to login into twitter to do searching and streaming.

You can stream someone's tweets this way:

var twitter = require('ntwitter');

var twit = new twitter({
  consumer_key: 'Twitter',
  consumer_secret: 'API',
  access_token_key: 'keys',
  access_token_secret: 'go here'
});

twit.stream('user', {track:'nodejs'}, function(stream) {
  stream.on('data', function (data) {
    console.dir(data);
  });
  stream.on('end', function (response) {
    // Handle a disconnection
  });
  stream.on('destroy', function (response) {
    // Handle a 'silent' disconnection from Twitter, no end/error event fired
  });
});

Finally, you can stream tweets from certain locations, defined by bounding boxes:

var twitter = require('ntwitter');

var twit = new twitter({
  consumer_key: 'Twitter',
  consumer_secret: 'API',
  access_token_key: 'keys',
  access_token_secret: 'go here'
});

twit.stream('statuses/filter', {'locations':'-122.75,36.8,-121.75,37.8,-74,40,-73,41'},
function(stream) {
  stream.on('data', function (data) {
    console.log(data);
  });
});

You can use Cole Gillespie's node-finden module to get the geographical coordinates for bounding boxes. Here is how Cole's software looks:

That's it. Super easy way to do all things twitter with ntwitter.

You can install ntwitter through npm as always:

npm install ntwitter

Ntwitter on GitHub: https://github.com/AvianFlu/ntwitter.

Sponsor this blog series!

Enjoy!

If you love these articles, subscribe to my blog for more, follow me on Twitter to find about my adventures, and watch me produce code on GitHub!

Node.js modules you should know about: read

2012-01-03T18:43:49Z

Hello everyone! This is the sixth post in my new node.js modules you should know about article series.

This time I'll introduce you to a brand new module called read. Read was created just yesterday by Isaac Z. Schlueter, the author of npm. Read is basically read(1) for node. You can read input from stdin with it easily.

Here is an example,

var read = require('read');

read({ prompt : 'Username: ' }, function (err, user) {
  read({ prompt : 'Password: ', silent : true }, function (err, pass) {
    console.log(user, pass);
    process.stdin.destroy();
  });
})

Nesting functions like this is ugly, so you better use seq, the asynchronous flow combinators library, by James Halliday. (I'll introduce you to this module some time soon.) Here is how it looks with seq:

var read = require('read');
var Seq = require('seq');

Seq()
  .seq(function () {
    read({ prompt : 'Username: ' }, this.into('user'));
  })
  .seq(function () {
    read({ prompt : 'Password: ', silent : true }, this.into('pass'));
  })
  .seq(function (pass) {
    console.log(this.vars.user, this.vars.pass);
  });

Here are all the options read supports:

prompt  - What to write to stdout before reading input.
silent  - Don't echo the output as the user types it.
num     - Max number of chars to read from terminal.
delim   - The char that means we're done. Default: "\n"
timeout - Number of ms to wait for user input before giving up.

Note: If silent is true, or num is set, or delim is something other than "\n", then read will set raw mode, and read character by character.

You can install read through npm as always:

npm install read

Sponsor this blog series!

Enjoy!

If you love these articles, subscribe to my blog for more, follow me on Twitter to find about my adventures, and watch me produce code on GitHub!

good coders code, great reuse

Announcing my third e-book "Perl One-Liners Explained"

Table of Contents

What are Perl One-Liners?

Book Preview

Buy it now!

Tweet about my book!

What's next?

Enjoy!

How Browserling Works [art]

Node.js modules you should know about: procstreams

Sponsor this blog series!

Enjoy!

Browserling has a new design!

Node.js modules you should know about: everyauth

Sponsor this blog series!

Enjoy!

How to setup Stripe payments with node.js

A Perl Regular Expression That Matches Prime Numbers

Node.js modules you should know about: jsonstream

Sponsor this blog series!

Enjoy!

Node.js modules you should know about: cradle

Sponsor this blog series!

Enjoy!

Node.js modules you should know about: semver

Sponsor this blog series!

Enjoy!

Node.js modules you should know about: express

Sponsor this blog series!

Enjoy!

Node.js modules you should know about: redis

Sponsor this blog series!

Enjoy!

Node.js modules you should know about: socket.io

Sponsor this blog series!

Enjoy!

Node.js modules you should know about: ntwitter

Sponsor this blog series!

Enjoy!

Node.js modules you should know about: read

Sponsor this blog series!

Enjoy!