ramble-on v0.2.1

ramble-on

ramble-on is your one-stop property returning shop!

Why should you use it?

A good question! Let's say you are working with a really big Javascript object.

var big_object = {
    foo: {
        bar: {
            baz: {
                main: [
                  "test"
                ]
              , niam: 3
            }
          , zab: false
        }
      , rab: null
    }
  , oof: [
      2
    ]
};

Let's also say that you want to return or set any arbitrary value in that object. At first, it may seem easy.

var x = big_object.foo.bar.baz.main[0]; // returns "test"

However, what if the exact structure of the object is hard to determine at "compile" time?

big_object.foo.bar = "Hello";
var x = big_object.foo.bar.baz.main[0]; // throws Error because of invalid property

In these cases, it would be nice to have a way to programmatically specify property access. You could start by creating a function that uses eval() to dynamically create a retrieval statement for a given object and properties array.

function get_property(object, properties) {
  var prop;
  eval("prop = object[" + properties.join("][") + "];");
  return prop;
}

However, you should not use eval (most of the time anyway). Also, you would need to create another function to set properties!

There has to be a better way!

Enter ramble-on...

ramble-on makes it easy to retrieve and set properties on nearly any object. You just call it with the object you want to traverse and an array of strings and integers representing the location of the object.

Example:

var ramble = require('ramble-on');

var object = big_object; // i.e. the object from the first code snippet
var property = ramble(object, ["foo", "bar", "baz"]);
console.log(JSON.stringify(property, null, 2));

Output:

{
  "main": [
   "test"
  ],
  "niam": 3
}

You can even set properties as well. Just add one parameter: the value to set

Example:

ramble(object, ["foo", "bar"], "Hello");
console.log(JSON.stringify(object, null, 2));

Output:

{
  "foo": {
    "bar": "Hello",
    "rab": null
  },
  "oof": [
    2
  ]
}

Heck, you can even handle circular dependencies!

Example:

var object = big_object; // NOTE: If you are following along, you might want to reset big_object.
ramble(object, ["foo", "bar", "baz", "main", 1], object);
var prop = ramble(object, ["foo", "bar", "baz", "main", 1, "oof", 0]);
console.log(prop); // Outputs: 2

NEW: If you want to create a nested value and do not want to manually create its parent values, just append a true to the arguments to tell ramble-on to create nested values.

Example:

var object = { foo: 'bar' };
ramble(object, ['fizz', 'buzz'], 15, true);
console.log(object.fizz.buzz); // Prints 15

NOTE: If you specify an integer as one of the properties, ramble-on will assume the previous property is an array instead of an object.

Example:

var object = { foo: 'bar' };
ramble(object, ['fizz', 0], 'buzz', true);
object.fizz.push('baz');
console.log(object.fizz.length) // Prints 2

Get ramble-on today!

How much would you pay for such a useful library? 500 dollars? 5,000 dollars?! ONE MILLION DOLLARS?!!!!

Well, you can pay $0 because ramble-on is released as Free Libre Open-Source Software under the terms of the MIT License. Copy it; share it; put it in a blender! Do all three at once!

Start using this sexy-cool library today by rambling to the root directory of your project and typing npm install ramble-on --save into the *nix console of your choice! (Requires: node.js; other options coming soon).