Automate template-driven updates of project file stats to project documentation.
npm install grunt-file-info>=0.4.0
shell
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:
`js
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.
$3
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:
`js
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])) }}'
}
}
}
}
});
`
$3
#### 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.
$3
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.
$3
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.
$3
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.
$3
#### Default Options
The following example simply outputs file size information for a source file and its minified version to the command line:
`js
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:
`js
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:
`js
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.
`js
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:
!diff.png
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.
`js
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.