Update README image.

Add support for default font specs in FRESH theme.json files. The "all"
format matches any format that doesn't have a specific key in "fonts".

.gitignore

@@ -1,4 +1,40 @@
 node_modules/
 tests/sandbox/
+doc/
 docs/
+local/
 npm-debug.log
+
+# Emacs detritus
+# -*- mode: gitignore; -*-
+*~
+\#*\#
+/.emacs.desktop
+/.emacs.desktop.lock
+*.elc
+auto-save-list
+tramp
+.\#*
+
+# Org-mode
+.org-id-locations
+*_archive
+
+# flymake-mode
+*_flymake.*
+
+# eshell files
+/eshell/history
+/eshell/lastdir
+
+# elpa packages
+/elpa/
+
+# reftex files
+*.rel
+
+# AUCTeX auto folder
+/auto/
+
+# cask packages
+.cask/

CHANGELOG.md

@@ -0,0 +1,306 @@
+CHANGELOG
+=========
+## v1.6.0
+
+### Major Improvements
+
+- Better consistency and coverage for all FRESH resumes and themes ([#45][i45]).
+
+- Initial support for overridable fonts in FRESH themes. Like a particular
+theme, but want to change the typography? The specific fonts used by a theme
+can now be overridden by the user. (FRESH themes only).
+
+- New resume sections! Support for `projects` and `affiliation` resume sections
+for technical and creative projects and memberships / clubs / associations,
+respectively ([#92][i92]).
+
+- New command! `PEEK` at any arbitrary field or entry on your `.json` resume.
+
+### Added
+
+- Improved handling of start and end dates on `employment`, `projects`,
+`education`, and other sections with start/end dates.
+
+- Support for an `.ignore` property on any FRESH or JSON Resume section or field.
+Ignored properties will be treated by HackMyResume as if they weren't present.
+
+- Emit extended status and error info with the `--debug` or `-d` switch.
+
+- The `-o` or `--options` switch can now handle either the path to a **JSON
+settings file** or **raw JSON/JavaScript**. Since the JSON double quote syntax
+is a bit cumbersome from the command line, HackMyResume accepts regular
+JavaScript object literal syntax:
+
+        hackmyresume build resume.json -o "{ theme: 'compact', silent: 'true' }"
+
+- Ability to disable sorting of resume sections (employments, projects, etc.)
+with the `--no-sort` option. HMR will respect the order of items as they appear
+in your resume `.json` file.
+
+- Improvements to the starter resume emitted by `hackmyresume new`.
+
+- Theme Authoring: Annotated the HTML and MS Word (XML) formats of the Modern
+theme for FRESH theme authors.
+
+- Theme Authoring: Support for templatized CSS files in FRESH themes. CSS files
+are now expanded via Handlebars or Underscore prior to copying to the
+destination.
+
+- Added CHANGELOG.md (this file).
+
+### Changed
+
+- Rewrote the HackMyResume man/help page.
+
+- Minor incremental updates to the [FRESCA][fresca] schema.
+
+- PDF generation now uses asynchronous `spawn()` which has better compatibility
+with old or boutique versions of Node.js.
+
+- Refactored colors in HackMyResume output. Errors will now display as red,
+warnings as yellow, successful operations as green, and informational messages
+as cyan.
+
+- Theme messages and usage tips will no longer display during resume generation
+by default. Use the `--tips` option to view them.
+
+- The `--no-tips` option (default: false) has been replaced with the `--tips`
+option, also defaulting to false.
+
+- Removed the `hello-world` theme from the [prebuilt themes][themes] that ship
+with HackMyResume. It can be installed separately from NPM:
+
+  ```bash
+  npm install fresh-theme-hello-world
+  hackmyresume resume.json -t node_modules/fresh-theme-hello-world
+  ```
+
+- sd
+
+### Fixed
+
+- PDF generation issues on older versions of Node.
+
+- Stack traces not being emitted correctly.
+
+- Missing `speaking` section will now appear on generated resumes ([#101][i101]).
+
+- Incomplete `education` details will now appear on generated resumes ([#65][i65]).
+
+- Missing employment end date being interpreted as "employment ends today"
+([#84][i84]).
+
+- Merging multiple source resumes during `BUILD` sometimes fails.
+
+- Document `--pdf` flag in README ([#111][i111]).
+
+### Internal
+
+- Logging messages have been moved out of core HackMyResume code ahead of
+localization support.
+
+- All HackMyResume console output is described in `msg.yml`.
+
+- Relaxed pure JavaScript requirement. CoffeeScript will now start appearing
+in HackMyResume and FluentCV sources!
+
+- Additional tests.
+
+## v1.5.2
+
+### Fixed
+
+- Tweak stack trace under `--debug`.
+
+## v1.5.1
+
+### Added
+
+- Preliminary support for `-d` or `--debug` flag. Forces HackMyResume to emit a stack trace under error conditions.
+
+## v1.5.0
+
+### Added
+
+- HackMyResume now supports **CLI-based generation of PDF formats across multiple engines (Phantom, wkhtmltopdf, etc)**. Instead of talking to these engines over a programmatic API, as in prior versions, HackMyResume 1.5+ speaks to them over the same command-line interface (CLI) you'd use if you were using these tools directly.
+
+- HackMyResume will now (attempt to) **generate a PDF output for JSON Resume themes** (in addition to HTML).
+
+- Minor README and FAQ additions.
+
+### Changed
+
+- **Cleaner, quicker installs**. Installing HackMyResume with `npm install hackmyresume -g` will no longer trigger a lengthy, potentially error-prone install for Phantom.js and/or wkhtmltopdf for PDF support. Instead, users can install these engines externally and HMR will use them when present.
+
+- Minor error handling improvements.
+
+### Fixed
+
+- Fixed an error with generating specific formats with the `BUILD` command (#97).
+
+- Fixed numerous latent/undocumented bugs and glitches.
+
+## v1.4.2
+
+### Added
+
+- Introduced [FAQ](https://github.com/hacksalot/HackMyResume/blob/master/FAQ.md).
+- Additional README notes.
+
+## v1.4.1
+
+### Added
+
+- `hackmyresume new` now generates a [valid starter resume with sample data](https://github.com/fluentdesk/fresh-resume-starter).
+
+### Fixed
+
+- Fixed warning message when `hackmyresume new` is run without a filename.
+
+## v1.4.0
+
+### Added
+
+- **"Projects" support**: FRESH resumes and themes can now store and display
+open source, commercial, private, personal, and creative projects.
+- **New command: ANALYZE**. Inspect your resume for gaps, keyword counts, and other metrics. (Experimental.)
+- **Side-by-side PDF generation** with Phantom and wkhtmltopdf. Use the `--pdf` or `-p` flag to pick between `phantom` and `wkhtmltopdf` generation.
+- **Disable PDF generation** with the `--pdf none` switch.
+- **Inherit formats between themes**. Themes can now inherit formats (Word, HTML, .txt, etc.) from other themes. (FRESH themes only.)
+- **Rename resume sections** to different languages or wordings.
+- **Specify complex options via external file**. Use with the `-o` or `--opts` option.
+- **Disable colors** with the `--no-color` flag.
+- **Theme messages and usage tips** instructions will now appear in the default HackMyResume output for the `build` command. Run `hackmyresume build resume.json -t awesome` for an example. Turn off with the `--no-tips` flag.
+- **Treat validation errors as warnings** with the `--assert` switch (VALIDATE command only).
+
+### Fixed
+
+- Fixed a minor glitch in the FRESCA schema.
+- Fixed encoding issues in the `Highlights` section of certain resumes.
+- Fix behavior of `-s` and `--silent` flags.
+
+### Changed
+
+- PDF generation now defaults to Phantom for all platforms, with `wkhtmltopdf`
+accessible with `--pdf wkhtmltopdf`.
+- Resumes are now validated, by default, prior to generation. This
+behavior can be disabled with the `--novalidate` or `--force` switch.
+- Syntax errors in source FRESH and JSON Resumes are now captured for all
+commands.
+- Minor updates to README.
+- Most themes now inherit Markdown and Plain Text formats from the **Basis**
+theme.
+
+### Internal
+
+- Switched from color to chalk.
+- Command invocations now handled through commander.js.
+- Improved FRESH theme infrastructure (more partials, more DRY).
+
+## v1.3.1
+
+### Added
+
+- Add additional Travis badges.
+
+### Fixed
+
+- Fix extraneous console log output when generating a FRESH theme to MS Word.
+- Fix Travis tests on `dev`.
+
+## v1.3.0
+
+### Added
+
+- **Local generation of JSON Resume themes**. To use a JSON Resume theme, first install it with `npm install jsonresume-theme-[blah]` (most JSON Resume themes are on NPM). Then pass it into HackMyResume via the `-t` parameter:
+
+    `hackmyresume BUILD resume.json TO out/somefile.all -t node_modules/jsonresume-theme-classy`
+- **Better Markdown support.** HackMyResume will start flowing basic Markdown styles to JSON Resume (HTML) themes. FRESH's existing Markdown support has also been improved.
+- **.PNG output formats** will start appearing in themes that declare an HTML output.
+- **Tweak CSS embedding / linking via the --css option** (`<style></style>` vs `<link>`). Only works for HTML (or HTML-driven) formats of FRESH themes. Use `--css=link` to link in CSS assets and `--css=embed` to embed the styles in the HTML document. For example `hackmyresume BUILD resume.json TO out/resume.all --css=link`.
+- **Improved Handlebars/Underscore helper support** for FRESH themes. Handlebars themes can access helpers via `{{helperName}}`. Underscore themes can access helpers via the `h` object.
+
+### Changed
+
+- **Distinguish between validation errors and syntax errors** when validating a FRESH or JRS resume with `hackmyresume validate <blah>`.
+- **Emit line and column info** for syntax errors during validation of FRESH and JRS resumes.
+- **FRESH themes now embed CSS into HTML formats by default** so that the HTML resume output doesn't have an external CSS file dependency by default. Users can specify normal linked stylesheets by setting `--css=link`.
+- **Renamed fluent-themes repo to fresh-themes** in keeping with the other parts of the project.
+
+### Fixed
+
+- Fix various encoding errors in MS Word outputs.
+- Fix assorted FRESH-to-JRS and JRS-to-FRESH conversion glitches.
+- Fix error when running HMR with no parameters.
+- Other minor fixes.
+
+## v1.3.0-beta
+
+- Numerous changes supporting v1.3.0.
+
+## v1.2.2
+
+### Fixed
+
+- Various in-passing fixes.
+
+## v1.2.1
+
+### Fixed
+
+- Fix `require('FRESCA')` error.
+- Fix `.history` and `.map` errors on loading incomplete or empty JRS resumes.
+
+### Added
+
+- Better test coverage of incomplete/empty resumes.
+
+## v1.2.0
+
+### Fixed
+
+- Fixed the `new` command: Generate a new FRESH-format resume with `hackmyresume new resume.json` or a new JSON Resume with `hackmyresume new resume.json -f jrs`.
+
+### Added
+
+- Introduced CLI tests.
+
+## v1.1.0
+
+### Fixed
+
+- MS Word formats: Fixed skill coloring/level bug.
+
+### Changed
+
+- Make the `TO` keyword optional. If no `TO` keyword is specified (for the `build` and `convert` commands), HMR will assume the last file passed in is the desired output file. So these are equivalent:
+
+    ```shell
+    hackmyresume BUILD resume.json TO out/resume.all
+    hackmyresume BUILD resume.json out/resume.all
+    ```
+
+    `TO` only needs to be included if you have multipled output files:
+
+    ```shell
+     hackmyresume BUILD resume.json TO out1.doc out2.html out3.tex
+    ```
+
+## v1.0.1
+
+### Fixed
+
+- Correctly generate MS Word hyperlinks from Markdown source data.
+
+## v1.0.0
+
+- Initial public 1.0 release.
+
+[i45]: https://github.com/hacksalot/HackMyResume/issues/45
+[i65]: https://github.com/hacksalot/HackMyResume/issues/65
+[i84]: https://github.com/hacksalot/HackMyResume/issues/84
+[i92]: https://github.com/hacksalot/HackMyResume/issues/92
+[i101]: https://github.com/hacksalot/HackMyResume/issues/101
+[i111]: https://github.com/hacksalot/HackMyResume/issues/111
+[fresca]: https://github.com/fluentdesk/FRESCA
+[themes]: https://github.com/fluentdesk/fresh-themes

FAQ.md

@@ -9,19 +9,29 @@ Frequently Asked Questions (FAQ)
 
 3. Test with `hackmyresume BUILD <resume-name>.json`. Look in the `out/` folder.
 
-4. Play around with different themes with the `-t` or `--theme` parameter. You can use any [FRESH](https://github.com/fluentdesk/fresh-themes) or [JSON Resume](https://jsonresume.org/themes) theme. The latter have to be installed first.
+4. Play around with different themes with the `-t` or `--theme` parameter.
+You can use any [FRESH](https://github.com/fluentdesk/fresh-themes) or
+[JSON Resume](https://jsonresume.org/themes) theme. The latter have to be
+installed first.
 
 ## What is FRESH?
 
-FRESH is the **F**luent **R**esume and **E**mployment **S**ystem for **H**umans. It's an open-source, user-first workflow, schema, and set of practices for technical candidates and recruiters.
+FRESH is the **F**luent **R**esume and **E**mployment **S**ystem for **H**umans.
+It's an open-source, user-first workflow, schema, and set of practices for
+technical candidates and recruiters.
 
 ## What is FRESCA?
 
-The **F**RESH **R**esume and **E**mployment **SC**hem**A**&mdash;an open-source, JSON-driven schema for resumes, CVs, and other employment artifacts. FRESCA is the recommended schema/format for FRESH, with optional support for JSON Resume.
+The **F**RESH **R**esume and **E**mployment **SC**hem**A**&mdash;an open-source,
+JSON-driven schema for resumes, CVs, and other employment artifacts. FRESCA is
+the recommended schema/format for FRESH, with optional support for JSON Resume.
 
 ## What is JSON Resume?
 
-An [open resume standard](http://jsonresume.org/themes/) sponsored by Hired.com. Like FRESCA, JSON Resume is JSON-driven and open-source. Unlike FRESCA, JSON Resume targets a worldwide audience where FRESCA is optimized for technical candidates.
+An [open resume standard](http://jsonresume.org/themes/) sponsored by Hired.com.
+Like FRESCA, JSON Resume is JSON-driven and open-source. Unlike FRESCA, JSON
+Resume targets a worldwide audience where FRESCA is optimized for technical
+candidates.
 
 ## Should I use the FRESH or JSON Resume format/schema for my resume?
 
@@ -31,24 +41,45 @@ Both! The workflow we like to use:
 2. Convert it to JSON Resume format for additional themes/tools.
 3. Maintain both versions.
 
-Both formats are open-source and both formats are JSON-driven. FRESH was designed as a universal container format and superset of existing formats, where the JSON Resume format is intended for a generic audience.
+Both formats are open-source and both formats are JSON-driven. FRESH was
+designed as a universal container format and superset of existing formats, where
+the JSON Resume format is intended for a generic audience.
 
 ## How do I use a FRESH theme?
 
-FRESH themes currently come preinstalled with HackMyResume.
+Several FRESH themes come preinstalled with HackMyResume; others can be
+installed from NPM and GitHub.
 
-1. Specify the theme name in the `--theme` or `-t` parameter to the **build** command:
+### To use a preinstalled FRESH theme:
+
+1. Pass the theme name into HackMyResume via the `--theme` or `-t` parameter:
 
     ```bash
-    hackmyresume BUILD my-resume.json --theme <theme-name>
+    hackmyresume build resume.json --theme compact
     ```
 
-    `<theme-name>` can be one of `positive`, `compact`, `modern`, `minimist`, `hello-world`, or `awesome`.
+### To use an external FRESH theme:
 
-2. Check your output folder. Although under FRESH, HTML formats are hardened to a degree for local file access, it's best to view HTML formats over a local web server connection.
+1. Install the theme locally. The easiest way to do that is with NPM.
+
+    ```bash
+    npm install fresh-theme-underscore
+    ```
+
+2. Pass the theme folder into HackMyResume:
+
+    ```bash
+    hackmyresume BUILD resume.json --theme node_modules/fresh-theme-underscore
+    ```
+
+3. Check your output folder. It's best to view HTML formats over a local web
+server connection.
 
 ## How do I use a JSON Resume theme?
 
+JSON Resume (JRS) themes can be installed from NPM and GitHub and passed into
+HackMyResume via the `--theme` or `-t` parameter.
+
 1. Install the theme locally. The easiest way to do that is with NPM.
 
     ```bash
@@ -61,15 +92,19 @@ FRESH themes currently come preinstalled with HackMyResume.
     hackmyresume BUILD resume.json --theme node_modules/jsonresume-theme-classy
     ```
 
-3. Check your output folder. It's best to view HTML formats over a local web server connection.
+3. Check your output folder. It's best to view HTML formats over a local web
+server connection.
 
 ## Should I keep my resume in version control?
 
-Absolutely! As text-based, JSON-driven documents, both FRESH and JSON Resume are ideal candidates for version control. Future versions of HackMyResume will have this functionality built-in.
+Absolutely! As text-based, JSON-driven documents, both FRESH and JSON Resume are
+ideal candidates for version control. Future versions of HackMyResume will have
+this functionality built in.
 
 ## Can I change the default section titles ("Employment", "Skills", etc.)?
 
-If you're using a FRESH theme, yes. First, create a HackMyResume options file mapping resume sections to your preferred section title:
+If you're using a FRESH theme, yes. First, create a HackMyResume options file
+mapping resume sections to your preferred section title:
 
 ```javascript
 // myoptions.json
@@ -90,6 +125,57 @@ hackmyresume BUILD resume.json -o myoptions.json
 
 This ability is currently only supported for FRESH resume themes.
 
+## How does resume merging work?
+
+Resume merging is a way of storing your resume in separate files that
+HackMyResume will merge into a single "master" resume file prior to generating
+specific output formats like HTML or PDF. It's a way of producing flexible,
+configurable, targeted resumes with minimal duplication.
+
+For example, a software developer who moonlights as a game programmer might
+create three FRESH or JRS resumes at different levels of specificity:
+
+- **generic.json**: A generic technical resume, suitable for all audiences.
+- **game-developer.json**: Overrides and amendments for game developer
+positions.
+- **blizzard.json**: Overrides and amendments specific to a hypothetical
+position at Blizzard.
+
+If you run `hackmyresume BUILD generic.json TO out/resume.all`, HMR will
+generate all available output formats for the `generic.json` as usual. But if
+you instead run...
+
+```bash
+hackmyresume BUILD generic.json game-developer.json TO out/resume.all
+```
+
+...HackMyResume will notice that multiple source resumes were specified and
+merge `game-developer.json` onto `generic.json` before generating, yielding a
+resume that's more suitable for game-developer-related positions.
+
+You can take this a step further. Let's say you want to do a targeted resume
+submission to a game developer position at Blizzard, and `blizzard.json`
+contains the edits and revisions you'd like to show up in the targeted resume.
+In that case, merge again! Feed all three resumes to HackMyResume, in order
+from most generic to most specific, and HMR will merge them all prior to
+generating the final output format(s) for your resume.
+
+```bash
+# Merge blizzard.json onto game-developer.json onto generic.json, then build
+hackmyresume BUILD generic.json game-developer.json blizzard.json TO out/resume.all
+```
+
+There's no limit to the number of resumes you can merge this way.
+
+You can also divide your resume into files containing different sections:
+
+- **resume-a.json**: Contains `info`, `employment`, and `summary` sections.
+- **resume-b.json**: Contains all other sections except `references`.
+- **references.json**: Contains the private `references` section.
+
+Under that scenario, `hackmyresume BUILD resume-a.json resume-b.json` would
+
+
 ## The HackMyResume terminal color scheme is giving me a headache. Can I disable it?
 
 Yes. Use the `--no-color` option to disable terminal colors:

Gruntfile.js

@@ -17,6 +17,16 @@ module.exports = function (grunt) {
       all: { src: ['test/*.js'] }
     },
 
+    jsdoc : {
+      dist : {
+        src: ['src/**/*.js'],
+        options: {
+          private: true,
+          destination: 'doc'
+        }
+      }
+    },
+
     clean: ['test/sandbox'],
 
     yuidoc: {
@@ -47,13 +57,14 @@ module.exports = function (grunt) {
 
   grunt.loadNpmTasks('grunt-simple-mocha');
   grunt.loadNpmTasks('grunt-contrib-yuidoc');
+  grunt.loadNpmTasks('grunt-jsdoc');
   grunt.loadNpmTasks('grunt-contrib-jshint');
   grunt.loadNpmTasks('grunt-contrib-clean');
 
   grunt.registerTask('test', 'Test the HackMyResume library.',
-    function( config ) { grunt.task.run( ['clean','jshint','simplemocha:all'] ); });
+    function( config ) { grunt.task.run(['clean','jshint','simplemocha:all']); });
   grunt.registerTask('document', 'Generate HackMyResume library documentation.',
-    function( config ) { grunt.task.run( ['yuidoc'] ); });
-  grunt.registerTask('default', [ 'test', 'yuidoc' ]);
+    function( config ) { grunt.task.run( ['jsdoc'] ); });
+  grunt.registerTask('default', [ 'test', 'jsdoc' ]);
 
 };

LICENSE.md

@@ -1,7 +1,7 @@
 The MIT License
 ===============
 
-Copyright (c) 2015 James M. Devlin (https://github.com/hacksalot)
+Copyright (c) 2016 hacksalot (https://github.com/hacksalot)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -10,7 +10,7 @@ shell. Author in clean Markdown and JSON, export to Word, HTML, PDF, LaTeX,
 plain text, and other arbitrary formats. Fight the power, save trees. Compatible
 with [FRESH][fresca] and [JRS][6] resumes.*
 
-![](assets/resume-bouqet.png)
+![](assets/hackmyresume.cli.1.6.0.png)
 
 HackMyResume is a dev-friendly, local-only Swiss Army knife for resumes and CVs.
 Use it to:
@@ -107,7 +107,7 @@ Use it when you need to submit, upload, print, or email resumes in specific
 formats.
 
     ```bash
-    # hackmyresume BUILD <INPUTS> TO <OUTPUTS> [-t THEME]
+    # hackmyresume BUILD <INPUTS...> TO <OUTPUTS...> [-t THEME]
     hackmyresume BUILD resume.json TO out/resume.all
     hackmyresume BUILD r1.json r2.json TO out/rez.html out/rez.md foo/rez.all
     ```
@@ -115,7 +115,7 @@ formats.
 - **new** creates a new resume in FRESH or JSON Resume format.
 
     ```bash
-    # hackmyresume NEW <OUTPUTS> [-f <FORMAT>]
+    # hackmyresume NEW <OUTPUTS...> [-f <FORMAT>]
     hackmyresume NEW resume.json
     hackmyresume NEW resume.json -f fresh
     hackmyresume NEW r1.json r2.json -f jrs
@@ -123,12 +123,18 @@ formats.
 
 - **analyze** inspects your resume for keywords, duration, and other metrics.
 
+    ```bash
+    # hackmyresume ANALYZE <INPUTS...>
+    hackmyresume ANALYZE resume.json
+    hackmyresume ANALYZE r1.json r2.json
+    ```
+
 - **convert** converts your source resume between FRESH and JSON Resume
 formats. Use it to convert between the two formats to take advantage of tools
 and services.
 
     ```bash
-    # hackmyresume CONVERT <INPUTS> TO <OUTPUTS>
+    # hackmyresume CONVERT <INPUTS...> TO <OUTPUTS...>
     hackmyresume CONVERT resume.json TO resume-jrs.json
     hackmyresume CONVERT 1.json 2.json 3.json TO out/1.json out/2.json out/3.json
     ```
@@ -137,11 +143,22 @@ and services.
 Resume schema. Use it to make sure your resume data is sufficient and complete.
 
     ```bash
-    # hackmyresume VALIDATE <INPUTS>
+    # hackmyresume VALIDATE <INPUTS...>
     hackmyresume VALIDATE resume.json
     hackmyresume VALIDATE r1.json r2.json r3.json
     ```
 
+- **peek** echoes your resume or any field, property, or object path on your
+resume to standard output.
+
+    ```bash
+    # hackmyresume PEEK <INPUTS...> [OBJECT-PATH]
+    hackmyresume PEEK rez.json # Echo the whole resume
+    hackmyresume PEEK rez.json info.brief # Echo the "info.brief" field
+    hackmyresume PEEK rez.json employment.history[1] # Echo the 1st job
+    hackmyresume PEEK rez.json rez2.json info.brief # Compare value
+    ```    
+
 ## Supported Output Formats
 
 HackMyResume supports these output formats:
@@ -163,7 +180,7 @@ image | .png, .bmp | Forthcoming.
 ## Use
 
 Assuming you've got a JSON-formatted resume handy, generating resumes in
-different formats and combinations easy. Just run:
+different formats and combinations is easy. Just run:
 
 ```bash
 hackmyresume BUILD <INPUTS> <OUTPUTS> [-t theme].
@@ -209,24 +226,36 @@ Generating YAML resume: out/resume.yml
 
 ### Applying a theme
 
-HackMyResume can work with any FRESH or JSON Resume theme. To specify a theme
-when generating your resume, use the `-t` or `--theme` parameter:
+HackMyResume can work with any FRESH or JSON Resume theme (the latter must be
+installed first). To specify a theme when generating your resume, use the `-t`
+or `--theme` parameter:
 
 ```bash
 hackmyresume BUILD resume.json TO out/rez.all -t [theme]
 ```
 
-The `[theme]` parameter can be the name of a predefined theme or the path to any
+The `[theme]` parameter can be the name of a predefined theme OR the path to any
 FRESH or JSON Resume theme folder:
 
 ```bash
 hackmyresume BUILD resume.json TO out/rez.all -t modern
 hackmyresume BUILD resume.json TO OUT.rez.all -t ../some-folder/my-custom-theme/
-hackmyresume BUILD resume.json TO OUT.rez.all -t npm_modules/jsonresume-theme-classy
+hackmyresume BUILD resume.json TO OUT.rez.all -t node_modules/jsonresume-theme-classy
 ```
 
-As of v1.4.0, available predefined themes are `positive`, `modern`, `compact`,
-`minimist`, and `hello-world`.
+FRESH themes are currently pre-installed with HackMyResume. JSON Resume themes
+can be installed prior to use:
+
+```bash
+# Install a JSON Resume theme into a local node_modules subfolder:
+npm install jsonresume-theme-[name]
+# Use it with HackMyResume
+hackmyresume build resume.json -t node_modules/jsonresume-theme-[name]
+```
+
+As of v1.6.0, available predefined FRESH themes are `positive`, `modern`,
+`compact`, `minimist`, and `hello-world`. For a list of JSON Resume themes,
+check the [NPM Registry](https://www.npmjs.com/search?q=jsonresume-theme).
 
 ### Merging resumes
 
@@ -279,6 +308,39 @@ hackmyresume BUILD me.json TO out/resume.all
 `out/resume.doc`, `out/resume.html`, `out/resume.txt`, `out/resume.pdf`, and
 `out/resume.json`.
 
+### Building PDFs
+
+*Users who don't care about PDFs can turn off PDF generation across all themes
+and formats with the `--pdf none` switch.*
+
+HackMyResume takes a unique approach to PDF generation. Instead of enforcing
+a specific PDF engine on users, HackMyResume will attempt to work with whatever
+PDF engine you have installed through the engine's command-line interface (CLI).
+Currently that means one or both of...
+
+- [wkhtmltopdf][3]
+- [Phantom.js][3]
+
+..with support for other engines planned in the future. But for now, **one or
+both of these engines must be installed and accessible on your PATH in order to
+generate PDF resumes with HackMyResume**. That means you should be able to
+invoke either of these tools directly from your shell or terminal without error:
+
+```bash
+wkhtmltopdf input.html output.pdf
+phantomjs script.js input.html output.pdf
+```
+
+Assuming you've installed one or both of these engines on your system, you can
+tell HackMyResume which flavor of PDF generation to use via the `--pdf` option
+(`-p` for short):
+
+```bash
+hackmyresume BUILD resume.json TO out.all --pdf phantom
+hackmyresume BUILD resume.json TO out.all --pdf wkhtmltopdf
+hackmyresume BUILD resume.json TO out.all --pdf none
+```
+
 ### Analyzing
 
 HackMyResume can analyze your resume for keywords, employment gaps, and other
@@ -292,7 +354,7 @@ Depending on the HackMyResume version, you should see output similar to:
 
 
 ```
-*** HackMyResume v1.4.1 ***
+*** HackMyResume v1.6.0 ***
 Reading resume: resume.json
 Analyzing FRESH resume: resume.json
 
@@ -388,7 +450,7 @@ hackmyresume VALIDATE resumeA.json resumeB.json
 HackMyResume will validate each specified resume in turn:
 
 ```bash
-*** HackMyResume v0.9.0 ***
+*** HackMyResume v1.6.0 ***
 Validating JSON resume: resumeA.json (INVALID)
 Validating JSON resume: resumeB.json (VALID)
 ```
@@ -407,10 +469,17 @@ where <INPUTS> is one or more resumes in FRESH or JSON Resume format, and
 autodetect the format (FRESH or JRS) of each input resume and convert it to the
 other format (JRS or FRESH).
 
-### External options
+### File-based Options
 
-Starting in v1.4.x you can pass options into HackMyResume via an external
-options or ".hackmyrc" file.
+You can pass options into HackMyResume via an external options or ".hackmyrc"
+file with the `--options` or `-o` switch:
+
+```bash
+hackmyresume BUILD resume.json -o path/to/options.json
+```
+
+The options file can contain any documented HackMyResume option, including
+`theme`, `silent`, `debug`, `pdf`, `css`, and other settings.
 
 ```javascript
 {
@@ -423,6 +492,18 @@ options or ".hackmyrc" file.
 }
 ```
 
+If a particular option is specified both on the command line and in an external
+options file, the explicit command-line option takes precedence.
+
+```bash
+# path/to/options.json specifes the POSITIVE theme
+# -t parameter specifies the COMPACT theme
+# The -t parameter wins.
+hackmyresume BUILD resume.json -o path/to/options.json -t compact
+> Reading resume: resume.json
+> Applying COMPACT theme (7 formats)
+```
+
 ### Prettifying
 
 HackMyResume applies [js-beautify][10]-style HTML prettification by default to

package.json

@@ -1,6 +1,6 @@
 {
   "name": "hackmyresume",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Generate polished résumés and CVs in HTML, Markdown, LaTeX, MS Word, PDF, plain text, JSON, XML, YAML, smoke signal, and carrier pigeon.",
   "repository": {
     "type": "git",
@@ -30,6 +30,7 @@
   ],
   "author": "hacksalot <hacksalot@indevious.com> (https://github.com/hacksalot)",
   "contributors": [
+    "aruberto (https://github.com/aruberto)",
     "jjanusch (https://github.com/driftdev)",
     "robertmain (https://github.com/robertmain)",
     "tomheon (https://github.com/tomheon)",
@@ -50,9 +51,11 @@
     "chalk": "^1.1.1",
     "commander": "^2.9.0",
     "copy": "^0.1.3",
-    "fresca": "~0.3.0",
-    "fresh-resume-starter": "^0.1.1",
-    "fresh-themes": "~0.12.0-beta",
+    "extend": "^3.0.0",
+    "fresca": "~0.6.0",
+    "fresh-jrs-converter": "^0.2.0",
+    "fresh-resume-starter": "^0.2.2",
+    "fresh-themes": "~0.13.0-beta",
     "fs-extra": "^0.24.0",
     "handlebars": "^4.0.5",
     "html": "0.0.10",
@@ -65,11 +68,14 @@
     "moment": "^2.10.6",
     "parse-filepath": "^0.6.3",
     "path-exists": "^2.1.0",
+    "printf": "^0.2.3",
     "recursive-readdir-sync": "^1.0.6",
     "simple-html-tokenizer": "^0.2.0",
     "slash": "^1.0.0",
     "string-padding": "^1.0.2",
+    "string.prototype.endswith": "^0.2.0",
     "string.prototype.startswith": "^0.2.0",
+    "traverse": "^0.6.6",
     "underscore": "^1.8.3",
     "webshot": "^0.16.0",
     "word-wrap": "^1.1.0",
@@ -78,12 +84,13 @@
   },
   "devDependencies": {
     "chai": "*",
-    "fresh-test-resumes": "^0.2.1",
+    "fresh-test-resumes": "^0.6.0",
     "grunt": "*",
     "grunt-cli": "^0.1.13",
     "grunt-contrib-clean": "^0.7.0",
     "grunt-contrib-jshint": "^0.11.3",
     "grunt-contrib-yuidoc": "^0.10.0",
+    "grunt-jsdoc": "^1.1.0",
     "grunt-simple-mocha": "*",
     "jsonresume-theme-boilerplate": "^0.1.2",
     "jsonresume-theme-classy": "^1.0.9",

src/cli/analyze.hbs

@@ -0,0 +1,30 @@
+
+{{style "SECTIONS (" "bold"}}{{style totals.numSections "white" }}{{style ")" "bold"}}
+
+        employment:     {{v totals.totals.employment "-" 2 "bold" }}
+          projects:     {{v totals.totals.projects "-" 2 "bold" }}
+         education:     {{v totals.totals.education "-" 2 "bold" }}
+           service:     {{v totals.totals.service "-" 2 "bold" }}
+            skills:     {{v totals.totals.skills "-" 2 "bold" }}
+           writing:     {{v totals.totals.writing "-" 2 "bold" }}
+          speaking:     {{v totals.totals.speaking "-" 2 "bold" }}
+           reading:     {{v totals.totals.reading "-" 2 "bold" }}
+            social:     {{v totals.totals.social "-" 2 "bold" }}
+        references:     {{v totals.totals.references "-" 2 "bold" }}
+      testimonials:     {{v totals.totals.testimonials "-" 2 "bold" }}
+         languages:     {{v totals.totals.languages "-" 2 "bold" }}
+         interests:     {{v totals.totals.interests "-" 2 "bold" }}
+
+{{style "COVERAGE (" "bold"}}{{style coverage.pct "white"}}{{style ")" "bold"}}
+
+        Total Days:  {{v coverage.duration.total "-" 5 "bold" }}
+          Employed:  {{v coverage.duration.work "-" 5 "bold" }}
+              Gaps:  {{v coverage.gaps.length "-" 5 "bold" }}  [{{#if coverage.gaps.length }}{{#each coverage.gaps }}{{#unless @first}} {{/unless}}{{gapLength duration }}{{/each}}{{/if}}]
+          Overlaps:  {{v coverage.overlaps.length "-" 5 "bold" }}  [{{#if coverage.overlaps.length }}{{#each coverage.overlaps }}{{#unless @first}} {{/unless}}{{gapLength duration }}{{/each}}{{/if}}]
+
+{{style "KEYWORDS (" "bold"}}{{style keywords.length "white" }}{{style ")" "bold"}}
+
+{{#each keywords }}{{{pad name 18}}}:  {{v count "-" 5 "bold"}} mention{{#isPlural count}}s{{/isPlural}}
+{{/each}}
+    -------------------------------
+{{v keywords.length "0" 9 "bold"}} {{style "KEYWORDS" "bold"}}   {{v keywords.totalKeywords "0" 5 "bold"}} {{style "mentions" "bold"}}

src/cli/error.js

@@ -0,0 +1,280 @@
+/**
+Error-handling routines for HackMyResume.
+@module cli/error
+@license MIT. See LICENSE.md for details.
+*/
+
+
+
+(function() {
+
+
+
+  var HMSTATUS = require('../core/status-codes')
+    , PKG = require('../../package.json')
+    , FS = require('fs')
+    , FCMD = require('../hackmyapi')
+    , PATH = require('path')
+    , WRAP = require('word-wrap')
+    , M2C = require('../utils/md2chalk.js')
+    , chalk = require('chalk')
+    , extend = require('extend')
+    , YAML = require('yamljs')
+    , printf = require('printf')
+    , SyntaxErrorEx = require('../utils/syntax-error-ex');
+    require('string.prototype.startswith');
+
+
+
+  /**
+  Error handler for HackMyResume. All errors are handled here.
+  @class ErrorHandler
+  */
+  var ErrorHandler = module.exports = {
+
+
+
+    init: function( debug, assert, silent ) {
+      this.debug = debug;
+      this.assert = assert;
+      this.silent = silent;
+      this.msgs = require('./msg.js').errors;
+      return this;
+    },
+
+
+
+    err: function( ex, shouldExit ) {
+
+      // Short-circuit logging output if --silent is on
+      var o = this.silent ? function() { } : _defaultLog;
+
+      // Special case; can probably be removed.
+      if( ex.pass ) throw ex;
+
+      // Load error messages
+      this.msgs = this.msgs || require('./msg.js').errors;
+
+      // Handle packaged HMR exceptions
+      if( ex.fluenterror ) {
+
+        // Output the error message
+        var objError = assembleError.call( this, ex );
+        o( this[ 'format_' + objError.etype ]( objError.msg ));
+
+        // Output the stack (sometimes)
+        if( objError.withStack ) {
+          var stack = ex.stack || (ex.inner && ex.inner.stack);
+          stack && o( chalk.gray( stack ) );
+        }
+
+        // Quit if necessary
+        if( ex.quit || objError.quit ) {
+          this.debug && o(
+            chalk.cyan('Exiting with error code ' + ex.fluenterror.toString()));
+          if( this.assert ) { ex.pass = true; throw ex; }
+          process.exit( ex.fluenterror );
+        }
+
+      }
+
+      // Handle raw exceptions
+      else {
+        o( ex );
+        var stackTrace = ex.stack || (ex.inner && ex.inner.stack);
+        if( stackTrace && this.debug )
+          o( M2C(ex.stack || ex.inner.stack, 'gray') );
+      }
+
+    },
+
+
+
+    format_error: function( msg ) {
+      msg = msg || '';
+      return chalk.red.bold(
+        msg.toUpperCase().startsWith('ERROR:') ? msg : 'Error: ' + msg );
+    },
+
+
+
+    format_warning: function( brief, msg ) {
+      return chalk.yellow(brief) + chalk.yellow(msg || '');
+    },
+
+
+    format_custom: function( msg ) {
+      return msg;
+    }
+
+
+
+  };
+
+
+
+  function _defaultLog() {
+    console.log.apply( console.log, arguments );
+  }
+
+
+
+  function assembleError( ex ) {
+
+    var msg = '', withStack = false, quit = false, etype = 'warning';
+    if( this.debug ) withStack = true;
+
+    switch( ex.fluenterror ) {
+
+      case HMSTATUS.themeNotFound:
+        msg = printf( M2C( this.msgs.themeNotFound.msg, 'yellow' ), ex.data);
+        break;
+
+      case HMSTATUS.copyCSS:
+        msg = M2C( this.msgs.copyCSS.msg, 'red' );
+        quit = false;
+        break;
+
+      case HMSTATUS.resumeNotFound:
+        msg = M2C( this.msgs.resumeNotFound.msg, 'yellow' );
+        break;
+
+      case HMSTATUS.missingCommand:
+        msg = M2C( this.msgs.missingCommand.msg + " (", 'yellow');
+        msg += Object.keys( FCMD.verbs ).map( function(v, idx, ar) {
+          return (idx === ar.length - 1 ? chalk.yellow('or ') : '') +
+            chalk.yellow.bold(v.toUpperCase());
+        }).join( chalk.yellow(', ')) + chalk.yellow(").\n\n");
+
+        msg += chalk.gray(FS.readFileSync(
+          PATH.resolve(__dirname, '../cli/use.txt'), 'utf8' ));
+        break;
+
+      case HMSTATUS.invalidCommand:
+        msg = printf( M2C( this.msgs.invalidCommand.msg, 'yellow'), ex.attempted );
+        break;
+
+      case HMSTATUS.resumeNotFoundAlt:
+        msg = M2C( this.msgs.resumeNotFoundAlt.msg, 'yellow' );
+        break;
+
+      case HMSTATUS.inputOutputParity:
+        msg = M2C( this.msgs.inputOutputParity.msg );
+        break;
+
+      case HMSTATUS.createNameMissing:
+        msg = M2C( this.msgs.createNameMissing.msg );
+        break;
+
+      case HMSTATUS.pdfGeneration:
+        msg = M2C( this.msgs.pdfGeneration.msg, 'bold' );
+        if( ex.inner ) msg += chalk.red('\n' + ex.inner);
+        withStack = true; quit = false; etype = 'error';
+        break;
+
+      case HMSTATUS.invalid:
+        msg = M2C( this.msgs.invalid.msg, 'red' );
+        etype = 'error';
+        break;
+
+      case HMSTATUS.generateError:
+        msg = (ex.inner && ex.inner.toString()) || ex;
+        quit = false;
+        etype = 'error';
+        break;
+
+      case HMSTATUS.fileSaveError:
+        msg = printf( M2C( this.msgs.fileSaveError.msg ), (ex.inner || ex).toString() );
+        etype = 'error';
+        quit = false;
+        break;
+
+      case HMSTATUS.invalidFormat:
+        ex.data.forEach(function(d){
+          msg += printf( M2C( this.msgs.invalidFormat.msg, 'bold' ),
+            ex.theme.name.toUpperCase(), d.format.toUpperCase());
+        }, this);
+        break;
+
+      case HMSTATUS.missingParam:
+        msg = printf( M2C( this.msgs.missingParam.msg ), ex.expected, ex.helper );
+        break;
+
+      case HMSTATUS.invalidHelperUse:
+        msg = printf( M2C( this.msgs.invalidHelperUse.msg ), ex.helper );
+        if( ex.error ) {
+          msg += '\n--> ' + assembleError.call( this, extend( true, {}, ex, {fluenterror: ex.error} )).msg;
+          //msg += printf( '\n--> ' + M2C( this.msgs.invalidParamCount.msg ), ex.expected );
+        }
+        quit = false;
+        etype = 'warning';
+        break;
+
+      case HMSTATUS.notOnPath:
+        msg = printf( M2C(this.msgs.notOnPath.msg, 'bold'), ex.engine);
+        quit = false;
+        etype = 'error';
+        break;
+
+      case HMSTATUS.readError:
+        if( !ex.quiet )
+          console.error(printf( M2C(this.msgs.readError.msg, 'red'), ex.file));
+        msg = ex.inner.toString();
+        etype = 'error';
+        break;
+
+      case HMSTATUS.mixedMerge:
+        msg = M2C( this.msgs.mixedMerge.msg );
+        quit = false;
+        break;
+
+      case HMSTATUS.invokeTemplate:
+        msg = M2C( this.msgs.invokeTemplate.msg, 'red' );
+        msg += M2C( '\n' + WRAP(ex.inner.toString(), { width: 60, indent: '   ' }), 'gray' );
+        etype = 'custom';
+        break;
+
+      case HMSTATUS.compileTemplate:
+        etype = 'error';
+        break;
+
+      case HMSTATUS.themeLoad:
+        msg = M2C( printf( this.msgs.themeLoad.msg, ex.attempted.toUpperCase() ), 'red');
+        if( ex.inner && ex.inner.fluenterror ) {
+          msg += M2C('\nError: ', 'red') + assembleError.call( this, ex.inner ).msg;
+        }
+        quit = true;
+        etype = 'custom';
+        break;
+
+      case HMSTATUS.parseError:
+        if( SyntaxErrorEx.is( ex.inner )) {
+          console.error( printf( M2C(this.msgs.readError.msg, 'red'), ex.file ) );
+          var se = new SyntaxErrorEx( ex, ex.raw );
+          msg = printf( M2C( this.msgs.parseError.msg, 'red' ),
+            se.line, se.col);
+        }
+        else if( ex.inner && ex.inner.line !== undefined && ex.inner.col !== undefined ) {
+          msg = printf( M2C( this.msgs.parseError.msg, 'red' ),
+            ex.inner.line, ex.inner.col);
+        }
+        else {
+          msg = ex;
+        }
+        etype = 'error';
+        break;
+
+    }
+
+    return {
+      msg: msg,              // The error message to display
+      withStack: withStack,  // Whether to include the stack
+      quit: quit,
+      etype: etype
+    };
+  }
+
+
+
+
+}());

src/cli/main.js

@@ -0,0 +1,331 @@
+/**
+Definition of the `main` function.
+@module cli/main
+@license MIT. See LICENSE.md for details.
+*/
+
+
+
+(function(){
+
+
+
+  var HMR  = require( '../hackmyapi')
+    , PKG = require('../../package.json')
+    , FS = require('fs')
+    , EXTEND = require('extend')
+    , chalk = require('chalk')
+    , PATH = require('path')
+    , HMSTATUS = require('../core/status-codes')
+    , HME = require('../core/event-codes')
+    , safeLoadJSON = require('../utils/safe-json-loader')
+    , StringUtils = require('../utils/string.js')
+    , _ = require('underscore')
+    , OUTPUT = require('./out')
+    , PAD = require('string-padding')
+    , Command = require('commander').Command;
+
+  var _opts = { };
+  var _title = chalk.white.bold('\n*** HackMyResume v' +PKG.version+ ' ***');
+  var _out = new OUTPUT( _opts );
+
+
+
+  /**
+  A callable implementation of the HackMyResume CLI. Encapsulates the command
+  line interface as a single method accepting a parameter array.
+  @alias module:cli/main.main
+  @param rawArgs {Array} An array of command-line parameters. Will either be
+  process.argv (in production) or custom parameters (in test).
+  */
+  var main = module.exports = function( rawArgs ) {
+
+    var initInfo = initialize( rawArgs );
+    var args = initInfo.args;
+
+    // Create the top-level (application) command...
+    var program = new Command('hackmyresume')
+      .version(PKG.version)
+      .description(chalk.yellow.bold('*** HackMyResume ***'))
+      .option('-s --silent', 'Run in silent mode')
+      .option('--no-color', 'Disable colors')
+      .option('--color', 'Enable colors')
+      .option('-d --debug', 'Enable diagnostics', false)
+      .option('-a --assert', 'Treat warnings as errors', false)
+      .option('-v --version', 'Show the version')
+      .allowUnknownOption();
+      program.jsonArgs = initInfo.options;
+
+    // Create the NEW command
+    program
+      .command('new')
+      .arguments('<sources...>')
+      .option('-f --format <fmt>', 'FRESH or JRS format', 'FRESH')
+      .alias('create')
+      .description('Create resume(s) in FRESH or JSON RESUME format.')
+      .action(function( sources ) {
+        execute.call( this, sources, [], this.opts(), logMsg);
+      });
+
+    // Create the VALIDATE command
+    program
+      .command('validate')
+      .arguments('<sources...>')
+      .description('Validate a resume in FRESH or JSON RESUME format.')
+      .action(function(sources) {
+        execute.call( this, sources, [], this.opts(), logMsg);
+      });
+
+    // Create the CONVERT command
+    program
+      .command('convert')
+      .description('Convert a resume to/from FRESH or JSON RESUME format.')
+      .action(function() {
+        var x = splitSrcDest.call( this );
+        execute.call( this, x.src, x.dst, this.opts(), logMsg);
+      });
+
+    // Create the ANALYZE command
+    program
+      .command('analyze')
+      .arguments('<sources...>')
+      .description('Analyze one or more resumes.')
+      .action(function( sources ) {
+        execute.call( this, sources, [], this.opts(), logMsg);
+      });
+
+    // Create the PEEK command
+    program
+      .command('peek')
+      .arguments('<sources...>')
+      .description('Peek at a resume field or section')
+      .action(function( sources, sectionOrField ) {
+        var dst = (sources && sources.length > 1) ? [sources.pop()] : [];
+        execute.call( this, sources, dst, this.opts(), logMsg);
+      });
+
+    // Create the BUILD command
+    program
+      .command('build')
+      .alias('generate')
+      .option('-t --theme <theme>', 'Theme name or path')
+      .option('-n --no-prettify', 'Disable HTML prettification', true)
+      .option('-c --css <option>', 'CSS linking / embedding')
+      .option('-p --pdf <engine>', 'PDF generation engine')
+      .option('--no-sort', 'Sort resume sections by date', false)
+      .option('--tips', 'Display theme tips and warnings.', false)
+      .description('Generate resume to multiple formats')
+      .action(function( sources, targets, options ) {
+        var x = splitSrcDest.call( this );
+        execute.call( this, x.src, x.dst, this.opts(), logMsg);
+      });
+
+    program.parse( args );
+
+    if (!program.args.length) { throw { fluenterror: 4 }; }
+
+  };
+
+
+
+  /** Massage command-line args and setup Commander.js. */
+  function initialize( ar ) {
+
+    var o = initOptions( ar );
+
+    o.silent || logMsg( _title );
+
+    // Emit debug prelude if --debug was specified
+    if( o.debug ) {
+      _out.log(chalk.cyan('The -d or --debug switch was specified. DEBUG mode engaged.'));
+      _out.log('');
+      _out.log(chalk.cyan(PAD('  Platform:',25, null, PAD.RIGHT)) + chalk.cyan.bold( process.platform === 'win32' ? 'windows' : process.platform ));
+      _out.log(chalk.cyan(PAD('  Node.js:',25, null, PAD.RIGHT)) + chalk.cyan.bold( process.version ));
+      _out.log(chalk.cyan(PAD('  HackMyResume:',25, null, PAD.RIGHT)) + chalk.cyan.bold('v' + PKG.version ));
+      _out.log(chalk.cyan(PAD('  FRESCA:',25, null, PAD.RIGHT)) + chalk.cyan.bold( PKG.dependencies.fresca ));
+      _out.log(chalk.cyan(PAD('  fresh-themes:',25, null, PAD.RIGHT)) + chalk.cyan.bold( PKG.dependencies['fresh-themes'] ));
+      _out.log(chalk.cyan(PAD('  fresh-jrs-converter:',25, null, PAD.RIGHT)) + chalk.cyan.bold( PKG.dependencies['fresh-jrs-converter'] ));
+      _out.log('');
+    }
+
+    // Handle invalid verbs here (a bit easier here than in commander.js)...
+    if( o.verb && !HMR.verbs[ o.verb ] && !HMR.alias[ o.verb ] ) {
+      throw { fluenterror: HMSTATUS.invalidCommand, quit: true,
+              attempted: o.orgVerb };
+    }
+
+    // Override the .missingArgument behavior
+    Command.prototype.missingArgument = function(name) {
+      if( this.name() !== 'new' ) {
+        throw { fluenterror: HMSTATUS.resumeNotFound, quit: true };
+      }
+    };
+
+    // Override the .helpInformation behavior
+    Command.prototype.helpInformation = function() {
+      var manPage = FS.readFileSync(
+        PATH.join(__dirname, 'use.txt'), 'utf8' );
+      return chalk.green.bold(manPage);
+    };
+
+    return {
+      args: o.args,
+      options: o.json
+    };
+  }
+
+
+
+  /** Init options prior to setting up command infrastructure. */
+  function initOptions( ar ) {
+    var oVerb, verb = '', args = ar.slice(), cleanArgs = args.slice(2), oJSON;
+    if( cleanArgs.length ) {
+
+      // Support case-insensitive sub-commands (build, generate, validate, etc)
+      var vidx = _.findIndex( cleanArgs, function(v){ return v[0] !== '-'; });
+      if( vidx !== -1 ) {
+        oVerb = cleanArgs[ vidx ];
+        verb = args[ vidx + 2 ] = oVerb.trim().toLowerCase();
+      }
+
+      // Remove --options --opts -o and process separately
+      var optsIdx = _.findIndex( cleanArgs, function(v){
+        return v === '-o' || v === '--options' || v === '--opts';
+      });
+      if(optsIdx !== -1) {
+        var optStr = cleanArgs[ optsIdx + 1];
+        args.splice( optsIdx + 2, 2 );
+        if( optStr && (optStr = optStr.trim()) ) {
+          //var myJSON = JSON.parse(optStr);
+          if( optStr[0] === '{')
+            oJSON = eval('(' + optStr + ')'); // jshint ignore:line
+          else {
+            var inf = safeLoadJSON( optStr );
+            if( !inf.ex )
+              oJSON = inf.json;
+            // TODO: Error handling
+          }
+        }
+      }
+    }
+
+    // Grab the --debug flag
+    var isDebug = _.some( args, function(v) {
+      return v === '-d' || v === '--debug';
+    });
+
+    // Grab the --silent flag
+    var isSilent = _.some( args, function(v) {
+      return v === '-s' || v === '--silent';
+    });
+
+    return {
+      debug: isDebug,
+      silent: isSilent,
+      orgVerb: oVerb,
+      verb: verb,
+      json: oJSON,
+      args: args
+    };
+  }
+
+
+
+  /** Invoke a HackMyResume verb. */
+  function execute( src, dst, opts, log ) {
+
+    loadOptions.call( this, opts, this.parent.jsonArgs );
+    var hand = require( './error' );
+    hand.init( _opts.debug, _opts.assert, _opts.silent );
+    var v = new HMR.verbs[ this.name() ]();
+    _opts.errHandler = v;
+    _out.init( _opts );
+    v.on( 'hmr:status', function() { _out.do.apply( _out, arguments ); });
+    v.on( 'hmr:error', function() {
+      hand.err.apply( hand, arguments );
+    });
+    v.invoke.call( v, src, dst, _opts, log );
+    if( v.errorCode )
+      process.exit(v.errorCode);
+  }
+
+
+
+  /**
+  Initialize HackMyResume options.
+  TODO: Options loading is a little hacky, for two reasons:
+    - Commander.js idiosyncracies
+    - Need to accept JSON inputs from the command line.
+  */
+  function loadOptions( o, cmdO ) {
+
+    // o and this.opts() seem to be the same (command-specific options)
+
+    // Load the specified options file (if any) and apply options
+    if( cmdO )
+      o = EXTEND(true, o, cmdO);
+
+    // Merge in command-line options
+    o = EXTEND( true, o, this.opts() );
+
+    // Kludge parent-level options until piping issue is resolved
+    if( this.parent.silent !== undefined && this.parent.silent !== null)
+      o.silent = this.parent.silent;
+    if( this.parent.debug !== undefined && this.parent.debug !== null)
+      o.debug = this.parent.debug;
+    if( this.parent.assert !== undefined && this.parent.assert !== null)
+      o.assert = this.parent.assert;
+
+    if( o.debug ) {
+      logMsg(chalk.cyan('OPTIONS:') + '\n');
+      _.each(o, function(val, key) {
+        logMsg(chalk.cyan('  %s') + chalk.cyan.bold(' %s'),
+          PAD(key,22,null,PAD.RIGHT), val);
+      });
+      logMsg('');
+    }
+
+    // Cache
+    EXTEND(true, _opts, o);
+  }
+
+
+
+  /** Split multiple command-line filenames by the 'TO' keyword */
+  function splitSrcDest() {
+
+    var params = this.parent.args.filter(function(j) { return String.is(j); });
+    if( params.length === 0 )
+      throw { fluenterror: HMSTATUS.resumeNotFound, quit: true };
+
+    // Find the TO keyword, if any
+    var splitAt = _.findIndex( params, function(p) {
+      return p.toLowerCase() === 'to';
+    });
+
+    // TO can't be the last keyword
+    if( splitAt === params.length - 1 && splitAt !== -1 ) {
+      logMsg(chalk.yellow('Please ') +
+        chalk.yellow.bold('specify an output file') +
+        chalk.yellow(' for this operation or ') +
+        chalk.yellow.bold('omit the TO keyword') +
+        chalk.yellow('.') );
+      return;
+    }
+
+    return {
+      src: params.slice(0, splitAt === -1 ? undefined : splitAt ),
+      dst: splitAt === -1 ? [] : params.slice( splitAt + 1 )
+    };
+  }
+
+
+
+  /** Simple logging placeholder. */
+  function logMsg() {
+    _opts.silent || console.log.apply( console.log, arguments );
+  }
+
+
+
+}());

src/cli/msg.js

@@ -0,0 +1,18 @@
+/**
+Message-handling routines for HackMyResume.
+@module msg.js
+@license MIT. See LICENSE.md for details.
+*/
+
+
+
+(function() {
+
+  var PATH = require('path');
+  var YAML = require('yamljs');
+
+  var cache = module.exports = function() {
+    return cache ? cache : YAML.load( PATH.join(__dirname, 'msg.yml') );
+  }();
+
+}());

src/cli/msg.yml

@@ -0,0 +1,98 @@
+events:
+  begin:
+    msg: Invoking **%s** command.
+  beforeCreate:
+    msg: Creating new **%s** resume: **%s**
+  afterRead:
+    msg: Reading **%s** resume: **%s**
+  beforeTheme:
+    msg: Verifying **%s** theme.
+  afterTheme:
+    msg: Verifying outputs:  ???
+  beforeMerge:
+    msg:
+      - "Merging **%s**"
+      - " onto **%s**"
+  applyTheme:
+    msg: Applying **%s** theme (**%s** format%s)
+  afterBuild:
+    msg:
+      - "The **%s** theme says:"
+      - |
+          "For best results view JSON Resume themes over a
+          local or remote HTTP connection. For example:
+
+            npm install http-server -g
+            http-server <resume-folder>
+
+          For more information, see the README."
+  afterGenerate:
+    msg:
+      - " (with %s)"
+      - "Skipping %s resume: %s"
+      - "Generating **%s** resume: **%s**"
+  beforeAnalyze:
+    msg: "Analyzing **%s** resume: **%s**"
+  beforeConvert:
+    msg: "Converting **%s** (**%s**) to **%s** (**%s**)"
+  afterValidate:
+    msg:
+      - "Validating **%s** against the **%s** schema: "
+      - "VALID!"
+      - "INVALID"
+      - "BROKEN"
+  beforePeek:
+    msg:
+      - Peeking at **%s** in **%s**
+      - Peeking at **%s**
+  afterPeek:
+    msg: "The specified key **%s** was not found in **%s**."
+  afterInlineConvert:
+    msg: Converting **%s** to **%s** format.
+errors:
+  themeNotFound:
+    msg: >
+      **Couldn't find the '%s' theme.** Please specify the name of a preinstalled
+      FRESH theme or the path to a locally installed FRESH or JSON Resume theme.
+  copyCSS:
+    msg: Couldn't copy CSS file to destination folder.
+  resumeNotFound:
+    msg: Please **feed me a resume** in FRESH or JSON Resume format.
+  missingCommand:
+    msg: Please **give me a command**
+  invalidCommand:
+    msg: Invalid command: '%s'
+  resumeNotFoundAlt:
+    msg: Please **feed me a resume** in either FRESH or JSON Resume format.
+  inputOutputParity:
+    msg: Please **specify an output file name** for every input file you wish to convert.
+  createNameMissing:
+    msg: Please **specify the filename** of the resume to create.
+  pdfGeneration:
+    msg: PDF generation failed. Make sure wkhtmltopdf is installed and accessible from your path.
+  invalid:
+    msg: Validation failed and the --assert option was specified.
+  invalidFormat:
+    msg: The **%s** theme doesn't support the **%s** format.
+  notOnPath:
+    msg: %s wasn't found on your system path or is inaccessible. PDF not generated.
+  readError:
+    msg: Reading **???** resume: **%s**
+  parseError:
+    msg: Invalid or corrupt JSON on line %s column %s.
+  invalidHelperUse:
+    msg: "**Warning**: Incorrect use of the **%s** theme helper."
+  fileSaveError:
+    msg: An error occurred while writing %s to disk: %s.
+  mixedMerge:
+    msg: "**Warning:** merging mixed resume types. Errors may occur."
+  invokeTemplate:
+    msg: "An error occurred during template invocation."
+  compileTemplate:
+    msg: "An error occurred during template compilation."
+  themeLoad:
+    msg: "Applying **%s** theme (? formats)"
+  invalidParamCount:
+    msg: "Invalid number of parameters. Expected: **%s**."
+  missingParam:
+    msg: The '**%s**' parameter was needed but not supplied.

src/cli/out.js

@@ -0,0 +1,229 @@
+/**
+Output routines for HackMyResume.
+@license MIT. See LICENSE.md for details.
+@module out.js
+*/
+
+
+
+(function() {
+
+
+
+  var chalk = require('chalk')
+    , HME = require('../core/event-codes')
+    , _ = require('underscore')
+    , Class = require('../utils/class.js')
+    , M2C = require('../utils/md2chalk.js')
+    , PATH = require('path')
+    , LO = require('lodash')
+    , FS = require('fs')
+    , EXTEND = require('extend')
+    , HANDLEBARS = require('handlebars')
+    , YAML = require('yamljs')
+    , printf = require('printf')
+    , pad = require('string-padding')
+    , dbgStyle = 'cyan';
+
+
+
+  /**
+  A stateful output module. All HMR console output handled here.
+  */
+  var OutputHandler = module.exports = Class.extend({
+
+
+
+    init: function( opts ) {
+      this.opts = EXTEND( true, this.opts || { }, opts );
+      this.msgs = YAML.load(PATH.join( __dirname, 'msg.yml' )).events;
+    },
+
+
+
+    log: function( msg ) {
+      msg = msg || '';
+      var printf = require('printf');
+      var finished = printf.apply( printf, arguments );
+      this.opts.silent || console.log( finished );
+    },
+
+
+
+    do: function( evt ) {
+
+      var that = this;
+      function L() {
+        that.log.apply( that, arguments );
+      }
+
+      switch( evt.sub ) {
+
+        case HME.begin:
+          this.opts.debug &&
+          L( M2C( this.msgs.begin.msg, dbgStyle), evt.cmd.toUpperCase() );
+          break;
+
+        case HME.error:
+          break;
+
+        case HME.beforeCreate:
+          L( M2C( this.msgs.beforeCreate.msg, 'green' ), evt.fmt, evt.file );
+          break;
+
+        case HME.beforeRead:
+          break;
+
+        case HME.afterRead:
+          break;
+
+        case HME.beforeTheme:
+          this.opts.debug &&
+            L( M2C( this.msgs.beforeTheme.msg, dbgStyle), evt.theme.toUpperCase() );
+          break;
+
+        case HME.afterParse:
+          L(
+            M2C( this.msgs.afterRead.msg, 'gray', 'white.dim'), evt.fmt.toUpperCase(), evt.file
+          );
+
+          break;
+
+        case HME.afterTheme:
+          break;
+
+        case HME.beforeMerge:
+          var msg = '';
+          evt.f.reverse().forEach( function( a, idx ) {
+            msg += printf(
+              ((idx === 0) ?
+                this.msgs.beforeMerge.msg[0] :
+                this.msgs.beforeMerge.msg[1] ), a.file
+            );
+          }, this);
+          L( M2C(msg, evt.mixed ? 'yellow' : 'gray', 'white.dim') );
+          break;
+
+        case HME.afterMerge:
+          break;
+
+        case HME.applyTheme:
+          this.theme = evt.theme;
+          var numFormats = Object.keys( evt.theme.formats ).length;
+          L( M2C(this.msgs.applyTheme.msg, evt.status === 'error' ? 'red' : 'gray', evt.status === 'error' ? 'bold' : 'white.dim'),
+            evt.theme.name.toUpperCase(),
+            numFormats, ( numFormats === 1 ? '' : 's') );
+          break;
+
+        case HME.end:
+          if( evt.cmd === 'build' ) {
+            var themeName = this.theme.name.toUpperCase();
+            if( this.opts.tips && (this.theme.message || this.theme.render) ) {
+              var WRAP = require('word-wrap');
+              if( this.theme.message ) {
+                L( M2C( this.msgs.afterBuild.msg[0], 'cyan' ), themeName );
+                L( M2C( this.theme.message, 'white' ));
+              }
+              else if ( this.theme.render ) {
+                L( M2C( this.msgs.afterBuild.msg[0], 'cyan'), themeName);
+                L( M2C( this.msgs.afterBuild.msg[1], 'white'));
+              }
+            }
+          }
+          break;
+
+        case HME.afterGenerate:
+          var suffix = '';
+          if( evt.fmt === 'pdf' ) {
+            if( this.opts.pdf ) {
+              if( this.opts.pdf !== 'none' ) {
+                suffix = printf( M2C( this.msgs.afterGenerate.msg[0], evt.error ? 'red' : 'green' ), this.opts.pdf );
+              }
+              else {
+                L( M2C( this.msgs.afterGenerate.msg[1], 'gray' ),
+                  evt.fmt.toUpperCase(), evt.file );
+                return;
+              }
+            }
+          }
+
+          L( M2C( this.msgs.afterGenerate.msg[2] + suffix, evt.error ? 'red' : 'green' ),
+              pad(evt.fmt.toUpperCase(),4,null,pad.RIGHT),
+              PATH.relative(process.cwd(), evt.file ));
+          break;
+
+        case HME.beforeAnalyze:
+          L( M2C( this.msgs.beforeAnalyze.msg, 'green' ), evt.fmt, evt.file);
+          break;
+
+        case HME.afterAnalyze:
+          var info = evt.info;
+          var rawTpl = FS.readFileSync( PATH.join( __dirname, 'analyze.hbs' ), 'utf8');
+          HANDLEBARS.registerHelper( require('../helpers/console-helpers') );
+          var template = HANDLEBARS.compile(rawTpl, { strict: false, assumeObjects: false });
+          var tot = 0;
+          info.keywords.forEach(function(g) { tot += g.count; });
+          info.keywords.totalKeywords = tot;
+          var output = template( info );
+          this.log( chalk.cyan(output) );
+          break;
+
+        case HME.beforeConvert:
+          L( M2C( this.msgs.beforeConvert.msg, 'green' ),
+            evt.srcFile, evt.srcFmt, evt.dstFile, evt.dstFmt
+          );
+          break;
+
+        case HME.afterInlineConvert:
+          L( M2C( this.msgs.afterInlineConvert.msg, 'gray', 'white.dim' ),
+            evt.file, evt.fmt );
+          break;
+
+        case HME.afterValidate:
+          var style = evt.isValid ? 'green' : 'yellow';
+          L(
+            M2C( this.msgs.afterValidate.msg[0], 'white' ) +
+            chalk[style].bold( evt.isValid ?
+                               this.msgs.afterValidate.msg[1] :
+                               this.msgs.afterValidate.msg[2] ),
+            evt.file, evt.fmt
+          );
+
+          if( evt.errors ) {
+            _.each(evt.errors, function(err,idx) {
+              L( chalk.yellow.bold('--> ') +
+                chalk.yellow(err.field.replace('data.','resume.').toUpperCase() + ' ' +
+                err.message) );
+            }, this);
+          }
+          break;
+
+        case HME.beforePeek:
+          // if( evt.target )
+          //   L(M2C(this.msgs.beforePeek.msg[0], evt.isError ? 'red' : 'green'), evt.target, evt.file);
+          // else
+          //   L(M2C(this.msgs.beforePeek.msg[1], evt.isError ? 'red' : 'green'), evt.file);
+          break;
+
+        case HME.afterPeek:
+          var sty = evt.error ? 'red' : ( evt.target !== undefined ? 'green' : 'yellow' );
+          if( evt.requested )
+            L(M2C(this.msgs.beforePeek.msg[0], sty), evt.requested, evt.file);
+          else
+            L(M2C(this.msgs.beforePeek.msg[1], sty), evt.file);
+
+          if( evt.target !== undefined )
+            console.dir( evt.target, { depth: null, colors: true } );
+          else if( !evt.error )
+            L(M2C( this.msgs.afterPeek.msg, 'yellow'), evt.requested, evt.file);
+          break;
+
+      }
+    }
+
+
+
+  });
+
+
+}());

src/cli/use.txt

@@ -0,0 +1,51 @@
+Usage:
+
+  hackmyresume <command> <sources> [TO <targets>] [<options>]
+
+Available commands:
+
+  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.
+
+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.
+  --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.
+
+Examples:
+
+  hackmyresume  BUILD resume.json TO out/resume.all --theme modern
+  hackmyresume  ANALYZE resume.json
+  hackmyresume  NEW my-new-resume.json --format JRS
+  hackmyresume  CONVERT resume-fresh.json TO resume-jrs.json
+  hackmyresume  VALIDATE resume.json
+  hackmyresume  PEEK resume.json employment[2].summary
+
+Tips:
+
+  - You can specify multiple sources and/or targets for all commands.
+  - You can use any FRESH or JSON Resume theme with HackMyResume.
+  - Specify a file extension of .all to generate your resume to all
+    available formats supported by the theme. (BUILD command.)
+  - The --theme parameter can specify either the name of a preinstalled
+    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
+    listing of all available FRESH themes.
+  - Report bugs to https://githut.com/hacksalot/HackMyResume/issues.

src/core/convert.js

@@ -1,419 +0,0 @@
-/**
-FRESH to JSON Resume conversion routiens.
-@license MIT. See LICENSE.md for details.
-@module convert.js
-*/
-
-
-
-(function(){ // TODO: refactor everything
-
-
-
-  var _ = require('underscore');
-
-
-
-  /**
-  Convert between FRESH and JRS resume/CV formats.
-  @class FRESHConverter
-  */
-  var FRESHConverter = module.exports = {
-
-
-
-    /**
-    Convert from JSON Resume format to FRESH.
-    @method toFresh
-    @todo Refactor
-    */
-    toFRESH: function( src, foreign ) {
-
-      foreign = (foreign === undefined || foreign === null) ? true : foreign;
-
-      return {
-        name: src.basics.name,
-        imp: src.basics.imp,
-        info: {
-          label: src.basics.label,
-          class: src.basics.class, // <--> round-trip
-          image: src.basics.picture,
-          brief: src.basics.summary
-        },
-        contact: {
-          email: src.basics.email,
-          phone: src.basics.phone,
-          website: src.basics.website,
-          other: src.basics.other // <--> round-trip
-        },
-        meta: meta( true, src.meta ),
-        location: {
-          city: src.basics.location.city,
-          region: src.basics.location.region,
-          country: src.basics.location.countryCode,
-          code: src.basics.location.postalCode,
-          address: src.basics.location.address
-        },
-        employment: employment( src.work, true ),
-        education: education( src.education, true),
-        service: service( src.volunteer, true),
-        skills: skillsToFRESH( src.skills ),
-        writing: writing( src.publications, true),
-        recognition: recognition( src.awards, true, foreign ),
-        social: social( src.basics.profiles, true ),
-        interests: src.interests,
-        testimonials: references( src.references, true ),
-        languages: src.languages,
-        disposition: src.disposition // <--> round-trip
-      };
-    },
-
-
-
-    /**
-    Convert from FRESH format to JSON Resume.
-    @param foreign True if non-JSON-Resume properties should be included in
-    the result, false if those properties should be excluded.
-    @todo Refactor
-    */
-    toJRS: function( src, foreign ) {
-
-      foreign = (foreign === undefined || foreign === null) ? false : foreign;
-
-      return {
-        basics: {
-          name: src.name,
-          label: src.info.label,
-          class: foreign ? src.info.class : undefined,
-          summary: src.info.brief,
-          website: src.contact.website,
-          phone: src.contact.phone,
-          email: src.contact.email,
-          picture: src.info.image,
-          location: {
-            address: src.location.address,
-            postalCode: src.location.code,
-            city: src.location.city,
-            countryCode: src.location.country,
-            region: src.location.region
-          },
-          profiles: social( src.social, false ),
-          imp: src.imp
-        },
-        work: employment( src.employment, false ),
-        education: education( src.education, false ),
-        skills: skillsToJRS( src.skills, false ),
-        volunteer: service( src.service, false ),
-        awards: recognition( src.recognition, false, foreign ),
-        publications: writing( src.writing, false ),
-        interests: src.interests,
-        references: references( src.testimonials, false ),
-        samples: foreign ? src.samples : undefined,
-        disposition: foreign ? src.disposition : undefined,
-        languages: src.languages
-      };
-
-    },
-
-
-
-    toSTRING: function( src ) {
-      function replacerJRS( key,value ) { // Exclude these keys
-        return _.some(['imp', 'warnings', 'computed', 'filt', 'ctrl', 'index',
-          'safeStartDate', 'safeEndDate', 'safeDate', 'safeReleaseDate',
-          'result', 'isModified', 'htmlPreview', 'display_progress_bar'],
-          function( val ) { return key.trim() === val; }
-        ) ? undefined : value;
-      }
-      function replacerFRESH( key,value ) { // Exclude these keys
-        return _.some(['imp', 'warnings', 'computed', 'filt', 'ctrl', 'index',
-          'safe', 'result', 'isModified', 'htmlPreview', 'display_progress_bar'],
-          function( val ) { return key.trim() === val; }
-        ) ? undefined : value;
-      }
-
-      return JSON.stringify( src, src.basics ? replacerJRS : replacerFRESH, 2 );
-    }
-
-  };
-
-
-
-  function meta( direction, obj ) {
-    //if( !obj ) return obj; // preserve null and undefined
-    if( direction ) {
-      obj = obj || { };
-      obj.format = obj.format || "FRESH@0.1.0";
-      obj.version = obj.version || "0.1.0";
-    }
-    return obj;
-  }
-
-
-
-  function employment( obj, direction ) {
-    if( !obj ) return obj;
-    if( !direction ) {
-      return obj && obj.history ?
-        obj.history.map(function(emp){
-          return {
-            company: emp.employer,
-            website: emp.url,
-            position: emp.position,
-            startDate: emp.start,
-            endDate: emp.end,
-            summary: emp.summary,
-            highlights: emp.highlights
-          };
-        }) : undefined;
-    }
-    else {
-      return {
-        history: obj && obj.length ?
-          obj.map( function( job ) {
-            return {
-              position: job.position,
-              employer: job.company,
-              summary: job.summary,
-              current: (!job.endDate || !job.endDate.trim() ||
-                job.endDate.trim().toLowerCase() === 'current') || undefined,
-              start: job.startDate,
-              end: job.endDate,
-              url: job.website,
-              keywords: [],
-              highlights: job.highlights
-            };
-          }) : undefined
-      };
-    }
-  }
-
-
-
-  function education( obj, direction ) {
-    if( !obj ) return obj;
-    if( direction ) {
-      return obj && obj.length ? {
-        level: "",
-        history: obj.map(function(edu){
-          return {
-            institution: edu.institution,
-            start: edu.startDate,
-            end: edu.endDate,
-            grade: edu.gpa,
-            curriculum: edu.courses,
-            url: edu.website || edu.url || undefined,
-            summary: edu.summary || "",
-            area: edu.area,
-            studyType: edu.studyType
-          };
-        })
-      } : undefined;
-    }
-    else {
-      return obj && obj.history ?
-        obj.history.map(function(edu){
-          return {
-            institution: edu.institution,
-            gpa: edu.grade,
-            courses: edu.curriculum,
-            startDate: edu.start,
-            endDate: edu.end,
-            area: edu.area,
-            studyType: edu.studyType
-          };
-        }) : undefined;
-    }
-  }
-
-
-
-  function service( obj, direction, foreign ) {
-    if( !obj ) return obj;
-    if( direction ) {
-      return {
-        history: obj && obj.length ? obj.map(function(vol) {
-          return {
-            type: 'volunteer',
-            position: vol.position,
-            organization: vol.organization,
-            start: vol.startDate,
-            end: vol.endDate,
-            url: vol.website,
-            summary: vol.summary,
-            highlights: vol.highlights
-          };
-        }) : undefined
-      };
-    }
-    else {
-      return obj && obj.history ?
-        obj.history.map(function(srv){
-          return {
-            flavor: foreign ? srv.flavor : undefined,
-            organization: srv.organization,
-            position: srv.position,
-            startDate: srv.start,
-            endDate: srv.end,
-            website: srv.url,
-            summary: srv.summary,
-            highlights: srv.highlights
-          };
-        }) : undefined;
-    }
-  }
-
-
-
-  function social( obj, direction ) {
-    if( !obj ) return obj;
-    if( direction ) {
-      return obj.map(function(pro){
-        return {
-          label: pro.network,
-          network: pro.network,
-          url: pro.url,
-          user: pro.username
-        };
-      });
-    }
-    else {
-      return obj.map( function( soc ) {
-        return {
-          network: soc.network,
-          username: soc.user,
-          url: soc.url
-        };
-      });
-    }
-  }
-
-
-
-  function recognition( obj, direction, foreign ) {
-    if( !obj ) return obj;
-    if( direction ) {
-      return obj && obj.length ? obj.map(
-        function(awd){
-          return {
-            flavor: foreign ? awd.flavor : undefined,
-            url: foreign ? awd.url: undefined,
-            title: awd.title,
-            date: awd.date,
-            from: awd.awarder,
-            summary: awd.summary
-          };
-      }) : undefined;
-    }
-    else {
-      return obj && obj.length ? obj.map(function(awd){
-        return {
-          flavor: foreign ? awd.flavor : undefined,
-          url: foreign ? awd.url: undefined,
-          title: awd.title,
-          date: awd.date,
-          awarder: awd.from,
-          summary: awd.summary
-        };
-      }) : undefined;
-    }
-  }
-
-
-
-  function references( obj, direction ) {
-    if( !obj ) return obj;
-    if( direction ) {
-      return obj && obj.length && obj.map(function(ref){
-        return {
-          name: ref.name,
-          flavor: 'professional',
-          quote: ref.reference,
-          private: false
-        };
-      });
-    }
-    else {
-      return obj && obj.length && obj.map(function(ref){
-        return {
-          name: ref.name,
-          reference: ref.quote
-        };
-      });
-    }
-  }
-
-
-
-  function writing( obj, direction ) {
-    if( !obj ) return obj;
-    if( direction ) {
-      return obj.map(function( pub ) {
-        return {
-          title: pub.name,
-          flavor: undefined,
-          publisher: pub.publisher,
-          url: pub.website,
-          date: pub.releaseDate,
-          summary: pub.summary
-        };
-      });
-    }
-    else {
-      return obj && obj.length ? obj.map(function(pub){
-        return {
-          name: pub.title,
-          publisher: pub.publisher &&
-            pub.publisher.name ? pub.publisher.name : pub.publisher,
-          releaseDate: pub.date,
-          website: pub.url,
-          summary: pub.summary
-        };
-      }) : undefined;
-    }
-  }
-
-
-
-  function skillsToFRESH( skills ) {
-    if( !skills ) return skills;
-    return {
-      sets: skills.map(function( set ) {
-        return {
-          name: set.name,
-          level: set.level,
-          skills: set.keywords
-        };
-      })
-    };
-  }
-
-
-
-  function skillsToJRS( skills ) {
-    if( !skills ) return skills;
-    var ret = [];
-    if( skills.sets && skills.sets.length ) {
-      ret = skills.sets.map(function(set){
-        return {
-          name: set.name,
-          level: set.level,
-          keywords: set.skills
-        };
-      });
-    }
-    else if( skills.list ) {
-      ret = skills.list.map(function(sk){
-        return {
-          name: sk.name,
-          level: sk.level,
-          keywords: sk.keywords
-        };
-      });
-    }
-    return ret;
-  }
-
-
-
-}());

src/core/error-handler.js

@@ -1,174 +0,0 @@
-/**
-Error-handling routines for HackMyResume.
-@module error-handler.js
-@license MIT. See LICENSE.md for details.
-*/
-// TODO: Logging library
-
-
-(function() {
-
-
-
-  var HACKMYSTATUS = require('./status-codes')
-    , PKG = require('../../package.json')
-    , FS = require('fs')
-    , FCMD = require('../hackmyapi')
-    , PATH = require('path')
-    , WRAP = require('word-wrap')
-    , chalk = require('chalk');
-
-
-
-  /**
-  An amorphous blob of error handling code for HackMyResume.
-  @class ErrorHandler
-  */
-  var ErrorHandler = module.exports = {
-
-    init: function( debug ) {
-      this.debug = debug;
-    },
-
-    err: function( ex, shouldExit ) {
-
-      var msg = '', exitCode, log = console.log, showStack = ex.showStack;
-
-      // If the exception has been handled elsewhere and shouldExit is true,
-      // let's get out of here, otherwise silently return.
-      if( ex.handled ) {
-        if( shouldExit )
-          process.exit( exitCode );
-        return;
-      }
-
-      // Get an error message -- either a HackMyResume error message or the
-      // exception's associated error message
-      if( ex.fluenterror ){
-        var errInfo = get_error_msg( ex );
-        msg = errInfo.msg;
-        exitCode = ex.fluenterror;
-        showStack = errInfo.showStack;
-      }
-      else {
-        msg = ex.toString();
-        exitCode = -1;
-        // Deal with pesky 'Error:' prefix.
-        var idx = msg.indexOf('Error: ');
-        msg = idx === -1 ? msg : msg.substring( idx + 7 );
-      }
-
-      // Log non-HackMyResume-handled errors in red with ERROR prefix. Log HMR
-      // errors as-is.
-      ex.fluenterror ?
-        log( msg.toString() ) :
-        log( chalk.red.bold('ERROR: ' + msg.toString()) );
-
-      // Selectively show the stack trace
-      if( (ex.stack || (ex.inner && ex.inner.stack)) &&
-         ((showStack && ex.code !== 'ENOENT' ) || (this.debug) ))
-        log( chalk.red( ex.stack || ex.stack.inner ) );
-
-      // Let the error code be the process's return code.
-      ( shouldExit || ex.shouldExit ) && process.exit( exitCode );
-    }
-
-  };
-
-
-
-  function get_error_msg( ex ) {
-
-    var msg = '', withStack = false, isError = false;
-    switch( ex.fluenterror ) {
-
-      case HACKMYSTATUS.themeNotFound:
-        msg = formatWarning(
-           chalk.bold("Couldn't find the '" + ex.data + "' theme."),
-          " Please specify the name of a preinstalled FRESH theme " +
-          "or the path to a locally installed FRESH or JSON Resume theme.");
-        break;
-
-      case HACKMYSTATUS.copyCSS:
-        msg = formatWarning("Couldn't copy CSS file to destination folder.");
-        break;
-
-      case HACKMYSTATUS.resumeNotFound:
-        msg = formatWarning('Please ' + chalk.bold('feed me a resume') +
-          ' in FRESH or JSON Resume format.');
-        break;
-
-      case HACKMYSTATUS.missingCommand:
-        msg = formatWarning("Please " +chalk.bold("give me a command") + " (");
-
-        msg += Object.keys( FCMD.verbs ).map( function(v, idx, ar) {
-          return (idx === ar.length - 1 ? chalk.yellow('or ') : '') +
-            chalk.yellow.bold(v.toUpperCase());
-        }).join( chalk.yellow(', ')) + chalk.yellow(").\n\n");
-
-        msg += chalk.gray(FS.readFileSync(
-          PATH.resolve(__dirname, '../use.txt'), 'utf8' ));
-        break;
-
-      case HACKMYSTATUS.invalidCommand:
-        msg = formatWarning('Invalid command: "'+chalk.bold(ex.attempted)+'"');
-        break;
-
-      case HACKMYSTATUS.resumeNotFoundAlt:
-        msg = formatWarning('Please ' + chalk.bold('feed me a resume') +
-          ' in either FRESH or JSON Resume format.');
-        break;
-
-      case HACKMYSTATUS.inputOutputParity:
-        msg = formatWarning('Please ' +
-          chalk.bold('specify an output file name') +
-          ' for every input file you wish to convert.');
-        break;
-
-      case HACKMYSTATUS.createNameMissing:
-        msg = formatWarning('Please ' +
-          chalk.bold('specify the filename of the resume') + ' to create.');
-        break;
-
-      case HACKMYSTATUS.pdfGeneration:
-        msg = formatError(chalk.bold('ERROR: PDF generation failed. ') +
-          'Make sure wkhtmltopdf is installed and accessible from your path.');
-        if( ex.inner ) msg += chalk.red('\n' + ex.inner);
-        withStack = true;
-        break;
-
-      case HACKMYSTATUS.invalid:
-        msg = formatError('Validation failed and the --assert option was ' +
-          'specified.');
-        break;
-
-      case HACKMYSTATUS.invalidFormat:
-        ex.data.forEach(function(d){ msg +=
-          formatWarning('The ' + chalk.bold(ex.theme.name.toUpperCase()) +
-          " theme doesn't support the " + chalk.bold(d.format.toUpperCase()) +
-          " format.\n");
-        });
-        break;
-
-      case HACKMYSTATUS.notOnPath:
-        msg = formatError( ex.engine + " wasn't found on your system path or" +
-          " is inaccessible. PDF not generated." );
-        break;
-
-    }
-    return {
-      msg: msg,
-      withStack: withStack
-    };
-  }
-
-  function formatError( msg ) {
-    return chalk.red.bold( 'ERROR: ' + msg );
-  }
-
-  function formatWarning( brief, msg ) {
-    return chalk.yellow(brief) + chalk.yellow(msg || '');
-  }
-
-
-}());

src/core/event-codes.js

@@ -0,0 +1,46 @@
+/**
+Event code definitions.
+@module event-codes.js
+@license MIT. See LICENSE.md for details.
+*/
+
+
+
+(function(){
+
+  var val = 0;
+
+  module.exports = {
+
+    error:            -1,
+    success:          0,
+    begin:            1,
+    end:              2,
+    beforeRead:       3,
+    afterRead:        4,
+    beforeCreate:     5,
+    afterCreate:      6,
+    beforeTheme:      7,
+    afterTheme:       8,
+    beforeMerge:      9,
+    afterMerge:       10,
+    beforeGenerate:   11,
+    afterGenerate:    12,
+    beforeAnalyze:    13,
+    afterAnalyze:     14,
+    beforeConvert:    15,
+    afterConvert:     16,
+    verifyOutputs:    17,
+    beforeParse:      18,
+    afterParse:       19,
+    beforePeek:       20,
+    afterPeek:        21,
+    beforeInlineConvert: 22,
+    afterInlineConvert: 23,
+    beforeValidate:   24,
+    afterValidate:    25
+  };
+
+
+
+}());

src/core/fluent-date.js

@@ -1,84 +1,95 @@
 /**
 The HackMyResume date representation.
-@license MIT. Copyright (c) 2015 James Devlin / FluentDesk.
-@module fluent-date.js
+@license MIT. See LICENSE.md for details.
+@module core/fluent-date
 */
 
-var moment = require('moment');
+(function(){
 
-/**
-Create a FluentDate from a string or Moment date object. There are a few date
-formats to be aware of here.
-1. The words "Present" and "Now", referring to the current date
-2. The default "YYYY-MM-DD" format used in JSON Resume ("2015-02-10")
-3. Year-and-month only ("2015-04")
-4. Year-only "YYYY" ("2015")
-5. The friendly HackMyResume "mmm YYYY" format ("Mar 2015" or "Dec 2008")
-6. Empty dates ("", " ")
-7. Any other date format that Moment.js can parse from
-Note: Moment can transparently parse all or most of these, without requiring us
-to specify a date format...but for maximum parsing safety and to avoid Moment
-deprecation warnings, it's recommended to either a) explicitly specify the date
-format or b) use an ISO format. For clarity, we handle these cases explicitly.
-@class FluentDate
-*/
-function FluentDate( dt ) {
-  this.rep = this.fmt( dt );
-}
+  var moment = require('moment');
 
-FluentDate/*.prototype*/.fmt = function( dt ) {
-  if( (typeof dt === 'string' || dt instanceof String) ) {
-    dt = dt.toLowerCase().trim();
-    if( /^(present|now|current)$/.test(dt) ) { // "Present", "Now"
-      return moment();
-    }
-    else if( /^\D+\s+\d{4}$/.test(dt) ) { // "Mar 2015"
-      var parts = dt.split(' ');
-      var month = (months[parts[0]] || abbr[parts[0]]);
-      var temp = parts[1] + '-' + (month < 10 ? '0' + month : month.toString());
-      return moment( temp, 'YYYY-MM' );
-    }
-    else if( /^\d{4}-\d{1,2}$/.test(dt) ) { // "2015-03", "1998-4"
-      return moment( dt, 'YYYY-MM' );
-    }
-    else if( /^\s*\d{4}\s*$/.test(dt) ) { // "2015"
-      return moment( dt, 'YYYY' );
-    }
-    else if( /^\s*$/.test(dt) ) { // "", " "
-      var defTime = {
-        isNull: true,
-        isBefore: function( other ) {
-          return( other && !other.isNull ) ? true : false;
-        },
-        isAfter: function( other ) {
-          return( other && !other.isNull ) ? false : false;
-        },
-        unix: function() { return 0; },
-        format: function() { return ''; },
-        diff: function() { return 0; }
-      };
-      return defTime;
+  /**
+  Create a FluentDate from a string or Moment date object. There are a few date
+  formats to be aware of here.
+  1. The words "Present" and "Now", referring to the current date
+  2. The default "YYYY-MM-DD" format used in JSON Resume ("2015-02-10")
+  3. Year-and-month only ("2015-04")
+  4. Year-only "YYYY" ("2015")
+  5. The friendly HackMyResume "mmm YYYY" format ("Mar 2015" or "Dec 2008")
+  6. Empty dates ("", " ")
+  7. Any other date format that Moment.js can parse from
+  Note: Moment can transparently parse all or most of these, without requiring us
+  to specify a date format...but for maximum parsing safety and to avoid Moment
+  deprecation warnings, it's recommended to either a) explicitly specify the date
+  format or b) use an ISO format. For clarity, we handle these cases explicitly.
+  @class FluentDate
+  */
+  function FluentDate( dt ) {
+    this.rep = this.fmt( dt );
+  }
+
+  FluentDate/*.prototype*/.fmt = function( dt, throws ) {
+
+    throws = (throws === undefined || throws === null) || throws;
+
+    if( (typeof dt === 'string' || dt instanceof String) ) {
+      dt = dt.toLowerCase().trim();
+      if( /^(present|now|current)$/.test(dt) ) { // "Present", "Now"
+        return moment();
+      }
+      else if( /^\D+\s+\d{4}$/.test(dt) ) { // "Mar 2015"
+        var parts = dt.split(' ');
+        var month = (months[parts[0]] || abbr[parts[0]]);
+        var temp = parts[1] + '-' + (month < 10 ? '0' + month : month.toString());
+        return moment( temp, 'YYYY-MM' );
+      }
+      else if( /^\d{4}-\d{1,2}$/.test(dt) ) { // "2015-03", "1998-4"
+        return moment( dt, 'YYYY-MM' );
+      }
+      else if( /^\s*\d{4}\s*$/.test(dt) ) { // "2015"
+        return moment( dt, 'YYYY' );
+      }
+      else if( /^\s*$/.test(dt) ) { // "", " "
+        var defTime = {
+          isNull: true,
+          isBefore: function( other ) {
+            return( other && !other.isNull ) ? true : false;
+          },
+          isAfter: function( other ) {
+            return( other && !other.isNull ) ? false : false;
+          },
+          unix: function() { return 0; },
+          format: function() { return ''; },
+          diff: function() { return 0; }
+        };
+        return defTime;
+      }
+      else {
+        var mt = moment( dt );
+        if(mt.isValid())
+          return mt;
+        if( throws )
+          throw 'Invalid date format encountered.';
+        return null;
+      }
     }
     else {
-      var mt = moment( dt );
-      if(mt.isValid())
-        return mt;
-      throw 'Invalid date format encountered.';
+      if( !dt ) {
+        return moment();
+      }
+      else if( dt.isValid && dt.isValid() )
+        return dt;
+      if( throws )
+        throw 'Unknown date object encountered.';
+      return null;
     }
-  }
-  else {
-    if( !dt ) {
-      return moment();
-    }
-    else if( dt.isValid && dt.isValid() )
-      return dt;
-    throw 'Unknown date object encountered.';
-  }
-};
+  };
 
-var months = {}, abbr = {};
-moment.months().forEach(function(m,idx){months[m.toLowerCase()]=idx+1;});
-moment.monthsShort().forEach(function(m,idx){abbr[m.toLowerCase()]=idx+1;});
-abbr.sept = 9;
+  var months = {}, abbr = {};
+  moment.months().forEach(function(m,idx){months[m.toLowerCase()]=idx+1;});
+  moment.monthsShort().forEach(function(m,idx){abbr[m.toLowerCase()]=idx+1;});
+  abbr.sept = 9;
 
-module.exports = FluentDate;
+  module.exports = FluentDate;
+
+}());

src/core/fresh-resume.js

@@ -1,7 +1,7 @@
 /**
 Definition of the FRESHResume class.
-@license MIT. See LICENSE .md for details.
-@module fresh-resume.js
+@license MIT. See LICENSE.md for details.
+@module core/fresh-resume
 */
 
 
@@ -11,7 +11,7 @@ Definition of the FRESHResume class.
 
 
   var FS = require('fs')
-    , extend = require('../utils/extend')
+    , extend = require('extend')
     , validator = require('is-my-json-valid')
     , _ = require('underscore')
     , __ = require('lodash')
@@ -19,7 +19,7 @@ Definition of the FRESHResume class.
     , moment = require('moment')
     , XML = require('xml-escape')
     , MD = require('marked')
-    , CONVERTER = require('./convert')
+    , CONVERTER = require('fresh-jrs-converter')
     , JRSResume = require('./jrs-resume');
 
 
@@ -27,7 +27,7 @@ Definition of the FRESHResume class.
   /**
   A FRESH resume or CV. FRESH resumes are backed by JSON, and each FreshResume
   object is an instantiation of that JSON decorated with utility methods.
-  @class FreshResume
+  @constructor
   */
   function FreshResume() {
 
@@ -38,16 +38,17 @@ Definition of the FRESHResume class.
   /**
   Initialize the FreshResume from file.
   */
-  FreshResume.prototype.open = function( file, title ) {
-    this.imp = { fileName: file };
-    this.imp.raw = FS.readFileSync( file, 'utf8' );
-    return this.parse( this.imp.raw, title );
+  FreshResume.prototype.open = function( file, opts ) {
+    var raw = FS.readFileSync( file, 'utf8' );
+    var ret = this.parse( raw, opts );
+    this.imp.file = file;
+    return ret;
   };
 
 
 
   /**
-  Initialize the the FreshResume from string.
+  Initialize the the FreshResume from JSON string data.
   */
   FreshResume.prototype.parse = function( stringData, opts ) {
     return this.parseJSON( JSON.parse( stringData ), opts );
@@ -60,31 +61,47 @@ Definition of the FRESHResume class.
   Open and parse the specified FRESH resume. Merge the JSON object model onto
   this Sheet instance with extend() and convert sheet dates to a safe &
   consistent format. Then sort each section by startDate descending.
+  @param rep {Object} The raw JSON representation.
+  @param opts {Object} Resume loading and parsing options.
+  {
+    date: Perform safe date conversion.
+    sort: Sort resume items by date.
+    compute: Prepare computed resume totals.
+  }
   */
   FreshResume.prototype.parseJSON = function( rep, opts ) {
-    // Convert JSON Resume to FRESH if necessary
-    if( rep.basics ) {
-      rep = CONVERTER.toFRESH( rep );
-      rep.imp = rep.imp || { };
-      rep.imp.orgFormat = 'JRS';
-    }
+
+    // Ignore any element with the 'ignore: true' designator.
+    var that = this, traverse = require('traverse'), ignoreList = [];
+    var scrubbed = traverse( rep ).map( function( x ) {
+      if( !this.isLeaf && this.node.ignore ) {
+        if ( this.node.ignore === true || this.node.ignore === 'true' ) {
+          ignoreList.push( this.node );
+          this.remove();
+        }
+      }
+    });
 
     // Now apply the resume representation onto this object
-    extend( true, this, rep );
+    extend( true, this, scrubbed );
 
-    // Set up metadata
-    opts = opts || { };
-    if( opts.imp === undefined || opts.imp ) {
-      this.imp = this.imp || { };
-      this.imp.title = (opts.title || this.imp.title) || this.name;
+    // If the resume already has a .imp object, then we are being called from
+    // the .dupe method, and there's no need to do any post processing
+    if( !this.imp ) {
+      // Set up metadata TODO: Clean up metadata on the object model.
+      opts = opts || { };
+      if( opts.imp === undefined || opts.imp ) {
+        this.imp = this.imp || { };
+        this.imp.title = (opts.title || this.imp.title) || this.name;
+      }
+      // Parse dates, sort dates, and calculate computed values
+      (opts.date === undefined || opts.date) && _parseDates.call( this );
+      (opts.sort === undefined || opts.sort) && this.sort();
+      (opts.compute === undefined || opts.compute) && (this.computed = {
+         numYears: this.duration(),
+         keywords: this.keywords()
+      });
     }
-    // Parse dates, sort dates, and calculate computed values
-    (opts.date === undefined || opts.date) && _parseDates.call( this );
-    (opts.sort === undefined || opts.sort) && this.sort();
-    (opts.compute === undefined || opts.compute) && (this.computed = {
-       numYears: this.duration(),
-       keywords: this.keywords()
-    });
     return this;
   };
 
@@ -94,8 +111,8 @@ Definition of the FRESHResume class.
   Save the sheet to disk (for environments that have disk access).
   */
   FreshResume.prototype.save = function( filename ) {
-    this.imp.fileName = filename || this.imp.fileName;
-    FS.writeFileSync( this.imp.fileName, this.stringify(), 'utf8' );
+    this.imp.file = filename || this.imp.file;
+    FS.writeFileSync( this.imp.file, this.stringify(), 'utf8' );
     return this;
   };
 
@@ -107,8 +124,8 @@ Definition of the FRESHResume class.
   FreshResume.prototype.saveAs = function( filename, format ) {
 
     if( format !== 'JRS' ) {
-      this.imp.fileName = filename || this.imp.fileName;
-      FS.writeFileSync( this.imp.fileName, this.stringify(), 'utf8' );
+      this.imp.file = filename || this.imp.file;
+      FS.writeFileSync( this.imp.file, this.stringify(), 'utf8' );
     }
     else {
       var newRep = CONVERTER.toJRS( this );
@@ -121,10 +138,15 @@ Definition of the FRESHResume class.
 
   /**
   Duplicate this FreshResume instance.
+  This method first extend()s this object onto an empty, creating a deep copy,
+  and then passes the result into a new FreshResume instance via .parseJSON.
+  We do it this way to create a true clone of the object without re-running any
+  of the associated processing.
   */
   FreshResume.prototype.dupe = function() {
+    var jso = extend( true, { }, this );
     var rnew = new FreshResume();
-    rnew.parse( this.stringify(), { } );
+    rnew.parseJSON( jso, { } );
     return rnew;
   };
 
@@ -159,47 +181,12 @@ Definition of the FRESHResume class.
   /**
   Create a copy of this resume in which all string fields have been run through
   a transformation function (such as a Markdown filter or XML encoder).
+  TODO: Move this out of FRESHResume.
   */
   FreshResume.prototype.transformStrings = function( filt, transformer ) {
-
-    var that = this;
     var ret = this.dupe();
-
-    // TODO: refactor recursion
-    function transformStringsInObject( obj, filters ) {
-
-      if( !obj ) return;
-      if( moment.isMoment( obj ) ) return;
-
-      if( _.isArray( obj ) ) {
-        obj.forEach( function(elem, idx, ar) {
-          if( typeof elem === 'string' || elem instanceof String )
-            ar[idx] = transformer( null, elem );
-          else if (_.isObject(elem))
-            transformStringsInObject( elem, filters );
-        });
-      }
-      else if (_.isObject( obj )) {
-        Object.keys( obj ).forEach(function(k) {
-          if( filters.length && _.contains(filters, k) )
-            return;
-          var sub = obj[k];
-          if( typeof sub === 'string' || sub instanceof String ) {
-            obj[k] = transformer( k, sub );
-          }
-          else if (_.isObject( sub ))
-            transformStringsInObject( sub, filters );
-        });
-      }
-
-    }
-
-    Object.keys( ret ).forEach(function(member){
-      if( !filt || !filt.length || !_.contains(filt, member) )
-        transformStringsInObject( ret[ member ], filt || [] );
-    });
-
-    return ret;
+    var trx = require('../utils/string-transformer');
+    return trx( ret, filt, transformer );
   };
 
 
@@ -462,7 +449,7 @@ Definition of the FRESHResume class.
     sortSection( 'employment.history' );
     sortSection( 'education.history' );
     sortSection( 'service.history' );
-    sortSection( 'projects.history' );
+    sortSection( 'projects' );
 
     // this.awards && this.awards.sort( function(a, b) {
     //   return( a.safeDate.isBefore(b.safeDate) ) ? 1

src/core/fresh-theme.js

@@ -9,14 +9,15 @@ Definition of the FRESHTheme class.
 
 
   var FS = require('fs')
-    , extend = require('../utils/extend')
     , validator = require('is-my-json-valid')
     , _ = require('underscore')
     , PATH = require('path')
     , parsePath = require('parse-filepath')
     , pathExists = require('path-exists').sync
-    , EXTEND = require('../utils/extend')
+    , EXTEND = require('extend')
+    , HMSTATUS = require('./status-codes')
     , moment = require('moment')
+    , loadSafeJson = require('../utils/safe-json-loader')
     , READFILES = require('recursive-readdir-sync');
 
 
@@ -47,11 +48,17 @@ Definition of the FRESHTheme class.
 
     // Load the theme
     var themeFile = PATH.join( themeFolder, 'theme.json' );
-    var themeInfo = JSON.parse( FS.readFileSync( themeFile, 'utf8' ) );
+    var themeInfo = loadSafeJson( themeFile );
+    if( themeInfo.ex ) throw {
+      fluenterror: themeInfo.ex.operation === 'parse' ?
+        HMSTATUS.parseError : HMSTATUS.readError,
+      inner: themeInfo.ex.inner
+    };
+
     var that = this;
 
     // Move properties from the theme JSON file to the theme object
-    EXTEND( true, this, themeInfo );
+    EXTEND( true, this, themeInfo.json );
 
     // Check for an "inherits" entry in the theme JSON.
     if( this.inherits ) {
@@ -189,7 +196,7 @@ Definition of the FRESHTheme class.
       var idx = _.findIndex(fmts, function( fmt ) {
         return fmt && fmt.pre === cssf.pre && fmt.ext === 'html';
       });
-      cssf.action = null;
+      cssf.major = false;
       if( idx > -1) {
         fmts[ idx ].css = cssf.data;
         fmts[ idx ].cssPath = cssf.path;
@@ -203,11 +210,6 @@ Definition of the FRESHTheme class.
       }
     });
 
-    // Remove CSS files from the formats array
-    fmts = fmts.filter( function( fmt) {
-      return fmt && (fmt.ext !== 'css');
-    });
-
     return formatsHash;
   }
 

src/core/jrs-resume.js

@@ -1,7 +1,7 @@
 /**
 Definition of the JRSResume class.
 @license MIT. See LICENSE.md for details.
-@module jrs-resume.js
+@module core/jrs-resume
 */
 
 
@@ -11,12 +11,12 @@ Definition of the JRSResume class.
 
 
   var FS = require('fs')
-    , extend = require('../utils/extend')
+    , extend = require('extend')
     , validator = require('is-my-json-valid')
     , _ = require('underscore')
     , PATH = require('path')
     , MD = require('marked')
-    , CONVERTER = require('./convert')
+    , CONVERTER = require('fresh-jrs-converter')
     , moment = require('moment');
 
 
@@ -39,7 +39,7 @@ Definition of the JRSResume class.
     //this.imp = { fileName: file }; <-- schema violation, tuck it into .basics
     this.basics = {
       imp: {
-        fileName: file,
+        file: file,
         raw: FS.readFileSync( file, 'utf8' )
       }
     };
@@ -60,14 +60,35 @@ Definition of the JRSResume class.
 
 
   /**
-  Initialize the JRSResume from JSON.
-  Open and parse the specified JRS resume. Merge the JSON object model onto this
-  Sheet instance with extend() and convert sheet dates to a safe & consistent
-  format. Then sort each section by startDate descending.
+  Initialize the JRSResume object from JSON.
+  Open and parse the specified JRS resume. Merge the JSON object model onto
+  this Sheet instance with extend() and convert sheet dates to a safe &
+  consistent format. Then sort each section by startDate descending.
+  @param rep {Object} The raw JSON representation.
+  @param opts {Object} Resume loading and parsing options.
+  {
+    date: Perform safe date conversion.
+    sort: Sort resume items by date.
+    compute: Prepare computed resume totals.
+  }
   */
   JRSResume.prototype.parseJSON = function( rep, opts ) {
     opts = opts || { };
-    extend( true, this, rep );
+
+    // Ignore any element with the 'ignore: true' designator.
+    var that = this, traverse = require('traverse'), ignoreList = [];
+    var scrubbed = traverse( rep ).map( function( x ) {
+      if( !this.isLeaf && this.node.ignore ) {
+        if ( this.node.ignore === true || this.node.ignore === 'true' ) {
+          ignoreList.push( this.node );
+          this.remove();
+        }
+      }
+    });
+
+    // Extend resume properties onto ourself.
+    extend( true, this, scrubbed );
+
     // Set up metadata
     if( opts.imp === undefined || opts.imp ) {
       this.basics.imp = this.basics.imp || { };
@@ -91,8 +112,8 @@ Definition of the JRSResume class.
   Save the sheet to disk (for environments that have disk access).
   */
   JRSResume.prototype.save = function( filename ) {
-    this.basics.imp.fileName = filename || this.basics.imp.fileName;
-    FS.writeFileSync(this.basics.imp.fileName, this.stringify( this ), 'utf8');
+    this.basics.imp.file = filename || this.basics.imp.file;
+    FS.writeFileSync(this.basics.imp.file, this.stringify( this ), 'utf8');
     return this;
   };
 
@@ -104,8 +125,8 @@ Definition of the JRSResume class.
   JRSResume.prototype.saveAs = function( filename, format ) {
 
     if( format === 'JRS' ) {
-      this.basics.imp.fileName = filename || this.imp.fileName;
-      FS.writeFileSync( this.basics.imp.fileName, this.stringify(), 'utf8' );
+      this.basics.imp.file = filename || this.basics.imp.file;
+      FS.writeFileSync( this.basics.imp.file, this.stringify(), 'utf8' );
     }
     else {
       var newRep = CONVERTER.toFRESH( this );
@@ -171,8 +192,9 @@ Definition of the JRSResume class.
   so tuck this into the .basic sub-object.
   */
   JRSResume.prototype.i = function() {
-    this.basics = this.basics || { imp: { } };
-    return this.basics;
+    this.basics = this.basics || { };
+    this.basics.imp = this.basics.imp || { };
+    return this.basics.imp;
   };
 
 

src/core/resume-factory.js

@@ -10,11 +10,14 @@ Definition of the ResumeFactory class.
 
 
 
-  require('string.prototype.startswith');
-  var FS = require('fs');
-  var ResumeConverter = require('./convert');
-  var chalk = require('chalk');
-  var SyntaxErrorEx = require('../utils/syntax-error-ex');
+  var FS          = require('fs'),
+  HACKMYSTATUS    = require('./status-codes'),
+  HME             = require('./event-codes'),
+  ResumeConverter = require('fresh-jrs-converter'),
+  chalk           = require('chalk'),
+  SyntaxErrorEx   = require('../utils/syntax-error-ex'),
+  _               = require('underscore');
+                    require('string.prototype.startswith');
 
 
 
@@ -28,15 +31,24 @@ Definition of the ResumeFactory class.
 
     /**
     Load one or more resumes from disk.
-    */
-    load: function ( sources, opts ) {
 
-      // Loop over all inputs, parsing each to JSON and then to a FRESHResume
-      // or JRSResume object.
-      var that = this;
+    @param {Object} opts An options object with settings for the factory as well
+    as passthrough settings for FRESHResume or JRSResume. Structure:
+
+        {
+          format: 'FRESH',    // Format to open as. ('FRESH', 'JRS', null)
+          objectify: true,    // FRESH/JRSResume or raw JSON?
+          inner: {            // Passthru options for FRESH/JRSResume
+            sort: false
+          }
+        }
+
+    */
+    load: function ( sources, opts, emitter ) {
+
       return sources.map( function( src ) {
-        return that.loadOne( src, opts );
-      });
+        return this.loadOne( src, opts, emitter );
+      }, this);
 
     },
 
@@ -45,18 +57,17 @@ Definition of the ResumeFactory class.
     /**
     Load a single resume from disk.
     */
-    loadOne: function( src, opts ) {
+    loadOne: function( src, opts, emitter ) {
 
-      var log = opts.log;
-      var toFormat = opts.format;
+      var toFormat = opts.format;     // Can be null
       var objectify = opts.objectify;
 
       // Get the destination format. Can be 'fresh', 'jrs', or null/undefined.
       toFormat && (toFormat = toFormat.toLowerCase().trim());
 
       // Load and parse the resume JSON
-      var info = _parse( src, opts );
-      if( info.error ) return info;
+      var info = _parse( src, opts, emitter );
+      if( info.fluenterror ) return info;
 
       // Determine the resume format: FRESH or JRS
       var json = info.json;
@@ -74,7 +85,7 @@ Definition of the ResumeFactory class.
       var rez;
       if( objectify ) {
         var ResumeClass = require('../core/' + (toFormat || orgFormat) + '-resume');
-        rez = new ResumeClass().parseJSON( json );
+        rez = new ResumeClass().parseJSON( json, opts.inner );
         rez.i().file = src;
       }
 
@@ -88,44 +99,38 @@ Definition of the ResumeFactory class.
 
 
 
-  function _parse( fileName, opts ) {
+  function _parse( fileName, opts, eve ) {
+
     var rawData;
     try {
 
-      // TODO: Core should not log
-      opts.log( chalk.cyan('Reading resume: ') + chalk.cyan.bold(fileName) );
-
       // Read the file
+      eve && eve.stat( HME.beforeRead, { file: fileName });
       rawData = FS.readFileSync( fileName, 'utf8' );
+      eve && eve.stat( HME.afterRead, { file: fileName, data: rawData });
 
-      // Parse it to JSON
-      return {
-        json: JSON.parse( rawData )
-      };
+      // Parse the file
+      eve && eve.stat( HME.beforeParse, { data: rawData });
+      var ret = { json: JSON.parse( rawData ) };
+      var orgFormat = ( ret.json.meta && ret.json.meta.format &&
+                        ret.json.meta.format.startsWith('FRESH@') ) ?
+                        'fresh' : 'jrs';
+      eve && eve.stat( HME.afterParse, { file: fileName, data: ret.json, fmt: orgFormat } );
 
+      return ret;
     }
-    catch( ex ) {
-
-      // JSON.parse failed due to invalid JSON
-      if ( !opts.muffle && ex instanceof SyntaxError) {
-        var info = new SyntaxErrorEx( ex, rawData );
-        opts.log( chalk.red.bold(fileName.toUpperCase() + ' contains invalid JSON on line ' +
-          info.line + ' column ' + info.col + '.' +
-          chalk.red(' Unable to validate.')));
-        opts.log( chalk.red.bold('INTERNAL: ' + ex) );
-        ex.handled = true;
-      }
-
-      // FS.readFileSync failed
-      if( !rawData || opts.throw ) throw ex;
-
-      return {
-        error: ex,
-        raw: rawData,
-        file: fileName
+    catch( e ) {
+      // Can be ENOENT, EACCES, SyntaxError, etc.
+      var ex = {
+        fluenterror: rawData ? HACKMYSTATUS.parseError : HACKMYSTATUS.readError,
+        inner: e, raw: rawData, file: fileName, shouldExit: false
       };
-
+      opts.quit && (ex.quit = true);
+      eve && eve.err( ex.fluenterror, ex );
+      if( opts.throw ) throw ex;
+      return ex;
     }
+
   }
 
 

src/core/spawn-watch.js

@@ -1,22 +0,0 @@
-/**
-@module spawn-watch.js
-*/
-
-(function() {
-
-// Catch various out-of-band child process errors such as ENOENT for PDFs
-// http://stackoverflow.com/q/27688804
-var SpawnWatcher = module.exports = function() {
-  var childProcess = require("child_process");
-  var oldSpawn = childProcess.spawn;
-  childProcess.spawn = function() {
-    return oldSpawn.apply(this, arguments)
-      .on('error', function(err) {
-        require('./error-handler').err( err, false );
-      });
-  };
-}();
-
-//SpawnWatcher();
-
-}());

src/core/status-codes.js

@@ -20,7 +20,18 @@ Status codes for HackMyResume.
     missingPackageJSON: 10,
     invalid: 11,
     invalidFormat: 12,
-    notOnPath: 13
+    notOnPath: 13,
+    readError: 14,
+    parseError: 15,
+    fileSaveError: 16,
+    generateError: 17,
+    invalidHelperUse: 18,
+    mixedMerge: 19,
+    invokeTemplate: 20,
+    compileTemplate: 21,
+    themeLoad: 22,
+    invalidParamCount: 23,
+    missingParam: 24
   };
 
 }());

src/generators/html-generator.js

@@ -10,6 +10,7 @@ Definition of the HTMLGenerator class.
     , FS = require('fs-extra')
     , HTML = require( 'html' )
     , PATH = require('path');
+    require('string.prototype.endswith');
 
   var HtmlGenerator = module.exports = TemplateGenerator.extend({
 
@@ -22,6 +23,8 @@ Definition of the HTMLGenerator class.
     the HTML resume prior to saving.
     */
     onBeforeSave: function( info ) {
+      if( info.outputFile.endsWith('.css') )
+        return info.mk;
       return this.opts.prettify ?
         HTML.prettyPrint( info.mk, this.opts.prettify ) : info.mk;
     }

src/generators/html-pdf-cli-generator.js

@@ -14,6 +14,7 @@ Definition of the HtmlPdfCLIGenerator class.
     , FS = require('fs-extra')
     , HTML = require( 'html' )
     , PATH = require('path')
+    , SPAWN = require('../utils/safe-spawn')
     , SLASH = require('slash');
 
 
@@ -40,15 +41,17 @@ Definition of the HtmlPdfCLIGenerator class.
 
       try {
         var safe_eng = info.opts.pdf || 'wkhtmltopdf';
-        engines[ safe_eng ].call( this, info.mk, info.outputFile );
+        if( safe_eng !== 'none' )
+          engines[ safe_eng ].call( this, info.mk, info.outputFile );
         return null; // halt further processing
       }
       catch(ex) {
         // { [Error: write EPIPE] code: 'EPIPE', errno: 'EPIPE', ... }
         // { [Error: ENOENT] }
         throw ( ex.inner && ex.inner.code === 'ENOENT' ) ?
-          { fluenterror: this.codes.notOnPath, engine: ex.cmd, stack: ex.inner.stack } :
-          { fluenterror: this.codes.pdfGeneration, inner: ex.inner, stack: ex.inner.stack };
+          { fluenterror: this.codes.notOnPath, inner: ex.inner, engine: ex.cmd,
+            stack: ex.inner && ex.inner.stack } :
+          { fluenterror: this.codes.pdfGeneration, inner: ex, stack: ex.stack };
       }
     }
 
@@ -75,24 +78,8 @@ Definition of the HtmlPdfCLIGenerator class.
       // Save the markup to a temporary file
       var tempFile = fOut.replace(/\.pdf$/i, '.pdf.html');
       FS.writeFileSync( tempFile, markup, 'utf8' );
+      var info = SPAWN( 'wkhtmltopdf', [ tempFile, fOut ] );
 
-      var spawn = require('child_process').spawnSync;
-      var info = spawn('wkhtmltopdf', [
-        tempFile, fOut
-      ]);
-      if( info.error ) {
-        throw {
-          cmd: 'wkhtmltopdf',
-          inner: info.error
-        };
-      }
-
-      // child.stdout.on('data', function(chunk) {
-      //   // output will be here in chunks
-      // });
-
-      // or if you want to send output elsewhere
-      //child.stdout.pipe(dest);
     },
 
 
@@ -109,29 +96,16 @@ Definition of the HtmlPdfCLIGenerator class.
       // Save the markup to a temporary file
       var tempFile = fOut.replace(/\.pdf$/i, '.pdf.html');
       FS.writeFileSync( tempFile, markup, 'utf8' );
-
       var scriptPath = SLASH( PATH.relative( process.cwd(),
         PATH.resolve( __dirname, '../utils/rasterize.js' ) ) );
       var sourcePath = SLASH( PATH.relative( process.cwd(), tempFile) );
       var destPath = SLASH( PATH.relative( process.cwd(), fOut) );
+      var info = SPAWN('phantomjs', [ scriptPath, sourcePath, destPath ]);
 
-      var spawn = require('child_process').spawnSync;
-      var info = spawn('phantomjs', [ scriptPath, sourcePath, destPath ]);
-      if( info.error ) {
-        throw {
-          cmd: 'phantomjs',
-          inner: info.error
-        };
-      }
-
-      // child.stdout.on('data', function(chunk) {
-      //   // output will be here in chunks
-      // });
-      //
-      // // or if you want to send output elsewhere
-      // child.stdout.pipe(dest);
     }
 
+
+
   };
 
 

src/generators/template-generator.js

@@ -4,6 +4,8 @@ Definition of the TemplateGenerator class. TODO: Refactor
 @module template-generator.js
 */
 
+
+
 (function() {
 
 
@@ -16,13 +18,185 @@ Definition of the TemplateGenerator class. TODO: Refactor
     , parsePath = require('parse-filepath')
     , MKDIRP = require('mkdirp')
     , BaseGenerator = require( './base-generator' )
-    , EXTEND = require('../utils/extend')
+    , EXTEND = require('extend')
     , FRESHTheme = require('../core/fresh-theme')
     , JRSTheme = require('../core/jrs-theme');
 
 
 
-  // Default options.
+  /**
+  TemplateGenerator performs resume generation via local Handlebar or Underscore
+  style template expansion and is appropriate for text-based formats like HTML,
+  plain text, and XML versions of Microsoft Word, Excel, and OpenOffice.
+  @class TemplateGenerator
+  */
+  var TemplateGenerator = module.exports = BaseGenerator.extend({
+
+
+
+    /** Constructor. Set the output format and template format for this
+    generator. Will usually be called by a derived generator such as
+    HTMLGenerator or MarkdownGenerator. */
+
+    init: function( outputFormat, templateFormat, cssFile ){
+      this._super( outputFormat );
+      this.tplFormat = templateFormat || outputFormat;
+    },
+
+
+
+    /** Generate a resume using string-based inputs and outputs without touching
+    the filesystem.
+    @method invoke
+    @param rez A FreshResume object.
+    @param opts Generator options.
+    @returns {Array} An array of objects representing the generated output
+    files. */
+
+    invoke: function( rez, opts ) {
+
+      opts = opts ?
+        (this.opts = EXTEND( true, { }, _defaultOpts, opts )) :
+        this.opts;
+
+      // Sort such that CSS files are processed before others
+      var curFmt = opts.themeObj.getFormat( this.format );
+      curFmt.files = _.sortBy( curFmt.files, function(fi) {
+        return fi.ext !== 'css';
+      });
+
+      // Run the transformation!
+      var results = curFmt.files.map( function( tplInfo, idx ) {
+        var trx = this.single( rez, tplInfo.data, this.format, opts, opts.themeObj, curFmt );
+        if( tplInfo.ext === 'css' ) { curFmt.files[idx].data = trx; }
+        else if( tplInfo.ext === 'html' ) {
+          //tplInfo.css contains the CSS data loaded by theme
+          //tplInfo.cssPath contains the absolute path to the source CSS File
+        }
+        return { info: tplInfo, data: trx };
+      }, this);
+
+      return {
+        files: results
+      };
+
+    },
+
+
+
+    /** Generate a resume using file-based inputs and outputs. Requires access
+    to the local filesystem.
+    @method generate
+    @param rez A FreshResume object.
+    @param f Full path to the output resume file to generate.
+    @param opts Generator options. */
+
+    generate: function( rez, f, opts ) {
+
+      // Prepare
+      this.opts = EXTEND( true, { }, _defaultOpts, opts );
+
+      // Call the string-based generation method to perform the generation.
+      var genInfo = this.invoke( rez, null );
+
+      var outFolder = parsePath( f ).dirname;
+      var curFmt = opts.themeObj.getFormat( this.format );
+
+      // Process individual files within this format. For example, the HTML
+      // output format for a theme may have multiple HTML files, CSS files,
+      // etc. Process them here.
+      genInfo.files.forEach(function( file ){
+
+        // Pre-processing
+        file.info.orgPath = file.info.orgPath || ''; // <-- For JRS themes
+        var thisFilePath = PATH.join( outFolder, file.info.orgPath );
+        if( this.onBeforeSave ) {
+          file.data = this.onBeforeSave({
+            theme: opts.themeObj,
+            outputFile: (file.info.major ? f : thisFilePath),
+            mk: file.data,
+            opts: this.opts
+          });
+          if( !file.data ) return; // PDF etc
+        }
+
+        // Write the file
+        var fileName = file.info.major ? f : thisFilePath;
+        MKDIRP.sync( PATH.dirname( fileName ) );
+        FS.writeFileSync( fileName, file.data,
+          { encoding: 'utf8', flags: 'w' } );
+
+        // Post-processing
+        this.onAfterSave && this.onAfterSave(
+          { outputFile: fileName, mk: file.data, opts: this.opts } );
+
+      }, this);
+
+      // Some themes require a symlink structure. If so, create it.
+      if( curFmt.symLinks ) {
+        Object.keys( curFmt.symLinks ).forEach( function(loc) {
+          var absLoc = PATH.join(outFolder, loc);
+          var absTarg = PATH.join(PATH.dirname(absLoc), curFmt.symLinks[loc]);
+           // 'file', 'dir', or 'junction' (Windows only)
+          var type = parsePath( absLoc ).extname ? 'file' : 'junction';
+          FS.symlinkSync( absTarg, absLoc, type);
+        });
+      }
+
+      return genInfo;
+
+    },
+
+
+
+    /** Perform a single resume resume transformation using string-based inputs
+    and outputs without touching the local file system.
+    @param json A FRESH or JRS resume object.
+    @param jst The stringified template data
+    @param format The format name, such as "html" or "latex"
+    @param cssInfo Needs to be refactored.
+    @param opts Options and passthrough data. */
+
+    single: function( json, jst, format, opts, theme, curFmt ) {
+      this.opts.freezeBreaks && ( jst = freeze(jst) );
+
+      var eng = require( '../renderers/' + theme.engine  + '-generator' );
+      var result = eng.generate( json, jst, format, curFmt, opts, theme );
+
+      this.opts.freezeBreaks && ( result = unfreeze(result) );
+      return result;
+    }
+
+
+  });
+
+
+
+  /** Export the TemplateGenerator function/ctor. */
+  module.exports = TemplateGenerator;
+
+
+
+
+  /** Freeze newlines for protection against errant JST parsers. */
+  function freeze( markup ) {
+    return markup
+      .replace( _reg.regN, _defaultOpts.nSym )
+      .replace( _reg.regR, _defaultOpts.rSym );
+  }
+
+
+
+  /** Unfreeze newlines when the coast is clear. */
+  function unfreeze( markup ) {
+    return markup
+      .replace( _reg.regSymR, '\r' )
+      .replace( _reg.regSymN, '\n' );
+  }
+
+
+
+  /** Default template generator options. */
   var _defaultOpts = {
     engine: 'underscore',
     keepBreaks: true,
@@ -57,260 +231,7 @@ Definition of the TemplateGenerator class. TODO: Refactor
 
 
 
-  /**
-  TemplateGenerator performs resume generation via local Handlebar or Underscore
-  style template expansion and is appropriate for text-based formats like HTML,
-  plain text, and XML versions of Microsoft Word, Excel, and OpenOffice.
-  @class TemplateGenerator
-  */
-  var TemplateGenerator = module.exports = BaseGenerator.extend({
-
-
-
-    init: function( outputFormat, templateFormat, cssFile ){
-      this._super( outputFormat );
-      this.tplFormat = templateFormat || outputFormat;
-    },
-
-
-    /**
-    String-based template generation method.
-    @method invoke
-    @param rez A FreshResume object.
-    @param opts Generator options.
-    @returns An array of objects representing the generated output files. Each
-    object has this format:
-
-        {
-          files: [ { info: { }, data: [ ] }, { ... } ],
-          themeInfo: { }
-        }
-
-    */
-    invoke: function( rez, opts ) {
-
-      // Carry over options
-      this.opts = EXTEND( true, { }, _defaultOpts, opts );
-
-      // Load the theme
-      var themeInfo = themeFromMoniker.call( this );
-      var theme = themeInfo.theme;
-      var tFolder = themeInfo.folder;
-      var tplFolder = PATH.join( tFolder, 'src' );
-      var curFmt = theme.getFormat( this.format );
-      var that = this;
-
-      // "Generate": process individual files within the theme
-      return {
-        files: curFmt.files.map( function( tplInfo ) {
-          return {
-            info: tplInfo,
-            data: tplInfo.action === 'transform' ?
-              transform.call( that, rez, tplInfo, theme ) : undefined
-          };
-        }).filter(function(item){ return item !== null; }),
-        themeInfo: themeInfo
-      };
-
-    },
-
-
-
-    /**
-    File-based template generation method.
-    @method generate
-    @param rez A FreshResume object.
-    @param f Full path to the output resume file to generate.
-    @param opts Generator options.
-    */
-    generate: function( rez, f, opts ) {
-
-      // Call the generation method
-      var genInfo = this.invoke( rez, opts );
-
-      // Carry over options
-      this.opts = EXTEND( true, { }, _defaultOpts, opts );
-
-      // Load the theme
-      var themeInfo = genInfo.themeInfo;
-      var theme = themeInfo.theme;
-      var tFolder = themeInfo.folder;
-      var tplFolder = PATH.join( tFolder, 'src' );
-      var outFolder = parsePath(f).dirname;
-      var curFmt = theme.getFormat( this.format );
-      var that = this;
-
-      // "Generate": process individual files within the theme
-      genInfo.files.forEach(function( file ){
-
-        var thisFilePath;
-
-        if( theme.engine === 'jrs' ) {
-          file.info.orgPath = '';
-        }
-
-        if( file.info.action === 'transform' ) {
-          thisFilePath = PATH.join( outFolder, file.info.orgPath );
-          try {
-            if( that.onBeforeSave ) {
-              file.data = that.onBeforeSave({
-                theme: theme,
-                outputFile: (file.info.major ? f : thisFilePath),
-                mk: file.data,
-                opts: that.opts
-              });
-              if( !file.data ) return; // PDF etc
-            }
-            var fileName = file.info.major ? f : thisFilePath;
-            MKDIRP.sync( PATH.dirname( fileName ) );
-            FS.writeFileSync( fileName, file.data,
-              { encoding: 'utf8', flags: 'w' } );
-            that.onAfterSave && that.onAfterSave(
-              { outputFile: fileName, mk: file.data, opts: that.opts } );
-          }
-          catch(ex) {
-            require('../core/error-handler').err(ex, false);
-          }
-        }
-        else if( file.info.action === null/* && theme.explicit*/ ) {
-          thisFilePath = PATH.join( outFolder, file.info.orgPath );
-          try {
-            MKDIRP.sync( PATH.dirname(thisFilePath) );
-            FS.copySync( file.info.path, thisFilePath );
-          }
-          catch(ex) {
-            ex.showStack = true;
-            require('../core/error-handler').err( ex );
-          }
-        }
-      });
-
-      // Some themes require a symlink structure. If so, create it.
-      if( curFmt.symLinks ) {
-        Object.keys( curFmt.symLinks ).forEach( function(loc) {
-          var absLoc = PATH.join(outFolder, loc);
-          var absTarg = PATH.join(PATH.dirname(absLoc), curFmt.symLinks[loc]);
-           // 'file', 'dir', or 'junction' (Windows only)
-          var type = parsePath( absLoc ).extname ? 'file' : 'junction';
-          FS.symlinkSync( absTarg, absLoc, type);
-        });
-      }
-
-      return genInfo;
-
-    },
-
-
-
-    /**
-    Perform a single resume JSON-to-DEST resume transformation.
-    @param json A FRESH or JRS resume object.
-    @param jst The stringified template data
-    @param format The format name, such as "html" or "latex"
-    @param cssInfo Needs to be refactored.
-    @param opts Options and passthrough data.
-    */
-    single: function( json, jst, format, cssInfo, opts, theme ) {
-      this.opts.freezeBreaks && ( jst = freeze(jst) );
-
-      var eng = require( '../renderers/' + theme.engine  + '-generator' );
-      var result = eng.generate( json, jst, format, cssInfo, opts, theme );
-
-      this.opts.freezeBreaks && ( result = unfreeze(result) );
-      return result;
-    }
-
-
-  });
-
-
-
-  /**
-  Export the TemplateGenerator function/ctor.
-  */
-  module.exports = TemplateGenerator;
-
-
-
-  /**
-  Given a theme title, load the corresponding theme.
-  */
-  function themeFromMoniker() {
-
-    // Verify the specified theme name/path
-    var tFolder = PATH.join(
-      parsePath( require.resolve('fresh-themes') ).dirname,
-      '/themes/',
-      this.opts.theme
-    );
-
-    var t;
-    if( this.opts.theme.startsWith('jsonresume-theme-') ) {
-      t = new JRSTheme().open( tFolder );
-    }
-    else {
-      var exists = require('path-exists').sync;
-      if( !exists( tFolder ) ) {
-        tFolder = PATH.resolve( this.opts.theme );
-        if( !exists( tFolder ) ) {
-          throw { fluenterror: this.codes.themeNotFound, data: this.opts.theme};
-        }
-      }
-      t = this.opts.themeObj || new FRESHTheme().open( tFolder );
-    }
-
-    // Load the theme and format
-    return {
-      theme: t,
-      folder: tFolder
-    };
-  }
-
-
-
-  function transform( rez, tplInfo, theme ) {
-    try {
-      var cssInfo = {
-        file: tplInfo.css ? tplInfo.cssPath : null,
-        data: tplInfo.css || null
-      };
-
-      return this.single( rez, tplInfo.data, this.format, cssInfo, this.opts,
-        theme );
-    }
-    catch(ex) {
-      ex.showStack = true;
-      require('../core/error-handler').err( ex );
-    }
-  }
-
-
-
-  /**
-  Freeze newlines for protection against errant JST parsers.
-  */
-  function freeze( markup ) {
-    return markup
-      .replace( _reg.regN, _defaultOpts.nSym )
-      .replace( _reg.regR, _defaultOpts.rSym );
-  }
-
-
-
-  /**
-  Unfreeze newlines when the coast is clear.
-  */
-  function unfreeze( markup ) {
-    return markup
-      .replace( _reg.regSymR, '\r' )
-      .replace( _reg.regSymN, '\n' );
-  }
-
-
-
-  /**
-  Regexes for linebreak preservation.
-  */
+  /** Regexes for linebreak preservation. */
   var _reg = {
     regN: new RegExp( '\n', 'g' ),
     regR: new RegExp( '\r', 'g' ),

src/hackmyapi.js

@@ -19,7 +19,8 @@ External API surface for HackMyResume.
       analyze: require('./verbs/analyze'),
       validate: require('./verbs/validate'),
       convert: require('./verbs/convert'),
-      new: require('./verbs/create')
+      new: require('./verbs/create'),
+      peek: require('./verbs/peek')
     },
     alias: {
       generate: require('./verbs/build'),

src/helpers/console-helpers.js

@@ -0,0 +1,67 @@
+/**
+Generic template helper definitions for command-line output.
+@module console-helpers.js
+@license MIT. See LICENSE.md for details.
+*/
+
+(function() {
+
+
+
+  var PAD   = require('string-padding')
+    , LO    = require('lodash')
+    , CHALK = require('chalk')
+    , _     = require('underscore');
+              require('../utils/string');
+
+
+
+  var consoleFormatHelpers = module.exports = {
+
+    v: function( val, defaultVal, padding, style ) {
+      retVal = ( val === null || val === undefined ) ? defaultVal : val;
+      var spaces = 0;
+      if( String.is(padding) ) {
+        spaces = parseInt( padding, 10 );
+        if( isNaN(spaces) ) spaces = 0;
+      }
+      else if( _.isNumber(padding) ) {
+        spaces = padding;
+      }
+
+      if( spaces !== 0 )
+        retVal = PAD( retVal, Math.abs(spaces), null, spaces > 0 ? PAD.LEFT : PAD.RIGHT );
+
+      if( style && String.is( style )) {
+        retVal = LO.get( CHALK, style )( retVal );
+      }
+
+      return retVal;
+    },
+
+    gapLength: function(val) {
+      if( val < 35 )
+        return CHALK.green.bold(val);
+      else if( val < 95 )
+        return CHALK.yellow.bold(val);
+      else
+        return CHALK.red.bold(val);
+    },
+
+    style: function( val, style ) {
+      return LO.get( CHALK, style )( val );
+    },
+
+    isPlural: function( val, options ) {
+      if( val > 1 )
+        return options.fn(this);
+    },
+
+    pad: function( val, spaces ) {
+      return PAD(val, Math.abs(spaces), null, spaces > 0 ? PAD.LEFT : PAD.RIGHT );
+    }
+  };
+
+
+
+}());

src/helpers/generic-helpers.js

@@ -0,0 +1,609 @@
+/**
+Generic template helper definitions for HackMyResume / FluentCV.
+@license MIT. See LICENSE.md for details.
+@module helpers/generic-helpers
+*/
+
+
+(function() {
+
+  var MD = require('marked')
+    , H2W = require('../utils/html-to-wpml')
+    , XML = require('xml-escape')
+    , FluentDate = require('../core/fluent-date')
+    , HMSTATUS = require('../core/status-codes')
+    , moment = require('moment')
+    , FS = require('fs')
+    , LO = require('lodash')
+    , PATH = require('path')
+    , printf = require('printf')
+    , _ = require('underscore')
+    , unused = require('../utils/string');
+
+  /** Generic template helper function definitions. */
+  var GenericHelpers = module.exports = {
+
+    /**
+    Convert the input date to a specified format through Moment.js.
+    If date is invalid, will return the time provided by the user,
+    or default to the fallback param or 'Present' if that is set to true
+    @method formatDate
+    */
+    formatDate: function(datetime, format, fallback) {
+      if (moment) {
+        var momentDate = moment( datetime );
+        if (momentDate.isValid()) return momentDate.format(format);
+      }
+
+      return datetime || (typeof fallback == 'string' ? fallback : (fallback === true ? 'Present' : null));
+    },
+
+    /**
+    Given a resume sub-object with a start/end date, format a representation of
+    the date range.
+    @method dateRange
+    */
+    dateRange: function( obj, fmt, sep, fallback, options ) {
+      if( !obj ) return '';
+      return _fromTo( obj.start, obj.end, fmt, sep, fallback, options );
+    },
+
+    /**
+    Format a from/to date range for display.
+    @method toFrom
+    */
+    fromTo: function() {
+      return _fromTo.apply( this, arguments );
+    },
+
+    /**
+    Return a named color value as an RRGGBB string.
+    @method toFrom
+    */
+    color: function( colorName, colorDefault ) {
+      // Key must be specified
+      if( !( colorName && colorName.trim()) ) {
+        _reportError( HMSTATUS.invalidHelperUse, {
+          helper: 'fontList', error: HMSTATUS.missingParam, expected: 'name'
+        });
+      }
+      else {
+        if( !GenericHelpers.theme.colors ) return colorDefault;
+        var ret = GenericHelpers.theme.colors[ colorName ];
+        if( !(ret && ret.trim()) )
+          return colorDefault;
+        return ret;
+      }
+    },
+
+    /**
+    Return true if the section is present on the resume and has at least one
+    element.
+    @method section
+    */
+    section: function( title, options ) {
+      title = title.trim().toLowerCase();
+      var obj = LO.get( this.r, title );
+      if( _.isArray( obj ) ) {
+        return obj.length ? options.fn(this) : undefined;
+      }
+      else if( _.isObject( obj )) {
+        return ( (obj.history && obj.history.length) ||
+            ( obj.sets && obj.sets.length ) ) ?
+            options.fn(this) : undefined;
+      }
+    },
+
+    /**
+    Emit the size of the specified named font.
+    @param key {String} A named style from the "fonts" section of the theme's
+    theme.json file. For example: 'default' or 'heading1'.
+    */
+    fontSize: function( key, defSize, units ){
+
+      var ret = ''
+        , hasDef = defSize && ( String.is( defSize ) || _.isNumber( defSize ));
+
+      // Key must be specified
+      if( !( key && key.trim()) ) {
+        _reportError( HMSTATUS.invalidHelperUse, {
+          helper: 'fontSize', error: HMSTATUS.missingParam, expected: 'key'
+        });
+        return ret;
+      }
+
+      else if ( GenericHelpers.theme.fonts ) {
+        var fontSpec = LO.get( GenericHelpers.theme.fonts, this.format + '.' + key );
+        if( !fontSpec ) {
+          // Check for an "all" format
+          if( GenericHelpers.theme.fonts.all )
+            fontSpec = GenericHelpers.theme.fonts.all[ key ];
+        }
+        if( fontSpec ) {
+          // fontSpec can be a string, an array, or an object
+          if( String.is( fontSpec )) {
+            // No font size was specified, only a font family.
+          }
+          else if( _.isArray( fontSpec )) {
+            // An array of fonts were specified. Each one could be a string
+            // or an object
+            if( !String.is( fontSpec[0] )) {
+              ret = fontSpec[0].size;
+            }
+          }
+          else {
+            // A font description object.
+            ret = fontSpec.size;
+          }
+        }
+      }
+
+      // We weren't able to lookup the specified key. Default to defFont.
+      if( !ret ) {
+        if( hasDef )
+          ret = defSize;
+        else {
+          _reportError( HMSTATUS.invalidHelperUse, {
+            helper: 'fontSize', error: HMSTATUS.missingParam,
+            expected: 'defSize'});
+          ret = '';
+        }
+      }
+
+      return ret;
+
+    },
+
+    /**
+    Emit the font face (such as 'Helvetica' or 'Calibri') associated with the
+    provided key.
+    @param key {String} A named style from the "fonts" section of the theme's
+    theme.json file. For example: 'default' or 'heading1'.
+    @param defFont {String} The font to use if the specified key isn't present.
+    Can be any valid font-face name such as 'Helvetica Neue' or 'Calibri'.
+    */
+    fontFace: function( key, defFont ) {
+
+      var ret = ''
+        , hasDef = defFont && String.is( defFont );
+
+      // Key must be specified
+      if( !( key && key.trim()) ) {
+        _reportError( HMSTATUS.invalidHelperUse, {
+          helper: 'fontFace', error: HMSTATUS.missingParam, expected: 'key'
+        });
+        return ret;
+      }
+
+      // If the theme has a "fonts" section, lookup the font face.
+      else if( GenericHelpers.theme.fonts ) {
+        var fontSpec = LO.get( GenericHelpers.theme.fonts, this.format + '.' + key );
+        if( !fontSpec ) {
+          // Check for an "all" format
+          if( GenericHelpers.theme.fonts.all )
+            fontSpec = GenericHelpers.theme.fonts.all[ key ];
+        }
+        if( fontSpec ) {
+          // fontSpec can be a string, an array, or an object
+          if( String.is( fontSpec )) {
+            ret = fontSpec;
+          }
+          else if( _.isArray( fontSpec )) {
+            // An array of fonts were specified. Each one could be a string
+            // or an object
+            ret = String.is( fontSpec[0] ) ? fontSpec[0] : fontSpec[0].name;
+          }
+          else {
+            // A font description object.
+            ret = fontSpec.name;
+          }
+        }
+      }
+
+      // We weren't able to lookup the specified key. Default to defFont.
+      if( !(ret && ret.trim()) ) {
+        ret = defFont;
+        if( !hasDef ) {
+          _reportError( HMSTATUS.invalidHelperUse, {
+            helper: 'fontFace', error: HMSTATUS.missingParam,
+            expected: 'defFont'});
+          ret = '';
+        }
+      }
+
+      return ret;
+    },
+
+    /**
+    Emit a comma-delimited list of font names suitable associated with the
+    provided key.
+    @param key {String} A named style from the "fonts" section of the theme's
+    theme.json file. For example: 'default' or 'heading1'.
+    @param defFontList {Array} The font list to use if the specified key isn't
+    present. Can be an array of valid font-face name such as 'Helvetica Neue'
+    or 'Calibri'.
+    @param sep {String} The default separator to use in the rendered output.
+    Defaults to ", " (comma with a space).
+    */
+    fontList: function( key, defFontList, sep ) {
+
+      var ret = ''
+        , hasDef = defFontList && String.is( defFontList );
+
+      // Key must be specified
+      if( !( key && key.trim()) ) {
+        _reportError( HMSTATUS.invalidHelperUse, {
+          helper: 'fontList', error: HMSTATUS.missingParam, expected: 'key'
+        });
+      }
+
+      // If the theme has a "fonts" section, lookup the font list.
+      else if( GenericHelpers.theme.fonts ) {
+        var fontSpec = LO.get( GenericHelpers.theme.fonts, this.format + '.' + key );
+        if( !fontSpec ) {
+          if( GenericHelpers.theme.fonts.all )
+            fontSpec = GenericHelpers.theme.fonts.all[ key ];
+        }
+
+        if( fontSpec ) {
+          // fontSpec can be a string, an array, or an object
+          if( String.is( fontSpec )) {
+            ret = fontSpec;
+          }
+          else if( _.isArray( fontSpec )) {
+            // An array of fonts were specified. Each one could be a string
+            // or an object
+            fontSpec = fontSpec.map( function( ff ) {
+              return "'" + (String.is( ff ) ? ff : ff.name) + "'";
+            });
+            ret = fontSpec.join( sep === undefined ? ', ' : (sep || '') );
+          }
+          else {
+            // A font description object.
+            ret = fontSpec.name;
+          }
+
+        }
+      }
+
+      // The key wasn't found in the "fonts" section. Default to defFont.
+      if( !(ret && ret.trim()) ) {
+        if( !hasDef ) {
+          _reportError( HMSTATUS.invalidHelperUse, {
+            helper: 'fontList', error: HMSTATUS.missingParam,
+            expected: 'defFontList'});
+          ret = '';
+        }
+        else {
+          ret = defFontList;
+        }
+      }
+
+      return ret;
+    },
+
+    /**
+    Capitalize the first letter of the word.
+    @method section
+    */
+    camelCase: function(val) {
+      val = (val && val.trim()) || '';
+      return val ? (val.charAt(0).toUpperCase() + val.slice(1)) : val;
+    },
+
+    /**
+    Return true if the context has the property or subpropery.
+    @method has
+    */
+    has: function( title, options ) {
+      title = title && title.trim().toLowerCase();
+      if( LO.get( this.r, title ) ) {
+        return options.fn(this);
+      }
+    },
+
+    /**
+    Generic template helper function to display a user-overridable section
+    title for a FRESH resume theme. Use this in lieue of hard-coding section
+    titles.
+
+    Usage:
+
+        {{sectionTitle "sectionName"}}
+        {{sectionTitle "sectionName" "sectionTitle"}}
+
+    Example:
+
+        {{sectionTitle "Education"}}
+        {{sectionTitle "Employment" "Project History"}}
+
+    @param sect_name The name of the section being title. Must be one of the
+    top-level FRESH resume sections ("info", "education", "employment", etc.).
+    @param sect_title The theme-specified section title. May be replaced by the
+    user.
+    @method sectionTitle
+    */
+    sectionTitle: function( sname, stitle ) {
+
+      // If not provided by the user, stitle should default to sname. ps.
+      // Handlebars silently passes in the options object to the last param,
+      // where in Underscore stitle will be null/undefined, so we check both.
+      stitle = (stitle && String.is(stitle) && stitle) || sname;
+
+      // If there's a section title override, use it.
+      return ( this.opts.stitles &&
+               this.opts.stitles[ sname.toLowerCase().trim() ] ) ||
+               stitle;
+    },
+
+    /**
+    Convert inline Markdown to inline WordProcessingML.
+    @method wpml
+    */
+    wpml: function( txt, inline ) {
+      if(!txt) return '';
+      inline = (inline && !inline.hash) || false;
+      txt = XML(txt.trim());
+      txt = inline ?
+        MD(txt).replace(/^\s*<p>|<\/p>\s*$/gi, '') :
+        MD(txt);
+      txt = H2W( txt );
+      return txt;
+    },
+
+    /**
+    Emit a conditional link.
+    @method link
+    */
+    link: function( text, url ) {
+      return url && url.trim() ?
+        ('<a href="' + url + '">' + text + '</a>') : text;
+    },
+
+    /**
+    Return the last word of the specified text.
+    @method lastWord
+    */
+    lastWord: function( txt ) {
+      return txt && txt.trim() ? _.last( txt.split(' ') ) : '';
+    },
+
+    /**
+    Convert a skill level to an RGB color triplet. TODO: refactor
+    @method skillColor
+    @param lvl Input skill level. Skill level can be expressed as a string
+    ("beginner", "intermediate", etc.), as an integer (1,5,etc), as a string
+    integer ("1", "5", etc.), or as an RRGGBB color triplet ('#C00000',
+    '#FFFFAA').
+    */
+    skillColor: function( lvl ) {
+      var idx = skillLevelToIndex( lvl );
+      var skillColors = (this.theme && this.theme.palette &&
+        this.theme.palette.skillLevels) ||
+        [ '#FFFFFF', '#5CB85C', '#F1C40F', '#428BCA', '#C00000' ];
+      return skillColors[idx];
+    },
+
+    /**
+    Return an appropriate height. TODO: refactor
+    @method lastWord
+    */
+    skillHeight: function( lvl ) {
+      var idx = skillLevelToIndex( lvl );
+      return ['38.25', '30', '16', '8', '0'][idx];
+    },
+
+    /**
+    Return all but the last word of the input text.
+    @method initialWords
+    */
+    initialWords: function( txt ) {
+      return txt && txt.trim() ? _.initial( txt.split(' ') ).join(' ') : '';
+    },
+
+    /**
+    Trim the protocol (http or https) from a URL/
+    @method trimURL
+    */
+    trimURL: function( url ) {
+      return url && url.trim() ? url.trim().replace(/^https?:\/\//i, '') : '';
+    },
+
+    /**
+    Convert text to lowercase.
+    @method toLower
+    */
+    toLower: function( txt ) {
+      return txt && txt.trim() ? txt.toLowerCase() : '';
+    },
+
+    /**
+    Convert text to lowercase.
+    @method toLower
+    */
+    toUpper: function( txt ) {
+      return txt && txt.trim() ? txt.toUpperCase() : '';
+    },
+
+    /**
+    Return true if either value is truthy.
+    @method either
+    */
+    either: function( lhs, rhs, options ) {
+      if (lhs || rhs) return options.fn(this);
+    },
+
+    /**
+    Conditional stylesheet link. Creates a link to the specified stylesheet with
+    <link> or embeds the styles inline with <style></style>, depending on the
+    theme author's and user's preferences.
+    @param url {String} The path to the CSS file.
+    @param linkage {String} The default link method. Can be either `embed` or
+    `link`. If omitted, defaults to `embed`. Can be overridden by the `--css`
+    command-line switch.
+    */
+
+    styleSheet: function( url, linkage ) {
+
+      // Establish the linkage style
+      linkage = this.opts.css || linkage || 'embed';
+
+      // Create the <link> or <style> tag
+      var ret = '';
+      if( linkage === 'link' ) {
+        ret = printf('<link href="%s" rel="stylesheet" type="text/css">', url);
+      }
+      else {
+        var rawCss = FS.readFileSync(
+          PATH.join( this.opts.themeObj.folder, '/src/', url ), 'utf8' );
+        var renderedCss = this.engine.generateSimple( this, rawCss );
+        ret = printf('<style>%s</style>', renderedCss );
+      }
+
+      // If the currently-executing template is inherited, append styles
+      if( this.opts.themeObj.inherits &&
+          this.opts.themeObj.inherits.html &&
+          this.format === 'html' ) {
+        ret += (linkage === 'link') ?
+          '<link href="' + this.opts.themeObj.overrides.path +
+          '" rel="stylesheet" type="text/css">' :
+          '<style>' + this.opts.themeObj.overrides.data + '</style>';
+      }
+
+      // TODO: It would be nice to use Handlebar.SafeString here, but these
+      // are supposed to be generic helpers. Provide an equivalent, or expose
+      // it when Handlebars is the chosen engine, which is most of the time.
+      return ret;
+    },
+
+    /**
+    Perform a generic comparison.
+    See: http://doginthehat.com.au/2012/02/comparison-block-helper-for-handlebars-templates
+    @method compare
+    */
+    compare: function(lvalue, rvalue, options) {
+      if (arguments.length < 3)
+        throw new Error("Handlerbars Helper 'compare' needs 2 parameters");
+      var operator = options.hash.operator || "==";
+      var operators = {
+          '==':       function(l,r) { return l == r; },
+          '===':      function(l,r) { return l === r; },
+          '!=':       function(l,r) { return l != r; },
+          '<':        function(l,r) { return l < r; },
+          '>':        function(l,r) { return l > r; },
+          '<=':       function(l,r) { return l <= r; },
+          '>=':       function(l,r) { return l >= r; },
+          'typeof':   function(l,r) { return typeof l == r; }
+      };
+      if (!operators[operator])
+        throw new Error("Handlerbars Helper 'compare' doesn't know the operator "+operator);
+      var result = operators[operator](lvalue,rvalue);
+      return result ? options.fn(this) : options.inverse(this);
+    }
+
+  };
+
+
+  /**
+  Report an error to the outside world without throwing an exception. Currently
+  relies on kludging the running verb into. opts.
+  */
+  function _reportError( code, params ) {
+    GenericHelpers.opts.errHandler.err( code, params );
+  }
+
+  /**
+  Format a from/to date range for display.
+  */
+  function _fromTo( dateA, dateB, fmt, sep, fallback ) {
+
+    // Prevent accidental use of safe.start, safe.end, safe.date
+    // The dateRange helper is for raw dates only
+    if( moment.isMoment( dateA ) || moment.isMoment( dateB ) ) {
+      _reportError( HMSTATUS.invalidHelperUse, { helper: 'dateRange' } );
+      return '';
+    }
+
+    var dateFrom, dateTo, dateTemp;
+
+    // Check for 'current', 'present', 'now', '', null, and undefined
+    dateA = dateA || '';
+    dateB = dateB || '';
+    var dateATrim = dateA.trim().toLowerCase();
+    var dateBTrim = dateB.trim().toLowerCase();
+    var reserved = ['current','present','now', ''];
+
+    fmt = (fmt && String.is(fmt) && fmt) || 'YYYY-MM';
+    sep = (sep && String.is(sep) && sep) || ' — ';
+
+    if( _.contains( reserved, dateATrim )) {
+      dateFrom = fallback || '???';
+    }
+    else {
+      dateTemp = FluentDate.fmt( dateA );
+      dateFrom = dateTemp.format( fmt );
+    }
+
+    if( _.contains( reserved, dateBTrim )) {
+      dateTo = fallback || 'Current';
+    }
+    else {
+      dateTemp = FluentDate.fmt( dateB );
+      dateTo = dateTemp.format( fmt );
+    }
+
+    if( dateFrom && dateTo ) {
+      return dateFrom + sep + dateTo;
+    }
+    else if( dateFrom || dateTo ) {
+      return dateFrom || dateTo;
+    }
+
+    return '';
+  }
+
+  function skillLevelToIndex( lvl ) {
+    var idx = 0;
+    if( String.is( lvl ) ) {
+      lvl = lvl.trim().toLowerCase();
+      var intVal = parseInt( lvl );
+      if( isNaN( intVal ) ) {
+        switch( lvl ) {
+          case 'beginner': idx = 1; break;
+          case 'intermediate': idx = 2; break;
+          case 'advanced': idx = 3; break;
+          case 'master': idx = 4; break;
+        }
+      }
+      else {
+        idx = Math.min( intVal / 2, 4 );
+        idx = Math.max( 0, idx );
+      }
+    }
+    else {
+      idx = Math.min( lvl / 2, 4 );
+      idx = Math.max( 0, idx );
+    }
+    return idx;
+  }
+
+}());
+
+// Note [1] --------------------------------------------------------------------
+// Make sure it's precisely a string or array since some template engines jam
+// their options/context object into the last parameter and we are allowing the
+// defFont parameter to be omitted in certain cases. This is a little kludgy,
+// but works fine for this case. If we start doing this regularly, we should
+// rebind these parameters.
+
+// Note [2]: -------------------------------------------------------------------
+// If execution reaches here, some sort of cosmic ray or sunspot has landed on
+// HackMyResume, or a theme author is deliberately messing with us by doing
+// something like:
+//
+// "fonts": {
+//   "default": "",
+//   "heading1": null
+// }
+//
+// Rather than sort it out, we'll just fall back to defFont.

src/helpers/handlebars-helpers.js

@@ -15,9 +15,10 @@ Template helper definitions for Handlebars.
   Register useful Handlebars helpers.
   @method registerHelpers
   */
-  module.exports = function( theme ) {
+  module.exports = function( theme, opts ) {
 
     helpers.theme = theme;
+    helpers.opts = opts;
     HANDLEBARS.registerHelper( helpers );
 
   };

src/helpers/underscore-helpers.js

@@ -0,0 +1,34 @@
+/**
+Template helper definitions for Underscore.
+@license MIT. Copyright (c) 2016 hacksalot (https://github.com/hacksalot)
+@module handlebars-helpers.js
+*/
+
+
+(function() {
+
+  var HANDLEBARS = require('handlebars')
+  , _ = require('underscore')
+  , helpers = require('./generic-helpers');
+
+  /**
+  Register useful Underscore helpers.
+  @method registerHelpers
+  */
+  module.exports = function( theme, opts, cssInfo, ctx, eng ) {
+
+    helpers.theme = theme;
+    helpers.opts = opts;
+    helpers.cssInfo = cssInfo;
+    helpers.engine = eng;
+    ctx.h = helpers;
+
+    _.each( helpers, function( hVal, hKey ) {
+      if( _.isFunction( hVal )) {
+        _.bind( hVal, ctx );
+      }
+    }, this);
+
+  };
+
+}());

src/index.js

@@ -4,242 +4,19 @@
 
 /**
 Command-line interface (CLI) for HackMyResume.
-@license MIT. Copyright (c) 2015 hacksalot (https://github.com/hacksalot)
+@license MIT. See LICENSE.md for details.
 @module index.js
 */
 
 
 
-var SPAWNW = require('./core/spawn-watch')
-  , HMR  = require( './hackmyapi')
-  , PKG = require('../package.json')
-  , FS = require('fs')
-  , EXTEND = require('./utils/extend')
-  , chalk = require('chalk')
-  , PATH = require('path')
-  , HACKMYSTATUS = require('./core/status-codes')
-  , safeLoadJSON = require('./utils/safe-json-loader')
-  , _opts = { }
-  , title = chalk.white.bold('\n*** HackMyResume v' + PKG.version + ' ***')
-  , StringUtils = require('./utils/string.js')
-  , _ = require('underscore')
-  , Command = require('commander').Command;
-
-
-
 try {
-  main();
+
+  require('./cli/main')( process.argv );
+
 }
 catch( ex ) {
-  require('./core/error-handler').err( ex, true );
-}
 
-
-/**
-Kick off the HackMyResume application.
-*/
-function main() {
-
-  var args = initialize();
-
-  // Create the top-level (application) command...
-  var program = new Command('hackmyresume')
-    .version(PKG.version)
-    .description(chalk.yellow.bold('*** HackMyResume ***'))
-    .option('-o --opts <optionsFile>', 'Path to a .hackmyrc options file')
-    .option('-s --silent', 'Run in silent mode')
-    .option('--no-color', 'Disable colors')
-    .option('--color', 'Enable colors')
-    .option('-d --debug', 'Enable diagnostics', false);
-    //.usage('COMMAND <sources> [TO <targets>]');
-
-  // Create the NEW command
-  program
-    .command('new')
-    .arguments('<sources...>')
-    .option('-f --format <fmt>', 'FRESH or JRS format', 'FRESH')
-    .alias('create')
-    .description('Create resume(s) in FRESH or JSON RESUME format.')
-    .action(function( sources ) {
-      execVerb.call( this, sources, [], this.opts(), logMsg);
-    });
-
-  // Create the VALIDATE command
-  program
-    .command('validate')
-    .arguments('<sources...>')
-    .option('-a --assert', 'Treat validation warnings as errors', false)
-    .description('Validate a resume in FRESH or JSON RESUME format.')
-    .action(function(sources) {
-      execVerb.call( this, sources, [], this.opts(), logMsg);
-    });
-
-  // Create the CONVERT command
-  program
-    .command('convert')
-    //.arguments('<sources...>')
-    .description('Convert a resume to/from FRESH or JSON RESUME format.')
-    .action(function() {
-      var x = splitSrcDest.call( this );
-      execVerb.call( this, x.src, x.dst, this.opts(), logMsg);
-    });
-
-  // Create the ANALYZE command
-  program
-    .command('analyze')
-    .arguments('<sources...>')
-    .description('Analyze one or more resumes.')
-    .action(function( sources ) {
-      execVerb.call( this, sources, [], this.opts(), logMsg);
-    });
-
-  // Create the BUILD command
-  program
-    .command('build')
-    .alias('generate')
-    //.arguments('<sources> TO [targets]')
-    //.usage('...')
-    .option('-t --theme <theme>', 'Theme name or path')
-    .option('-n --no-prettify', 'Disable HTML prettification', true)
-    .option('-c --css <option>', 'CSS linking / embedding', 'embed')
-    .option('-p --pdf <engine>', 'PDF generation engine')
-    .option('--no-tips', 'Disable theme tips and warnings.', false)
-    .description('Generate resume to multiple formats')
-    .action(function( sources, targets, options ) {
-      var x = splitSrcDest.call( this );
-      execVerb.call( this, x.src, x.dst, this.opts(), logMsg);
-    });
-
-  // program.on('--help', function(){
-  //   console.log('  Examples:');
-  //   console.log('');
-  //   console.log('    $ custom-help --help');
-  //   console.log('    $ custom-help -h');
-  //   console.log('');
-  // });
-
-  program.parse( args );
-
-  if (!program.args.length) { throw { fluenterror: 4 }; }
+  require('./cli/error').err( ex, true );
 
 }
-
-
-
-
-
-/**
-Massage command-line args and setup Commander.js.
-*/
-function initialize() {
-
-  logMsg( title );
-
-  // Support case-insensitive sub-commands (build, generate, validate, etc.)..
-  var oVerb, verb = '', args = process.argv.slice(), cleanArgs = args.slice(2);
-  if( cleanArgs.length ) {
-    var verbIdx = _.findIndex( cleanArgs, function(v){ return v[0] !== '-'; });
-    if( verbIdx !== -1 ) {
-      oVerb = cleanArgs[ verbIdx ];
-      verb = args[ verbIdx + 2 ] = oVerb.trim().toLowerCase();
-    }
-  }
-
-  // Handle invalid verbs here (a bit easier here than in commander.js)...
-  if( verb && !HMR.verbs[ verb ] && !HMR.alias[ verb ] ) {
-    throw { fluenterror: HACKMYSTATUS.invalidCommand, shouldExit: true,
-            attempted: oVerb };
-  }
-
-  // Override the .missingArgument behavior
-  Command.prototype.missingArgument = function(name) {
-    if( this.name() !== 'new' )
-      throw { fluenterror: HACKMYSTATUS.resumeNotFound };
-  };
-
-  // Override the .helpInformation behavior
-  Command.prototype.helpInformation = function() {
-    var manPage = FS.readFileSync( PATH.join(__dirname, 'use.txt'), 'utf8' );
-    return chalk.green.bold(manPage);
-  };
-
-  return args;
-}
-
-
-
-/**
-Invoke a HackMyResume verb.
-*/
-function execVerb( src, dst, opts, log ) {
-  loadOptions.call( this, opts );
-  require('./core/error-handler').init( _opts.debug );
-  HMR.verbs[ this.name() ].call( null, src, dst, _opts, log );
-}
-
-
-
-/**
-Initialize HackMyResume options.
-*/
-function loadOptions( o ) {
-
-  o.opts = this.parent.opts;
-
-  // Load the specified options file (if any) and apply options
-  if( o.opts && String.is( o.opts )) {
-    var json = safeLoadJSON( PATH.relative( process.cwd(), o.opts ) );
-    json && ( o = EXTEND( true, o, json ) );
-    if( !json ) {
-      throw safeLoadJSON.error;
-    }
-  }
-
-  // Merge in command-line options
-  o = EXTEND( true, o, this.opts() );
-  o.silent = this.parent.silent;
-  o.debug = this.parent.debug;
-  _opts = o;
-}
-
-
-
-/**
-Split multiple command-line filenames by the 'TO' keyword
-*/
-function splitSrcDest() {
-
-  var params = this.parent.args.filter(function(j) { return String.is(j); });
-  if( params.length === 0 )
-    throw { fluenterror: HACKMYSTATUS.resumeNotFound };
-
-  // Find the TO keyword, if any
-  var splitAt = _.findIndex( params, function(p) {
-    return p.toLowerCase() === 'to';
-  });
-
-  // TO can't be the last keyword
-  if( splitAt === params.length - 1 && splitAt !== -1 ) {
-    logMsg(chalk.yellow('Please ') +
-      chalk.yellow.bold('specify an output file') +
-      chalk.yellow(' for this operation or ') +
-      chalk.yellow.bold('omit the TO keyword') +
-      chalk.yellow('.') );
-    return;
-  }
-
-  return {
-    src: params.slice(0, splitAt === -1 ? undefined : splitAt ),
-    dst: splitAt === -1 ? [] : params.slice( splitAt + 1 )
-  };
-}
-
-
-
-/**
-Simple logging placeholder.
-*/
-function logMsg( msg ) {
-  msg = msg || '';
-  _opts.silent || console.log( msg );
-}

src/inspectors/gap-inspector.js

@@ -1,7 +1,7 @@
 /**
 Employment gap analysis for HackMyResume.
 @license MIT. See LICENSE.md for details.
-@module gap-inspector.js
+@module inspectors/gap-inspector
 */
 
 
@@ -19,7 +19,6 @@ Employment gap analysis for HackMyResume.
 
   /**
   Identify gaps in the candidate's employment history.
-  @class gapInspector
   */
   var gapInspector = module.exports = {
 
@@ -32,8 +31,9 @@ Employment gap analysis for HackMyResume.
     /**
     Run the Gap Analyzer on a resume.
     @method run
-    @return An array of object representing gaps in the candidate's employment
-    history. Each object provides the start, end, and duration of the gap:
+    @return {Array} An array of object representing gaps in the candidate's
+    employment history. Each object provides the start, end, and duration of the
+    gap:
         { <-- gap
           start: // A Moment.js date
           end: // A Moment.js date

src/inspectors/keyword-inspector.js

@@ -17,6 +17,8 @@ Keyword analysis for HackMyResume.
 
   /**
   Analyze the resume's use of keywords.
+  TODO: BUG: Keyword search regex is inaccurate, especially for one or two
+  letter keywords like "C" or "CLI".
   @class keywordInspector
   */
   var keywordInspector = module.exports = {
@@ -37,19 +39,44 @@ Keyword analysis for HackMyResume.
     */
     run: function( rez ) {
 
+      // "Quote" or safely escape a keyword so it can be used as a regex. For
+      // example, if the keyword is "C++", yield "C\+\+".
       // http://stackoverflow.com/a/2593661/4942583
       function regex_quote(str) {
         return (str + '').replace(/[.?*+^$[\]\\(){}|-]/ig, "\\$&");
       }
 
+      // Create a searchable plain-text digest of the resume
+      // TODO: BUG: Don't search within keywords for other keywords. Job A
+      // declares the "foo" keyword. Job B declares the "foo & bar" keyword. Job
+      // B's mention of "foobar" should not count as a mention of "foo".
+      // To achieve this, remove keywords from the search digest and treat them
+      // separately.
       var searchable = '';
       rez.transformStrings( ['imp', 'computed', 'safe'], function trxString( key, val ) {
         searchable += ' ' + val;
       });
 
+      // Assemble a regex skeleton we can use to test for keywords with a bit
+      // more 
+      var prefix = '(?:' + ['^', '\\s+', '[\\.,]+'].join('|') + ')';
+      var suffix = '(?:' + ['$', '\\s+', '[\\.,]+'].join('|') + ')';
+
       return rez.keywords().map(function(kw) {
-        //var regex = new RegExp( '\\b' + regex_quote( kw )/* + '\\b'*/, 'ig');
-        var regex = new RegExp( regex_quote( kw ), 'ig');
+
+        // 1. Using word boundary or other regex class is inaccurate
+        //
+        //    var regex = new RegExp( '\\b' + regex_quote( kw )/* + '\\b'*/, 'ig');
+        //
+        // 2. Searching for the raw keyword is inaccurate ("C" will match any
+        // word containing a 'c'!).
+        //
+        //    var regex = new RegExp( regex_quote( kw ), 'ig');
+        //
+        // 3. Instead, use a custom regex with special delimeters.
+
+        var regex_str = prefix + regex_quote( kw ) + suffix;
+        var regex = new RegExp( regex_str, 'ig');
         var myArray, count = 0;
         while ((myArray = regex.exec( searchable )) !== null) {
           count++;

src/inspectors/totals-inspector.js

@@ -30,25 +30,29 @@ Section analysis for HackMyResume.
     /**
     Run the Totals Inspector on a resume.
     @method run
-    @return An array of objects containing summary information for each section
-    on the resume.
+    @return An object containing summary information for each section on the
+    resume.
     */
     run: function( rez ) {
 
-      var ret = { };
+      var sectionTotals = { };
       _.each( rez, function(val, key){
         if( _.isArray( val ) && !_.isString(val) ) {
-          ret[ key ] = val.length;
+          sectionTotals[ key ] = val.length;
         }
         else if( val.history && _.isArray( val.history ) ) {
-          ret[ key ] = val.history.length;
+          sectionTotals[ key ] = val.history.length;
         }
         else if( val.sets && _.isArray( val.sets ) ) {
-          ret[ key ] = val.sets.length;
+          sectionTotals[ key ] = val.sets.length;
         }
       });
 
-      return ret;
+      return {
+        totals: sectionTotals,
+        numSections: Object.keys( sectionTotals ).length
+      };
+
     }
 
 

src/renderers/generic-helpers.js

@@ -1,290 +0,0 @@
-/**
-Generic template helper definitions for HackMyResume / FluentCV.
-@license MIT. See LICENSE.md for details.
-@module generic-helpers.js
-*/
-
-
-(function() {
-
-  var MD = require('marked')
-    , H2W = require('../utils/html-to-wpml')
-    , XML = require('xml-escape')
-    , moment = require('moment')
-    , LO = require('lodash')
-    , _ = require('underscore')
-    , unused = require('../utils/string');
-
-  /**
-  Generic template helper function definitions.
-  @class GenericHelpers
-  */
-  var GenericHelpers = module.exports = {
-
-    /**
-    Convert the input date to a specified format through Moment.js.
-    If date is invalid, will return the time provided by the user, 
-    or default to the fallback param or 'Present' if that is set to true
-    @method formatDate
-    */
-    formatDate: function(datetime, format, fallback) {
-      if (moment) {
-        var momentDate = moment( datetime );
-        if (momentDate.isValid()) return momentDate.format(format);
-      }
-
-      return datetime || (typeof fallback == 'string' ? fallback : (fallback === true ? 'Present' : null));
-    },
-
-    /**
-    Format a from/to date range.
-    @method dateRange
-    */
-    dateRange: function( obj, fmt, sep, options ) {
-      fmt = (fmt && String.is(fmt) && fmt) || 'YYYY-MM';
-      sep = (sep && String.is(sep) && sep) || ' — ';
-      if( obj.safe ) {
-        var dateA = (obj.safe.start && obj.safe.start.format(fmt)) || '';
-        var dateB = (obj.safe.end && obj.safe.end.format(fmt)) || '';
-        if( obj.safe.start && obj.safe.end ) {
-          return dateA + sep + dateB ;
-        }
-        else if( obj.safe.start || obj.safe.end ) {
-          return dateA || dateB;
-        }
-      }
-      return '';
-    },
-
-    /**
-    Return true if the section is present on the resume and has at least one
-    element.
-    @method section
-    */
-    section: function( title, options ) {
-      title = title.trim().toLowerCase();
-      var obj = LO.get( this.r, title );
-      if( _.isArray( obj ) ) {
-        return obj.length ? options.fn(this) : undefined;
-      }
-      else if( _.isObject( obj )) {
-        return ( (obj.history && obj.history.length) ||
-            ( obj.sets && obj.sets.length ) ) ?
-            options.fn(this) : undefined;
-      }
-    },
-
-    /**
-    Capitalize the first letter of the word.
-    @method section
-    */
-    camelCase: function(val) {
-      val = (val && val.trim()) || '';
-      return val ? (val.charAt(0).toUpperCase() + val.slice(1)) : val;
-    },
-
-    /**
-    Return true if the context has the property or subpropery.
-    @method has
-    */
-    has: function( title, options ) {
-      title = title && title.trim().toLowerCase();
-      if( LO.get( this.r, title ) ) {
-        return options.fn(this);
-      }
-    },
-
-    /**
-    Generic template helper function to display a user-overridable section
-    title for a FRESH resume theme. Use this in lieue of hard-coding section
-    titles.
-
-    Usage:
-
-        {{sectionTitle "sectionName"}}
-        {{sectionTitle "sectionName" "sectionTitle"}}
-
-    Example:
-
-        {{sectionTitle "Education"}}
-        {{sectionTitle "Employment" "Project History"}}
-
-    @param sect_name The name of the section being title. Must be one of the
-    top-level FRESH resume sections ("info", "education", "employment", etc.).
-    @param sect_title The theme-specified section title. May be replaced by the
-    user.
-    @method sectionTitle
-    */
-    sectionTitle: function( sname, stitle ) {
-
-      // If not provided by the user, stitle should default to sname. ps.
-      // Handlebars silently passes in the options object to the last param,
-      // where in Underscore stitle will be null/undefined, so we check both.
-      stitle = (stitle && String.is(stitle) && stitle) || sname;
-
-      // If there's a section title override, use it.
-      return ( this.opts.stitles &&
-               this.opts.stitles[ sname.toLowerCase().trim() ] ) ||
-               stitle;
-    },
-
-    /**
-    Convert inline Markdown to inline WordProcessingML.
-    @method wpml
-    */
-    wpml: function( txt, inline ) {
-      if(!txt) return '';
-      inline = (inline && !inline.hash) || false;
-      txt = XML(txt.trim());
-      txt = inline ?
-        MD(txt).replace(/^\s*<p>|<\/p>\s*$/gi, '') :
-        MD(txt);
-      txt = H2W( txt );
-      return txt;
-    },
-
-    /**
-    Emit a conditional link.
-    @method link
-    */
-    link: function( text, url ) {
-      return url && url.trim() ?
-        ('<a href="' + url + '">' + text + '</a>') : text;
-    },
-
-    /**
-    Return the last word of the specified text.
-    @method lastWord
-    */
-    lastWord: function( txt ) {
-      return txt && txt.trim() ? _.last( txt.split(' ') ) : '';
-    },
-
-    /**
-    Convert a skill level to an RGB color triplet. TODO: refactor
-    @method skillColor
-    @param lvl Input skill level. Skill level can be expressed as a string
-    ("beginner", "intermediate", etc.), as an integer (1,5,etc), as a string
-    integer ("1", "5", etc.), or as an RRGGBB color triplet ('#C00000',
-    '#FFFFAA').
-    */
-    skillColor: function( lvl ) {
-      var idx = skillLevelToIndex( lvl );
-      var skillColors = (this.theme && this.theme.palette &&
-        this.theme.palette.skillLevels) ||
-        [ '#FFFFFF', '#5CB85C', '#F1C40F', '#428BCA', '#C00000' ];
-      return skillColors[idx];
-    },
-
-    /**
-    Return an appropriate height. TODO: refactor
-    @method lastWord
-    */
-    skillHeight: function( lvl ) {
-      var idx = skillLevelToIndex( lvl );
-      return ['38.25', '30', '16', '8', '0'][idx];
-    },
-
-    /**
-    Return all but the last word of the input text.
-    @method initialWords
-    */
-    initialWords: function( txt ) {
-      return txt && txt.trim() ? _.initial( txt.split(' ') ).join(' ') : '';
-    },
-
-    /**
-    Trim the protocol (http or https) from a URL/
-    @method trimURL
-    */
-    trimURL: function( url ) {
-      return url && url.trim() ? url.trim().replace(/^https?:\/\//i, '') : '';
-    },
-
-    /**
-    Convert text to lowercase.
-    @method toLower
-    */
-    toLower: function( txt ) {
-      return txt && txt.trim() ? txt.toLowerCase() : '';
-    },
-
-    /**
-    Return true if either value is truthy.
-    @method either
-    */
-    either: function( lhs, rhs, options ) {
-      if (lhs || rhs) return options.fn(this);
-    },
-
-    /**
-    Conditional stylesheet link. Either display the link or embed the stylesheet
-    via <style></style> tag.
-    */
-    styleSheet: function( file, options ) {
-      var styles = ( this.opts.css === 'link') ?
-        '<link href="' + file + '" rel="stylesheet" type="text/css">' :
-        '<style>' + this.cssInfo.data + '</style>';
-      if( this.opts.themeObj.inherits &&
-          this.opts.themeObj.inherits.html &&
-          this.format === 'html' ) {
-        styles += (this.opts.css === 'link') ?
-          '<link href="' + this.opts.themeObj.overrides.path + '" rel="stylesheet" type="text/css">' :
-          '<style>' + this.opts.themeObj.overrides.data + '</style>';
-      }
-      return styles;
-    },
-
-    /**
-    Perform a generic comparison.
-    See: http://doginthehat.com.au/2012/02/comparison-block-helper-for-handlebars-templates
-    @method compare
-    */
-    compare: function(lvalue, rvalue, options) {
-      if (arguments.length < 3)
-        throw new Error("Handlerbars Helper 'compare' needs 2 parameters");
-      var operator = options.hash.operator || "==";
-      var operators = {
-          '==':       function(l,r) { return l == r; },
-          '===':      function(l,r) { return l === r; },
-          '!=':       function(l,r) { return l != r; },
-          '<':        function(l,r) { return l < r; },
-          '>':        function(l,r) { return l > r; },
-          '<=':       function(l,r) { return l <= r; },
-          '>=':       function(l,r) { return l >= r; },
-          'typeof':   function(l,r) { return typeof l == r; }
-      };
-      if (!operators[operator])
-        throw new Error("Handlerbars Helper 'compare' doesn't know the operator "+operator);
-      var result = operators[operator](lvalue,rvalue);
-      return result ? options.fn(this) : options.inverse(this);
-    }
-
-  };
-
-  function skillLevelToIndex( lvl ) {
-    var idx = 0;
-    if( String.is( lvl ) ) {
-      lvl = lvl.trim().toLowerCase();
-      var intVal = parseInt( lvl );
-      if( isNaN( intVal ) ) {
-        switch( lvl ) {
-          case 'beginner': idx = 1; break;
-          case 'intermediate': idx = 2; break;
-          case 'advanced': idx = 3; break;
-          case 'master': idx = 4; break;
-        }
-      }
-      else {
-        idx = Math.min( intVal / 2, 4 );
-        idx = Math.max( 0, idx );
-      }
-    }
-    else {
-      idx = Math.min( lvl / 2, 4 );
-      idx = Math.max( 0, idx );
-    }
-    return idx;
-  }
-
-}());

src/renderers/handlebars-generator.js

@@ -1,7 +1,7 @@
 /**
 Definition of the HandlebarsGenerator class.
 @license MIT. See LICENSE.md for details.
-@module handlebars-generator.js
+@module renderers/handlebars-generator
 */
 
 
@@ -13,10 +13,11 @@ Definition of the HandlebarsGenerator class.
   var _ = require('underscore')
     , HANDLEBARS = require('handlebars')
     , FS = require('fs')
-    , registerHelpers = require('./handlebars-helpers')
+    , registerHelpers = require('../helpers/handlebars-helpers')
     , PATH = require('path')
     , parsePath = require('parse-filepath')
     , READFILES = require('recursive-readdir-sync')
+    , HMSTATUS = require('../core/status-codes')
     , SLASH = require('slash');
 
 
@@ -29,29 +30,50 @@ Definition of the HandlebarsGenerator class.
 
 
 
+    generateSimple: function( data, tpl ) {
 
-    generate: function( json, jst, format, cssInfo, opts, theme ) {
+      try {
+        // Compile and run the Handlebars template.
+        var template = HANDLEBARS.compile( tpl, { strict: false, assumeObjects: false } );
+        return template( data );
+      }
+      catch( ex ) {
+        throw {
+          fluenterror: template ?
+            HMSTATUS.invokeTemplate : HMSTATUS.compileTemplate,
+          inner: ex
+        };
+      }
 
+    },
+
+
+
+    generate: function( json, jst, format, curFmt, opts, theme ) {
+
+      // Set up partials and helpers
       registerPartials( format, theme );
-      registerHelpers( theme );
+      registerHelpers( theme, opts );
 
       // Preprocess text
       var encData = json;
       ( format === 'html' || format === 'pdf' ) && (encData = json.markdownify());
       ( format === 'doc' ) && (encData = json.xmlify());
 
-      // Compile and run the Handlebars template.
-      var template = HANDLEBARS.compile(jst, { strict: false, assumeObjects: false });
-      return template({
+      // Set up the context
+      var ctx = {
         r: encData,
         RAW: json,
         filt: opts.filters,
-        cssInfo: cssInfo,
         format: format,
         opts: opts,
+        engine: this,
+        results: curFmt.files,
         headFragment: opts.headFragment || ''
-      });
+      };
 
+      // Render the template
+      return this.generateSimple( ctx, jst );
     }
 
 
@@ -61,7 +83,7 @@ Definition of the HandlebarsGenerator class.
 
 
   function registerPartials(format, theme) {
-    if( format === 'html' || format === 'doc' ) {
+    if( _.contains( ['html','doc','md','txt'], format )) {
 
       // Locate the global partials folder
       var partialsFolder = PATH.join(
@@ -70,15 +92,12 @@ Definition of the HandlebarsGenerator class.
         format
       );
 
-      // Register global partials in the /partials folder
+      // Register global partials in the /partials/[format] folder
       // TODO: Only do this once per HMR invocation.
       _.each( READFILES( partialsFolder, function(error){ }), function( el ) {
         var pathInfo = parsePath( el );
         var name = SLASH( PATH.relative( partialsFolder, el )
-          .replace(/\.html$|\.xml$/, '') );
-        if( pathInfo.dirname.endsWith('section') ) {
-          name = SLASH(name.replace(/\.html$|\.xml$/, ''));
-        }
+          .replace(/\.(?:html|xml|hbs|md|txt)$/i, '') );
         var tplData = FS.readFileSync( el, 'utf8' );
         var compiledTemplate = HANDLEBARS.compile( tplData );
         HANDLEBARS.registerPartial( name, compiledTemplate );

src/renderers/jrs-generator.js

@@ -13,7 +13,7 @@ Definition of the JRSGenerator class.
   var _ = require('underscore')
     , HANDLEBARS = require('handlebars')
     , FS = require('fs')
-    , registerHelpers = require('./handlebars-helpers')
+    , registerHelpers = require('../helpers/handlebars-helpers')
     , PATH = require('path')
     , parsePath = require('parse-filepath')
     , READFILES = require('recursive-readdir-sync')
@@ -33,18 +33,6 @@ Definition of the JRSGenerator class.
 
     generate: function( json, jst, format, cssInfo, opts, theme ) {
 
-      // JSON Resume themes don't have a specific structure, so the safest thing
-      // to do is copy all files from source to dest.
-      // var COPY = require('copy');
-      // var globs = [ '*.css', '*.js', '*.png', '*.jpg', '*.gif', '*.bmp' ];
-      // COPY.sync( globs , outFolder, {
-      //   cwd: theme.folder, nodir: true,
-      //   ignore: ['node_modules/','node_modules/**']
-      //   // rewrite: function(p1, p2) {
-      //   //   return PATH.join(p2, p1);
-      //   // }
-      // });
-
       // Disable JRS theme chatter (console.log, console.error, etc.)
       var off = ['log', 'error', 'dir'], org = off.map(function(c){
         var ret = console[c]; console[c] = function(){}; return ret;
@@ -68,6 +56,7 @@ Definition of the JRSGenerator class.
   };
 
 
+
   function MDIN(txt) { // TODO: Move this
     return MD(txt || '' ).replace(/^\s*<p>|<\/p>\s*$/gi, '');
   }

src/renderers/underscore-generator.js

@@ -8,7 +8,9 @@ Definition of the UnderscoreGenerator class.
 
 
 
-  var _ = require('underscore');
+  var _ = require('underscore')
+    , registerHelpers = require('../helpers/underscore-helpers')
+    , HMSTATUS = require('../core/status-codes');
 
 
   /**
@@ -17,6 +19,23 @@ Definition of the UnderscoreGenerator class.
   */
   var UnderscoreGenerator = module.exports = {
 
+    generateSimple: function( data, tpl ) {
+
+      try {
+        // Compile and run the Handlebars template.
+        var template = _.template( tpl );
+        return template( data );
+      }
+      catch( ex ) {
+        throw {
+          fluenterror: template ?
+            HMSTATUS.invokeTemplate : HMSTATUS.compileTemplate,
+          inner: ex
+        };
+      }
+
+    },
+
     generate: function( json, jst, format, cssInfo, opts, theme ) {
 
       // Tweak underscore's default template delimeters
@@ -31,23 +50,20 @@ Definition of the UnderscoreGenerator class.
       // Strip {# comments #}
       jst = jst.replace( delims.comment, '');
 
-      var helpers = require('./generic-helpers');
-      helpers.opts = opts;
-      helpers.cssInfo = cssInfo;
-
-      // Compile and run the template. TODO: avoid unnecessary recompiles.
-      var compiled = _.template(jst);
-      var ret = compiled({
+      var ctx = {
         r: format === 'html' || format === 'pdf' || format === 'png' ? json.markdownify() : json,
         filt: opts.filters,
         XML: require('xml-escape'),
         RAW: json,
         cssInfo: cssInfo,
+        //engine: this,
         headFragment: opts.headFragment || '',
-        opts: opts,
-        h: helpers
-      });
-      return ret;
+        opts: opts
+      };
+
+      registerHelpers( theme, opts, cssInfo, ctx, this );
+
+      return this.generateSimple( ctx, jst );
     }
 
   };

src/use.txt

@@ -1,27 +0,0 @@
-Usage:
-
-    hackmyresume <COMMAND> <SOURCES> [TO <TARGETS>] [-t <THEME>] [-f <FORMAT>]
-
-<COMMAND> should be BUILD, NEW, CONVERT, VALIDATE, ANALYZE or HELP. <SOURCES>
-should be the path to one or more FRESH or JSON Resume format resumes. <TARGETS>
-should be the name of the destination resume to be created, if any. The <THEME>
-parameter should be the name of a predefined theme (for example: COMPACT,
-MINIMIST, MODERN, or HELLO-WORLD) or the relative path to a custom theme.
-<FORMAT> should be either FRESH (for a FRESH-format resume) or JRS (for a JSON
-Resume-format resume).
-
-    hackmyresume BUILD resume.json TO out/resume.all
-    hackmyresume NEW resume.json
-    hackmyresume CONVERT resume.json TO resume-jrs.json
-    hackmyresume ANALYZE resume.json
-    hackmyresume VALIDATE resume.json
-
-Both SOURCES and TARGETS can accept multiple files:
-
-    hackmyresume BUILD r1.json r2.json TO out/resume.all out2/resume.html
-    hackmyresume NEW r1.json r2.json r3.json
-    hackmyresume ANALYZE r1.json r2.json r3.json
-    hackmyresume VALIDATE resume.json resume2.json resume3.json
-
-See https://github.com/hacksalot/hackmyresume/blob/master/README.md for more
-information.

src/utils/extend.js

@@ -1,79 +0,0 @@
-/**
-Definition of the `extend` method.
-@license MIT. Copyright (c) 2015 James Devlin / FluentDesk.
-@module extend.js
-*/
-
-function _extend() {
-
-  function isPlainObject( obj ) {
-    if ((typeof obj !== "object") || obj.nodeType ||
-      (obj !== null && obj === obj.window)) {
-      return false;
-    }
-    if (obj.constructor &&
-      !hasOwnProperty.call( obj.constructor.prototype, "isPrototypeOf" )) {
-      return false;
-    }
-    return true;
-  }
-
-  var options
-    , name
-    , src
-    , copy
-    , copyIsArray
-    , clone
-    , target = arguments[0] || {}
-    , i = 1
-    , length = arguments.length
-    , deep = false;
-
-  // Handle a deep copy situation
-  if (typeof target === "boolean") {
-    deep = target;
-    // Skip the boolean and the target
-    target = arguments[i] || {};
-    i++;
-  }
-
-  // Handle case when target is a string or something (possible in deep copy)
-  //if (typeof target !== "object" && !jQuery.isFunction(target))
-  if (typeof target !== "object" && typeof target !== "function")
-    target = {};
-
-  for (; i < length; i++) {
-    // Only deal with non-null/undefined values
-    if ((options = arguments[i]) !== null) {
-      // Extend the base object
-      for (name in options) {
-        src = target[name];
-        copy = options[name];
-
-        // Prevent never-ending loop
-        if (target === copy) continue;
-
-        // Recurse if we're merging plain objects or arrays
-        if (deep && copy && (isPlainObject(copy) ||
-          (copyIsArray = (copy.constructor === Array)))) {
-          if (copyIsArray) {
-            copyIsArray = false;
-            clone = src && (src.constructor === Array) ? src : [];
-          } else {
-            clone = src && isPlainObject(src) ? src : {};
-          }
-          // Never move original objects, clone them
-          target[name] = _extend(deep, clone, copy);
-          // Don't bring in undefined values
-        } else if (copy !== undefined) {
-          target[name] = copy;
-        }
-      }
-    }
-  }
-
-  // Return the modified object
-  return target;
-}
-
-module.exports = _extend;

src/utils/md2chalk.js

@@ -0,0 +1,19 @@
+/**
+Inline Markdown-to-Chalk conversion routines.
+@license MIT. See LICENSE.md for details.
+@module md2chalk.js
+*/
+
+(function(){
+
+  var MD = require('marked');
+  var CHALK = require('chalk');
+  var LO = require('lodash');
+
+  module.exports = function( v, style, boldStyle ) {
+    boldStyle = boldStyle || 'bold';
+    var temp = v.replace(/\*\*(.*?)\*\*/g, LO.get( CHALK, boldStyle )('$1'));
+    return style ? LO.get( CHALK, style )(temp) : temp;
+  };
+
+}());

src/utils/safe-json-loader.js

@@ -8,16 +8,38 @@ Definition of the SafeJsonLoader class.
 
 (function() {
 
-  var FS = require('fs');
+
+
+  var FS = require('fs')
+    , SyntaxErrorEx = require('./syntax-error-ex');
+
+
 
   module.exports = function loadSafeJson( file ) {
+
+    var ret = { };
     try {
-      return JSON.parse( FS.readFileSync( file ) );
+
+      ret.raw = FS.readFileSync( file, 'utf8' );
+      ret.json = JSON.parse( ret.raw );
+
     }
-    catch(ex) {
-      loadSafeJson.error = ex;
+    catch( ex ) {
+
+      // If we get here, either FS.readFileSync or JSON.parse failed.
+      // We'll return HMSTATUS.readError or HMSTATUS.parseError.
+      var retRaw = ret.raw && ret.raw.trim();
+
+      ret.ex = {
+        operation: retRaw ? 'parse' : 'read',
+        inner: SyntaxErrorEx.is( ex ) ? (new SyntaxErrorEx( ex, retRaw )) : ex,
+        file: file
+      };
+
     }
-    return null;
+
+    return ret;
+
   };
 
 

src/utils/safe-spawn.js

@@ -0,0 +1,45 @@
+/**
+Safe spawn utility for HackMyResume / FluentCV.
+@module safe-spawn.js
+@license MIT. See LICENSE.md for details.
+*/
+
+
+
+(function() {
+
+
+
+  module.exports = function( cmd, args, isSync ) {
+
+    try {
+
+      var spawn = require('child_process')[ isSync? 'spawnSync' : 'spawn'];
+      var info = spawn( cmd, args );
+
+      if( !isSync ) {
+        info.on('error', function(err) {
+          throw {
+            cmd: 'wkhtmltopdf',
+            inner: err
+          };
+        });
+      }
+      else {
+        if( info.error ) {
+          throw {
+            cmd: 'wkhtmltopdf',
+            inner: info.error
+          };
+        }
+      }
+      
+    }
+    catch( ex ) {
+
+    }
+  };
+
+
+
+}());

src/utils/string-transformer.js

@@ -0,0 +1,65 @@
+/**
+Object string transformation.
+@module string-transformer.js
+@license MIT. See LICENSE.md for details.
+*/
+
+
+
+(function() {
+
+
+
+  var _ = require('underscore');
+  var moment = require('moment');
+
+
+
+  /**
+  Create a copy of this object in which all string fields have been run through
+  a transformation function (such as a Markdown filter or XML encoder).
+  */
+  module.exports = function( ret, filt, transformer ) {
+
+    var that = this;
+
+    // TODO: refactor recursion
+    function transformStringsInObject( obj, filters ) {
+
+      if( !obj ) return;
+      if( moment.isMoment( obj ) ) return;
+
+      if( _.isArray( obj ) ) {
+        obj.forEach( function(elem, idx, ar) {
+          if( typeof elem === 'string' || elem instanceof String )
+            ar[idx] = transformer( null, elem );
+          else if (_.isObject(elem))
+            transformStringsInObject( elem, filters );
+        });
+      }
+      else if (_.isObject( obj )) {
+        Object.keys( obj ).forEach(function(k) {
+          if( filters.length && _.contains(filters, k) )
+            return;
+          var sub = obj[k];
+          if( typeof sub === 'string' || sub instanceof String ) {
+            obj[k] = transformer( k, sub );
+          }
+          else if (_.isObject( sub ))
+            transformStringsInObject( sub, filters );
+        });
+      }
+
+    }
+
+    Object.keys( ret ).forEach(function(member){
+      if( !filt || !filt.length || !_.contains(filt, member) )
+        transformStringsInObject( ret[ member ], filt || [] );
+    });
+
+    return ret;
+  };
+
+
+
+}());

src/utils/syntax-error-ex.js

@@ -11,31 +11,25 @@ Definition of the SyntaxErrorEx class.
   Represents a SyntaxError exception with line and column info.
   Collect syntax error information from the provided exception object. The
   JavaScript `SyntaxError` exception isn't interpreted uniformly across environ-
-  ments, so we first check for a .lineNumber and .columnNumber and, if that's
-  not present, fall back to the JSONLint library, which provides that info.
+  ments, so we reparse on error to grab the line and column.
   See: http://stackoverflow.com/q/13323356
   @class SyntaxErrorEx
   */
 
-  module.exports = function SyntaxErrorEx( ex, rawData ) {
+  function SyntaxErrorEx( ex, rawData ) {
 
     var lineNum = null, colNum = null;
-    if( ex.lineNumber !== undefined && ex.lineNumber !== null ) {
-      lineNum = ex.lineNumber;
-    }
-    if( ex.columnNumber !== undefined && ex.columnNumber !== null ) {
-      colNum = ex.columnNumber;
-    }
-    if( lineNum === null || colNum === null ) {
-      var JSONLint = require('json-lint'); // TODO: json-lint or is-my-json-valid?
-      var lint = JSONLint( rawData, { comments: false } );
-      if( lineNum === null ) lineNum = (lint.error ? lint.line : '???');
-      if( colNum === null ) colNum = (lint.error ? lint.character : '???');
-    }
-    this.line = lineNum;
-    this.col = colNum;
+    var JSONLint = require('json-lint');
+    var lint = JSONLint( rawData, { comments: false } );
+    this.line = (lint.error ? lint.line : '???');
+    this.col =  (lint.error ? lint.character : '???');
 
+  }
+
+  SyntaxErrorEx.is = function( ex ) {
+    return ex instanceof SyntaxError;
   };
 
+  module.exports = SyntaxErrorEx;
 
 }());

src/verbs/analyze.js

@@ -1,6 +1,6 @@
 /**
 Implementation of the 'analyze' verb for HackMyResume.
-@module create.js
+@module verbs/analyze
 @license MIT. See LICENSE.md for details.
 */
 
@@ -12,81 +12,68 @@ Implementation of the 'analyze' verb for HackMyResume.
 
   var MKDIRP = require('mkdirp')
     , PATH = require('path')
+    , HMEVENT = require('../core/event-codes')
+    , HMSTATUS = require('../core/status-codes')
     , _ = require('underscore')
     , ResumeFactory = require('../core/resume-factory')
+    , Verb = require('../verbs/verb')
     , chalk = require('chalk');
 
 
 
+  var AnalyzeVerb = module.exports = Verb.extend({
+
+    init: function() {
+      this._super('analyze');
+    },
+
+    invoke: function() {
+      this.stat( HMEVENT.begin, { cmd: 'analyze' });
+      analyze.apply( this, arguments );
+      this.stat( HMEVENT.end );
+    }
+
+  });
+
+
+
   /**
   Run the 'analyze' command.
   */
-  module.exports = function analyze( sources, dst, opts, logger ) {
-    var _log = logger || console.log;
-    if( !sources || !sources.length ) throw { fluenterror: 3 };
+  function analyze( sources, dst, opts ) {
+    if( !sources || !sources.length )
+      throw { fluenterror: HMSTATUS.resumeNotFound, quit: true };
 
     var nlzrs = _loadInspectors();
 
-    sources.forEach( function(src) {
+    _.each(sources, function(src) {
       var result = ResumeFactory.loadOne( src, {
-        log: _log, format: 'FRESH', objectify: true, throw: false
-      });
-      result.error || _analyze( result, nlzrs, opts, _log );
-    });
+        format: 'FRESH', objectify: true
+      }, this);
+      if( result.fluenterror )
+        this.setError( result.fluenterror, result );
+      else
+        _analyze.call(this, result, nlzrs, opts );
+    }, this);
 
-  };
+  }
 
 
 
   /**
   Analyze a single resume.
   */
-  function _analyze( resumeObject, nlzrs, opts, log ) {
+  function _analyze( resumeObject, nlzrs, opts ) {
     var rez = resumeObject.rez;
     var safeFormat =
       (rez.meta && rez.meta.format && rez.meta.format.startsWith('FRESH')) ?
       'FRESH' : 'JRS';
 
-    var padding = 20;
-    log(chalk.cyan('Analyzing ') + chalk.cyan.bold(safeFormat) +
-      chalk.cyan(' resume: ') + chalk.cyan.bold(resumeObject.file));
+    this.stat( HMEVENT.beforeAnalyze, { fmt: safeFormat, file: resumeObject.file });
     var info = _.mapObject( nlzrs, function(val, key) {
       return val.run( resumeObject.rez );
     });
-
-    log(chalk.cyan.bold('\nSECTIONS') + chalk.cyan(' (') + chalk.white.bold(_.keys(info.totals).length) + chalk.cyan('):\n'));
-    var pad = require('string-padding');
-    _.each( info.totals, function(tot, key) {
-      log(chalk.cyan(pad(key + ': ',20)) + chalk.cyan.bold(pad(tot.toString(),5)));
-    });
-
-    log();
-    log(chalk.cyan.bold('COVERAGE') + chalk.cyan(' (') + chalk.white.bold( info.coverage.pct ) + chalk.cyan('):\n'));
-    log(chalk.cyan(pad('Total Days: ', padding)) + chalk.cyan.bold( pad(info.coverage.duration.total.toString(),5) ));
-    log(chalk.cyan(pad('Employed: ', padding)) + chalk.cyan.bold( pad((info.coverage.duration.total - info.coverage.duration.gaps).toString(),5) ));
-    log(chalk.cyan(pad('Gaps:     ', padding + 4)) + chalk.cyan.bold(info.coverage.gaps.length) + chalk.cyan('  [') + info.coverage.gaps.map(function(g) {
-        var clr = 'green';
-        if( g.duration > 35 ) clr = 'yellow';
-        if( g.duration > 90 ) clr = 'red';
-        return chalk[clr].bold( g.duration) ;
-      }).join(', ') + chalk.cyan(']') );
-      log(chalk.cyan(pad('Overlaps:     ', padding + 4)) + chalk.cyan.bold(info.coverage.overlaps.length) + chalk.cyan('  [') + info.coverage.overlaps.map(function(ol) {
-          var clr = 'green';
-          if( ol.duration > 35 ) clr = 'yellow';
-          if( ol.duration > 90 ) clr = 'red';
-          return chalk[clr].bold( ol.duration) ;
-        }).join(', ') + chalk.cyan(']') );
-
-    var tot = 0;
-    log();
-    log( chalk.cyan.bold('KEYWORDS') + chalk.cyan(' (') + chalk.white.bold( info.keywords.length ) +
-      chalk.cyan('):\n\n') +
-      info.keywords.map(function(g) {
-        tot += g.count;
-        return chalk.cyan( pad(g.name + ': ', padding) ) + chalk.cyan.bold( pad( g.count.toString(), 5 )) + chalk.cyan(' mentions');
-      }).join('\n'));
-
-    log(chalk.cyan( pad('TOTAL: ', padding) ) + chalk.white.bold( pad( tot.toString(), 5 )) + chalk.cyan(' mentions'));
+    this.stat( HMEVENT.afterAnalyze, { info: info } );
   }
 
 

src/verbs/build.js

@@ -1,32 +1,55 @@
 /**
-Implementation of the 'generate' verb for HackMyResume.
-@module generate.js
+Implementation of the 'build' verb for HackMyResume.
+@module verbs/build
 @license MIT. See LICENSE.md for details.
 */
-// TODO: EventEmitter
+
 
 
 (function() {
 
 
 
-  var PATH = require('path')
-    , FS = require('fs')
-    , MD = require('marked')
-    , MKDIRP = require('mkdirp')
-    , EXTEND = require('../utils/extend')
-    , HACKMYSTATUS = require('../core/status-codes')
-    , parsePath = require('parse-filepath')
-    , _opts = require('../core/default-options')
-    , FluentTheme = require('../core/fresh-theme')
-    , JRSTheme = require('../core/jrs-theme')
-    , ResumeFactory = require('../core/resume-factory')
-    , _ = require('underscore')
-    , _fmts = require('../core/default-formats')
-    , extend = require('../utils/extend')
-    , chalk = require('chalk')
-    , pad = require('string-padding')
-    , _err, _log, rez;
+  var _              = require('underscore')
+    , PATH           = require('path')
+    , FS             = require('fs')
+    , MD             = require('marked')
+    , MKDIRP         = require('mkdirp')
+    , extend         = require('extend')
+    , parsePath      = require('parse-filepath')
+    , RConverter     = require('fresh-jrs-converter')
+    , HMSTATUS       = require('../core/status-codes')
+    , HMEVENT        = require('../core/event-codes')
+    , RTYPES         = { FRESH: require('../core/fresh-resume'),
+                         JRS: require('../core/jrs-resume') }
+    , _opts          = require('../core/default-options')
+    , FRESHTheme     = require('../core/fresh-theme')
+    , JRSTheme       = require('../core/jrs-theme')
+    , ResumeFactory  = require('../core/resume-factory')
+    , _fmts          = require('../core/default-formats')
+    , Verb           = require('../verbs/verb');
+
+  var _err, _log, _rezObj;
+
+
+
+  /** An invokable resume generation command. */
+  var BuildVerb = module.exports = Verb.extend({
+
+    /** Create a new build verb. */
+    init: function() {
+      this._super('build');
+    },
+
+    /** Invoke the Build command. */
+    invoke: function() {
+      this.stat( HMEVENT.begin, { cmd: 'build' } );
+      var ret = build.apply( this, arguments );
+      this.stat( HMEVENT.end );
+      return ret;
+    }
+
+  });
 
 
 
@@ -38,79 +61,95 @@ Implementation of the 'generate' verb for HackMyResume.
   @param theme Friendly name of the resume theme. Defaults to "modern".
   @param logger Optional logging override.
   */
-  function build( src, dst, opts, logger, errHandler ) {
+  function build( src, dst, opts ) {
 
-    prep( src, dst, opts, logger, errHandler );
-
-    // Load the theme...we do this first because the theme choice (FRESH or
-    // JSON Resume) determines what format we'll convert the resume to.
-    var tFolder = verifyTheme( _opts.theme );
-    var theme = loadTheme( tFolder );
-
-    // Check for invalid outputs
-    var inv = verifyOutputs( dst, theme );
-    if( inv && inv.length ) {
-      throw {fluenterror: HACKMYSTATUS.invalidFormat, data: inv, theme: theme};
+    if( !src || !src.length ) {
+      this.err( HMSTATUS.resumeNotFound, { quit: true } );
     }
 
-    // Load input resumes...
-    if( !src || !src.length ) { throw { fluenterror: 3 }; }
-    var sheets = ResumeFactory.load(src, {
-      log: _log, format: theme.render ? 'JRS' : 'FRESH',
-      objectify: true, throw: true
-    }).map(function(sh){ return sh.rez; });
+    prep( src, dst, opts );
 
-    // Merge input resumes...
-    var msg = '';
-    rez = _.reduceRight( sheets, function( a, b, idx ) {
-      msg += ((idx == sheets.length - 2) ?
-        chalk.cyan('Merging ') + chalk.cyan.bold(a.i().file) : '') +
-        chalk.cyan(' onto ') + chalk.cyan.bold(b.i().file);
-      return extend( true, b, a );
-    });
-    msg && _log(msg);
+    // Load input resumes as JSON...
+    var sheetObjects = ResumeFactory.load(src, {
+      format: null, objectify: false, quit: true, inner: { sort: _opts.sort }
+    }, this);
 
-    // Output theme messages
-    var numFormats = Object.keys(theme.formats).length;
-    var themeName = theme.name.toUpperCase();
-    _log( chalk.yellow('Applying ') + chalk.yellow.bold(themeName) +
-      chalk.yellow(' theme (' + numFormats + ' format' +
-        ( numFormats === 1 ? ')' : 's)') ));
+    // Explicit check for any resume loading errors...
+    if( !sheetObjects ||
+        _.some( sheetObjects, function(so) { return so.fluenterror; } ) ) {
+      return null;
+    }
+
+    var sheets = sheetObjects.map(function(r) { return r.json; });
+
+    // Load the theme...
+    var theme;
+    this.stat( HMEVENT.beforeTheme, { theme: _opts.theme });
+    try {
+      var tFolder = verifyTheme.call( this, _opts.theme );
+      theme = _opts.themeObj = loadTheme( tFolder );
+    }
+    catch( ex ) {
+      var newEx = {
+        fluenterror: HMSTATUS.themeLoad,
+        inner: ex,
+        attempted: _opts.theme
+      };
+      this.err( HMSTATUS.themeLoad, newEx );
+      return null;
+    }
+    this.stat( HMEVENT.afterTheme, { theme: theme });
+
+    // Check for invalid outputs...
+    var inv = verifyOutputs.call( this, dst, theme );
+    if( inv && inv.length ) {
+      this.err( HMSTATUS.invalidFormat, { data: inv, theme: theme } );
+    }
+
+    // Merge input resumes, yielding a single source resume.
+    var rez;
+    if( sheets.length > 1 ) {
+      var isFRESH = !sheets[0].basics;
+      var mixed = _.any( sheets, function(s) { return isFRESH ? s.basics : !s.basics; });
+      this.stat( HMEVENT.beforeMerge, { f: _.clone(sheetObjects), mixed: mixed });
+      if( mixed ) {
+        this.err( HMSTATUS.mixedMerge );
+      }
+      rez = _.reduceRight( sheets, function( a, b, idx ) {
+        return extend( true, b, a );
+      });
+      this.stat( HMEVENT.afterMerge, { r: rez } );
+    }
+    else {
+      rez = sheets[0];
+    }
+
+    // Convert the merged source resume to the theme's format, if necessary
+    var orgFormat = rez.basics ? 'JRS' : 'FRESH';
+    var toFormat = theme.render ? 'JRS' : 'FRESH';
+    if( toFormat !== orgFormat ) {
+      this.stat( HMEVENT.beforeInlineConvert );
+      rez = RConverter[ 'to' + toFormat ]( rez );
+      this.stat( HMEVENT.afterInlineConvert, { file: sheetObjects[0].file, fmt: toFormat });
+    }
+
+    // Add freebie formats to the theme
+    addFreebieFormats( theme  );
+    this.stat( HMEVENT.applyTheme, { r: rez, theme: theme });
+
+    // Load the resume into a FRESHResume or JRSResume object
+    _rezObj = new (RTYPES[ toFormat ])().parseJSON( rez );
 
     // Expand output resumes...
     var targets = expand( dst, theme );
 
     // Run the transformation!
-    targets.forEach( function(t) {
-      t.final = single( t, theme, targets );
-    });
-
-    if( _opts.tips && (theme.message || theme.render) ) {
-      var WRAP = require('word-wrap');
-      if( theme.message ) {
-        _log( WRAP( chalk.gray('The ' + themeName +
-          ' theme says: "') + chalk.white(theme.message) + chalk.gray('"'),
-          { width: _opts.wrap, indent: '' } ));
-      }
-      else {
-        _log( WRAP( chalk.gray('The ' + themeName +
-          ' theme says: "') + chalk.white('For best results view JSON Resume ' +
-          'themes over a local or remote HTTP connection. For example:'),
-          { width: _opts.wrap, indent: '' }
-        ));
-        _log('');
-        _log(
-          '    npm install http-server -g\r' +
-          '    http-server <resume-folder>' );
-        _log('');
-        _log(chalk.white('For more information, see the README."'),
-          { width: _opts.wrap, indent: '' } );
-      }
-    }
-
+    _.each(targets, function(t) {
+      t.final = single.call( this, t, theme, targets );
+    }, this);
 
     // Don't send the client back empty-handed
-    return { sheet: rez, targets: targets, processed: targets };
+    return { sheet: _rezObj, targets: targets, processed: targets };
   }
 
 
@@ -118,22 +157,20 @@ Implementation of the 'generate' verb for HackMyResume.
   /**
   Prepare for a BUILD run.
   */
-  function prep( src, dst, opts, logger, errHandler ) {
-
-    // Housekeeping
-    _log = logger || console.log;
-    _err = errHandler || error;
+  function prep( src, dst, opts ) {
 
     // Cherry-pick options //_opts = extend( true, _opts, opts );
     _opts.theme = (opts.theme && opts.theme.toLowerCase().trim()) || 'modern';
     _opts.prettify = opts.prettify === true;
-    _opts.css = opts.css || 'embed';
+    _opts.css = opts.css;
     _opts.pdf = opts.pdf;
     _opts.wrap = opts.wrap || 60;
     _opts.stitles = opts.sectionTitles;
     _opts.tips = opts.tips;
+    _opts.errHandler = opts.errHandler;
     _opts.noTips = opts.noTips;
     _opts.debug = opts.debug;
+    _opts.sort = opts.sort;
 
     // If two or more files are passed to the GENERATE command and the TO
     // keyword is omitted, the last file specifies the output file.
@@ -151,65 +188,61 @@ Implementation of the 'generate' verb for HackMyResume.
   */
   function single( targInfo, theme, finished ) {
 
+    var ret, ex, f = targInfo.file;
+
     try {
-      if( !targInfo.fmt ) {
-        return;
-      }
-      var f = targInfo.file
-        , fType = targInfo.fmt.outFormat
+
+      if( !targInfo.fmt ) {  return; }
+      var fType = targInfo.fmt.outFormat
         , fName = PATH.basename(f, '.' + fType)
         , theFormat;
 
-      var suffix = '';
-      if( targInfo.fmt.outFormat === 'pdf' ) {
-        if( _opts.pdf ) {
-          if( _opts.pdf !== 'none' ) {
-            suffix = chalk.green(' (with ' + _opts.pdf + ')');
-          }
-          else {
-            _log( chalk.gray('Skipping   ') +
-              chalk.white.bold(
-                pad(targInfo.fmt.outFormat.toUpperCase(),4,null,pad.RIGHT)) +
-              chalk.gray(' resume') + suffix + chalk.green(': ') +
-              chalk.white( PATH.relative(process.cwd(), f )) );
-            return;
-          }
-        }
-      }
-
-      _log( chalk.green('Generating ') +
-        chalk.green.bold(
-          pad(targInfo.fmt.outFormat.toUpperCase(),4,null,pad.RIGHT)) +
-        chalk.green(' resume') + suffix + chalk.green(': ') +
-        chalk.green.bold( PATH.relative(process.cwd(), f )) );
+      this.stat( HMEVENT.beforeGenerate, {
+        fmt: targInfo.fmt.outFormat,
+        file: PATH.relative(process.cwd(), f)
+      });
 
       // If targInfo.fmt.files exists, this format is backed by a document.
       // Fluent/FRESH themes are handled here.
       if( targInfo.fmt.files && targInfo.fmt.files.length ) {
-          theFormat = _fmts.filter(
-            function(fmt) { return fmt.name === targInfo.fmt.outFormat; })[0];
-          MKDIRP.sync( PATH.dirname( f ) ); // Ensure dest folder exists;
-          _opts.targets = finished;
-          return theFormat.gen.generate( rez, f, _opts );
+        theFormat = _fmts.filter(
+          function(fmt) { return fmt.name === targInfo.fmt.outFormat; })[0];
+        MKDIRP.sync( PATH.dirname( f ) ); // Ensure dest folder exists;
+        _opts.targets = finished;
+        ret = theFormat.gen.generate( _rezObj, f, _opts );
       }
-
       //Otherwise this is an ad-hoc format (JSON, YML, or PNG) that every theme
       // gets "for free".
       else {
-
         theFormat = _fmts.filter( function(fmt) {
           return fmt.name === targInfo.fmt.outFormat;
         })[0];
-
         var outFolder = PATH.dirname( f );
         MKDIRP.sync( outFolder ); // Ensure dest folder exists;
-
-        return theFormat.gen.generate( rez, f, _opts );
+        ret = theFormat.gen.generate( _rezObj, f, _opts );
       }
     }
-    catch( ex ) {
-      _err( ex );
+    catch( e ) {
+      // Catch any errors caused by generating this file and don't let them
+      // propagate -- typically we want to continue processing other formats
+      // even if this format failed.
+      ex = e;
     }
+
+    this.stat( HMEVENT.afterGenerate, {
+      fmt: targInfo.fmt.outFormat,
+      file: PATH.relative( process.cwd(), f ),
+      error: ex
+    });
+
+    if( ex ) {
+      if( ex.fluenterror )
+        this.err( ex.fluenterror, ex );
+      else
+        this.err( HMSTATUS.generateError, { inner: ex } );
+    }
+
+    return ret;
   }
 
 
@@ -219,6 +252,8 @@ Implementation of the 'generate' verb for HackMyResume.
   */
   function verifyOutputs( targets, theme ) {
 
+    this.stat(HMEVENT.verifyOutputs, { targets: targets, theme: theme });
+
     return _.reject(
       targets.map( function( t ) {
         var pathInfo = parsePath( t );
@@ -236,13 +271,15 @@ Implementation of the 'generate' verb for HackMyResume.
 
 
   /**
-  Expand output files. For example, "foo.all" should be expanded to
-  ["foo.html", "foo.doc", "foo.pdf", "etc"].
-  @param dst An array of output files as specified by the user.
+  Reinforce the chosen theme with "freebie" formats provided by HackMyResume.
+  A "freebie" format is an output format such as JSON, YML, or PNG that can be
+  generated directly from the resume model or from one of the theme's declared
+  output formats. For example, the PNG format can be generated for any theme
+  that declares an HTML format; the theme doesn't have to provide an explicit
+  PNG template.
   @param theTheme A FRESHTheme or JRSTheme object.
   */
-  function expand( dst, theTheme ) {
-
+  function addFreebieFormats( theTheme ) {
     // Add freebie formats (JSON, YAML, PNG) every theme gets...
     // Add HTML-driven PNG only if the theme has an HTML format.
     theTheme.formats.json = theTheme.formats.json || {
@@ -259,6 +296,17 @@ Implementation of the 'generate' verb for HackMyResume.
         ext: 'yml', path: null, data: null
       };
     }
+  }
+
+
+
+  /**
+  Expand output files. For example, "foo.all" should be expanded to
+  ["foo.html", "foo.doc", "foo.pdf", "etc"].
+  @param dst An array of output files as specified by the user.
+  @param theTheme A FRESHTheme or JRSTheme object.
+  */
+  function expand( dst, theTheme ) {
 
     // Set up the destination collection. It's either the array of files passed
     // by the user or 'out/resume.all' if no targets were specified.
@@ -308,7 +356,7 @@ Implementation of the 'generate' verb for HackMyResume.
     if( !exists( tFolder ) ) {
       tFolder = PATH.resolve( themeNameOrPath );
       if( !exists( tFolder ) ) {
-        throw { fluenterror: 1, data: _opts.theme };
+        this.err( HMSTATUS.themeNotFound, { data: _opts.theme } );
       }
     }
     return tFolder;
@@ -324,7 +372,7 @@ Implementation of the 'generate' verb for HackMyResume.
 
     // Create a FRESH or JRS theme object
     var theTheme = _opts.theme.indexOf('jsonresume-theme-') > -1 ?
-      new JRSTheme().open(tFolder) : new FluentTheme().open( tFolder );
+      new JRSTheme().open(tFolder) : new FRESHTheme().open( tFolder );
 
     // Cache the theme object
     _opts.themeObj = theTheme;
@@ -334,23 +382,4 @@ Implementation of the 'generate' verb for HackMyResume.
 
 
 
-  /**
-  Handle an exception. Placeholder.
-  */
-  function error( ex ) {
-    throw ex;
-  }
-
-
-
-  function MDIN(txt) { // TODO: Move this
-    return MD(txt || '' ).replace(/^\s*<p>|<\/p>\s*$/gi, '');
-  }
-
-
-
-  module.exports = build;
-
-
-
 }());

src/verbs/convert.js

@@ -1,6 +1,6 @@
 /**
 Implementation of the 'convert' verb for HackMyResume.
-@module convert.js
+@module verbs/convert
 @license MIT. See LICENSE.md for details.
 */
 
@@ -12,57 +12,77 @@ Implementation of the 'convert' verb for HackMyResume.
 
   var ResumeFactory = require('../core/resume-factory')
     , chalk = require('chalk')
-    , HACKMYSTATUS = require('../core/status-codes');
+    , Verb = require('../verbs/verb')
+    , HMSTATUS = require('../core/status-codes')
+    , _ = require('underscore')
+    , HMEVENT = require('../core/event-codes');
+
+
+  var ConvertVerb = module.exports = Verb.extend({
+
+    init: function() {
+      this._super('convert');
+    },
+
+    invoke: function() {
+      this.stat( HMEVENT.begin, { cmd: 'convert' });
+      convert.apply( this, arguments );
+      this.stat( HMEVENT.end );
+    }
+
+  });
 
 
 
   /**
   Convert between FRESH and JRS formats.
   */
-  module.exports = function convert( srcs, dst, opts, logger ) {
+  function convert( srcs, dst, opts ) {
 
     // Housekeeping
-    var _log = logger || console.log;
-    if( !srcs || !srcs.length ) { throw { fluenterror: 6 }; }
+    if( !srcs || !srcs.length ) { throw { fluenterror: 6, quit: true }; }
     if( !dst || !dst.length ) {
       if( srcs.length === 1 ) {
-        throw { fluenterror: HACKMYSTATUS.inputOutputParity };
+        throw { fluenterror: HMSTATUS.inputOutputParity, quit: true };
       }
       else if( srcs.length === 2 ) {
         dst = dst || []; dst.push( srcs.pop() );
       }
       else {
-        throw { fluenterror: HACKMYSTATUS.inputOutputParity };
+        throw { fluenterror: HMSTATUS.inputOutputParity, quit: true };
       }
     }
     if(srcs && dst && srcs.length && dst.length && srcs.length !== dst.length){
-      throw { fluenterror: HACKMYSTATUS.inputOutputParity };
+      throw { fluenterror: HMSTATUS.inputOutputParity, quit: true };
     }
 
     // Load source resumes
-    srcs.forEach( function( src, idx ) {
+    _.each(srcs, function( src, idx ) {
 
       // Load the resume
       var rinfo = ResumeFactory.loadOne( src, {
-        log: _log, format: null, objectify: true, throw: true
+        format: null, objectify: true, throw: false
       });
 
+      // If a load error occurs, report it and move on to the next file (if any)
+      if( rinfo.fluenterror ) {
+        this.err( rinfo.fluenterror, rinfo );
+        return;
+      }
+
       var s = rinfo.rez
         , srcFmt = ((s.basics && s.basics.imp) || s.imp).orgFormat === 'JRS' ?
           'JRS' : 'FRESH'
         , targetFormat = srcFmt === 'JRS' ? 'FRESH' : 'JRS';
 
-      // TODO: Core should not log
-      _log( chalk.green('Converting ') + chalk.green.bold(rinfo.file) +
-        chalk.green(' (' + srcFmt + ') to ') + chalk.green.bold(dst[idx]) +
-        chalk.green(' (' + targetFormat + ').'));
+      this.stat(HMEVENT.beforeConvert, { srcFile: rinfo.file, srcFmt: srcFmt, dstFile: dst[idx], dstFmt: targetFormat });
 
       // Save it to the destination format
       s.saveAs( dst[idx], targetFormat );
 
-    });
+    }, this);
 
-  };
+  }
 
 
 

src/verbs/create.js

@@ -1,31 +1,60 @@
 /**
 Implementation of the 'create' verb for HackMyResume.
-@module create.js
+@module verbs/create
 @license MIT. See LICENSE.md for details.
 */
 
+
+
 (function(){
 
+
+
   var MKDIRP = require('mkdirp')
     , PATH = require('path')
     , chalk = require('chalk')
-    , HACKMYSTATUS = require('../core/status-codes');
+    , Verb = require('../verbs/verb')
+    , _ = require('underscore')
+    , HMSTATUS = require('../core/status-codes')
+    , HMEVENT = require('../core/event-codes');
+
+
+
+  var CreateVerb = module.exports = Verb.extend({
+
+    init: function() {
+      this._super('new');
+    },
+
+    invoke: function() {
+      this.stat( HMEVENT.begin, { cmd: 'create' });
+      create.apply( this, arguments );
+      this.stat( HMEVENT.begin, { cmd: 'convert' });
+    }
+
+  });
+
+
 
   /**
   Create a new empty resume in either FRESH or JRS format.
   */
-  module.exports = function create( src, dst, opts, logger ) {
-    var _log = logger || console.log;
-    if( !src || !src.length ) throw { fluenterror: HACKMYSTATUS.createNameMissing };
-    src.forEach( function( t ) {
-      var safeFormat = opts.format.toUpperCase();
-      _log(chalk.green('Creating new ') + chalk.green.bold(safeFormat) +
-        chalk.green(' resume: ') + chalk.green.bold(t));
+  function create( src, dst, opts ) {
+
+    if( !src || !src.length )
+      throw { fluenterror: HMSTATUS.createNameMissing, quit: true };
+
+    _.each( src, function( t ) {
+      var safeFmt = opts.format.toUpperCase();
+      this.stat( HMEVENT.beforeCreate, { fmt: safeFmt, file: t } );
       MKDIRP.sync( PATH.dirname( t ) ); // Ensure dest folder exists;
-      var RezClass = require('../core/' + safeFormat.toLowerCase() + '-resume' );
+      var RezClass = require('../core/' + safeFmt.toLowerCase() + '-resume' );
       RezClass.default().save(t);
-      //FLUENT[ safeFormat + 'Resume' ].default().save( t );
-    });
-  };
+      this.stat( HMEVENT.afterCreate, { fmt: safeFmt, file: t } );
+    }, this);
+
+  }
+
+
 
 }());

src/verbs/peek.js

@@ -0,0 +1,83 @@
+/**
+Implementation of the 'peek' verb for HackMyResume.
+@module verbs/peek
+@license MIT. See LICENSE.md for details.
+*/
+
+
+
+(function(){
+
+
+
+  var Verb = require('../verbs/verb')
+    , _ = require('underscore')
+    , __ = require('lodash')
+    , safeLoadJSON = require('../utils/safe-json-loader')
+    , HMSTATUS = require('../core/status-codes')
+    , HMEVENT = require('../core/event-codes');
+
+
+
+  var PeekVerb = module.exports = Verb.extend({
+
+    init: function() {
+      this._super('peek');
+    },
+
+    invoke: function() {
+      this.stat( HMEVENT.begin, { cmd: 'peek' } );
+      peek.apply( this, arguments );
+      this.stat( HMEVENT.end );
+    }
+
+  });
+
+
+
+  /**
+  Peek at a resume, resume section, or resume field.
+  */
+  function peek( src, dst, opts ) {
+
+    if(!src || !src.length) throw {fluenterror: HMSTATUS.resumeNotFound};
+
+    var objPath = (dst && dst[0]) || '';
+
+    _.each( src, function( t ) {
+
+      // Fire the 'beforePeek' event 2nd, so we have error/warning/success
+      this.stat( HMEVENT.beforePeek, { file: t, target: objPath } );
+
+      // Load the input file JSON 1st
+      var obj = safeLoadJSON( t );
+
+      // Fetch the requested object path (or the entire file)
+      var tgt;
+      if( !obj.ex )
+        tgt = objPath ? __.get( obj.json, objPath ) : obj.json;
+
+      // Fire the 'afterPeek' event with collected info
+      this.stat( HMEVENT.afterPeek, {
+        file: t,
+        requested: objPath,
+        target: tgt,
+        error: obj.ex
+      });
+
+      // safeLoadJSON can only return a READ error or a PARSE error
+      if( obj.ex ) {
+        var errCode = obj.ex.operation === 'parse' ? HMSTATUS.parseError : HMSTATUS.readError;
+        if( errCode === HMSTATUS.readError )
+          obj.ex.quiet = true;
+        this.setError( errCode, obj.ex );
+        this.err( errCode, obj.ex );
+      }
+
+    }, this);
+
+  }
+
+
+
+}());

src/verbs/validate.js

@@ -1,26 +1,48 @@
 /**
 Implementation of the 'validate' verb for HackMyResume.
-@module validate.js
+@module verbs/validate
 @license MIT. See LICENSE.md for details.
 */
 
+
+
 (function() {
 
+
+
   var FS = require('fs');
   var ResumeFactory = require('../core/resume-factory');
   var SyntaxErrorEx = require('../utils/syntax-error-ex');
   var chalk = require('chalk');
-  var HACKMYSTATUS = require('../core/status-codes');
+  var Verb = require('../verbs/verb');
+  var HMSTATUS = require('../core/status-codes');
+  var HMEVENT = require('../core/event-codes');
+  var _ = require('underscore');
 
-  module.exports =
 
-  /**
-  Validate 1 to N resumes in either FRESH or JSON Resume format.
-  */
-  function validate( sources, unused, opts, logger ) {
-    var _log = logger || console.log;
-    if( !sources || !sources.length ) { throw { fluenterror: 6 }; }
-    var isValid = true;
+
+  /** An invokable resume validation command. */
+  var ValidateVerb = module.exports = Verb.extend({
+
+    init: function() {
+      this._super('validate');
+    },
+
+    invoke: function() {
+      this.stat( HMEVENT.begin, { cmd: 'validate' } );
+      validate.apply( this, arguments );
+      this.stat( HMEVENT.end );
+    }
+
+  });
+
+
+
+  /** Validate 1 to N resumes in FRESH or JSON Resume format. */
+  function validate( sources, unused, opts ) {
+
+    if( !sources || !sources.length )
+      throw { fluenterror: HMSTATUS.resumeNotFoundAlt, quit: true };
 
     var validator = require('is-my-json-valid');
     var schemas = {
@@ -29,76 +51,53 @@ Implementation of the 'validate' verb for HackMyResume.
     };
 
     var resumes = ResumeFactory.load( sources, {
-      log: _log,
       format: null,
-      objectify: false,
-      throw: false,
-      muffle: true
-    });
+      objectify: false
+    }, this );
 
-    // Load input resumes...
-    resumes.forEach(function( src ) {
+    // Validate input resumes. Return a { file: <f>, isValid: <v>} object for
+    // each resume (valid, invalid, or broken).
+    return resumes.map( function( src ) {
 
-      if( src.error ) {
-        // TODO: Core should not log
-        _log( chalk.white('Validating ') + chalk.gray.bold(src.file) +
-        chalk.white(' against ') + chalk.gray.bold('AUTO') +
-        chalk.white(' schema:') + chalk.red.bold(' BROKEN') );
+      var ret =  { file: src, isValid: false };
 
-        var ex = src.error; // alias
-        if ( ex instanceof SyntaxError) {
-          var info = new SyntaxErrorEx( ex, src.raw );
-          _log( chalk.red.bold('--> ' + src.file.toUpperCase() + ' contains invalid JSON on line ' +
-            info.line + ' column ' + info.col + '.' +
-            chalk.red(' Unable to validate.') ) );
-          _log( chalk.red.bold('    INTERNAL: ' + ex) );
-        }
-        else {
-          _log(chalk.red.bold('ERROR: ' + ex.toString()));
-        }
-        if( opts.assert ) throw { fluenterror: HACKMYSTATUS.invalid };
-        return;
+      // If there was an error reading the resume
+      if( src.fluenterror ) {
+        if( opts.assert ) throw src;
+        this.setError( src.fluenterror, src );
+        return ret;
       }
 
-      var json = src.json;
-      var isValid = false;
-      var style = 'green';
-      var errors = [];
-      var fmt = json.basics ? 'jrs' : 'fresh';
-
+      // Successfully read the resume. Now parse it as JSON.
+      var json = src.json, fmt = json.basics ? 'jrs' : 'fresh', errors = [];
       try {
         var validate = validator( schemas[ fmt ], { // Note [1]
           formats: {
-            date: /^\d{4}(?:-(?:0[0-9]{1}|1[0-2]{1})(?:-[0-9]{2})?)?$/
+             date: /^\d{4}(?:-(?:0[0-9]{1}|1[0-2]{1})(?:-[0-9]{2})?)?$/
           }
         });
 
-        isValid = validate( json );
-        if( !isValid ) {
-          style = 'yellow';
+        ret.isValid = validate( json );
+        if( !ret.isValid ) {
           errors = validate.errors;
         }
 
       }
-      catch(exc) {
-        return;
+      catch( exc ) {
+        return ret;
       }
 
-      _log( chalk.white('Validating ') + chalk.white.bold(src.file) + chalk.white(' against ') +
-        chalk.white.bold(fmt.replace('jars','JSON Resume').toUpperCase()) +
-        chalk.white(' schema: ') + chalk[style].bold(isValid ? 'VALID!' : 'INVALID') );
+      this.stat( HMEVENT.afterValidate, { file: src.file, isValid: ret.isValid,
+        fmt: fmt.replace( 'jars', 'JSON Resume' ), errors: errors });
 
-      errors.forEach(function(err,idx) {
-        _log( chalk.yellow.bold('--> ') +
-          chalk.yellow(err.field.replace('data.','resume.').toUpperCase() + ' ' +
-          err.message) );
-      });
-
-      if( opts.assert && !isValid ) {
-        throw { fluenterror: HACKMYSTATUS.invalid, shouldExit: true };
+      if( opts.assert && !ret.isValid ) {
+        throw { fluenterror: HMSTATUS.invalid, shouldExit: true };
       }
 
-    });
-  };
+      return ret;
+
+    }, this);
+
+  }
 
 }());

src/verbs/verb.js

@@ -0,0 +1,96 @@
+/**
+Definition of the Verb class.
+@module verbs/verb
+@license MIT. See LICENSE.md for details.
+*/
+
+
+
+(function(){
+
+
+
+  // Use J. Resig's nifty class implementation
+  var Class = require( '../utils/class' )
+    , EVENTS = require('events');
+
+
+
+
+  /**
+  An instantiation of a HackMyResume command.
+  @class Verb
+  */
+  var Verb = module.exports = Class.extend({
+
+
+
+    /**
+    Constructor. Automatically called at creation.
+    */
+    init: function( moniker ) {
+      this.moniker = moniker;
+      this.emitter = new EVENTS.EventEmitter();
+    },
+
+
+
+    /**
+    Forward subscriptions to the event emitter.
+    */
+    on: function() {
+      this.emitter.on.apply( this.emitter, arguments );
+    },
+
+
+
+    /**
+    Fire an arbitrary event, scoped to "hmr:".
+    */
+    fire: function(evtName, payload) {
+      payload = payload || { };
+      payload.cmd = this.moniker;
+      this.emitter.emit( 'hmr:' + evtName, payload );
+      return true;
+    },
+
+
+
+    /**
+    Handle an error condition.
+    */
+    err: function( errorCode, payload, hot ) {
+      payload = payload || { };
+      payload.sub = payload.fluenterror = errorCode;
+      payload.throw = hot;
+      this.fire( 'error', payload );
+      if( hot ) throw payload;
+      return true;
+    },
+
+
+
+    /**
+    Fire the 'hmr:status' error event.
+    */
+    stat: function( subEvent, payload ) {
+      payload = payload || { };
+      payload.sub = subEvent;
+      this.fire('status', payload);
+      return true;
+    },
+
+
+    /**
+    Associate error info with the invocation.
+    */
+    setError: function( code, obj ) {
+      this.errorCode = code;
+      this.errorObj = obj;
+    }
+
+
+
+  });
+
+}());

test/hmr-options.json

@@ -0,0 +1,4 @@
+{
+  "theme": "positive",
+  "debug": true
+}

test/test-api.js

@@ -0,0 +1,207 @@
+/**
+@module test-api.js
+*/
+
+var chai = require('chai')
+  , expect = chai.expect
+  , should = chai.should()
+  , path = require('path')
+  , _ = require('underscore')
+	, FRESHResume = require('../src/core/fresh-resume')
+  , FCMD = require( '../src/hackmyapi')
+  , validator = require('is-my-json-valid')
+  , HMRMAIN = require('../src/cli/main')
+  , EXTEND = require('extend');
+
+chai.config.includeStack = false;
+
+var _sheet;
+
+var opts = {
+  format: 'FRESH',
+  prettify: true,
+  silent: false,
+  assert: true  // Causes validation errors to throw exceptions
+};
+
+var opts2 = {
+  format: 'JRS',
+  prettify: true,
+  silent: true
+};
+
+var sb = 'test/sandbox/';
+var ft = 'node_modules/fresh-test-resumes/src/fresh/';
+
+var tests = [
+
+  [ 'new',
+    [sb + 'new-fresh-resume.json'],
+    [],
+    opts,
+    ' (FRESH format)'
+  ],
+
+  [ 'new',
+    [sb + 'new-jrs-resume.json'],
+    [],
+    opts2,
+    ' (JRS format)'
+  ],
+
+  [
+    'new',
+    [sb + 'new-1.json', sb + 'new-2.json', sb + 'new-3.json'],
+    [],
+    opts,
+    ' (multiple FRESH resumes)'
+  ],
+
+  [ 'new',
+    [sb + 'new-jrs-1.json', sb + 'new-jrs-2.json', sb + 'new-jrs-3.json'],
+    [],
+    opts,
+    ' (multiple JRS resumes)'
+  ],
+
+  [ '!new',
+    [],
+    [],
+    opts,
+    " (when a filename isn't specified)"
+  ],
+
+  [ 'validate',
+    [ft + 'jane-fullstacker.json'],
+    [],
+    opts,
+    ' (jane-q-fullstacker|FRESH)'
+  ],
+
+  [ 'validate',
+    [ft + 'johnny-trouble.json'],
+    [],
+    opts,
+    ' (johnny-trouble|FRESH)'
+  ],
+
+  [ 'validate',
+    [sb + 'new-fresh-resume.json'],
+    [],
+    opts,
+    ' (new-fresh-resume|FRESH)'
+  ],
+
+  [ 'validate',
+    ['test/resumes/jrs-0.0.0/richard-hendriks.json'],
+    [],
+    opts2,
+    ' (richard-hendriks.json|JRS)'
+  ],
+
+  [ 'validate',
+    ['test/resumes/jrs-0.0.0/jane-incomplete.json'],
+    [],
+    opts2,
+    ' (jane-incomplete.json|JRS)'
+  ],
+
+  [ 'validate',
+    [sb + 'new-1.json', sb + 'new-jrs-resume.json', sb + 'new-1.json',
+      sb + 'new-2.json', sb + 'new-3.json'],
+    [],
+    opts,
+    ' (5|BOTH)'
+  ],
+
+  [ 'analyze',
+    [ft + 'jane-fullstacker.json'],
+    [],
+    opts,
+    ' (jane-q-fullstacker|FRESH)'
+  ],
+
+  [ 'analyze',
+    ['test/resumes/jrs-0.0.0/richard-hendriks.json'],
+    [],
+    opts2,
+    ' (richard-hendriks|JRS)'
+  ],
+
+  [ 'build',
+    [ ft + 'jane-fullstacker.json', ft + 'override/jane-fullstacker-override.fresh.json' ],
+    [ sb + 'merged/jane-fullstacker-gamedev.fresh.all'],
+    opts,
+    ' (jane-q-fullstacker w/ override|FRESH)'
+  ],
+
+  [ 'build',
+    [ ft + 'override/jane-partial-a.json', ft + 'override/jane-partial-b.json',
+      ft + 'override/jane-partial-c.json' ],
+    [ sb + 'merged/jane-abc.fresh.all'],
+    opts,
+    ' (jane merge A + B + C|FRESH)',
+    function( r ) {
+      var expected = [
+        'name','meta','info', 'contact', 'location', 'projects', 'social',
+        'employment', 'education', 'affiliation', 'service', 'skills',
+        'samples', 'writing', 'reading', 'speaking', 'recognition',
+        'references', 'testimonials', 'languages', 'interests',
+        'extracurricular', 'governance'
+      ];
+      return Object.keys( _.pick( r, expected ) ).length === expected.length;
+    }
+  ],
+
+  [ '!build',
+    [ ft + 'jane-fullstacker.json'],
+    [ sb + 'shouldnt-exist.pdf' ],
+    EXTEND(true, {}, opts, { theme: 'awesome' }),
+    ' (jane-q-fullstacker + Awesome + PDF|FRESH)'
+  ]
+
+];
+
+describe('Testing API interface', function () {
+
+    function run( verb, src, dst, opts, msg, fnTest ) {
+
+      msg = msg || '.';
+      var shouldSucceed = true;
+      if( verb[0] === '!' ) {
+        verb = verb.substr(1);
+        shouldSucceed = false;
+      }
+
+      it( 'The ' + verb.toUpperCase() + ' command should ' + (shouldSucceed ? ' SUCCEED' : ' FAIL') + msg, function () {
+
+        function runIt() {
+          try {
+            var v = new FCMD.verbs[verb]();
+            v.on('hmr:error', function(ex) { throw ex; });
+            var r = v.invoke( src, dst, opts );
+            if( fnTest )
+              if( !fnTest( r.sheet ) )
+                throw "Test: Unexpected API result.";
+          }
+          catch(ex) {
+            console.error(ex);
+            if( ex.stack || (ex.inner && ex.inner.stack))
+              console.error( ex.stack || ex.inner.stack );
+            throw ex;
+          }
+        }
+
+        if( shouldSucceed )
+          runIt.should.not.Throw();
+        else
+          runIt.should.Throw();
+      });
+
+    }
+
+    tests.forEach( function(a) {
+      run.apply( /* The players of */ null, a );
+    });
+
+});

test/test-cli.js

@@ -1,94 +1,76 @@
 /**
+CLI test routines for HackMyResume.
 @module test-cli.js
 */
 
-var chai = require('chai')
-  , expect = chai.expect
-  , should = chai.should()
-  , path = require('path')
-  , _ = require('underscore')
-	, FRESHResume = require('../src/core/fresh-resume')
-  , FCMD = require( '../src/hackmyapi')
-  , validator = require('is-my-json-valid')
-  , EXTEND = require('../src/utils/extend');
 
-chai.config.includeStack = false;
+
+var chai = require('chai')
+  , should = chai.should()
+  , HMRMAIN = require('../src/cli/main')
+  , CHALK = require('chalk')
+  , FS = require('fs')
+  , PATH = require('path')
+  , PKG = require('../package.json')
+  , _ = require('underscore');
+
+
+
+var gather = '';
+var ConsoleLogOrg = console.log;
+var ProcessExitOrg = process.exit;
+var commandRetVal = 0;
+
 
 describe('Testing CLI interface', function () {
 
-    var _sheet;
+  // TODO: use sinon
+  // Replacement for process.exit()
+  function MyProcessExit( retVal ) {
+    commandRetVal = retVal;
+  }
 
+  // HackMyResume CLI stub. Handle a single HMR invocation.
+  function HackMyResumeStub( argsString ) {
 
-    var opts = {
-      format: 'FRESH',
-      prettify: true,
-      silent: false,
-      assert: true  // Causes validation errors to throw exceptions
-    };
+    var args = argsString.split(' ');
+    args.unshift( process.argv[1] );
+    args.unshift( process.argv[0] );
+    process.exit = MyProcessExit;
 
-    var opts2 = {
-      format: 'JRS',
-      prettify: true,
-      silent: true
-    };
-
-    var sb = 'test/sandbox/';
-    var ft = 'node_modules/fresh-test-resumes/src/';
-
-    [
-
-      [ 'new',      [sb + 'new-fresh-resume.json'], [], opts, ' (FRESH format)' ],
-      [ 'new',      [sb + 'new-jrs-resume.json'], [], opts2, ' (JRS format)'],
-      [ 'new',      [sb + 'new-1.json', sb + 'new-2.json', sb + 'new-3.json'], [], opts, ' (multiple FRESH resumes)' ],
-      [ 'new',      [sb + 'new-jrs-1.json', sb + 'new-jrs-2.json', sb + 'new-jrs-3.json'], [], opts, ' (multiple JRS resumes)' ],
-      [ '!new',     [], [], opts, " (when a filename isn't specified)" ],
-
-      [ 'validate', [ft + 'jane-fullstacker.fresh.json'], [], opts, ' (jane-q-fullstacker|FRESH)' ],
-      [ 'validate', [ft + 'johnny-trouble.fresh.json'], [], opts, ' (johnny-trouble|FRESH)' ],
-      [ 'validate', [sb + 'new-fresh-resume.json'], [], opts, ' (new-fresh-resume|FRESH)' ],
-      [ 'validate', ['test/resumes/jrs-0.0.0/richard-hendriks.json'], [], opts2, ' (richard-hendriks.json|JRS)' ],
-      [ 'validate', ['test/resumes/jrs-0.0.0/jane-incomplete.json'], [], opts2, ' (jane-incomplete.json|JRS)' ],
-      [ 'validate', [sb + 'new-1.json', sb + 'new-jrs-resume.json', sb + 'new-1.json', sb + 'new-2.json', sb + 'new-3.json'], [], opts, ' (5|BOTH)' ],
-
-      [ 'analyze',  [ft + 'jane-fullstacker.fresh.json'], [], opts, ' (jane-q-fullstacker|FRESH)' ],
-      [ 'analyze',  ['test/resumes/jrs-0.0.0/richard-hendriks.json'], [], opts2, ' (richard-hendriks|JRS)' ],
-
-      [ 'build',    [ ft + 'jane-fullstacker.fresh.json', ft + 'override/jane-fullstacker-override.fresh.json' ], [ sb + 'merged/jane-fullstacker-gamedev.fresh.all'], opts, ' (jane-q-fullstacker w/ override|FRESH)' ],
-      [ '!build',   [ ft + 'jane-fullstacker.fresh.json'], [ sb + 'shouldnt-exist.pdf' ], EXTEND(true, opts, { theme: 'awesome' }), ' (jane-q-fullstacker + Awesome + PDF|FRESH)' ]
-
-    ].forEach( function(a) {
-
-      run.apply( /* The players of */ null, a );
-
-    });
-
-
-    function run( verb, src, dst, opts, msg ) {
-      msg = msg || '.';
-      var shouldSucceed = true;
-      if( verb[0] === '!' ) {
-        verb = verb.substr(1);
-        shouldSucceed = false;
-      }
-      it( 'The ' + verb.toUpperCase() + ' command should ' + (shouldSucceed ? ' SUCCEED' : ' FAIL') + msg, function () {
-        function runIt() {
-          try {
-            FCMD.verbs[verb]( src, dst, opts, opts.silent ?
-              function(){} : function(msg){ msg = msg || ''; console.log(msg); } );
-          }
-          catch(ex) {
-            console.error(ex);
-            console.error(ex.stack);
-            throw ex;
-          }
-        }
-        if( shouldSucceed )
-          runIt.should.not.Throw();
-        else
-          runIt.should.Throw();
-      });
+    try {
+      var HMRMAIN = require('../src/cli/main');
+      HMRMAIN( args );
     }
+    catch( ex ) {
+      require('../src/cli/error').err( ex, false );
+      //if(ex.stack || (ex.inner && ex.inner.stacl))
+        //console.log(ex.stack || ex.inner.stack);
+    }
+    process.exit = ProcessExitOrg;
 
+  }
 
+  // Run a test through the stub, gathering console.log output into "gather"
+  // and testing against it.
+  function run( args, expErr ) {
+    var title = args;
+    it( 'Testing: "' + title + '"\n\n', function() {
+      commandRetVal = 0;
+      HackMyResumeStub( args );
+      commandRetVal.should.equal( parseInt(expErr, 10) );
+    });
+  }
+
+  var lines = FS.readFileSync( PATH.join( __dirname, './test-hmr.txt'), 'utf8').split('\n');
+  lines.forEach(function(l){
+    if( l && l.trim() ) {
+      if(l[0] !== '#') {
+        var lineInfo = l.split('|');
+        var errCode = lineInfo[0];
+        run( lineInfo.length > 1 ? lineInfo[1] : '', errCode );
+      }
+    }
+  });
 
 });

test/test-converter.js

@@ -1,39 +0,0 @@
-
-var chai = require('chai')
-  , expect = chai.expect
-  , should = chai.should()
-  , path = require('path')
-  , parsePath = require('parse-filepath')
-  , _ = require('underscore')
-	, FRESHResume = require('../src/core/fresh-resume')
-  , CONVERTER = require('../src/core/convert')
-  , FS = require('fs')
-  , MKDIRP = require('mkdirp')
-  , _ = require('underscore');
-
-chai.config.includeStack = false;
-
-describe('FRESH/JRS converter', function () {
-
-    var _sheet;
-
-	  it('should round-trip from JRS to FRESH to JRS without modifying or losing data', function () {
-
-      var fileA = path.join( __dirname, 'resumes/jrs-0.0.0/richard-hendriks.json' );
-      var fileB = path.join( __dirname, 'sandbox/richard-hendriks.json' );
-
-      _sheet = new FRESHResume().open( fileA );
-      MKDIRP.sync( parsePath( fileB ).dirname );
-      _sheet.saveAs( fileB, 'JRS' );
-
-      var rawA = FS.readFileSync( fileA, 'utf8' );
-      var rawB = FS.readFileSync( fileB, 'utf8' );
-
-      var objA = JSON.parse( rawA );
-      var objB = JSON.parse( rawB );
-
-      _.isEqual(objA, objB).should.equal(true);
-
-    });
-
-});

test/test-fresh-sheet.js

@@ -58,5 +58,14 @@ function testResume(opts) {
 }
 
 var sects = [ 'info', 'employment', 'service', 'skills', 'education', 'writing', 'recognition', 'references' ];
-testResume({ title: 'jane-q-fullstacker', path: 'node_modules/fresh-test-resumes/src/jane-fullstacker.fresh.json', duration: 7, sections: sects });
-testResume({ title: 'johnny-trouble-resume', path: 'node_modules/fresh-test-resumes/src/johnny-trouble.fresh.json', duration: 4, sections: sects });
+testResume({ title: 'jane-q-fullstacker', path: 'node_modules/fresh-test-resumes/src/fresh/jane-fullstacker.json', duration: 7, sections: sects });
+testResume({ title: 'johnny-trouble-resume', path: 'node_modules/fresh-test-resumes/src/fresh/johnny-trouble.json', duration: 4, sections: sects });
+
+sects = [ 'info', 'contact', 'location' ];
+testResume({ title: 'jane-q-fullstacker A', path: 'node_modules/fresh-test-resumes/src/fresh/override/jane-partial-a.json', duration: 0, sections: sects });
+
+sects = [ 'projects', 'social', 'employment', 'education', 'affiliation' ];
+testResume({ title: 'jane-q-fullstacker B', path: 'node_modules/fresh-test-resumes/src/fresh/override/jane-partial-b.json', duration: 7, sections: sects });
+
+sects = [ 'service', 'skills', 'samples', 'writing', 'reading', 'speaking', 'recognition', 'references', 'testimonials', 'languages', 'interests', 'extracurricular', 'governance' ];
+testResume({ title: 'jane-q-fullstacker C', path: 'node_modules/fresh-test-resumes/src/fresh/override/jane-partial-c.json', duration: 0, sections: sects });

test/test-hmr.txt

@@ -0,0 +1,27 @@
+0|
+0|--help
+0|-h
+0|--debug
+0|-d
+5|notacommand
+3|build
+14|build doesnt-exist.json
+14|build doesnt-exist.json -t not-a-theme
+14|build doesnt-exist.json -t node_modules/not-a-theme
+8|new
+0|new test/sandbox/cli-test/new-empty-resume.auto.json
+0|new test/sandbox/cli-test/new-empty-resume.jrs.json -f jrs
+0|new test/sandbox/cli-test/new-empty-resume.fresh.json -f fresh
+3|analyze
+14|analyze doesnt-exist.json
+3|convert
+7|convert doesnt-exist.json
+3|validate
+14|validate doesnt-exist.json
+0|validate node_modules/fresh-test-resumes/src/fresh/jane-fullstacker.json
+3|peek
+14|peek doesnt-exist.json
+14|peek doesnt-exist.json not.a.path
+0|peek test/resumes/jrs-0.0.0/richard-hendriks.json work[0]
+0|peek node_modules/fresh-test-resumes/src/fresh/jane-fullstacker.json employment.history[1]
+0|peek node_modules/fresh-test-resumes/src/fresh/johnny-trouble.json skills.sets

test/test-stdout.js

@@ -0,0 +1,144 @@
+/**
+Output test routines for HackMyResume.
+@module test-stdout.js
+*/
+
+
+
+var chai = require('chai')
+  , expect = chai.expect
+  , HMRMAIN = require('../src/cli/main')
+  , CHALK = require('chalk')
+  , FS = require('fs')
+  , PATH = require('path')
+  , PKG = require('../package.json')
+  , _ = require('underscore');
+
+
+
+var gather = '';
+var ConsoleLogOrg = console.log;
+var ProcessExitOrg = process.exit;
+
+
+
+describe('Testing Ouput interface', function () {
+
+  // TODO: use sinon
+  // Replacement for console.log
+  function MyConsoleLog( msg ) {
+    gather += Array.prototype.slice.call(arguments).join(' ');
+    ConsoleLogOrg.apply(this, arguments);
+  }
+
+  // Replacement for process.exit()
+  function MyProcessExit() {
+
+  }
+
+  // HackMyResume CLI stub. Handle a single HMR invocation.
+  function HackMyResumeStub( args ) {
+
+    console.log = MyConsoleLog;
+    process.exit = MyProcessExit;
+    CHALK.enabled = false;
+
+    try {
+      args.unshift( process.argv[1] );
+      args.unshift( process.argv[0] );
+      var HMRMAIN = require('../src/cli/main');
+      HMRMAIN( args );
+    }
+    catch( ex ) {
+      require('../src/cli/error').err( ex, false );
+    }
+    CHALK.enabled = true;
+    process.exit = ProcessExitOrg;
+    console.log = ConsoleLogOrg;
+
+  }
+
+  // Run a test through the stub, gathering console.log output into "gather"
+  // and testing against it.
+  function run( title, args, tests ) {
+    it( title, function() {
+
+      gather = '';
+      HackMyResumeStub( args );
+
+      expect(
+        _.all( tests, function(t) {
+          return gather.indexOf(t) > -1;
+        })
+      ).to.equal(true);
+
+    });
+  }
+
+  var title = '*** HackMyResume v' + PKG.version + ' ***';
+  var feedMe = 'Please feed me a resume in FRESH or JSON Resume format.';
+  var manPage = FS.readFileSync( PATH.resolve( __dirname, '../src/cli/use.txt' ), 'utf8');
+
+  run('HMR should output a help string when no command is specified',
+      [], [ title, 'Please give me a command (BUILD, ANALYZE, VALIDATE, CONVERT, NEW, or PEEK).' ]);
+
+  run('BUILD should output a tip when no source is specified',
+      ['build'], [ title, feedMe ]);
+
+  run('VALIDATE should output a tip when no source is specified',
+     ['validate'], [ title, feedMe ]);
+
+  run('ANALYZE should output a tip when no source is specified',
+      ['analyze'], [ title, feedMe ]);
+
+  run('BUILD should display an error on a broken resume',
+     ['build',
+      'node_modules/fresh-test-resumes/src/fresh/johnny-trouble.broken.json',
+      '-t', 'modern'
+    ], [ title, 'Error: Invalid or corrupt JSON on line'  ]);
+
+  run('CONVERT should output a tip when no source is specified',
+      ['convert'], [ title, feedMe ]);
+
+  run('NEW should output a tip when no source is specified',
+      ['new'], [ title, 'Please specify the filename of the resume to create.' ]);
+
+  // This will cause the HELP doc to be emitted, followed by an "unknown option --help"
+  // error in the log, based on the way we're calling into HMR. As long as the test
+  // passes, any extraneous error messages can be ignored here.
+  run('HMR should output help doc with --help',
+      ['--help'], [ manPage ]);
+
+  run('HMR should accept raw JSON via --options',
+      [
+        'build',
+        'node_modules/fresh-test-resumes/src/fresh/jane-fullstacker.json',
+        'to',
+        'test/sandbox/temp/janeq-1.all',
+        '-o',
+        "{ theme: 'compact', debug: true, pdf: 'wkhtmltopdf' }"],
+      [ 'Applying COMPACT theme (', '(with wkhtmltopdf)'] );
+
+  run('HMR should accept a JSON settings file via --options',
+      [
+        'build',
+        'node_modules/fresh-test-resumes/src/fresh/jane-fullstacker.json',
+        'to',
+        'test/sandbox/temp/janeq-2.all',
+        '--options',
+        "test/hmr-options.json"],
+      [ 'Applying POSITIVE theme'] );
+
+  run('Explicit command line options should override --options',
+      [
+        'build',
+        'node_modules/fresh-test-resumes/src/fresh/jane-fullstacker.json',
+        'to',
+        'test/sandbox/temp/janeq-3.all',
+        '--options',
+        "test/hmr-options.json",
+        "-t",
+        "modern"
+      ],
+      [ 'Applying MODERN theme'] );
+});

test/test-themes.js

@@ -1,6 +1,5 @@
 
-var SPAWNWATCHER = require('../src/core/spawn-watch')
-  , chai = require('chai')
+var chai = require('chai')
   , expect = chai.expect
   , should = chai.should()
   , path = require('path')
@@ -10,7 +9,8 @@ var SPAWNWATCHER = require('../src/core/spawn-watch')
   , validator = require('is-my-json-valid')
   , READFILES = require('recursive-readdir-sync')
   , fileContains = require('../src/utils/file-contains')
-  , FS = require('fs');
+  , FS = require('fs')
+  , CHALK = require('chalk');
 
 chai.config.includeStack = true;
 
@@ -32,17 +32,16 @@ function genThemes( title, src, fmt ) {
             format: fmt,
             prettify: true,
             silent: false,
-            css: 'embed'
+            css: 'embed',
+            debug: true
           };
           try {
-            HMR.verbs.build( src, dst, opts, function(msg) {
-              msg = msg || '';
-              console.log(msg);
-            });
+            var v = new HMR.verbs.build();
+            v.invoke( src, dst, opts );
           }
           catch(ex) {
-            console.log(ex);
-            console.log(ex.stack);
+            console.error( ex );
+            console.error( ex.stack );
             throw ex;
           }
         }
@@ -53,7 +52,7 @@ function genThemes( title, src, fmt ) {
     genTheme(fmt, src, 'hello-world');
     genTheme(fmt, src, 'compact');
     genTheme(fmt, src, 'modern');
-    genTheme(fmt, src, 'minimist');
+    genTheme(fmt, src, 'underscore');
     genTheme(fmt, src, 'awesome');
     genTheme(fmt, src, 'positive');
     genTheme(fmt, src, 'jsonresume-theme-boilerplate', 'node_modules/jsonresume-theme-boilerplate' );
@@ -69,15 +68,15 @@ function folderContains( needle, haystack ) {
   return _.some( READFILES( path.join(__dirname, haystack) ), function( absPath ) {
     if( FS.lstatSync( absPath ).isFile() ) {
       if( fileContains( absPath, needle ) ) {
-        console.log('Found invalid metadata in ' + absPath);
+        console.error('Found invalid metadata in ' + absPath);
         return true;
       }
     }
   });
 }
 
-genThemes( 'jane-q-fullstacker', ['node_modules/fresh-test-resumes/src/jane-fullstacker.fresh.json'], 'FRESH' );
-genThemes( 'johnny-trouble', ['node_modules/fresh-test-resumes/src/johnny-trouble.fresh.json'], 'FRESH' );
+genThemes( 'jane-q-fullstacker', ['node_modules/fresh-test-resumes/src/fresh/jane-fullstacker.json'], 'FRESH' );
+genThemes( 'johnny-trouble', ['node_modules/fresh-test-resumes/src/fresh/johnny-trouble.json'], 'FRESH' );
 genThemes( 'richard-hendriks', ['test/resumes/jrs-0.0.0/richard-hendriks.json'], 'JRS' );
 
 describe('Verifying generated theme files...', function() {