Negligent Pachinko Machine
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    grunt-file-infopublic

    grunt-file-info

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

    inject.png

    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:

    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.

    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.

    install

    npm i grunt-file-info

    Downloadsweekly downloads

    140

    version

    1.0.14

    license

    MIT

    repository

    github.com

    last publish

    collaborators

    • avatar