From 98f20c368cf2c87db9a9e6f2ab1a344115f5543c Mon Sep 17 00:00:00 2001 From: hacksalot Date: Sat, 10 Feb 2018 13:03:52 -0500 Subject: [PATCH] feat: introduce HELP command Add support for a "HELP" verb in the HackMyResume CLI, allowing separate help pages for each HackMyResume command per #205. The following command invocations are recognized. hackmyresume help hackmyresume help build hackmyresume help new hackmyresume help convert hackmyresume help analyze hackmyresume help validate hackmyresume help peek hackmyresume help help --- dist/cli/help/analyze.txt | 23 +++++++++++++ dist/cli/help/build.txt | 69 ++++++++++++++++++++++++++++++++++++++ dist/cli/help/convert.txt | 34 +++++++++++++++++++ dist/cli/help/help.txt | 23 +++++++++++++ dist/cli/help/new.txt | 27 +++++++++++++++ dist/cli/help/peek.txt | 30 +++++++++++++++++ dist/cli/help/validate.txt | 27 +++++++++++++++ dist/cli/main.js | 22 +++++++++--- dist/cli/use.txt | 42 +++++++++++------------ src/cli/help/analyze.txt | 23 +++++++++++++ src/cli/help/build.txt | 69 ++++++++++++++++++++++++++++++++++++++ src/cli/help/convert.txt | 34 +++++++++++++++++++ src/cli/help/help.txt | 23 +++++++++++++ src/cli/help/new.txt | 27 +++++++++++++++ src/cli/help/peek.txt | 30 +++++++++++++++++ src/cli/help/validate.txt | 27 +++++++++++++++ src/cli/main.coffee | 33 +++++++++++++----- src/cli/use.txt | 42 +++++++++++------------ 18 files changed, 546 insertions(+), 59 deletions(-) create mode 100644 dist/cli/help/analyze.txt create mode 100644 dist/cli/help/build.txt create mode 100644 dist/cli/help/convert.txt create mode 100644 dist/cli/help/help.txt create mode 100644 dist/cli/help/new.txt create mode 100644 dist/cli/help/peek.txt create mode 100644 dist/cli/help/validate.txt create mode 100644 src/cli/help/analyze.txt create mode 100644 src/cli/help/build.txt create mode 100644 src/cli/help/convert.txt create mode 100644 src/cli/help/help.txt create mode 100644 src/cli/help/new.txt create mode 100644 src/cli/help/peek.txt create mode 100644 src/cli/help/validate.txt diff --git a/dist/cli/help/analyze.txt b/dist/cli/help/analyze.txt new file mode 100644 index 0000000..5635f16 --- /dev/null +++ b/dist/cli/help/analyze.txt @@ -0,0 +1,23 @@ +**analyze** | Analyze a FRESH resume document for statistics + +Usage: + + hackmyresume ANALYZE [] + hackmyresume ANALYZE [] + +Parameters: + + **** + + Absolute or relative path(s) to one or more FRESH or + JSON Resume documents to be analyzed. Multiple resumes + can be specified, separated by spaces: + + hackmyresume ANALYZE r1.json r2.json r3.json + +Options: + + **None.** + +The ANALYZE command performs simple analysis on a FRESH or +JSON Resume document. diff --git a/dist/cli/help/build.txt b/dist/cli/help/build.txt new file mode 100644 index 0000000..e572f5c --- /dev/null +++ b/dist/cli/help/build.txt @@ -0,0 +1,69 @@ +**build** | Generate resumes in supported output formats + +Usage: + + hackmyresume BUILD TO [] + +Parameters: + + **** + + Absolute or relative path(s) to one or more resumes in + FRESH or JSON format, separated by spaces. If multiple + resumes are specified, they will be merged into a + single resume prior to transformation. + + hackmyresume BUILD resume.json output.all + hackmyresume BUILD base.json developer.json gamedev.json TO out/resume.all + + **** + + Absolute or relative path(s) to one or more outbound + resume(s), separated by spaces. If multiple output + resumes are specified, all of them will be generated. + The desired format of each resume will be determined + from the file extension: + + .all Generate all supported formats + .html HTML 5 + .doc MS Word + .pdf Adobe Acrobat PDF + .txt plain text + .md Markdown + .png PNG Image + .latex LaTeX + + Note: not all formats are supported by all themes. + Check the theme's documentation for details. + +Options: + + **--theme -t ** + + Relative or absolute path to a FRESH or JSON Resume + theme, or the name of a built-in theme. + + As of 1.9.0, the following built-in themes are + provided: basis, modern, positive, compact, awesome. + + **--pdf -p ** + + Specify the PDF engine to use. Legal values are: + + - none: Don't generate a PDF. + - wkhtmltopdf: Use the wkhtmltopdf PDF engine. + - phantom: use the PhantomJS PDF engine. + - weazyprint: use the WeazyPrint PDF engine. + + **--no-escape** + + Disable escaping / encoding of resume data during + resume generation. Handlebars themes only. + + **--private** + + Include resume fields marked as private. + +The BUILD command generates themed resumes and CVs in +multiple formats from a single source of truth in the form +of a FRESH or JSON Resume document. diff --git a/dist/cli/help/convert.txt b/dist/cli/help/convert.txt new file mode 100644 index 0000000..dd6092b --- /dev/null +++ b/dist/cli/help/convert.txt @@ -0,0 +1,34 @@ +**convert** | Convert resumes between FRESH and JRS formats + +Usage: + + hackmyresume CONVERT TO [] + +Parameters: + + **** + + Absolute or relative path(s) to one or more FRESH or + JSON Resume documents (*.json), separated by spaces. + + **** + + The desired absolute or relative path(s) of the newly + converted resume(s). HackMyResume will create the + converted resume(s) here. + +Options: + + **--format -f ** + + The desired format for the new resume(s). Valid values + are 'FRESH', 'JRS', or, to target the latest edge + version of the JSON Resume Schema, 'JRS@1'. + + If this parameter is omitted, the destination format + will be inferred from the source resume's format. If + the source format is FRESH, the destination format + will be JSON Resume, and vice-versa. + +The CONVERT command converts one or more resume documents +between FRESH and JSON Resume formats. diff --git a/dist/cli/help/help.txt b/dist/cli/help/help.txt new file mode 100644 index 0000000..f259bba --- /dev/null +++ b/dist/cli/help/help.txt @@ -0,0 +1,23 @@ +**help** | View help on a specific HackMyResume command + +Usage: + + hackmyresume HELP + +Parameters: + + **** + + The HackMyResume command to view help information for. + Must be BUILD, NEW, CONVERT, ANALYZE, VALIDATE, PEEK, + or HELP. + + hackmyresume help convert + hackmyresume help help + +Options: + + **None.** + +The HELP command displays help information for a specific +HackMyResume command, including the HELP command itself. diff --git a/dist/cli/help/new.txt b/dist/cli/help/new.txt new file mode 100644 index 0000000..0d7f05e --- /dev/null +++ b/dist/cli/help/new.txt @@ -0,0 +1,27 @@ +**new** | Create a new FRESH or JRS resume document + +Usage: + + hackmyresume NEW [] + +Parameters: + + **** + + Absolute or relative path(s) to one or more FRESH or + JSON Resume documents (*.json), separated by spaces: + + hackmyresume NEW r1.json r2.json r3.json + +Options: + + **--format -f ** + + The desired format for the new resume(s). Valid values + are 'FRESH', 'JRS', or, to target the latest edge + version of the JSON Resume Schema, 'JRS@1'. + +The NEW command generates one or more new resumes in FRESH +or JSON Resume format. This document can serve as a source +of truth for resume and career data and an input to tools +like HackMyResume or resume-cli. diff --git a/dist/cli/help/peek.txt b/dist/cli/help/peek.txt new file mode 100644 index 0000000..576b42e --- /dev/null +++ b/dist/cli/help/peek.txt @@ -0,0 +1,30 @@ +**peek** | View portions of a resume from the command line + +Usage: + + hackmyresume PEEK [] + +Parameters: + + **** + + Absolute or relative path(s) to one or more FRESH or + JSON Resume documents to be validated. Multiple resumes + can be specified, separated by spaces: + + hackmyresume PEEK r1.json r2.json r3.json + + **** + + The part of the resume to peek at. + +Options: + + **--assert -a** + + Tell HackMyResume to return a non-zero process exit + code if a resume fails to validate. + +The PEEK command displays a specific piece or part of the +resume without requiring the resume to be opened in an +editor. diff --git a/dist/cli/help/validate.txt b/dist/cli/help/validate.txt new file mode 100644 index 0000000..08a062e --- /dev/null +++ b/dist/cli/help/validate.txt @@ -0,0 +1,27 @@ +**validate** - Validate a resume for correctness + +Usage: + + hackmyresume VALIDATE [] + hackmyresume VALIDATE [] + +Parameters: + + **** + + Absolute or relative path(s) to one or more FRESH or + JSON Resume documents to be validated. Multiple resumes + can be specified, separated by spaces: + + hackmyresume ANALYZE r1.json r2.json r3.json + +Options: + + **--assert -a** + + Tell HackMyResume to return a non-zero process exit + code if a resume fails to validate. + +The VALIDATE command validates a FRESH or JSON Resume +document against its governing schema, verifying that the +resume is correctly structured. diff --git a/dist/cli/main.js b/dist/cli/main.js index ca0636d..b730320 100644 --- a/dist/cli/main.js +++ b/dist/cli/main.js @@ -92,6 +92,16 @@ Definition of the `main` function. x = splitSrcDest.call(this); execute.call(this, x.src, x.dst, this.opts(), logMsg); }); + program.command('help')["arguments"]('[command]').description('Get help on a HackMyResume command').action(function(command) { + var cmd, manPage; + cmd = command && command.trim(); + if (cmd) { + manPage = FS.readFileSync(PATH.join(__dirname, 'help/' + cmd + '.txt'), 'utf8'); + } else { + manPage = FS.readFileSync(PATH.join(__dirname, 'use.txt'), 'utf8'); + } + console.log(M2C(manPage, 'white', 'yellow.bold')); + }); program.parse(args); if (!program.args.length) { throw { @@ -135,7 +145,7 @@ Definition of the `main` function. _out.log(''); } _err.init(o.debug, o.assert, o.silent); - if (o.verb && !HMR.verbs[o.verb] && !HMR.alias[o.verb]) { + if (o.verb && !HMR.verbs[o.verb] && !HMR.alias[o.verb] && o.verb !== 'help') { _err.err({ fluenterror: HMSTATUS.invalidCommand, quit: true, @@ -143,14 +153,16 @@ Definition of the `main` function. }, true); } Command.prototype.missingArgument = function(name) { - _err.err({ - fluenterror: this.name() !== 'new' ? HMSTATUS.resumeNotFound : HMSTATUS.createNameMissing - }, true); + if (this.name() !== 'help') { + _err.err({ + fluenterror: this.name() !== 'new' ? HMSTATUS.resumeNotFound : HMSTATUS.createNameMissing + }, true); + } }; Command.prototype.helpInformation = function() { var manPage; manPage = FS.readFileSync(PATH.join(__dirname, 'use.txt'), 'utf8'); - return chalk.green.bold(manPage); + return M2C(manPage, 'white', 'yellow'); }; return { args: o.args, diff --git a/dist/cli/use.txt b/dist/cli/use.txt index fd73d38..760cf9d 100644 --- a/dist/cli/use.txt +++ b/dist/cli/use.txt @@ -1,32 +1,28 @@ +**HackMyResume** | A Swiss Army knife for resumes and CVs. + Usage: - hackmyresume [TO ] [] + hackmyresume [] -Available commands: +Available commands (type "hackmyresume help COMMAND" for details): - BUILD Build your resume to the destination format(s). - ANALYZE Analyze your resume for keywords, gaps, and metrics. - VALIDATE Validate your resume for errors and typos. - CONVERT Convert your resume between FRESH and JSON Resume. - NEW Create a new resume in FRESH or JSON Resume format. - PEEK View a specific field or element on your resume. + **BUILD** Build your resume to the destination format(s). + **ANALYZE** Analyze your resume for keywords, gaps, and metrics. + **VALIDATE** Validate your resume for errors and typos. + **NEW** Create a new resume in FRESH or JSON Resume format. + **CONVERT** Convert your resume between FRESH and JSON Resume. + **PEEK** View a specific field or element on your resume. + **HELP** View help on a specific HackMyResume command. Available options: - --theme -t Path to a FRESH or JSON Resume theme. - --pdf -p Specify the PDF engine to use (wkhtmltopdf or phantom). - --options -o Load options from an external JSON file. - --format -f The format (FRESH or JSON Resume) to use. - --debug -d Emit extended debugging info. - --assert -a Treat resume validation warnings as errors. - --private Include resume fields marked as private - --no-colors Disable terminal colors. - --tips Display theme messages and tips. - --help -h Display help documentation. - --version -v Display the current version. - -Not all options are supported for all commands. For example, the ---theme option is only supported for the BUILD command. + **--options -o** Load options from an external JSON file. + **--debug -d** Emit extended debugging info. + **--assert -a** Treat resume validation warnings as errors. + **--no-colors** Disable terminal colors. + **--tips** Display theme messages and tips. + **--help -h** Display help documentation. + **--version -v** Display the current version. Examples: @@ -47,6 +43,6 @@ Tips: theme, or the path to a local FRESH or JSON Resume theme. - Visit https://www.npmjs.com/search?q=jsonresume-theme for a full listing of all available JSON Resume themes. - - Visit https://github.com/fluentdesk/fresh-themes for a complete + - Visit https://github.com/fresh-standard/fresh-themes for a complete listing of all available FRESH themes. - Report bugs to https://githut.com/hacksalot/HackMyResume/issues. diff --git a/src/cli/help/analyze.txt b/src/cli/help/analyze.txt new file mode 100644 index 0000000..5635f16 --- /dev/null +++ b/src/cli/help/analyze.txt @@ -0,0 +1,23 @@ +**analyze** | Analyze a FRESH resume document for statistics + +Usage: + + hackmyresume ANALYZE [] + hackmyresume ANALYZE [] + +Parameters: + + **** + + Absolute or relative path(s) to one or more FRESH or + JSON Resume documents to be analyzed. Multiple resumes + can be specified, separated by spaces: + + hackmyresume ANALYZE r1.json r2.json r3.json + +Options: + + **None.** + +The ANALYZE command performs simple analysis on a FRESH or +JSON Resume document. diff --git a/src/cli/help/build.txt b/src/cli/help/build.txt new file mode 100644 index 0000000..e572f5c --- /dev/null +++ b/src/cli/help/build.txt @@ -0,0 +1,69 @@ +**build** | Generate resumes in supported output formats + +Usage: + + hackmyresume BUILD TO [] + +Parameters: + + **** + + Absolute or relative path(s) to one or more resumes in + FRESH or JSON format, separated by spaces. If multiple + resumes are specified, they will be merged into a + single resume prior to transformation. + + hackmyresume BUILD resume.json output.all + hackmyresume BUILD base.json developer.json gamedev.json TO out/resume.all + + **** + + Absolute or relative path(s) to one or more outbound + resume(s), separated by spaces. If multiple output + resumes are specified, all of them will be generated. + The desired format of each resume will be determined + from the file extension: + + .all Generate all supported formats + .html HTML 5 + .doc MS Word + .pdf Adobe Acrobat PDF + .txt plain text + .md Markdown + .png PNG Image + .latex LaTeX + + Note: not all formats are supported by all themes. + Check the theme's documentation for details. + +Options: + + **--theme -t ** + + Relative or absolute path to a FRESH or JSON Resume + theme, or the name of a built-in theme. + + As of 1.9.0, the following built-in themes are + provided: basis, modern, positive, compact, awesome. + + **--pdf -p ** + + Specify the PDF engine to use. Legal values are: + + - none: Don't generate a PDF. + - wkhtmltopdf: Use the wkhtmltopdf PDF engine. + - phantom: use the PhantomJS PDF engine. + - weazyprint: use the WeazyPrint PDF engine. + + **--no-escape** + + Disable escaping / encoding of resume data during + resume generation. Handlebars themes only. + + **--private** + + Include resume fields marked as private. + +The BUILD command generates themed resumes and CVs in +multiple formats from a single source of truth in the form +of a FRESH or JSON Resume document. diff --git a/src/cli/help/convert.txt b/src/cli/help/convert.txt new file mode 100644 index 0000000..dd6092b --- /dev/null +++ b/src/cli/help/convert.txt @@ -0,0 +1,34 @@ +**convert** | Convert resumes between FRESH and JRS formats + +Usage: + + hackmyresume CONVERT TO [] + +Parameters: + + **** + + Absolute or relative path(s) to one or more FRESH or + JSON Resume documents (*.json), separated by spaces. + + **** + + The desired absolute or relative path(s) of the newly + converted resume(s). HackMyResume will create the + converted resume(s) here. + +Options: + + **--format -f ** + + The desired format for the new resume(s). Valid values + are 'FRESH', 'JRS', or, to target the latest edge + version of the JSON Resume Schema, 'JRS@1'. + + If this parameter is omitted, the destination format + will be inferred from the source resume's format. If + the source format is FRESH, the destination format + will be JSON Resume, and vice-versa. + +The CONVERT command converts one or more resume documents +between FRESH and JSON Resume formats. diff --git a/src/cli/help/help.txt b/src/cli/help/help.txt new file mode 100644 index 0000000..f259bba --- /dev/null +++ b/src/cli/help/help.txt @@ -0,0 +1,23 @@ +**help** | View help on a specific HackMyResume command + +Usage: + + hackmyresume HELP + +Parameters: + + **** + + The HackMyResume command to view help information for. + Must be BUILD, NEW, CONVERT, ANALYZE, VALIDATE, PEEK, + or HELP. + + hackmyresume help convert + hackmyresume help help + +Options: + + **None.** + +The HELP command displays help information for a specific +HackMyResume command, including the HELP command itself. diff --git a/src/cli/help/new.txt b/src/cli/help/new.txt new file mode 100644 index 0000000..0d7f05e --- /dev/null +++ b/src/cli/help/new.txt @@ -0,0 +1,27 @@ +**new** | Create a new FRESH or JRS resume document + +Usage: + + hackmyresume NEW [] + +Parameters: + + **** + + Absolute or relative path(s) to one or more FRESH or + JSON Resume documents (*.json), separated by spaces: + + hackmyresume NEW r1.json r2.json r3.json + +Options: + + **--format -f ** + + The desired format for the new resume(s). Valid values + are 'FRESH', 'JRS', or, to target the latest edge + version of the JSON Resume Schema, 'JRS@1'. + +The NEW command generates one or more new resumes in FRESH +or JSON Resume format. This document can serve as a source +of truth for resume and career data and an input to tools +like HackMyResume or resume-cli. diff --git a/src/cli/help/peek.txt b/src/cli/help/peek.txt new file mode 100644 index 0000000..576b42e --- /dev/null +++ b/src/cli/help/peek.txt @@ -0,0 +1,30 @@ +**peek** | View portions of a resume from the command line + +Usage: + + hackmyresume PEEK [] + +Parameters: + + **** + + Absolute or relative path(s) to one or more FRESH or + JSON Resume documents to be validated. Multiple resumes + can be specified, separated by spaces: + + hackmyresume PEEK r1.json r2.json r3.json + + **** + + The part of the resume to peek at. + +Options: + + **--assert -a** + + Tell HackMyResume to return a non-zero process exit + code if a resume fails to validate. + +The PEEK command displays a specific piece or part of the +resume without requiring the resume to be opened in an +editor. diff --git a/src/cli/help/validate.txt b/src/cli/help/validate.txt new file mode 100644 index 0000000..08a062e --- /dev/null +++ b/src/cli/help/validate.txt @@ -0,0 +1,27 @@ +**validate** - Validate a resume for correctness + +Usage: + + hackmyresume VALIDATE [] + hackmyresume VALIDATE [] + +Parameters: + + **** + + Absolute or relative path(s) to one or more FRESH or + JSON Resume documents to be validated. Multiple resumes + can be specified, separated by spaces: + + hackmyresume ANALYZE r1.json r2.json r3.json + +Options: + + **--assert -a** + + Tell HackMyResume to return a non-zero process exit + code if a resume fails to validate. + +The VALIDATE command validates a FRESH or JSON Resume +document against its governing schema, verifying that the +resume is correctly structured. diff --git a/src/cli/main.coffee b/src/cli/main.coffee index 79b6f86..156672c 100644 --- a/src/cli/main.coffee +++ b/src/cli/main.coffee @@ -132,6 +132,22 @@ main = module.exports = ( rawArgs, exitCallback ) -> return ) + # Create the HELP command + program + .command('help') + .arguments('[command]') + .description('Get help on a HackMyResume command') + .action ( command ) -> + cmd = command && command.trim() + if cmd + manPage = FS.readFileSync( + PATH.join(__dirname, 'help/' + cmd + '.txt'), 'utf8' ) + else + manPage = FS.readFileSync( + PATH.join(__dirname, 'use.txt'), 'utf8' ) + console.log M2C(manPage, 'white', 'yellow.bold') + return + program.parse( args ) if !program.args.length @@ -171,24 +187,25 @@ initialize = ( ar, exitCallback ) -> _err.init o.debug, o.assert, o.silent # Handle invalid verbs here (a bit easier here than in commander.js)... - if o.verb && !HMR.verbs[ o.verb ] && !HMR.alias[ o.verb ] + if o.verb && !HMR.verbs[ o.verb ] && !HMR.alias[ o.verb ] && o.verb != 'help' _err.err fluenterror: HMSTATUS.invalidCommand, quit: true, attempted: o.orgVerb, true # Override the .missingArgument behavior Command.prototype.missingArgument = (name) -> - _err.err - fluenterror: - if this.name() != 'new' - then HMSTATUS.resumeNotFound - else HMSTATUS.createNameMissing - , true + if this.name() != 'help' + _err.err + fluenterror: + if this.name() != 'new' + then HMSTATUS.resumeNotFound + else HMSTATUS.createNameMissing + , true return # Override the .helpInformation behavior Command.prototype.helpInformation = -> manPage = FS.readFileSync( PATH.join(__dirname, 'use.txt'), 'utf8' ) - return chalk.green.bold(manPage) + return M2C(manPage, 'white', 'yellow') return { args: o.args, diff --git a/src/cli/use.txt b/src/cli/use.txt index fd73d38..760cf9d 100644 --- a/src/cli/use.txt +++ b/src/cli/use.txt @@ -1,32 +1,28 @@ +**HackMyResume** | A Swiss Army knife for resumes and CVs. + Usage: - hackmyresume [TO ] [] + hackmyresume [] -Available commands: +Available commands (type "hackmyresume help COMMAND" for details): - BUILD Build your resume to the destination format(s). - ANALYZE Analyze your resume for keywords, gaps, and metrics. - VALIDATE Validate your resume for errors and typos. - CONVERT Convert your resume between FRESH and JSON Resume. - NEW Create a new resume in FRESH or JSON Resume format. - PEEK View a specific field or element on your resume. + **BUILD** Build your resume to the destination format(s). + **ANALYZE** Analyze your resume for keywords, gaps, and metrics. + **VALIDATE** Validate your resume for errors and typos. + **NEW** Create a new resume in FRESH or JSON Resume format. + **CONVERT** Convert your resume between FRESH and JSON Resume. + **PEEK** View a specific field or element on your resume. + **HELP** View help on a specific HackMyResume command. Available options: - --theme -t Path to a FRESH or JSON Resume theme. - --pdf -p Specify the PDF engine to use (wkhtmltopdf or phantom). - --options -o Load options from an external JSON file. - --format -f The format (FRESH or JSON Resume) to use. - --debug -d Emit extended debugging info. - --assert -a Treat resume validation warnings as errors. - --private Include resume fields marked as private - --no-colors Disable terminal colors. - --tips Display theme messages and tips. - --help -h Display help documentation. - --version -v Display the current version. - -Not all options are supported for all commands. For example, the ---theme option is only supported for the BUILD command. + **--options -o** Load options from an external JSON file. + **--debug -d** Emit extended debugging info. + **--assert -a** Treat resume validation warnings as errors. + **--no-colors** Disable terminal colors. + **--tips** Display theme messages and tips. + **--help -h** Display help documentation. + **--version -v** Display the current version. Examples: @@ -47,6 +43,6 @@ Tips: theme, or the path to a local FRESH or JSON Resume theme. - Visit https://www.npmjs.com/search?q=jsonresume-theme for a full listing of all available JSON Resume themes. - - Visit https://github.com/fluentdesk/fresh-themes for a complete + - Visit https://github.com/fresh-standard/fresh-themes for a complete listing of all available FRESH themes. - Report bugs to https://githut.com/hacksalot/HackMyResume/issues.