Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Merge pull request #4 from nicoreed/master

[docs fix]: Improved the docs and made a few bug fixes
  • Loading branch information...
commit 5571e30f2186f0b8061dd36f5356d1f95ef7169d 2 parents c8bcb57 + dd54e40
@nicoreed nicoreed authored
View
240 README.md
@@ -14,97 +14,88 @@ CLI output formatting tools: "Your CLI Formatting Friend".
[sudo] npm install cliff
```
-## Motivation
-Cliff is the swiss army knife of CLI formatting tools. It is based on highly flexible and powerful libraries:
-
-* [winston][0]: A multi-transport async logging library for node.js
-* [eyes][1]: A customizable value inspector for node.js
-* [colors][2]: Get colors in your node.js console like what
-
## Usage
There are a number of methods available in Cliff for common logging tasks in command-line tools. If you're looking for more usage, checkout the [examples in this repository][3]:
-1. Inspecting Objects
-2. Logging rows of data
+1. Logging rows of data
+2. Inspecting Objects
-### Inspecting Objects
+### Logging rows of data
-**cliff.inspect(obj)**
+**cliff.stringifyRows(rows[, colors])**
-The `inspect` method is a lightweight wrapper to a pre-configured [eyes][1] inspector. Here is how it is created:
+Takes a set of Arrays and row headers and returns properly formatted and padded rows. Here's a sample:
``` js
-cliff.inspect = eyes.inspector({ stream: null,
- styles: { // Styles applied to stdout
- all: null, // Overall style applied to everything
- label: 'underline', // Inspection labels, like 'array' in `array: [1, 2, 3]`
- other: 'inverted', // Objects which don't have a literal representation, such as functions
- key: 'grey', // The keys in object literals, like 'a' in `{a: 1}`
- special: 'grey', // null, undefined...
- number: 'blue', // 0, 1, 2...
- bool: 'magenta', // true false
- regexp: 'green', // /\d+/
- }
-});
+ var cliff = require('../lib/cliff');
+
+ var rows = [
+ ['Name', 'Flavor', 'Dessert'],
+ ['Alice', 'cherry', 'yogurt'],
+ ['Bob', 'carmel', 'apples'],
+ ['Joe', 'chocolate', 'cake'],
+ ['Nick', 'vanilla', 'ice cream']
+ ];
+
+ console.log(cliff.stringifyRows(rows, ['red', 'blue', 'green']));
```
-If you wish to change the coloring of objects that are logged using `cliff` you only need to override `cliff.inspect` with a new [eyes][1] inspector.
+![output from string-rows.js][string-rows]
-**cliff.putObject(obj, [rewriters, padding])**
+**cliff.putRows(level, rows[, colors])**
-The `putObject` method is a simple helper function for prefixing and styling inspected object output from [eyes][1]. Here's a quick sample:
+The `putRows` method is a simple helper that takes a set of Arrays and row headers and logs properly formatted and padded rows (logs `stringifyRows` to [winston][0]). Here's a quick sample:
``` js
-var cliff = require('cliff');
+ var cliff = require('../lib/cliff');
-cliff.putObject({
- literal: "bazz",
- arr: [
- "one",
- 2,
- ],
- obj: {
- host: "localhost",
- port: 5984,
- auth: {
- username: "admin",
- password: "password"
- }
- }
-});
-```
+ var rows = [
+ ['Name', 'Flavor', 'Dessert'],
+ ['Alice', 'cherry', 'yogurt'],
+ ['Bob', 'carmel', 'apples'],
+ ['Joe', 'chocolate', 'cake'],
+ ['Nick', 'vanilla', 'ice cream']
+ ];
-The resulting output on the command-line would be (sadly the colors do not translate):
-
-``` bash
-$ node examples/put-object.js
-data: {
-data: arr: [ 'one', 2 ],
-data: literal: 'bazz',
-data: obj: {
-data: host: 'localhost',
-data: port: 5984,
-data: auth: { username: 'admin', password: 'password' }
-data: }
-data: }
+ cliff.putRows('data', rows, ['red', 'blue', 'green']);
```
-### Logging rows of data
+The resulting output on the command-line would be:
+
+![output from put-rows.js][put-rows]
+
+**cliff.stringifyObjectRows(objs, properties[, colors])**
+*used to be: cliff.rowifyObjects(objs, properties, colors)*
+
+Takes a set of Objects and the properties to extract from them and returns properly formatted and padded rows. Here's a sample:
+
+``` js
+ var cliff = require('../lib/cliff');
+
+ var objs = [], obj = {
+ name: "bazz",
+ address: "1234 Nowhere Dr.",
+ };
+
+ for (var i = 0; i < 10; i++) {
+ objs.push({
+ name: obj.name,
+ address: obj.address,
+ id: Math.random().toString()
+ });
+ }
-**cliff.stringifyRows(rows, colors)**
-Takes a set of Arrays and row headers and returns properly formatted and padded rows.
+ console.log(cliff.stringifyObjectRows(objs, ['id', 'name', 'address'], ['red', 'blue', 'green']));
+```
-**cliff.putRows(level, rows, colors)**
-Similar to `stringifyRows`, but it will log to the console using [winston][0] at the specified level.
+![output from string-object-rows.js][string-object-rows]
-**cliff.rowifyObjects(objs, properties, colors)**
-Takes a set of Objects and the properties to extract from them and returns properly formatted and padded rows.
+**cliff.putObjectRows(level, objs, properties[, colors])**
-**cliff.putObjectRows(level, objs, properties, colors)**
-Similar to `rowifyObjects`, but it will log to the console using [winston][0] at the specified level. Here's a sample:
+Takes a set of Objects and the properties to extract from them and it will log to the console. (it prints `stringifyObjectRows` with [winston][0]). Here's a sample:
``` js
- var cliff = require('cliff');
+ var cliff = require('../lib/cliff');
var objs = [], obj = {
name: "bazz",
@@ -122,32 +113,115 @@ Similar to `rowifyObjects`, but it will log to the console using [winston][0] at
cliff.putObjectRows('data', objs, ['id', 'name', 'address']);
```
-``` bash
- $ node examples/put-object-rows.js
- data: id name address
- data: 0.4157979858573526 bazz 1234 Nowhere Dr.
- data: 0.7140450903680176 bazz 1234 Nowhere Dr.
- data: 0.39573496161028743 bazz 1234 Nowhere Dr.
- data: 0.8285396825522184 bazz 1234 Nowhere Dr.
- data: 0.40711840940639377 bazz 1234 Nowhere Dr.
- data: 0.7133555023465306 bazz 1234 Nowhere Dr.
- data: 0.006228019250556827 bazz 1234 Nowhere Dr.
- data: 0.5560931102372706 bazz 1234 Nowhere Dr.
- data: 0.14310582634061575 bazz 1234 Nowhere Dr.
- data: 0.4638693502638489 bazz 1234 Nowhere Dr.
-```
+![output from string-object-rows.js][string-object-rows]
+
+**Colors Parameter**
+
+The `colors` parameter is an array that colors the first row. It uses the [colors.js][2]. You can use any of those.
+
+``` js
+ var cliff = require('../lib/cliff');
+
+ var rows = [
+ ['Name', 'Flavor', 'Dessert'],
+ ['Alice'.grey, 'cherry'.cyan, 'yogurt'.yellow],
+ ['Bob'.magenta, 'carmel'.rainbow, 'apples'.white],
+ ['Joe'.italic, 'chocolate'.underline, 'cake'.inverse],
+ ['Nick'.bold, 'vanilla', 'ice cream']
+ ];
+
+ cliff.putRows('data', rows, ['red', 'blue', 'green']);
+```
+
+The resulting output on the command-line would be:
+
+![output from puts-rows-colors.js][put-rows-colors]
+
+### Inspecting Objects
+
+**cliff.inspect(obj)**
+
+The `inspect` method is a lightweight wrapper to a pre-configured [eyes][1] inspector. If you wish to change the coloring of objects that are logged using `cliff` you only need to override `cliff.inspect` with a new [eyes][1] inspector. Here is how to use it:
+
+``` js
+ var cliff = require('../lib/cliff');
+
+ console.log(cliff.inspect({
+ literal: "bazz",
+ arr: [
+ "one",
+ 2,
+ ],
+ obj: {
+ host: "localhost",
+ port: 5984,
+ auth: {
+ username: "admin",
+ password: "password"
+ }
+ }
+ }));
+```
+
+![output from inspect.js][inspect]
+
+**cliff.putObject(obj, [rewriters, padding])**
+
+The `putObject` method is a simple helper function for prefixing and styling inspected object output from [eyes][1]. Here's a quick sample:
+
+``` js
+var cliff = require('cliff');
+
+cliff.putObject({
+ literal: "bazz",
+ arr: [
+ "one",
+ 2,
+ ],
+ obj: {
+ host: "localhost",
+ port: 5984,
+ auth: {
+ username: "admin",
+ password: "password"
+ }
+ }
+});
+```
+
+The resulting output on the command-line would be:
+
+![output from put-object.js][put-object]
## Run Tests
-All of the winston tests are written in [vows][4], and cover all of the use cases described above.
+
+All of the cliff tests are written in [vows][4], and cover all of the use cases described above.
```
npm test
```
+## Motivation
+
+Cliff is the swiss army knife of CLI formatting tools. It is based on highly flexible and powerful libraries:
+
+* [winston][0]: A multi-transport async logging library for node.js
+* [eyes][1]: A customizable value inspector for node.js
+* [colors][2]: Get colors in your node.js console like what
+
+
#### Author: [Charlie Robbins](http://twitter.com/indexzero)
[0]: http://github.com/indexzero/winston
[1]: http://github.com/cloudhead/eyes.js
[2]: http://github.com/marak/colors.js
[3]: http://github.com/nodejitsu/cliff/tree/master/examples
-[4]: http://vowsjs.org
+[4]: http://vowsjs.org
+
+[inspect]: https://github.com/nicoreed/cliff/raw/master/assets/inspect.png
+[put-object-rows]: https://github.com/nicoreed/cliff/raw/master/assets/put-object-rows.png
+[put-object]: https://github.com/nicoreed/cliff/raw/master/assets/put-object.png
+[put-rows-colors]: https://github.com/nicoreed/cliff/raw/master/assets/put-rows-colors.png
+[put-rows]: https://github.com/nicoreed/cliff/raw/master/assets/put-rows.png
+[string-object-rows]: https://github.com/nicoreed/cliff/raw/master/assets/string-object-rows.png
+[string-rows]: https://github.com/nicoreed/cliff/raw/master/assets/string-rows.png
View
BIN  assets/inspect.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN  assets/put-object-rows.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN  assets/put-object.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN  assets/put-rows-colors.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN  assets/put-rows.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN  assets/string-object-rows.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN  assets/string-rows.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
24 examples/inspect.js
@@ -0,0 +1,24 @@
+/*
+ * put-object.js: Example usage for `cliff.putObject`.
+ *
+ * (C) 2010, Nodejitsu Inc.
+ *
+ */
+
+var cliff = require('../lib/cliff');
+
+console.log(cliff.inspect({
+ literal: "bazz",
+ arr: [
+ "one",
+ 2,
+ ],
+ obj: {
+ host: "localhost",
+ port: 5984,
+ auth: {
+ username: "admin",
+ password: "password"
+ }
+ }
+}));
View
12 examples/put-rows-colors.js
@@ -0,0 +1,12 @@
+var cliff = require('../lib/cliff');
+
+var rows = [
+ ['Name', 'Flavor', 'Dessert'],
+ ['Alice'.grey, 'cherry'.cyan, 'yogurt'.yellow],
+ ['Bob'.magenta, 'carmel'.rainbow, 'apples'.white],
+ ['Joe'.italic, 'chocolate'.underline, 'cake'.inverse],
+ ['Nick'.bold, 'vanilla', 'ice cream']
+];
+
+cliff.putRows('data', rows, ['red', 'blue', 'green']);
+
View
11 examples/put-rows.js
@@ -0,0 +1,11 @@
+var cliff = require('../lib/cliff');
+
+var rows = [
+ ['Name', 'Flavor', 'Dessert'],
+ ['Alice', 'cherry', 'yogurt'],
+ ['Bob', 'carmel', 'apples'],
+ ['Joe', 'chocolate', 'cake'],
+ ['Nick', 'vanilla', 'ice cream']
+];
+
+cliff.putRows('data', rows, ['red', 'blue', 'green']);
View
23 examples/string-object-rows.js
@@ -0,0 +1,23 @@
+/*
+ * put-object-rows.js: Example usage for `cliff.putObjectRows`.
+ *
+ * (C) 2010, Nodejitsu Inc.
+ *
+ */
+
+var cliff = require('../lib/cliff');
+
+var objs = [], obj = {
+ name: "bazz",
+ address: "1234 Nowhere Dr.",
+};
+
+for (var i = 0; i < 10; i++) {
+ objs.push({
+ name: obj.name,
+ address: obj.address,
+ id: Math.random().toString()
+ });
+}
+
+console.log(cliff.stringifyObjectRows(objs, ['id', 'name', 'address'], ['red', 'blue', 'green']));
View
11 examples/string-rows.js
@@ -0,0 +1,11 @@
+var cliff = require('../lib/cliff');
+
+var rows = [
+ ['Name', 'Flavor', 'Dessert'],
+ ['Alice', 'cherry', 'yogurt'],
+ ['Bob', 'carmel', 'apples'],
+ ['Joe', 'chocolate', 'cake'],
+ ['Nick', 'vanilla', 'ice cream']
+];
+
+console.log(cliff.stringifyRows(rows, ['red', 'blue', 'green']));
View
24 lib/cliff.js
@@ -72,11 +72,10 @@ cliff.columnMajor = function (rows) {
cliff.arrayLengths = function (arrs) {
var i, lengths = [];
for (i = 0; i < arrs.length; i += 1) {
- lengths.push(winston.longestElement(arrs[i].map(function(elem) {
+ lengths.push(longestElement(arrs[i].map(function(elem) {
return cliff.stringifyLiteral(elem);
})));
}
-
return lengths;
};
@@ -98,7 +97,7 @@ cliff.stringifyRows = function (rows, colors) {
for (i = 0; i < row.length; i += 1) {
item = cliff.stringifyLiteral(row[i]);
item = colorize ? item[colors[i]] : item;
- length = item.length;
+ length = realLength(item);
padding = length < lengths[i] ? lengths[i] - length + 2 : 2;
rowtext += item + new Array(padding).join(' ');
}
@@ -128,7 +127,7 @@ cliff.stringifyRows = function (rows, colors) {
// Extracts the lists of `properties` from the specified `objs`
// and formats them according to `cliff.stringifyRows`.
//
-cliff.rowifyObjects = function (objs, properties, colors) {
+cliff.stringifyObjectRows = cliff.rowifyObjects = function (objs, properties, colors) {
var rows = [properties].concat(objs.map(function (obj) {
return cliff.extractFrom(obj, properties);
}));
@@ -241,4 +240,19 @@ cliff.typeOf = function typeOf (value) {
}
return s;
-};
+}
+
+var realLength = function (str) {
+ return ("" + str).replace(/\u001b\[\d+m/g,'').length;
+}
+
+var longestElement = function (a) {
+ var l = 0;
+ for (var i = 0; i < a.length; i++) {
+ var new_l = realLength(a[i]);
+ if (l < new_l) {
+ l = new_l;
+ }
+ }
+ return l;
+}
Please sign in to comment.
Something went wrong with that request. Please try again.