#
Pretty Diff - Documentation

Color Scheme

Explore some samples. For any questions, comments, requests, or feedback please join the Pretty Diff mailing list or chat on Gitter. Find Pretty Diff on GitHub.

## About This Application

### Introduction

This tool was originally created to compare minified code by attaching a beautifier and minifier to a file comparison tool. Over the years it has grown into custom language parsers capable of performing a variety of language analysis. This application is 100% vanilla JavaScript and is API independent.

### License

@source http://prettydiff.com/prettydiff.js

@documentation - English http://prettydiff.com/documentation.xhtml

@licstart The following is the entire license notice for Pretty Diff.

This code may not be used or redistributed unless the following conditions are met:

- Prettydiff created by Austin Cheney originally on 3 Mar 2009. http://prettydiff.com/
- The use of diffview.js and prettydiff.js must contain the following copyright:
  1. Copyright © 2007, Snowtide Informatics Systems, Inc. All rights reserved.
  2. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  3. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  4. Neither the name of the Snowtide Informatics Systems nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
  5. used as diffview function: http://prettydiff.com/lib/diffview.js
- The code mentioned above has significantly expanded documentation in each of the respective function's external JS file as linked from the documentation page: http://prettydiff.com/documentation.xhtml
- In addition to the previously stated requirements any use of any component, aside from directly using the full files in their entirety, must restate the license mentioned at the top of each concerned file.

If each and all these conditions are met use, extension, alteration, and redistribution of Pretty Diff and its required assets is unlimited and free without author permission.

@licend The above is the entire license notice for Pretty Diff.

### Informational Guides

1. Using jsscope to understand scope, inheritance, and scope chains in JavaScript
2. Ignoring specified tags from markup beautification
3. So its kind of like recursive command line diff, but in JavaScript
4. Processing the JSX format from Facebook's React
5. Saving colorful JavaScript code samples
6. Conforming to popular style guides with the styleguide option
7. What Pretty Diff can do to auto-correct some sloppiness in JavaScript.
8. Brief overview of the prettydiff.js code architecture
9. Native Modules in Pretty Diff
10. The .prettydiffrc file

### Unrelated Guides

1. The DOM Explained, Quick and Simple
2. A/B Testing for the Web
3. Explaining Closure To A Child
4. Becoming a JavaScript Rock Star (In the Real World)

## Execution

- ### Execute in a NodeJS app:

  Install the prettydiff package locally

  `npm install prettydiff`

  Add this following code to your application

  `var prettydiff = require("prettydiff"),` `args = {` `source: "asdf",` `diff : "asdd",` `lang : "text",` `},` `output = prettydiff.api(args);`

- ### Execute on command line with NodeJS:

  Install the prettydiff package globally

  `npm install prettydiff -g`

  Example of a command line instruction

  `prettydiff source:"c:\mydirectory\myfile.js" readmethod:"file" diff:"c:\myotherfile.js"`

- ### Execute with WSH:

  `cscript prettydiff.wsf /source:"myFile.xml" /mode:"beautify"`

- ### Execute from JavaScript:

  `var global = {},` `args = {` `source: "asdf",` `diff : "asdd",` `lang : "text",` `},` `output = prettydiff(args);`

## Unit Tests

### Requirements and Execution

The Pretty Diff unit tests are defined in the file test/lint.js and require Node.js and NPM to execute. To run the tests type this command on the command line from inside the prettydiff package directory:

`npm test`

### Test Details

Running the tests will check if the unit tests have run before the current day and if not will attempt to install the latest version of JSLint from NPM. JSLint will then be run on all JavaScript files in the repo directories aside from a few exceptions. On the first file that produces JSLint warnings the warnings are reported to the command line and the process is halted as an error.

Once JSLint completes all the files are read from the directories: test/samples_raw and test/samples_correct. Each file from the raw directory is processed through Pretty Diff and then compared to the same named file in the correct directory. If every comparison is a match the unit tests exit cleanly. The first file to fail a comparison is output to the command line as a diff report using Pretty Diff with the diffcli option.

## Environments

### Web Tool

The web tool is the means of accessing Pretty Diff through a web browser from the domain http://prettydiff.com/ or locally from the prettydiff.com.xhtml file. This HTML interface is entirely powered by the node-local.js library.

To access the tool's options just scroll down the page a bit. Options are sorted by language categorty and then alphabetically the name of each option's respective API key.

Since some of Pretty Diff's reporting capabilities are generated as HTML the web tool is the easiest way to examine these features. Some of these features include colorful JavaScript code by scope and the diff report.

To save down an HTML report follow these easy steps:

1. Generate the report in question, such as running a regular code comparison.
2. The web tool generates reports in a floating window on the page. In the top right corner of this window are three square icons. The first such icon is red with the letter " S". Click this icon.
3. In Firefox you will be automatically prompted to save a file that is a fully prepared document containing the necessary HTML, CSS, and JavaScript. In other browsers a textarea will appear containing the code of a complete and fully prepared document for saving into a file using other software, such as a text editor.
4. In the cases where only the report is desired, instead of a complete document, the web tool provides an option Save Preference. Select the option for Report Only. Instead of generating a complete document this option will instead generate four textareas for: necessary CSS, necessary JavaScript, HTML formatted data about the report, and the report content itself.

For convenience and additional productivity the Code Report window can be dragged offscreen to the right of the page. Doing this will allow unobstructed access to the web tool and allow the generated code report to be visible simultaneously. This is particularly handy if working in the web tool frequently across multiple monitors.

### Executing with Node.js

Using Node.js is the preferred way to access Pretty Diff from the command line. This access can be a manual action or the result of other automation.

Pretty Diff can be manually downloaded from the Github repository or more easily installed with NPM. Pretty Diff supports both a local and a global NPM installation.

Here are some examples of running Pretty Diff from the command line with global NPM installation:

1. `npm install prettydiff -g`
2. `prettydiff source:"myCodeLocation" readmethod:"file" mode:"beautify"`

Running Pretty Diff from a local NPM installation or from a manual download is a bit more tedious, but allows easier experimentation with the code. Here is a code example:

1. `npm install prettydiff`
2. `node node_modules/prettydiff/api/node-local.js source:"myCodeLocation" readmethod:"file" mode:"beautify"`

Pretty Diff can also be used as a Node module in other code projects. Here is an example in code:

1. `var prettydiff = require("prettydiff"),` `args = {` `source: "asdf",` `diff : "asdd",` `lang : "text"` `},` `output = [];`
2. `output = prettydiff.api(args);`

Pretty Diff supports saved configurations using a .prettydiffrc file. Pretty Diff will first for the file in the command prompt's current directory and then look for it in the application's directory. Pretty Diff will attempt to parse this file first as a simple JSON object, but advanced logic is allowed in the provide format. This file is not evaluated until after the options from the command prompt are evaluated, so the JS logic format allows setting options relative to the values of other provided options. Additional technical details are available in the guide.

Some Node specific funtionality is provided.

- diffcli The diffcli option allows for differences to be printed to the screen directly instead of generating HTML based code reports. This functionality closely resembles the old Unix diff utility.
- readmethod The readmethod option determines how the application should interact with the filesystem or remote files.
- summaryonly The summaryonly option allows for Pretty Diff to perform a full examination, but only outputs to screen a list of changed files and a count of differences and writes no files.

### Executing with Windows Script Host (WSH)

Windows Script Host allows for a JavaScript run time in Windows environments from a command line with output directly returned to the command line or in a debugger window. To execute JavaScript with WSH a file is needed to supply the JavaScript function call, pass arguments from command line into a JavaScript compatible format, and to request dependencies.

An actively maintained API is provided at api/prettydiff.wsf. A WSF file follows basic XML syntax and may allow multiple operations of different languages to execute in tandem so long as each operation is confined to a job tag. The named elements in the example file are used to intercept arguments supplied via command line.

The example file would be operated for HTML compatibility using the following command: `cscript prettydiff.wsf /source:"my_source_file.js" /html:true /mode:"beautify"`

Writing the output of a WSH task into a file would require an additional ActiveX instruction in the wsh.wsf file or would require the automation of script execution in the context of the PowerShell language.

## Web Tool URI Parameters

1. c - This parameter receives the name of a supported color scheme.
2. d - This parameter receives a URI as a value that points a difference code source. If the value of this URI contains ampersand characters, &, or question mark characters, ?, please escape the ampersands characters to "%26" and the question mark characters to %3F.
3. jscorrect - This presence of this parameter sets the jscorrect parameter to boolean "true". No value is required.
4. jsscope - This parameter forcefully applies the jsscope feature of the JSPretty library and does not require a value.
5. l - This parameter receives a value of markup, html, auto, javascript, js, css, csv, or text. This bypasses all other language settings and determinations thereby forcefully applying the language against the supplied value to this parameter. The value of "html" is identical to the value "markup" except that it forces the option "Presume SGML type HTML" for all modes while "markup" unsets this option. The values "javascript" and "js" are treated equally.
6. m - This parameter receives a value of beautify, minify, or diff. This parameter sets the mode of the tool.
7. s - This parameter receives a URI as a value that points a code source. If the value of this URI contains ampersand characters, &, or question mark characters, ?, please escape the ampersands characters to "%26" and the question mark characters to %3F. The tool executes this code automatically on page load for beautify and minify modes, but only for diff mode if a source is provided with the d parameter.
8. ace - If this parameter is present with a value of false the Ace code editor will be discarded in favor of HTML textarea elements.

The parameters are optional and are provided solely for portability. The parameters may occur in any order. Examples:

1. http://prettydiff.com/?l=html&s=http://google.com/&m=beautify
2. http://prettydiff.com/?s=http://www.amazon.com/Definitive-XML-Schema-Priscilla-Walmsley/dp/0130655678/ref=sr_1_1%3Fie=UTF8%26qid=1312890971%26sr=8-1&html&m=beautify

## Pretty Diff Options

### Precedence

Pretty Diff sets option values according to this order of precedence from highest priority to lowest:

1. The styleguide option, which is only used in the jspretty library.
2. The Pretty Diff comment.
3. The .prettydiffrc file, which is only available to the node-local file (command line Node.js).
4. User supplied options
5. Default option values

### Option Definitions

1. #### api

   - ##### Description

     Used internally to decide if some small JavaScript functions need to be included with report output based upon the operating environment.

2. #### braceline

   - ##### Description

     In JavaScript a new line is inserted after opening curly braces and before closing curly braces.

   - ##### Type

     boolean

   - ##### Default

     false

   - ##### As labeled in the HTML tool

     Brace Lines

3. #### bracepadding

   - ##### Description

     Inserts a space after the start of a contain and before the end of the container in JavaScript if the contents of that container are not indented; such as: conditions, function arguments, and escaped sequences of template strings.

   - ##### Type

     boolean

   - ##### Default

     false

   - ##### As labeled in the HTML tool

     Brace Padding

4. #### braces

   - ##### Description

     Sets the style of indentation during CSS and JavaScript beautification. The default value "knr" sets a JSLint compliant beautification scheme and the other value "allman" puts opening curly braces on their own line.

   - ##### Type

     string

   - ##### Accepts

     knr, allman

   - ##### Default

     knr

   - ##### As labeled in the HTML tool

     Style of Indent

5. #### color (node-local.js only)

   - ##### Description

     Specifies which color scheme to apply to the output file.

   - ##### Type

     string

   - ##### Default

     white

   - ##### Accepted values

     canvas, default, shadow, white

6. #### comments

   - ##### Description

     Determines whether comments should be indented. This property is only used in beautification mode.

   - ##### Type

     string

   - ##### Accepted values

     indent, noindent

   - ##### Default

     indent

   - ##### As labeled in the HTML tool

     Indent Comments

7. #### commline

   - ##### Description

     Whether a blank line should be forced above markup comments.

   - ##### Type

     boolean

   - ##### Default

     false

   - ##### As labeled in the HTML tool

     Force an Empty Line Above Comments

8. #### conditional

   - ##### Description

     Retain Internet Explorer conditional HTML comments during minification of HTML.

   - ##### Type

     boolean

   - ##### Default

     false

   - ##### As labeled in the HTML tool

     IE Comments, HTML Only

9. #### content

   - ##### Description

     Determines if string literals in JavaScript and content in markup should be normalized to a literal value of text prior to a diff operation. This property is only used if mode is set to diff.

   - ##### Type

     boolean

   - ##### Default

     false

   - ##### As labeled in the HTML tool

     Ignore Content, Markup / JavaScript

10. #### context

    - ##### Description

      In the diff mode a numeric value sets the number of matching (equivalent) lines to precede and follow each line containing a difference to provide code context. An empty or non-numeric value returns a diff report with all lines of code.

    - ##### Type

      string or number

    - ##### Default

      no value (empty string)

    - ##### As labeled in the HTML tool

      Context size

11. #### correct

    - ##### Description

      A limited attempt to automatically correct certain stylistic code problems that JSLint complains about and missing closing list item tags in HTML. This option will insert missing semicolons, insert missing curly braces, convert some instances of "--" and "++" operators to "-=" and "+=" respectively, and convert "new Object()" and "new Array()" into "{}" and "[]" respectively.

    - ##### Type

      boolean

    - ##### Default

      false

    - ##### Informational Guide

      jscorrect option

    - ##### As labeled in the HTML tool

      Fix Sloppy Code

12. #### crlf

    - ##### Description

      If the line termination of processed output should be Windows CRLF format. Unix format (LF) is the default.

    - ##### Type

      boolean

    - ##### Default

      false

    - ##### As labeled in the HTML tool

      Line Termination

13. #### cssinsertlines

    - ##### Description

      Forces new line characters between blocks of CSS code. This option will override option preserve.

    - ##### Type

      boolean

    - ##### Default

      false

    - ##### As labeled in the HTML tool

      Insert Extra Lines

14. #### csvchar

    - ##### Description

      Stores the string value used as a data separator for the "csv" language. Any string is accepted, but if value of lang property is not set to "csv" this property is ignored.

    - ##### Type

      string

    - ##### Default

      , (comma)

    - ##### As labeled in the HTML tool

      Character separator

15. #### diff

    - ##### Description

      Code sample to compare the source code sample against. This property is required when mode is set to diff, but is otherwise ignored.

    - ##### Type

      string

    - ##### Default

      none

    - ##### As labeled in the HTML tool

      New Text

16. #### diffcli

    - ##### Description

      An option only available from the node-local.js API file for Node.js. This option will output a list of differences in color to the console. If more than one file is compared it will indicate which files are deleted or new. If the output option is not specified the node-local.js will convert the diffcli option to a value of true. If the value of diffcli is true and the context option is omitted the context option will be provided a value of 2. For additional information please read the diffcli guide.

    - ##### Type

      boolean

    - ##### Default

      false

    - ##### Informational Guide

      Using diffcli

    - ##### As labeled in the HTML tool

      not in the HTML tool

17. #### diffcomments

    - ##### Description

      Retain code comments so that code and comments can be compared by the diff process.

    - ##### Type

      boolean

    - ##### Default

      false

    - ##### As labeled in the HTML tool

      Code Comments

18. #### difflabel

    - ##### Description

      Sets a label describing the value of diff code sample.

    - ##### Type

      string

    - ##### Default

      new

    - ##### As labeled in the HTML tool

      New label (optional)

19. #### diffspaceignore

    - ##### Description

      Ignores white space only differences from the diff tool.

    - ##### Type

      boolean

    - ##### Default

      false

    - ##### As labeled in the HTML tool

      Ignore White Space Differences

20. #### diffview

    - ##### Description

      Determines if the diff report should be expressed is a side-by-side comparison or a single column inline view.

    - ##### Type

      string

    - ##### Accepted values

      sidebyside, inline

    - ##### Default

      sidebyside

    - ##### As labeled in the HTML tool

      Diff View Type

21. #### dustjs

    - ##### Description

      Presume the provided markup code is a Dust.js template. This option is for internal use only and is automatically enabled if language value is dustjs or if the Dust.js language is detected from auto-detection.

    - ##### Type

      boolean

    - ##### Default

      false

    - ##### As labeled in the HTML tool

      Dust.js Template

22. #### elseline

    - ##### Description

      If the "else" keyword should be pushed onto a new line in JavaScript beautification.

    - ##### Type

      boolean

    - ##### Default

      false

    - ##### As labeled in the HTML tool

      Else on New Line

23. #### endcomma

    - ##### Description

      If a terminating comma should be inserted into arrays, object literals, and destructured objects.

    - ##### Type

      boolean

    - ##### Default

      false

    - ##### As labeled in the HTML tool

      Trailing Commas

24. #### force_indent

    - ##### Description

      Allows every piece of code and content in a markup language to be indented without regard for the creation of white space tokens or code semantics.

    - ##### Type

      boolean

    - ##### Default

      false

    - ##### As labeled in the HTML tool

      Force Indentation

25. #### help (node-local.js only)

    - ##### Description

      Displays documenation to the command line or console.

26. #### html

    - ##### Description

      Forces markup code to be interpreted as HTML. HTML mode identifies certain tags as singletons by tag name even if they are no closed with "/>" syntax. It also ignores beautification on "<pre>" elements and tolerates "<li>" elements that do not a closing "</li>" tag. This option will be automatically assigned a value of true if the lang option is provided a value of "auto" and the code can be identified as HTML.

    - ##### Type

      boolean

    - ##### Default

      false

    - ##### As labeled in the HTML tool

      Presume HTML

27. #### inchar

    - ##### Description

      Stores the character literal used for an indentation. A single indentation is the result of this value repeated the number of times specified in the insize option.

    - ##### Type

      string

    - ##### Default

      (a single space)

    - ##### As labeled in the HTML tool

      Indentation character

28. #### inlevel

    - Pads JavaScript and markup beautification with additional indentation. Useful in the case of submitting code to a markdown format that identifies code by a padding of 4 spaces for each code line.

    - ##### Type

      number

    - ##### Default

      0

    - ##### As labeled in the HTML tool

      Code padding, Markup / JavaScript

29. #### insize

    - ##### Description

      Stores the number of times the inchar value must repeat to comprise a single indentation.

    - ##### Type

      number

    - ##### Default

      4

    - ##### As labeled in the HTML tool

      Indentation size

30. #### jsscope

    - ##### Description

      Produce HTML output for JavaScript beautification that colors variables based upon their scope of declaration. Using colors this feature highlights inheritance, scope depth, and closure. The value "none" turns this feature off. The value "html" creates a formatted HTML code sample for displaying HTML code samples on web pages. The value "report" creates the code for a complete HTML file. For additional information please read the jsscope guide and the jshtml guide.

    - ##### Type

      string

    - ##### Accepted values

      none, html, report

    - ##### Default

      none

    - ##### Informational Guide

      jsscope features and saving colorful code as HTML

    - ##### As labeled in the HTML tool

      Scope Analysis

31. #### lang

    - ##### Description

      Tells the diff program which language it is receiving. The value "auto" allows the application to determine between CSS, JavaScript, and Markup without human effort. If the auto value cannot determine the language it will default to a value of text if the mode is diff or it will default to a value of JavaScript for other modes.

    - ##### Type

      string

    - ##### Accepted values

      auto, css, csv, javascript, markup, text

    - ##### Default

      auto

    - ##### As labeled in the HTML tool

      Code type

32. #### langdefault

    - ##### Description

      If the lang option is set to a value of "auto" the value of langdefault determines what the default language should be in case where a language cannot be detected from the code sample.

    - ##### Type

      string

    - ##### Accepted values

      css, csv, javascript, markup, text

    - ##### Default

      javascript (dom.js - HTML tool), text (node-local.js and prettydiff.wsf)

    - ##### As labeled in the HTML tool

      Auto detect default

33. #### methodchain

    - ##### Description

      Whether consecutive methods should be continuously chained onto a single line of code.

    - ##### Type

      string

    - ##### Accepted values

      chain, indent, none

    - ##### Default

      indent

    - ##### As labeled in the HTML tool

      Chain Methods

34. #### miniwrap

    - ##### Description

      Whether minified JavaScript code should wrap after a specified character width. This option requires a value for option wrap.

    - ##### Type

      boolean

    - ##### Default

      false

    - ##### As labeled in the HTML tool

      Minify Wrapping, for use with wrap

35. #### mode

    - ##### Description

      The operation to be performed.

    - ##### Type

      string

    - ##### Accepted values

      beautify, diff, minify, parse

    - ##### Default

      diff

    - ##### As labeled in the HTML tool

      Function

36. #### neverflatten

    - ##### Description

      Prevents flattening of destructured lists in JavaScript.

    - ##### Type

      boolean

    - ##### Default

      false

    - ##### As labeled in the HTML tool

      Never Flatten Destructured Lists

37. #### nocaseindent

    - ##### Description

      If the JavaScript keywords case and default should receive the same indentation as their parent switch keyword. This feature is required by certain code validators and style checkers, such as JSLint.

    - ##### Type

      boolean

    - ##### Default

      false

    - ##### As labeled in the HTML tool

      Case Indentation

38. #### noleadzero

    - ##### Description

      If in CSS values leading 0s immediately preceeding a decimal should be removed or prevented.

    - ##### Type

      boolean

    - ##### Default

      false

    - ##### As labeled in the HTML tool

      Leading 0s

39. #### objsort

    - ##### Description

      Sorts properties of objects in JavaScript and/or CSS and/or attributs in HTML. The accepted values determine which language this option should be applied.

    - ##### Type

      string

    - ##### Accepted values

      all, css, js, markup, none

    - ##### Default

      js

    - ##### As labeled in the HTML tool

      Property Sorting, CSS / JavaScript

40. #### output (node-local.js only)

    - ##### Description

      Determines the location of where files should be saved.

    - ##### Type

      string

41. #### preserve

    - ##### Description

      Retain empty lines in either JavaScript or CSS like languages. Consecutive empty lines will be converted to a single empty line.

    - ##### Type

      string

    - ##### Accepted values

      all, css, js, none

    - ##### Default

      js

    - ##### As labeled in the HTML tool

      Empty Lines, CSS / JavaScript

42. #### quote

    - ##### Description

      Diff only language independent option to normalize single quote characters to double quote characters.

    - ##### Type

      boolean

    - ##### Default

      false

    - ##### As labeled in the HTML tool

      Diff Quotes

43. #### quoteconvert

    - ##### Description

      Convert the quote characters delimiting strings from either double or single quotes to the other. Applies to JavaScript and CSS and to attributes in markup.

    - ##### Type

      string

    - ##### Accepted values

      double, single, none

    - ##### Default

      none

    - ##### As labeled in the HTML tool

      Quotes, Markup / JavaScript

44. #### readmethod (node-local.js only)

    - ##### Description

      Determines how input should be received. The value auto changes to directory, file, or screen depending on the source type. The value directory will read all files from a single directory. The value file reads the contents of a single file. The value filescreen reads the contents of a file but outputs the result to the console. The value screen will look to the console for code input and outputs to the console. The value subdirectory will recursively read files in subdirectories.

    - ##### Type

      string

    - ##### Default

      screen

    - ##### Accepted values

      auto, directory, file, filescreen, screen, subdirectory

45. #### report (node-local.js only)

    - ##### Description

      Determines if a meta data report should be generated.

    - ##### Type

      boolean

    - ##### Default

      true

46. #### selectorlist

    - ##### Description

      Retains comma separated CSS selectors on a single line of code.

    - ##### Type

      boolean

    - ##### Default

      false

    - ##### As labeled in the HTML tool

      Comma Separated Selector Lists

47. #### semicolon

    - ##### Descriptiong

      If semicolon characters at the end of a line should be removed prior to a diff operation.

    - ##### Type

      boolean

    - ##### Default

      false

    - ##### As labeled in the HTML tool

      Trailing Semicolons

48. #### source

    - ##### Description

      A code sample to operate upon.

    - ##### Type

      string

    - ##### Default

      none

    - ##### As labeled in the HTML tool

      Base Text (diff), Beautification input (beauty), Minification input (minify)

49. #### sourcelabel

    - ##### Descriptiong

      Sets a label describing the value of source property in the diff report.

    - ##### Type

      string

    - ##### Default

      Base

    - ##### As labeled in the HTML tool

      Base label (optional)

50. #### space

    - ##### Description

      Inserts a space following a function keyword for anonymous functions in JavaScript beautification.

    - ##### Type

      boolean

    - ##### Default

      true

    - ##### As labeled in the HTML tool

      Function Space

51. #### spaceclose

    - ##### Description

      Whether markup self-closing tags should terminate with or without a space, for example " />" or " />". A value of true forces the space and false forces its removal.

    - ##### Type

      boolean

    - ##### Default

      false

    - ##### As labeled in the HTML tool

      End Self-Closing Tags with a Space

52. #### style

    - ##### Description

      Whether CSS and JavaScript code should be indented according to the surrounding markup or if they should be indented starting from 0. This property is only applied to markup code containing CSS and JavaScript.

    - ##### Type

      boolean

    - ##### Default

      true

    - ##### As labeled in the HTML tool

      Indent Style/Script

53. #### styleguide

    - ##### Description

      Provides a packaged set of option configurations for JavaScript interpretation to more closely conform to popular style guides. In the face of a conflict between something configured to the value of a styleguide option setting and a separately specified option the styleguide overrides. For additional information please see the styleguide guide.

    - ##### Type

      string

    - ##### Accepted values

      airbnb, crockford, google, grunt, jquery, mediawiki, yandex, none

    - ##### Default

      none

    - ##### Informational Guide

      styleguide definitions

    - ##### As labeled in the HTML tool

      Style Guide

54. #### summaryonly (node-local.js only)

    - ##### Description

      A Node only option if there should be no files generated and no output to the screen except for a final summary.

    - ##### Type

      boolean

    - ##### Default

      false

55. #### tagmerge

    - ##### Description

      Combines adjacent start and end tags of the same name into a single self-closing tag, for example: `<a href="homepage.html"></a>` into `<a href="homepage.html"/>`.

    - ##### Type

      boolean

    - ##### Default

      false

    - ##### As labeled in the HTML tool

      Merge Empty Tag Sets Into A Single Self-Closing Tag

56. #### tagsort

    - ##### Description

      Sort child items of each respective markup parent element.

    - ##### Type

      boolean

    - ##### Default

      false

    - ##### As labeled in the HTML tool

      Sort child text/elements of each parent element

57. #### ternaryline

    - ##### Description

      By default Pretty Diff will indent on the ? and : operators of ternary statements. Setting this option to true keep these operators on the same line of code.

    - ##### Type

      boolean

    - ##### Default

      false

    - ##### As labeled in the HTML tool

      Ternary Formatting

58. #### textpreserve

    - ##### Description

      Preserve all text exactly as provided. This option eliminates any sort of beautification or wrapping upon text content in markup type languages.

    - ##### Type

      boolean

    - ##### Default

      false

    - ##### As labeled in the HTML tool

      Preserve text content

59. #### titanium

    - ##### Description

      If the JavaScript parser should parse Titanium Style Sheets instead of JavaScript. This option may be set explicitly, but is primarily used internally from language detection or if the value of the lang option is "tss".

    - ##### Type

      boolean

    - ##### Default

      false

    - ##### As labeled in the HTML tool

      not in the HTML tool

60. #### topcoms

    - ##### Description

      If minification should include into the output all comments at the top of JavaScript or CSS input before any code.

    - ##### Type

      boolean

    - ##### Default

      false

    - ##### As labeled in the HTML tool

      Top Comments, CSS / JavaScript

61. #### varword

    - ##### Description

      If a single var should be used to declare a list of variables or if a var keyword should be used per variable. A value of each will convert comma separated variable lists into separate statements each starting with a var keyword. The value list will convert consecutive variable statements to a comma separated list. The value none omits this option.

    - ##### Type

      string

    - ##### Accepted values

      each, list, none

    - ##### Default

      none

    - ##### As labeled in the HTML tool

      Variable Lists

62. #### vertical

    - ##### Description

      If lists of assignments or properties should be vertically aligned for faster and easier reading. The accepted values determine to which language this option should be applied.

    - ##### Type

      boolean

    - ##### Accepted values

      all, css, js, none

    - ##### Default

      js

    - ##### As labeled in the HTML tool

      Vertically Align, CSS / JavaScript

63. #### wrap

    - ##### Description

      In a markup document this option sets how many columns wide text content may be before wrapping onto a new line. In JavaScript this option determines the maximum length of a string literal and line comment before being broken in + separated fragments. The value 0 disables text wrapping. A negative value combines + separated string literals into a single string.

    - ##### Type

      number

    - ##### Default

      80

    - ##### As labeled in the HTML tool

      Wrap text, JavaScript / Markup

### Practices of Pretty Diff

Pretty Diff hopes to encourage conventions of efficiency, but not at cost to recursion, regression testing, or altered functionality. For example consider the situation of minifying markup. In a typical scenario the practice of code minifcation is to remove all code comments and all white space characters not absolutely necessary for syntax interpretation. If the most aggressive form of minification is exercised upon markup the functionality of the code is certainly changed. Consider these two examples:

1. `<p>This is a paragraph with a text field. <input type="text"/></p>`
2. `<p>This is a paragraph with a text field.<input type="text"/></p>`

The difference between the two examples above is the difference of a single space character between the period and the input tag. In markup white space characters are tokenized when the code is parsed to output by default, and rarely is this default challenged. Tokenized white space means sequential white space characters are converted to a single space character and then sequential space characters are converted to a single space character. This means the presence of some white space characters are completely trivial, while others are not. A single space character separating words of content is not trivial if it is an isolated space. In the above sample the difference of a space separating the input tag from the content is also not trivial since it alters how tokenized content is interpreted.

If markup code were fully minified then all white space characters outside of syntax containers, such as tags, would be removed, thereby making the content illegible. Markup can still be correctly minified, but only when rendering of tokenized white space is fully considered. The opposite of this problem is accidental addition of white space characters from flawed beautification schemes. Consider the following two examples:

1. `<p>This is a statement with a <a href="#">hyperlink</a>.</p>`
2. `<p>` `This is a statement with a` `<a href="#">` `hyperlink` `</a>` `.` `</p>`
3. `<p>This is a statement with a` `<a href="#">hyperlink</a>.` `</p>`

The differences between the first two examples is that the second example introduces white space tokens where they do not exist in the first example. In the first example there are no characters between the opening <p> tag and the text or the opening <a> and the text while this is not true of the second example. Therefore these two statements are not similar enough for a logical comparison. A well crafted beautifier, or pretty printer, will take these differences into account so far as to alter the entirety of a code base for easier reading but not at the cost of manipulating how the code is parsed by a given interpreter. The third example is correct output that does not introduce additional white space characters to the parsed and tokenized output.

Code must never be minified if it cannot be automatically recovered into an easily readable form and must never be beautified if such beautification changes how the code is parsed. This is the importance of regression. The most extreme form of minification is referred to as obfuscation. Obfuscation removes all code comments and all white space characters not absolutely required for syntax compliance, but goes one step further and changes all variable and command names to the fewest available character length. Pretty Diff considers the practice of obfuscation to be harmful as its practice eliminates the possibility of regression. Without the possibility for regression recursive practices are improbable.

An instantiation of a pattern where the pattern's presence is available in the given instance without regard for multiplication is said to be idempotent. A recursive practice is the ability replicate an action where the replication does not harm the potential of further replication, or the idempotent nature of a pattern, upon or resulting from that action. In the case of Pretty Diff code that begins unminified should be capable of being minified, beautified, minified again, and so on without harm or difference to the functional integrity of the supplied code. Any process that prevents such recursive practices, such as obfuscation, are harmful and must be avoided.

Comments are the regression exception. There is no way to efficiently reduce code while retaining comments and documentation. Pretty Diff strongly recommends that documentation be separated from production code into either a redundant development version or into a separated documentation archive so that it can be preserved apart from the production code.

There is one extremely limited exception to functional interference observed by Pretty Diff. The Cascading Style Sheets language provides a syntax and vocabulary that are limited and fully known. Therefore functional changes can, and are, supplied to CSS code during minification because in this one narrow instance there is no harm to regression. Superior minification can be performed by supplying minor functional changes to the code which be easily and intelligently reversed without error or prior knowledge of the code sample.

### Pretty Diff Comment

The Pretty Diff option comment is similar in convention to the JSLint option comment. In the case where multiple Pretty Diff option comments are present in a document only the first will be processed. If in diff mode and an option comment is present in the diff code but not the source code then this option comment will be processed. In order for the option comment to be recognized it must start with /*prettydiff.com and end with */. The options are listed in this comment separated by commas as a colon separated name value pair. The options match the exact value definition for the Pretty Diff application properties above and options that allow abstract values must have their values enclosed in either single or double quotes. The options can be listed in any order. The option comment should be separated from other comments to prevent any possibility of corrupted interpretation. These are examples of appropriate option strings:

- /*prettydiff.com api.mode:beautify, api.lang:javascript, api.inchar:"abc"*/
- <!--/*prettydiff.com api.mode: beautify, api.lang: javascript, api.inchar: "abc", api.html: true */-->

### Input and Output

The function outputs an array of two indexes. The first array index is always the processed data and the second array index contains meta data about the report. In the case of the "beautify", "minify", and "parse" operations the first index of the output array is the processed source code as text and the second array index is the code report, as seen generated on the client side tool, formatted as HTML. The output from the diff operation returns an HTML table of the actual diff output as the first array index and a some minor meta data about the number of errors in the second array index with both indexes formatted as HTML and neither comprising a complete HTML document.

## How to Contribute

### Summary of the Code

Pretty Diff is written in an imperative functional manner. This means the architecture of the code and its separation of concerns is achieved by a tree of functions. For instance, major libraries are a top level function, major tasks are their first level of nested functions, and so forth. The organization of these functions in both name and relationship is extremely declarative, but the actual code instructions are extremely direct to their purpose without any attempt to describe their purpose or reasoning.

The best way to examine the Pretty Diff code is in any code editor that allows folding on functions and syntax coloring for JavaScript. Without a code folding feature the code will appear extremely large and challenging to work with.

The primary application file is prettydiff.js. It provides a central point by which all features, options, and libraries are interconnected.

The library files are located in the lib directory and may be run independently apart from the rest of the Pretty Diff application.

### Local Development Environment

Pretty Diff requires no build process and no dependencies to start modifying and executing the code. You can get the code by these means:

- Clone from Github - `git clone https://github.com/prettydiff/prettydiff.git`
- Install from NPM locally - `npm install prettydiff`
- Manually grabbing the files from the site:
  - api/dom.js
  - api/node-local.js
  - api/prettydiff.wsf
  - lib/csspretty.js
  - lib/csvpretty.js
  - lib/diffview.js
  - lib/jspretty.js
  - lib/markuppretty.js
  - lib/safeSort.js
  - diffview.css
  - documentation.xhtml
  - prettydiff.com.xhtml
  - prettydiff.js

Pretty Diff supports both local and global NPM installation, but local installation is preferred for code examination. The node-local.js file is not required to dive into the Pretty Diff application unless you wish to experiment with command line functionality. I have found that it is faster to experiment with application features using the web tool where the options are already presented as a collection of radio buttons.

This is all the knowledge you need to jump into the Pretty Diff code, but the code may likely open more questions than answers. Feel free to open issues on Github or email to info@prettydiff.com.

### Publication Process

In the process of publishing new features for QA and experimental considerations updates are dumped into http://prettydiff.com/ignore/testlocation.

Pretty Diff mostly adheres to the principles of semver for publishing updates. Semver is defined by proximity of changes to an application's API while Pretty Diff also accounts for breadth of code changes in a given release and depth of functional changes.

New versions (official releases) are first launched to the Pretty Diff webserver. Pushes to the Github master branch only occur from the web server as a tagged release. Pretty Diff is willing to accept pushes to branches pull requests to branchs from any location. Only after the master branch on Github is updated with a release is the code published to NPM.

Pretty Diff uses the milestone feature of Github issues to document the development roadmap. You can see exactly what priorities are major releases and in which order they will be approached according to milestone release version. You can also influence the roadmap by providing bug reports and requesting enhancements.

## Checklist for Adding New Options

1. Define the option in this documentation file.
2. Add the new option to Prettydiff's core function.
   1. Define the options default with a variable at the top of core.
   2. Add the new option, and its values, to the pdcomment child function.
   3. Add the new option to each appropriate library reference for each appropriate mode.
3. Add the new option to the appropriate library files.
   1. Write a brief description of the new option in the libraries' top comments.
   2. Define the option's default using a variable at the top of the library.
   3. Add the appropriate functionality to the library for the option to do its job.
4. Add the new option to node-local.js and prettydiff.wsf.
   1. Add the new option to the help/error documentation.
   2. Add the new option to the default option list.
   3. Define the new option's default by using an assignment to a property on the object passed into Prettydiff.
5. Add the new option to dom.js.
   1. Add the new object to the appropriate modes in the recycle function to be passed to Prettydiff.
   2. Add the new object to the options function to build out the option string that displays in the web tool.
6. Add the new option to the HTML (prettydiff.com.xhtml) for each mode as appropriate.
7. Test the new option.
   1. Verify the option works as intended for each point of interaction added to the HTML.
   2. Verify the option is added to the option string.
   3. Verify the change of interaction on the HTML is saved by clearing cache and refreshing the page.
8. Add the appropriate description of the option to the API documentation.
9. If necessary write a guide to more fully describe the benefit and impact of the new feature.

## Components Files

A list of code components, author information, and dates of revision.
Component | Author(s) | Summary | Revised
--- | --- | --- | ---
ace | Ace Code Editor | Ace Code Editor. |
csspretty.js | Austin Cheney | CSS parser. |
csvpretty.js | Austin Cheney | The function that beautifies character sequence values. |
diffview.css | Austin Cheney | The CSS that powers everything to do with the form, diff output, and this documentation. |
diffview.js | Chas Emerick - Original Austin Cheney - Major Revision | Builds the HTML diff output. |
documentation.xhtml | Austin Cheney | This documentation page. |
dom.js | Austin Cheney | A supplemental JavaScript file providing DOM access and interaction with the web tool. |
jspretty.js | Austin Cheney Harry Whitfield - QA support | Beautifies JavaScript code. |
markuppretty.js | Austin Cheney | Minifies markup code. |
node-local.js | Austin Cheney | An API for processing the local command line JavaScript with Node.js |
prettydiff.com.xhtml | Austin Cheney | Actual Pretty Diff tool HTML file. |
prettydiff.js | Austin Cheney | Actual Pretty Diff application code. |
prettydiff.wsf | Austin Cheney | Pretty Diff API for Windows Script Host. |
safeSort.js | Austin Cheney | A small sorting library. |

Please send comments, feedback, and requests to info@prettydiff.com.