grunt-file-info

Automate template-driven updates of project file stats to project documentation.

Getting Started

This plugin requires Grunt >=0.4.0

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-file-info --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-file-info');

The file_info task

Run this task with the grunt file_info command.

Task targets, files and options may be specified according to the grunt Configuring tasks guide.

Overview

In your project's Gruntfile, add a section named file_info to the data object passed into grunt.initConfig().

The following example injects file size information for a source file and its minified version into a README.md file that already has a section whose layout conforms to the options.inject.text template:

grunt.initConfig({
  file_info: {
    source_files: {
      src: ['source_file.js', 'minified_source_file.js'],
      options: {
        inject: {
          dest: 'README.md',
          text: '###Size' + 
                grunt.util.linefeed + grunt.util.linefeed + 
                'Original: {{= sizeText(size(src[0])) }}' + 
                grunt.util.linefeed + grunt.util.linefeed + 
                'Minified: {{= sizeText(size(src[1])) }}' + 
                grunt.util.linefeed + grunt.util.linefeed + 
                'Gzipped:  {{= sizeText(gzipSize(src[1])) }}'
        }
      }
    }
  }
});

Options

options.stdout

Type: boolean or string
Default: true

If falsy, output to the command line is suppressed.

If true, results for each file specified by src are output to the command line using the default layout.

If a string is passed, it is applied as a template (using mustache-style delimiters) specifying how results are output to the command line.

options.inject

Type: object or array of object
Default: undefined

An inject config object or array of inject config objects having the following properties:

| | Required | Description | | :---: | :---: | :--- | | dest | Yes | An injection target filepath string or array of injection target filepath strings. | | text | Yes | A template string (using mustache-style delimiters) to define where and how results are injected into the file(s) specified by dest. | | report | No | If truthy, inject status is output to the command line. Otherwise, no status is reported. Default: true |

The template defined by text is used to:

1. identify the portion of text to replace in an injection target file

2. extract current field values from an injection target file for comparison against calculated values

3. determine the text to inject into an injection target file (if changes are detected)

options.injectReport

Type: boolean
Default: true

Provides a default value for the report property of options.inject config objects.

Command-Line Output and File Injection Templates

options.stdout and options.inject.text values are processed through Lo-Dash templating via Grunt. As such, these templates conform to the semantics set forth by Lo-Dash template specs.

In order to control the timing of template processing within the file_info task, custom delimiters of the form {{ }} are used for these templates.

Lo-Dash functions are accessible within fields of such templates via standard Lo-Dash syntax (eg, _.first([1,2,3])). Additionally, underscore.string methods are similiarly accessible (eg, _.titleize("hello cruel world")).

The file_info task also furnishes certain Template Functions and Template Variables within template fields, as outlined below.

Template Functions

The following functions are available within fields of templates defined by options.stdout and options.inject.text:

size (string filepath)

Returns the size in bytes of the file specified by filepath.

gzipSize (string filepath)

Returns the gzipped size in bytes of the file specified by filepath.

sizeText (number bytes [, number lpadding])

Returns unit-adjusted and optionally-padded text (eg, "2 kB", "632 bytes") corresponding to a number of bytes.

spaceSavings (string filepath)

Returns the percentage space savings gained by gzipping the file specified by filepath.

modified (string filepath)

Returns the date that the contents of the file specified by filepath were last modified.

modifiedAgo (string filepath)

Returns a string (eg, "10 days ago") describing how long ago the contents of the file specified by filepath were last modified. This function is generally more useful to stdout templates than file injection templates.

filename (string filepath)

Returns the file name portion (including file type) of a file path.

filetype (string filepath)

Returns the file type portion (without the leading '.') of a file path.

config ([string configName])

Returns the value of the item stored in grunt.config(configName).

Additionally, the following function is available within fields of templates defined by options.inject.text:

pass ([number index])

Returns the matched value of a template field when that template is matched against existing text of an injection target file. index is the 1-based order of the matched field within the template and defaults to the order of the field in which pass() is called.

Template Variables

The following variables are available within fields of templates defined by options.stdout and options.inject.text:

filesSrc

An array of expanded filepath strings of all src files to get file info for. Note that this is not the same as src, which refers to the raw (ie, non-expanded) value of the src property of the file_info config target object.

Usage Examples

Default Options

The following example simply outputs file size information for a source file and its minified version to the command line:

grunt.initConfig({
    file_info: {
        source_files: {
            src: ['source_file.js', 'minified_source_file.js']
        }
    }
});

Output:

source_files stats:

source_file.js                22.5 kB (4.2 kB gzipped)
minified_source_file.js       17.9 kB (3.9 kB gzipped)

Customized Command-Line Output

The following example outputs file size information for a source file and its minified version to the command line according to a custom template:

grunt.initConfig({
  file_info: {
    source_files: {
      src: ['source_file.js', 'minified_source_file.js'],
      options: {
        stdout: 
          'Original: {{= sizeText(size(src[0]), 7) }}' + grunt.util.linefeed + 
          'Minified: {{= sizeText(size(src[1]), 7) }}' + grunt.util.linefeed + 
          'Gzipped:  {{= sizeText(gzipSize(src[1]), 7) }} ({{= spaceSavings(src[1]) }}% savings)'
      }
    }
  }
});

Output:

Original:      22.5 kB
Minified:      17.9 kB
Gzipped:        3.9 kB (78.06% savings)

The following example outputs a file's name, modification date, and size to the command line according to a custom template:

grunt.initConfig({
    file_info: {
        source_files: {
            src: 'src/source_file.js',
            options: {
                stdout: 
                  'Name: {{= filename(src) }}' + grunt.util.linefeed + 
                  'Date: {{= modified(src).toDateString() }}' + grunt.util.linefeed + 
                  'Size: {{= sizeText(size(src)) }}'
            }
        }
    }
});

Output:

Name: source_file.js
Date: Sat Dec 07 2013
Size: 22.5 kB

File Injection

The following example injects file size information for a source file and its minified version into a README.md file according to a template specified by options.inject.text. The template is used to match the portion of the file to replace as well as to generate the replacement text.

grunt.initConfig({
  file_info: {
    source_files: {
      src: ['source_file.js', 'minified_source_file.js'],
      options: {
        inject: {
          dest: 'README.md',
          text: 
            '###Size' + 
            grunt.util.linefeed + grunt.util.linefeed + 
            '|          | Dependent Version | Standalone Version |' + grunt.util.linefeed + 
            '| :------- | ----------------: | -----------------: |' + grunt.util.linefeed + 
            '| Original | {{= _.lpad(pass(), 17) }} | {{= sizeText(size(src[0]), 18) }} |' + 
            grunt.util.linefeed + 
            '| Minified | {{= _.lpad(pass(), 17) }} | {{= sizeText(size(src[1]), 18) }} |' + 
            grunt.util.linefeed + 
            '| Gzipped  | {{= _.lpad(pass(), 17) }} | {{= sizeText(gzipSize(src[1]), 18) }} |'
        }
      }
    }
  }
});

Injected text:

###Size

|          | Dependent Version | Standalone Version |
| :------- | ----------------: | -----------------: |
| Original |           22.5 kB |            57.5 kB |
| Minified |              7 kB |            17.2 kB |
| Gzipped  |            1.5 kB |             3.8 kB |

File injection occurs only if a portion of the destination file matches options.inject.text and one or more corresponding field values change, in which case a diff report is normally output to the command line for the matching portion of text. For example:

If the destination file does not exist, it is created and populated with the generated text. In this case the template function pass() yields an empty string since there are no field values to propagate.

Note that in the example above, text is written to the destination file only if any of the size values for "Standalone Version" have changed. "Dependent Version" values in this case are simply propagated from existing text.

Kitchen Sink

The following extensive example shows the use of two file_info targets that each write source file stats for a particular version of an application to a corresponding column of the same markdown table of a README.md file.

grunt.initConfig({
 file_info: {
  source_verion_1: {
   src: ['dist/v1/source_file.js', 'dist/v1/minified_source_file.js'],
   options: {
    inject: {
     dest: 'README.md',
     text: 
      '###Size' + grunt.util.linefeed + grunt.util.linefeed + 
      '|          | Dependent Version | Standalone Version |' + grunt.util.linefeed + 
      '| :------- | ----------------: | -----------------: |' + grunt.util.linefeed + 
      '| Original | {{= sizeText(size(src[0]), 17) }} | {{= _.lpad(pass(), 18) }} |' + 
      grunt.util.linefeed + 
      '| Minified | {{= sizeText(size(src[1]), 17) }} | {{= _.lpad(pass(), 18) }} |' + 
      grunt.util.linefeed + 
      '| Gzipped  | {{= sizeText(gzipSize(src[1]), 17) }} | {{= _.lpad(pass(), 18) }} |'
    },
    stdout: 
     'Original: {{= sizeText(size(src[0]), 7) }}' + grunt.util.linefeed + 
     'Minified: {{= sizeText(size(src[1]), 7) }}' + grunt.util.linefeed + 
     'Gzipped:  {{= sizeText(gzipSize(src[1]), 7) }} ({{= spaceSavings(src[1]) }}% savings)'
   }
  },
  source_verion_2: {
   src: ['dist/v2/source_file.js', 'dist/v2/minified_source_file.js'],
   options: {
    inject: {
     dest: 'README.md',
     text: 
      '###Size' + grunt.util.linefeed + grunt.util.linefeed + 
      '|          | Dependent Version | Standalone Version |' + grunt.util.linefeed + 
      '| :------- | ----------------: | -----------------: |' + grunt.util.linefeed + 
      '| Original | {{= _.lpad(pass(), 17) }} | {{= sizeText(size(src[0]), 18) }} |' + 
      grunt.util.linefeed + 
      '| Minified | {{= _.lpad(pass(), 17) }} | {{= sizeText(size(src[1]), 18) }} |' + 
      grunt.util.linefeed + 
      '| Gzipped  | {{= _.lpad(pass(), 17) }} | {{= sizeText(gzipSize(src[1]), 18) }} |'
    },
    stdout: 
     'Original: {{= sizeText(size(src[0]), 7) }}' + grunt.util.linefeed + 
     'Minified: {{= sizeText(size(src[1]), 7) }}' + grunt.util.linefeed + 
     'Gzipped:  {{= sizeText(gzipSize(src[1]), 7) }} ({{= spaceSavings(src[1]) }}% savings)'
   }
  }
 }
});

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.