Insert Header

Insert a license header into each file in a provided file list.

Usage

var insertHeader = require( '@stdlib/_tools/licenses/insert-header-file-list' );

insertHeader( files, header, clbk )

Asynchronously inserts a license header into each file in a provided file list.

var join = require( 'path' ).join;

var files = [
    join( __dirname, 'examples', 'index.js' )
];

var header = '// This file is a part of stdlib. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0';

insertHeader( files, header, done );

function done( error ) {
    if ( error ) {
        throw error;
    }
}

To insert license headers using an object whose keys are filename extensions and whose values are license header strings,

var join = require( 'path' ).join;

var files = [
    join( __dirname, 'README.md' ),
    join( __dirname, 'examples', 'index.js' )
];

var header = {
    // JavaScript files:
    'js': '// This file is a part of stdlib. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0',

    // Julia files:
    'jl': '# This file is a part of stdlib. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0',

    // Markdown files:
    'md': '<!-- This file is a part of stdlib. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -->',

    // Everything else:
    'default': '/* This file is a part of stdlib. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 */'
};

insertHeader( files, header, done );

function done( error ) {
    if ( error ) {
        throw error;
    }
}

If a provided header object includes a default property, the value assigned to that property is inserted into all files having filename extensions not explicitly included in the object; otherwise, the function ignores any file not having a filename extension explicitly included in the object.

insertHeader.sync( files, header )

Synchronously inserts a license header into each file in a provided file list.

var join = require( 'path' ).join;

var files = [
    join( __dirname, 'examples', 'index.js' )
];

var header = '// This file is a part of stdlib. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0';

var err = insertHeader.sync( files, header );
if ( err ) {
    throw err;
}

Notes

  • Input files are overwritten. If overwriting files is not desired, copy files to another location and provide the updated file paths.
  • File paths are resolved relative to the current working directory of the calling process.
  • License headers are inserted after shebang lines (if already present).

Examples

var join = require( 'path' ).join;
var readFile = require( '@stdlib/fs/read-file' ).sync;
var writeFile = require( '@stdlib/fs/write-file' ).sync;
var unlink = require( '@stdlib/fs/unlink' ).sync;
var licenseHeader = require( '@stdlib/_tools/licenses/header' );
var insertHeader = require( '@stdlib/_tools/licenses/insert-header-file-list' ).sync;

// Create a temporary file:
var src = join( __dirname, 'examples', 'fixtures', 'file.js.txt' );
var tmp = join( __dirname, 'examples', 'fixtures', 'tmp.js.txt' );
var err = writeFile( tmp, readFile( src ) );
if ( err ) {
    throw err;
}

// Specify a list of files in which to insert headers:
var files = [
    tmp
];

// Create a header object containing license headers:
var headers = {
    'txt': licenseHeader( 'Apache-2.0', 'js', {
        'year': 2018,
        'copyright': 'The Stdlib Authors'
    })
};

// Insert header:
err = insertHeader( files, headers );
if ( err ) {
    throw err;
}

// Print the contents of the temporary file:
console.log( readFile( tmp, 'utf8' ) );

// Remove the temporary file:
err = unlink( tmp );
if ( err ) {
    throw err;
}

CLI

Usage

Usage: insert-license-header-file-list [options] [<file> <file> ...]

Options:

  -h, --help             Print this message.
  -V, --version          Print the package version.
      --split sep        Separator used to split stdin data. Default: /\\r?\\n/.
      --header filepath  License header file path.

Notes

  • To provide multiple license headers, set multiple --header option arguments, where each argument value must include a file extension prefix. For example,

    $ insert-license-header-file-list --header='awk:./beep.txt' --header='js:./boop.txt' --header='default:./foo.txt' ./README.md
    
  • If the split separator is a regular expression, ensure that the option value is properly escaped.

    # Not escaped...
    $ <stdout> | insert-license-header-file-list --split /\r?\n/
    
    # Escaped...
    $ <stdout> | insert-license-header-file-list --split /\\r?\\n/
    
  • File paths may be relative or absolute file paths. Relative file paths are resolved relative to the current working directory of the calling process.

Examples

$ insert-license-header-file-list ./examples/index.js

To use as part of a standard stream pipeline,

$ echo -n $'./README.md\t./examples/index.js\t' | insert-license-header-file-list --split /\\t/