columnify - npm Package Compare versions

Comparing version 0.0.2 to 0.0.3

index.js

 "use strict"
 
 module.exports = function(items, options) {
+
+  // defaults
   options = options || Object.create(null)
@@ -19,2 +21,3 @@ var defaultColumn = options.defaultColumn || {
 
+  // if not suppled column names, automatically determine columns from data
   if (!columnNames.length) {
@@ -28,4 +31,4 @@ items.forEach(function(item) {
 
+  // initialize each column
   var columns = columnNames.reduce(function(columns, columnName) {
-    // initialize each column
     columns[columnName] = {}
@@ -35,9 +38,11 @@ return columns
 
+  // set column defaults
   columnNames.forEach(function(columnName) {
     var column = columns[columnName]
     var width = options.widths[columnName] || defaultColumn
-    column.maxWidth = width.maxWidth || defaultColumn.maxWidth || 0
+    column.maxWidth = width.maxWidth || defaultColumn.maxWidth || Infinity
     column.minWidth = width.minWidth || defaultColumn.minWidth || 0
   })
 
+  // sanitize data
   items = items.map(function(item) {
@@ -63,3 +68,4 @@ var result = Object.create(null)
 
-  // get actual width between min & max
+  // get actual max-width between min & max
+  // based on length of data in columns
   columnNames.forEach(function(columnName) {
@@ -78,3 +84,4 @@ var column = columns[columnName]
     items = items.map(function(item) {
-      item[columnName] = splitLines(item[columnName], column.width)
+      item[columnName] = splitIntoLines(item[columnName], column.width)
+      // only include first line if truncating
       if (options.truncate) item[columnName] = item[columnName].slice(0, 1)
@@ -86,2 +93,4 @@ return item
   var rows = createRows(items, columns, columnNames)
+
+  // conceive output
   return rows.reduce(function(output, row) {
@@ -94,2 +103,11 @@ return output.concat(row.reduce(function(rowOut, line) {
 
+/**
+ * Convert wrapped lines into rows with padded values.
+ *
+ * @param Array items data to process
+ * @param Array columns column width settings for wrapping
+ * @param Array columnNames column ordering
+ * @return Array items wrapped in arrays, corresponding to lines
+ */
+
 function createRows(items, columns, columnNames) {
@@ -102,2 +120,3 @@ return items.map(function(item) {
     })
+    // combine matching lines of each rows
     for (var i = 0; i < numLines; i++) {
@@ -107,3 +126,3 @@ row[i] = row[i] || []
         var column = columns[columnName]
-        var val = item[columnName][i] || ''
+        var val = item[columnName][i] || '' // || '' ensures empty columns get padded
         row[i].push(padRight(val, column.width))
@@ -116,2 +135,12 @@ })
 
+/**
+ * Pad `str` up to total length `max` with `chr`.
+ * If `str` is longer than `max`, padRight will return `str` unaltered.
+ *
+ * @param String str string to pad
+ * @param Number max total length of output string
+ * @param String chr optional. Character to pad with. default: ' '
+ * @return String padded str
+ */
+
 function padRight(str, max, chr) {
@@ -124,7 +153,12 @@ var length = 1 + max - str.length
 
-function padLeft(str, max, chr) {
-  return Array.apply(null, {length: 1 + max - str.length}).join(chr || ' ') + str
-}
+/**
+ * Split a String `str` into lines of maxiumum length `max`.
+ * Splits on word boundaries.
+ *
+ * @param String str string to split
+ * @param Number max length of each line
+ * @return Array Array containing lines.
+ */
 
-function splitLines(str, max) {
+function splitIntoLines(str, max) {
   return str.trim().split(' ').reduce(function(lines, word) {
@@ -131,0 +165,0 @@ var line = lines[lines.length - 1]

package.json

 {
   "name": "columnify",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Render data in text columns, with in-column text-wrap.",
@@ -5,0 +5,0 @@ "main": "index.js",

Readme.md

 # columnify
 
+[![Build Status](https://travis-ci.org/timoxley/columnify.png?branch=master)](https://travis-ci.org/timoxley/columnify)
+
 Create text-based columns suitable for console output. 
 Supports minimum and maximum column widths via truncation and text wrapping.
 
-Designed to handle sensible wrapping in npm search results.
+Designed to [handle sensible wrapping in npm search results](https://github.com/isaacs/npm/pull/2328).
 
+## Installation & Update
+
+```
+$ npm install --save columnify@latest
+```
+
+## Usage
+
+```js
+var columnify = require('columnify')
+var columns = columnify(data, options)
+console.log(columns)
+```
+
 ## Examples
 
-Text is aligned under column headings.
+### Simple Columns
 
+Text is aligned under column headings. Columns are automatically resized to fit the content of the largest cell. 
+Each cell will be padded with spaces to fill the available space and ensure column contents are left-aligned.
+
 ```js
@@ -16,3 +35,3 @@ var columnify = require('columnify')
 var columns = columnify([{
-  name: 'module1',
+  name: 'mod1',
   version: '0.0.1'
@@ -28,3 +47,3 @@ }, {
 NAME    VERSION
-module1 0.0.1  
+mod1    0.0.1  
 module2 0.2.0  
@@ -35,4 +54,3 @@ ```
 
-You can define the maximum width before wrapping for
-individual cells in columns.
+You can define the maximum width before wrapping for individual cells in columns. Minimum width is also supported. Wrapping will happen at word boundaries. Empty cells or those which do not fill the max/min width will be padded with spaces.
 
@@ -64,3 +82,3 @@ ```js
 
-Instead of wrapping, you can simply truncate at the maxiumum column width.
+You can disable wrapping and instead truncate content at the maximum column width. Truncation respects word boundaries.
 
@@ -88,3 +106,3 @@ ```js
 
-Columns can be split with custom characters.
+If your columns need some bling, you can split columns with custom characters.
 
@@ -105,4 +123,33 @@ ```js
 
+### Filtering & Ordering Columns
+
+By default, all properties are converted into columns, whether or not they exist on every object or not. 
+
+To explicitly specify which columns to include, and in which order, supply a "columns" array:
+
+```js
+var data = [{
+  name: 'module1',
+  description: 'some description',
+  version: '0.0.1',
+}, {
+  name: 'module2',
+  description: 'another description',
+  version: '0.2.0',
+}]
+
+var columns = columnify(data, {
+  columns: ['name', 'version'] // note description not included
+})
+
+console.log(columns)
+```
+
+```
+NAME    VERSION
+module1 0.0.1
+module2 0.2.0
+```
 ## License
 
 MIT

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

12962

increased by23.73%

Number of package files

16

increased by6.67%

Lines of code

265

increased by12.77%

Number of lines in readme file

150

increased by45.63%

No dependency changes