• lets you break your scripts out into discreet chunks for functionality
• improves performance by minimizing the number of HTTP requests

Example, assuming this hypothetical directory structure:

- canvas
--- tools.js
- color.js
- lang
--- enumerable.js
- main.js

The content of main.js:

// Declare your dependencies and assign them to variables.
var color = require('color');
var ctools = require('canvas/tools');
var enumerable = require('lang/enumerable');

// Use your imported scripts!
var rgb = color.hex2rgb("#C00");
var myCanvas = ctools.attach("some-canvas-id");

enumerable.each(["stuff", "things", "other"], function(item, i) {
  // ...
});

As you can see, at the top of the file you simply require the scripts you’d like to use before using them. That’s it, done! Modulr takes care of fetching them and writing them into the file.

Modulr avoids global-scope pollution

Note that each require invocation assigns the result to a variable. The scripts which get concatenated via require are trapped within a closure, ensuring that your scripts do not pollute the global scope.

Modulr makes your code more portable

Another great thing about Modulr is that if follows the CommonJS API, allowing you to declare your script dependencies in plain old JavaScript. No config files or embedded tokens, just JavaScript. This has the added benefit of making your scripts more portable — as long as your environment supports the CommonJS API (node, narwhal, etc) your scripts will know how to resolve their dependencies.

Creating a CommonJS compatible module

In order for a script to work with the CommonJS API it must assign public properties to the exports object.

The content of color.js illustrates this:

// Define your functionality:
function hex2rgb(hex) {
  /* ... */
}

function rgb2hex(rgb) {
  /* ... */
}

// Attach your API to the exports object:
exports.hex2rgb = hex2rgb;
exports.rgb2hex = rgb2hex;

A working example

To get in and get your hands dirty, check out my working example up on Github. It’s very tiny, and attempts to get the core ideas through as simply as possible.

http://github.com/dandean/modulr-demo

Suggestions and corrections are always welcome.

If it doesn’t already exist, create your download directories and cd into it:

  $ mkdir ~/downloads/git
  $ cd ~/downloads/git

Then, pull down the latest Node.js source code from GitHub:

  $ git clone git://github.com/ry/node.git

Since we’re on a Dreamhost shared server, we have to specify a personal directory for the node binaries to install to. This is because Dreamhost won’t allow us (for good reason) to install whatever we want into location which is shared by every other user on your server.

So, lets create our OWN /usr/local/bin directory:

  $ mkdir ~/usr/local/bin

Now that we’ve got that, let’s get into the node Git repo and configure node to use our new custom bin directory:

  $ ./configure --prefix=~/usr/local

If everything went well, make should handle the rest!

  $ make
  > ... a whole bunch of compilation output ...
  $ make install
  > ... more output ...
  > Done!

Now, you need to do one more thing to make node visible to your own scripts: add the new node binaries to your PATH! To do this you need to add the following line to two files in your home directory: .bashrc and .bash_profile.

  export PATH=$PATH:/home/[YOUR USER NAME]/usr/local/bin

You’re almost done! Just save both of those files, close your connection, reconnect, and check if you can run node! You should get something like this:

  $ node --version
  > v0.1.33-221-gff56d63

Hot shit! Now go build some killer Node.js apps!

In short, Aaron Cruz, here is a quick summary of the naming conventions which I adhere to:

var MyClass = Class.create({
  initialize: function(arg1, arg2) {
    this.publicProperty = "'Public' property";
    this._privateProperty = "'Private' property";
    var localVariable = null;
  },

  publicMethod: function() {
    return "'Public' method";
  },

  isBooleanMethod: function() {
    return true;
  },

  _privateMethod: function() {
    return "'Private' method";
  },

  __eventHandlerMethodClick: function(e) {
    return "Click-event handler method";
  }
});

MyClass.classProperty = "Class-level property";

MyClass.classMethod = function() {
  return "Class-level method";
};

MyClass.MY_CLASS_CONSTANT = "CONSTANT's should never change";

MyClass.ClassEnumOrSubType = {
  value0: 0,
  value1: 1,
  value2: 2,
  value3: 4,
  value4: 8
};

While the above example uses the Prototype class structure, none of the principles themselves are Prototype-specific.

Unfortunately I constantly forget how to do simple tasks, not to speak of complex ones. This post is going to serve as my very own GIT manual so I can make these translations easily and not have to remember the intricacies.

Updating your local repositories with remote changes: git pull

To get the latest changes from your remote repository merged into your local master, run git pull. This is pretty much the same as running git fetch then git merge origin/master. Think of this as the GIT version of svn:update or Vault’s “Get Latest”.

git pull

Pushing local changes to your remote repository

git add 'your file name'  #do this for each file or folder with changes
git commit -a -m 'Your commit message'
git push origin master

Rejected!

If a push to your remote repository gets rejected, it’s probably because remote files have been changed since you last used git pull. Run git pull then git push origin/master again. With any luck you should be in business.

Push master to origin/master

git push origin master
> To git@github.com:<username>/<reponame>.git
>  ! [rejected]        master -> master (non-fast forward)
> error: failed to push some refs to 'git@github.com:<username>/<reponame>.git'

Damn! Shit’s broke! Pull again then re-try your push!

git pull
> Merge made by recursive.

git push origin master
> Counting objects: 10, done.
> Compressing objects: 100% (5/5), done.
> Writing objects: 100% (6/6), 814 bytes, done.
> Total 6 (delta 1), reused 0 (delta 0)
> To git@github.com:<username>/<reponame>.git
>    65a1527..79239e9  master -> master

It worked!

Updating your fork of another user’s repository

get fetch origin
git fetch upstream
git merge upstream/master
git push origin master

There’s probably an easier way to do that, but I haven’t figured out as of this writing.

Counting the number of commits (and commiters)

git shortlog -s -n

This just gives you a nice clean list. The best I can figure out is to clean it up with some regex and count it.

• Replace all letters and spaces with nothing: [a-z ]+
• Replace new lines with commas
• Wrap the result in array delimiting square brackets
• Count it up with JavaScript

var commits = [744,536,68ö,39,17...1,1,1,1,1,1,1,1,1,1,1];
var count = 0;

commits.forEach(function(x) {
  count += x;
});
console.log(count);

If somebody has a better way, please tell me — this approach is overly complicated.

The Prototype Version:

Element.addMethods({
  /**
   *  Element#getTextContent(@element) -> String
   *  Cross-browser means of getting Element#textContent or Element#innerText
   **/
  getTextContent: function(element) {
    if (!Object.isUndefined(element.textContent)) {
      return element.textContent;
    }
    return element.innerText;
  }
});

The Procedural Version

/**
 * Gets the text content of the specified element.
 * @param element {HTMLElement} The html element
 * @return {String} The string content of the specified element.
 */
function getTextContent(element) {
  if (typeof element.textContent != "undefined") {
    return element.textContent;
  }
  return element.innerText;
}

// JavaScript
"Hello There".toUpperCase().split(' ');

// C#
"Hello There".ToUpper().Split(new Char[] {' '});

# Ruby
"Hello There".upcase.split(' ')

# Python
"Hello There".upper().split()

// PHP
explode(' ', strtoupper('Hello There'));

// PHP using Fluent
S('Hello There')->toupper()->explode(' ');

Fluent Data Types

OMG! “Strings!”

Using the Fluent_String class you can chain your string manipulation functions together on to one line, much like a sentence.

// Trim the white space from the left and right; Set to title case;
echo S('    fluent data type, huzaa!!   ')->trim()->ucwords();

// PRINTS: "Fluent Data Type, Huzaa!!"

// The same as above, but replace whitespace with 3 exclamations
echo S('    fluent data type, huzaa!!   ')->trim()->ucwords()
	->preg_replace("/s+/",'!!!');

// PRINTS: "Fluent!!!Data!!!Type,!!!Huzaa!!";

Neat, simple, arrays

The Fluent_Array class works just like the above string class. Splice, shift, count, asort, whatever, at will.

echo A(array('Bush','Clinton'))->splice(2,0,array('Bush','Clinton'))
	->push('Please stop now.');

// PRINTS: "Bush, Clinton, Bush, Clinton, Please stop now."

echo A(array('Bush','Clinton'))->splice(2,0,array('Bush','Clinton'))
	->push('Please stop now.')->unique();

// PRINTS: "Bush, Clinton, Please stop now."

Numbers…

Same goes for numbers, except that both int and float are handled within a single class: Fluent_Number.

// Find the circumference of a circle which has a radius of 3.5cm
echo N(3.5)->times(2)->times(M_PI);

// PRINTS: 21.991148575129

// Find the radius of a circle based on circumference
echo N(21.991148575129)->divide(M_PI)->divide(2)->round(1);

// PRINTS: 3.5

Boolean === Complete

To round it out, the Boolean data type is also supported. This is in place for completeness, so that when you’re dealing with a Fluent object, you’re always returned a Fluent object.

echo B(false);

// PRINTS: false

Core Data

You might have asked by now: “what if I want the actual piece if data instead of the Fluent object?” Well, the data at the core of every object is always available to you via the ‘value’ property of the Fluent object, so it’s easy to leave the object behind and pass on the actual data.

echo O(5)->value;

// PRINTS: 5

Caveats

There are, of course, some caveats that could trip you up, especially when dealing with numbers. For instance, if you try to directly add to Fluent_Number objects you’ll be given an E_NOTICE, the objects will be incorrectly ‘added’, and you’ll be sent on your way:

echo $bad = N(10) + N(20);
Notice: Object of class Fluent_Number could not be converted to int

// PRINTS: 2

Uncaveat

The correct way is to use operators on the value of an object is to directly work on the core data of the object:

echo $good = N(10)->value + N(20)->value; // return type = int
echo $good = N(10)->plus(20);             // return type = Fluent_Number

// PRINTS: 30

Transmogrify that shit

It’s very common that a single piece of data will need to be different types of data at different points in your application. Fluent objects automatically and intelligently convert your object from one Fluent Data Type to the next based on the data type of the return value, so you won’t have to create new Fluent objects whenever your data changes form:

echo O('President Bush is an evil bigot.')      // string
	->explode(' ')                          // array
	->splice(1,1,array('Cheney'))           // array
	->join(' ');                            // string

// PRINTS: President Cheney is an evil bigot.

echo O('President Bush is an evil bigot.')      // string
	->explode(' ')                          // array
	->splice(1,1,array('Cheney'))           // array
	->join(' ')                             // string
	->rev();                                // string

// PRINTS: .togib live na si yenehC tnediserP

echo O('President Bush is an evil bigot.')      // string
	->explode(' ')                          // array
	->splice(1,1,array('Cheney'))           // array
	->join(' ')                             // string
	->rev()                                 // string
	->len()                                 // int
	->times(19.5)                           // int
	->plus(3);                              // int

// PRINTS: 666

Oh PHP, you’re so crazy.

I can’t really say that PHP was the most well thought out thing in the world, and that’s probably because it wasn’t really thought out. PHP has adapted as a language as the web has grown and changed, which has enabled people of all skill level to get right in and create amazing tools. The language is incredibly simple but capable of astounding complexity.

This, of course, has its down side: when it comes to function names, function argument order, and function return values some crazy ass shit went down.

Fluent objects keep those unsightly stretch marks out of view by automatically shortening function names to their succinct names, among other things.

array_splice(), your name sucks

If you’ve been looking closely you’ll have noticed that instead of strtoupper(), strrev() and array_splice() we’ve been using splice(), toupper() and rev(). This feature is universally applied to all functions with name prepended by ‘str’, str_’ and ‘array_’.

What kind of order is this?

Another incredibly annoying thing about PHP is that there seems to be no logic to how the order of arguments was applied accross functions. The subject of the function, depending on the function, could be either the 1st, 2nd, or 3rd argument passed in.

With Fluent objects, the subject of the function is always the data within the Fluent object itself. This means that when you’re reading the documentation at php.net, remember that you should refrain from passing the subject as an argument… just pretend it doesn’t exist.

// Normal sprintf
echo sprintf('Hello %s.','There');

// Fluent sprintf
echo S('Hello %s.')->sprintf('There');

// Multi-chained Fluent sprintf
echo S('Hello %s.')->sprintf('There %s')->sprintf('Sucka');

// Normal str_replace
echo str_replace(')','(','Sad :)');

// Fluent str_replace
echo S('Sad :)')->replace(')','(');

What are you looking at?

What makes Fluent objects so valuable is our ability to chain function calls together indefinitely. In order to do this we always need to have a handle on what we’re dealing with. PHP throws us for a loop here because many of the array functions require that the subject array be passed in as an argument by reference, using the & operator. This then modifies the array you passed in, and returns a result, which is in many cases not the modified array but a boolean “success” indicator, a portion of the original array, the length of the resulting array, and so on.

Our Fluent objects solve this problem by always returning the modified array while at the same time populating the native property of the Fluent object with the value usually returned by the native PHP function.

$fruit = array('apple','orange','kiwi');
$result = array_push($fruit,'banana');

var_dump($fruit);

// PRINTS: array(4) {
//   [0]=>string(5) "apple"
//   [1]=>string(6) "orange"
//   [2]=>string(4) "kiwi"
//   [3]=>string(6) "banana"
// }

var_dump($result);
PRINTS: int(4)

Compare that to how a Fluent object behaves:

$fruit = A(array('apple','orange','kiwi'))->push('banana');

var_dump($fruit->value);

// PRINTS: array(4) {
//   [0]=>string(5) "apple"
//   [1]=>string(6) "orange"
//   [2]=>string(4) "kiwi"
//   [3]=>string(6) "banana"
// }

var_dump($fruit->native->value);

// PRINTS: int(4)

Shorter is Better

I created these classes to make programming in PHP quicker and more elegant. For this reason you don’t have to use new Fluent_String() to start using the string class. You can if you want, of course, but each data type already has its own one letter shortcut function: A(), S(), N(), and B().

There is also one more shortcut function for when you don’t care what you’re passing in, you just want it to be a Fluent object: O(). This function will take whatever it is you give it and return the appropriate Fluent data object.

And…

That’s basically it, really. Please download it and try it out. If you do, let me know what you think, where it could be improved upon, and if there are any stupid bugs that I missed.

In the future I plan to deal with a couple outstanding issues. First I’ll update Fluent to allow you to provide your own data type classes to use instead of mine (or extended from mine). Also, an important part of proving the usefulness of Fluent will be to figure out how performant they are. So fairly soon you should be able to expect some benchmarks to compare function calls to their native incarnation.