DailyJS

DailyJS

The JavaScript blog.


Tagdocumentation
Featured

books node documentation bootstrap

Bootstrap 3, Node Web Development, Groc

Posted on .

Bootstrap 3

Bootstrap 3's homepage.

Bootstrap 3 RC1 is out, and you'll see Bootstrap 3 on the front page of getbootstrap.com:

With over ~1,600 commits, ~72,000 additions/deletions, and ~300 files changed, everything has changed. We've added features, removed features, and cleaned up a lot more. The v3 pull request on GitHub has all the details you'll need for a complete list of changes and some helpful migration tips.

Before you get too excited you should know that it'll take some work to migrate to Bootstrap 3. There's no magic migration button as far as I know. Grids still scale up to 12 columns, but now use the class prefix .col-. Forms have different classes and tweaked markup, but the newer markup seems better to me. I don't think we need <div class="controls"> anymore, for example.

Node Web Development - Second Edition

Node Web Development - Second Edition has been released, written by David Herron .

He's written a post about it on his blog:

The final version of the sample application includes user authentication support, the ability to work with multiple database engines, be deployed on cloud services, and it dynamically sends data back and forth between server and browser to dynamically update the screen when other people edit things, and to support sending little messages between users of the application.

Groc

In Rock Your Doc With Groc, Our Favorite Automated Frontend Documentation Tool, a fork of Groc is discussed which adds support for tags:

We just couldn’t find a tool that gave us everything we needed. In the end, we created our own automated documentation tool by forking Docco and adding (hacking) support for Tags.

Groc, by Ian MacLeod, is a fork of docco by Jeremy Ashkenas. The post on Gilt's blog does a good job of explaining why they need tags and how they use them.

Featured

databases node modules mongo documentation async markdown

Node Roundup: MongloDB, parseq.js, node-netpbm

Posted on .

You can send in your Node projects for review through our contact form or @dailyjs.

MongloDB

MongloDB Logo

MongloDB (GitHub: onglo / MongloDB, License: MIT) by Christian Sullivan is a database written with JavaScript that's compatible with MongoDB's queries. It has a plugin system for persistence, and a datastore for Titanium Mobile -- this effectively allows a form of MongoDB to be used within iOS and Android applications.

Monglo has a DataStore API that can be used to persist data locally or remotely. It's based around an object that implements each CRUD operation:

var monglo = require('./index').Monglo  
  , db = monglo('DemoDB')
  ;

function DemoStore(){  
  return {
     insert: function() {}
   , update: function() {}
   , open: function() {}
   , remove: function() {}
   , all: function() {}
  };
}

db.use('store', new DemoStore());  

parseq.js

parseq.js (GitHub: sutoiku / parseq, License: MIT, npm: parseq) from Sutoiku, Inc. is a flow control library for organising parallel and sequential operations. To manage asynchronous operations, this can be passed. If several calls are made, then this() can be passed, and the next function will receive an array that contains the results in the order they were called.

The same author also recently released jsdox, which is another JSDoc to Markdown generator.

netpbm

netpbm (GitHub: punkave / node-netpbm, License: MIT, npm: netpbm) by Tom Boutell scales and converts images using the netpbm toolkit, which is a venerable set of graphics programs found on many Unix systems.

This library is a wrapper around the netpbm binaries, and takes advantage of the fact that most netpbm programs only read one row of pixels at a time into memory to keep memory usage low.

Featured

node modules documentation authentication debugging markdown

Node Roundup: Markdox, node-authenticate, node-codein

Posted on .

You can send in your Node projects for review through our contact form or @dailyjs.

Markdox

Markdox (License: MIT, npm: markdox) by Charles Bourasseau is a documentation generator based on Dox (which TJ changed to output JSON only) that produces Markdown. It can be used in the shell, or programatically.

This is a straightforward way of generating API documentation that works with services that support Markdown, like GitHub.

authenticate-pam

authenticate-pam (License: MIT, npm: authenticate-pam) by Damian Kaczmarek is an asynchronous PAM authentication addon. It uses libpam to authenticate users with a simple, idiomatic Node API:

var pam = require('authenticate-pam');  
pam.authenticate('myusername', 'mysecretpassword', function(err) {  
  if (err) {
    console.log(err);
  } else {
    console.log('Authenticated!');
  }
});

node-codein

node-codein (License: MIT, npm: node-codein) by "ketamynx" is a Windows-friendly Node interface based on WebKit Inspector. It can display objects graphically as trees, and can also execute code.

Although it looks like a debugger interface, it seems like the author intends for it to be used as a friendly alternative to the REPL.

Featured

databases node modules documentation couchdb

Node Roundup: 0.7.12, nd, futoncli

Posted on .

You can send in your Node projects for review through our contact form or @dailyjs.

Node 0.7.12: Prepare for 0.8!

Node 0.7.12 is here, and Isaac Schlueter said Node 0.8.0 will be released later this week:

Please try out this release. There will be very virtually no changes between this and the v0.8.x release family. This is the last chance to comment before it is locked down for stability. The API is effectively frozen now.

That means it's crunch time! Efforts have been made to preserve support for binary addons that use libeio and libev, but libev will be officially deprecated in 0.8 and gone in 0.9.

The 0.6 era feels like halcyon days -- a time when Node received a huge amount of attention from the mainstream technology press, and stronger than ever developer interest. I'd like to wish the core team the best of luck with the 0.8 release.

nd

Back in April, TJ Holowaychuk released mad(1), an alternative manual page system based on Markdown. Now Russ Frank has released nd (License: MIT, npm: nd), which is similar to mad but focused on displaying documentation for npm modules and is written in JavaScript.

Typing nd module will display the documentation associated with module. The project's readme contains lots of tips for finding documentation within modules and displaying it, and it also points out that it supports Windows -- it'll run fine in the standard cmd.exe command interpreter.

futoncli

Futon

If you're working with CouchDB, then futoncli (License: Apache 2.0, npm: futon) by Nuno Job may be useful. It's a command-line tool for managing CouchDB, and is based on the author's nano database driver.

Once installed, the futon binary will accept commands, and configuration can be persisted to the ~/.futoncliconf file. The author has made a video of futoncli to demonstrate the main features.

Featured

tutorials node documentation unix essay

Unix and Node: Command-line Arguments

Posted on .

Shebang Bootcamp

Writing an executable script with Node begins with the shebang: #!, followed by the path to a Node executable. Not all Unix systems use the same file system layout, and not all users want to install Node in the same place. Since the shebang must specify an absolute path, a common way around this is to introduce a level of indirection through env:

#!/usr/bin/env node

This can be seen in many popular Node modules, and in other scripting languages too. If I try and run a script like this in my shell, I'll get an error:

➜ ./echo.js
zsh: permission denied: ./echo.js  

I have read permission on the file, but it isn't executable:

➜ ls -l
-rw-r--r--  1 alex  wheel  21  1 Mar 17:24 echo.js
➜ chmod u+x ./echo.js 
➜ ls -l
total 8  
-rwxr--r--  1 alex  wheel  21  1 Mar 17:24 echo.js

Here I've used chmod to set the executable flag for the user that owns the file. Most people use the octal notation for setting permissions, which looks complicated but isn't as hard as it seems.

Argument Vector

Command-line arguments are available through the process global in an array called argv. This term comes from "argument vector", influenced by C where it's conventional to name the argument count and argument vector this way:

int main(int argc, char *argv[])  

Technically these parameters could be named anything, but this is a strongly followed convention.

Compared to C, JavaScript's array is a handy type for representing arguments:

#!/usr/bin/env node

console.log('Arguments:', process.argv.length);  
console.log(process.argv);  

Running this script with no arguments shows what the script was run with:

Arguments: 2  
[ 'node', '/private/tmp/unix-node/echo.js' ]

Conversely, passing in arguments looks like this:

➜ ./echo.js --text JavaScript in the shell
Arguments: 7  
[ 'node',
  '/private/tmp/unix-node/echo.js',
  '--text',
  'JavaScript',
  'in',
  'the',
  'shell' ]

Handling more complex arguments takes a little bit of work, so it's often preferable to offload the effort to a suitable module. However, some scripts have simple requirements, so array manipulation of process.argv may suffice. This example is from Node's cluster.js file:

exports.start = function() {  
  amMaster = true;

  if (process.argv.length < 1) {
    console.error('Usage: node cluster script.js');
    process.exit(1);
  }

  var args = process.argv.slice(2);
  var scriptFilename = args.shift();

The length of process.argv is validated to ensure the expected option has been supplied, and process.exit(1) is called if validation fails. This is interesting because an argument has been supplied to process.exit. Why 1?

Exit Status

Unix and Unix-like systems use a convention that a non-zero exit status from a program is an error. In C, EXIT_FAILURE is a macro that can be used to denote this, and on POSIX systems this value is 1. Changing the previous example to return a non-zero exit code looks like this:

#!/usr/bin/env node

console.log('Arguments:', process.argv.length);  
console.log(process.argv);

if (process.argv.length < 3) {  
  process.exit(1);
}

Running this script with no arguments should return 1. However, look what happens:

➜ ./echo.js 
Arguments: 2  
[ 'node', '/private/tmp/unix-node/echo.js' ]

... nothing? There's no error message or anything! This is actually a good thing -- think back to the philosophies behind Unix, in particular Doug McIlroy's quote:

Write programs to handle text streams, because that is a universal interface.

In a world based around text streams, we don't want default behaviour that's too noisy. If someone built upon this script, they'd rather deal with a concrete error status. This value can be obtained in most shells by reading $?:

➜ echo $?
1  

Option Parsing Libraries

The two most popular option parsing libraries for Node are Optimist (License: MIT/X11, npm: optimist) and Commander.js (GitHub: visionmedia / commander.js, License: MIT, npm: commander) by TJ Holowaychuk. These are both well-maintained libraries by active members of the Node community.

Optimist has its own argv object that can deal with grouped, long, and short options, and can even display usage:

#!/usr/bin/env node
var argv = require('optimist')  
    .usage('Usage: $0 -x [num] -y [num]')
    .demand(['x','y'])
    .argv;

console.log(argv.x / argv.y);  

Commander.js has a chainable API that's like a DSL for option processing:

#!/usr/bin/env node

var program = require('commander');

program  
  .version('0.0.1')
  .option('-p, --peppers', 'Add peppers')
  .option('-P, --pineapple', 'Add pineapple')
  .option('-b, --bbq', 'Add bbq sauce')
  .option('-c, --cheese [type]', 'Add the specified type of cheese [marble]', 'marble')
  .parse(process.argv);

console.log('you ordered a pizza with:');  
if (program.peppers) console.log('  - peppers');  
if (program.pineapple) console.log('  - pineappe');  
if (program.bbq) console.log('  - bbq');  
console.log('  - %s cheese', program.cheese);  

The program's usage is automatically generated.

Conclusion

In Node, powerful option parsing is only an npm install away. The built-in process.argv array is also convenient and easy to manage for simple situations. Just remember to exit programs with conventional status codes, or angry shell scripters may fill up your GitHub issues before you know it!