Useful tools for developing userscripts - in both CLI and API modes (CLI uses asynchronous calls while API can use either).



Table of Contents

- Features
- Installation
- Compatibility
- Usage
- CLI usage
- API usage
- Examples
- CLI examples
- Creating a .meta.js file from a .user.js file
- Extracting the entire metadata block
- API examples
- Extracting the .meta.js metablock and writing it to a new file
- Extracting the full metadata block
- Combining with UglifyJS
- Grunt task example
- Notes before running tests

Features

- Extract the entire metadata block
- Extract the small portion of the metadata block that's required for .meta.js files (@updateURL)

#Installation

``sh
npm install -g userscript-utils
`

Compatibility

Requires node version >=0.12

Usage

CLI usage

> {lamb} userscript-utils --help
>
> Userscript utilities
>
> Usage: userscript-utils [options]
> Pass -h or --help to any command to display command-specific help
>
> Commands:
>
> get-metablock - Retrieve the entire metadata block
> get-updateblock - Retrieve a shortened metadata block for .meta.js files

----------

> {lamb} userscript-utils get-metablock --help
>
> Retrieve the entire metadata block
>
> Usage: userscript-utils get-metablock [options]
>
> Options:
>
> -h, --help - Display this help
> -i, --infile - Get contents from a file as opposed to STDIN
> -o, --outfile - Output result to a file as opposed to STDOUT

----------

> {lamb} userscript-utils get-updateblock --help
>
> Retrieve the shortened metadata block required for .meta.js files and @updateURL
>
> Usage: userscript-utils get-updateblock [options]
>
> Options:
>
> -h, --help - Display this help
> -i, --infile - Get contents from a file as opposed to STDIN
> -o, --outfile - Output result to a file as opposed to STDOUT
> -u, --updateurl - Include the @updateURL tag in the output
> -d, --downloadurl - Include the @downloadURL tag in the output

API usage

See generated JSDoc.

Examples

CLI examples

$3

Bare minimum:
`sh
userscript-utils get-updateblock -i foo.user.js -o foo.meta.js;
#or
userscript-utils get-updateblock -i foo.user.js >> foo.meta.js;
`
Include @updateURL & @downloadURL:
`sh
userscript-utils get-updateblock -i foo.user.js -o foo.meta.js -du;
#or
userscript-utils get-updateblock -i foo.user.js -du >> foo.meta.js;
`
From STDIN:
`sh
cat foo.user.js | userscript-utils get-updateblock -o foo.meta.js;
#or
cat foo.user.js | userscript-utils get-updateblock >> foo.meta.js;
`
Or simply view the output by omitting the -o and --output options.

$3

Same options/arguments as above with the exception of -d, -u, --downloadurl and --updateurl being invalid:
`sh
userscript-utils get-metablock -i foo.user.js -o foo.big.meta.js;
`

API examples

$3

`js
var utils = require('userscript-utils').getUpdateMetablock,
fs = require('fs'),
inputFile = "foo.user.js",
outputFile = "foo.meta.js",
//For fs.writeFile
innerCallback = function (e) {
if (e) {
throw e;
}
},
//For userscript-utils
outerCallback = function (e, o) {
if (e) {
throw e;
} else {
fs.writeFile(outputFile, o, 'utf8', innerCallback);
}
};

//Bare minimum
utils.fromFile(inputFile, outerCallback);

//Include @updateURL
utils.fromFile(inputFile, outerCallback, true);

//Include @downloadURL
utils.fromFile(inputFile, outerCallback, false, true);

//Include @updateURL @downloadURL
utils.fromFile(inputFile, outerCallback, true, true);

// For synchronous mode simply omit the callback argument and replate the method with "fromFileSync":
try {
utils.fromFileSync(inputFile);
} catch (e) {
//handle
}

//And you can just as easily do the same if you have the file contents as a string:
utils.fromString(stringContainingFileContents, outerCallback);

try {
utils.fromStringSync(stringContainingFileContents);
} catch (e) {
//handle
}
`

$3

`js
var utils = require('userscript-utils').getMetablock,
fs = require('fs'),
inputFile = "foo.user.js",
outputFile = "foo.meta.js",
//For fs.writeFile
innerCallback = function (e) {
if (e) {
throw e;
}
},
//For userscript-utils
outerCallback = function (e, o) {
if (e) {
throw e;
} else {
fs.writeFile(outputFile, o, 'utf8', innerCallback);
}
};

//Async
utils.fromFile(inputFile, outerCallback);

// Sync
try {
utils.fromFileSync(inputFile);
} catch (e) {
//handle
}

//And you can just as easily do the same if you have the file contents as a string:
utils.fromString(stringContainingFileContents, outerCallback);

try {
utils.fromStringSync(stringContainingFileContents);
} catch (e) {
//handle
}
`

$3

`js
var utils = require('userscript-utils'),
minify = require('uglify-js').minify,
fs = require('fs'),
inFile = "foo.user.js",
outFile = "foo.min.user.js";

//Get our metablock
utils.getMetablock.fromFile(inFile, function (e, metablock) {
if (e) {
throw e;
} else {
// Minify the JS
var minified = minify(inFile).code;

//Open our file for writing
fs.open(outFile, 'w', function (e, fd) {
if (e) {
throw e;
} else {
//Write our file
fs.write(fd, metablock + "\n" + minified, function (e) {
try {
if (e) {
throw e;
}
} finally {
fs.close(fd, function (e) {
if (e) {
throw e;
}
});
}
});
}
});
}
});
`

Grunt task example

You'll need grunt-run:
`sh
npm i --save-dev grunt-run;
`
Add a run task to your Gruntfile.js under any name (e.g. foo) containing a CLI command to execute, e.g.:
`js
module.exports = function (grunt) {
// Initializing configuration objects
grunt.initConfig({
run: {
foo: {
exec: 'userscript-utils get-updateblock -i foo.user.js -o foo.meta.js'
}
}
});

grunt.loadNpmTasks('grunt-run');
};
`
Run the task:
`sh
grunt run:foo;
`

Notes before running tests

If you cloned this repository and want to run tests be sure to run npm link` beforehand otherwise you'll get errors!