#
Pretty Diff - Documentation

Color Scheme

Explore some samples or browse Pretty Diff on GitHub.

##

### Purpose

Pretty Diff is a language aware code comparison tool, beautifier, minifier, and parser for a variety of web oriented languages.

Pretty Diff was created to compare code samples for various web based languages even if one (or both) code samples were minified. Currently, the project operates by beautifying code and then comparing that the beautified product of the code samples. The goal in a future version is to introduce the comparison step directly into the beautifiers between the parse step and the beautification step to become a truely language aware code comparison and analysis tool.

### Goals

portability
  The project should be immediately available cross platform, across various interfaces, and without a build process. All documentation and required supporting artifacts are included with the project code.
productivity
  The project should save a developer substantial time by make code easier to read against a varient of settings and opinions and reduce the steps to complete a given code analysis task.
reproducibility
  Code pushed through the project in any one mode should be equally restorable to its previous state using a different mode.
simplicity
  The project should do more with less code. The intended audience of this project are software developers, who may need to modify the project code to fit custom needs. Less code means custom mode, but also means clearer separation of concerns, clearer organization, and fewer algorithms.

### Supported Operations (modes)

Pretty Diff currently supports these four operations:

diff
  The code comparison mode. This is the default mode and the only mode to require two code samples.
beautify
  Pretty Diff has progressively moved from community driven dependencies to custom parsers to accomplish code beautification for a diversity of features and requests.
minify
  Each of Pretty Diff's beautification libraries has a minify feature. The goal is to reduce code size but only to such an extent that the code can be restored to its prior state through beautification, excluding code comments.
parse
  Most code parsers generate a final product called an Abstract Syntax Tree (AST). Pretty Diff, instead, produces parallel arrays for its internal operations. The parse mode simply makes these data arrays available for independent analysis.
analysis
  HTML formatted reports evaluating the code. The reports differ in content and structure by the parser(s) used.

### Language Classifications

The project maintains three primary language libraries and a minor parser for CSV format. The three major libraries each include a parser, beautifier, and minifier. All libraries are located at the lib directory.

csspretty
  This library provides support for Cascading Style Sheets and similar languages, such as the popular preprocessors: LESS and SCSS (SASS).
jspretty
  This library provides support for JavaScript and several templating languages that use a JavaScript-like syntax. React JSX format is supplied by this library with assistance from the markuppretty library.
markuppretty
  The markuppretty library supports XML, HTML, and a wide variety of HTML templating schemes such as Handlebars and Mustache templates.

##

### General Output

New in version 2 is that most opertions will output a single string. This makes the application more predictable and easier to integrate into other applications. Brief metadata about the operation is stored in a global object named global.prettydiff.meta.

### Exceptions

For increased speed and convenience there are some features that could not be delivered as a single string. The list is as follows:

- Parse mode with parseFormat:parallel will return an object with a key named definition and a key named data. The data property will contain an object of arrays by name and the definition object will contain and object of identify key names to the data object where each value defines the data type.
- Parse mode with parseFormat:sequential will a nearly identical object to that described by parseFormat:parallel. The only difference is that the data property contains an array of array children where each child array is a parsed token and corresponding data fields.
- Parse mode with parseFormat:htmltable will return a string of the parse data arranged in an HTML table.
- Diff mode with diffcli:true will return an array of numbers representing the locations of differences from the supplied code samples for custom processing and formatting on the command line.
- The option nodeasync returns an array where all prior described output is the first index and the second index is an object containing brief metadata, otherwise stored in the global.prettydiff.meta object. The reason for this is to allow meta data collection during parallel operations without collision. If this option is ignored then all prior described output formats are generated and the meta data is dumped in the global.prettydiff.meta object, but that meta data is not reliable. An unintended byproduct of this feature is that Pretty Diff version 2 can accomplish nearly complete backwards compatibility to Pretty Diff v1 by setting this option to true.

##

1. #### apacheVelocity

   - ##### Description

     Enables Apache Velocity syntax support in the markuppretty.js library. If accessing the markuppretty.js library directly without the Pretty Diff application set the option apacheVelocity to true. Otherwise, this option can be set directly or by providing the value apacheVelocity to option lang. Velocity is not supported in minification mode.

   - ##### Type

     boolean

   - ##### Default

     false

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

     (only available in the language selection)

2. #### api

   - ##### Description

     Used internally to decide how to format documents and reports.

3. #### attributetoken

   - ##### Description

     Attributes in markup languages when in mode parse will output attributes as separate tokens in the parse table output instead of a data property on the parent element.

   - ##### Type

     boolean

   - ##### Default

     false

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

     Parse Attributes

4. #### brace_style

   - ##### Description

     This option exists to emulate the brace_style option provided by JSBeautify using other existing Pretty Diff options.

   - ##### Type

     string

   - ##### Accepted values

     collapse, collapse-preserve-inline, expand, none

   - ##### Default

     none

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

     Brace Style

5. #### 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

6. #### bracepadding

   - ##### Description

     Inserts a space after the start of a container 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

7. #### 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

   - ##### Accepted values

     knr, allman

   - ##### Default

     knr

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

     Style of Indent

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

   - ##### Description

     Specifies which color scheme to apply to the output file.

   - ##### Type

     string

   - ##### Accepted values

     canvas, shadow, white

   - ##### Default

     white

9. #### 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

10. #### 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

11. #### compressedcss

    - ##### Description

      In CSS this allows for beautified blocks and selectors but minified properties and values to allow faster reading of large CSS code from a structured perspective.

    - ##### Type

      boolean

    - ##### Default

      false

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

      Compressed CSS

12. #### 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

13. #### 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

14. #### 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

15. #### 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

16. #### crlf

    - ##### Description

      If the line termination of processed output should be Windows CRLF format. Unix format (LF) is the default. A true value will use the JavaScript "\r\n" which should equate to CRLF. A false value will use the JavaScript "\n" which should equate to LF.

    - ##### Type

      boolean

    - ##### Default

      false

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

      Line Termination

17. #### 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

18. #### 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

19. #### 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

20. #### 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

21. #### 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

22. #### 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)

23. #### 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

24. #### 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

25. #### 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

26. #### 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

27. #### endcomma

    - ##### Description

      If a terminating comma should be inserted into arrays, object literals, and destructured objects. The multiline value forces terminating commas but only to objects and arrays that are beautified to more than one line. As a result the multiline value is only available to beautify and diff modes and it behaves identically to the never value during parse time.

    - ##### Type

      string

    - ##### Accepted values

      always, multiline, never

    - ##### Default

      never

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

      Trailing Commas

28. #### endquietly (node-local.js only)

    - ##### Description

      Determines whether terminal logging should be printed to the console. quite - Suppresses terminal logging. log - Forces terminal logging. The default setting surpresses terminal logging if readmethod is file or filescreen.

    - ##### Type

      string

    - ##### Accepted values

      quiet, log, any other string

    - ##### Default

      (empty string)

29. #### force_attribute

    - ##### Description

      Forces all markup attributes to be indented each on their own line of code.

    - ##### Type

      boolean

    - ##### Default

      false

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

      Force Attribute Indentation

30. #### 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

31. #### formatArray

    - ##### Description

      Determines whether JavaScript array indexes should always indented, remain on a single line, or left to the default formatting.

    - ##### Type

      string

    - ##### Accepted values

      default, indent, inline

    - ##### Default

      default

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

      Formatting Arrays

32. #### formatObject

    - ##### Description

      Determines whether JavaScript object properties should always indented, remain on a single line, or left to the default formatting.

    - ##### Type

      string

    - ##### Accepted values

      default, indent, inline

    - ##### Default

      default

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

      Formatting Object Literals

33. #### functionname

    - ##### Description

      Wether a space should occur between a function name and the arguments parenthesis.

    - ##### Type

      boolean

    - ##### Default

      false

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

      Space After Function Name

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

    - ##### Description

      Displays documenation to the command line or console.

35. #### 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

36. #### 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

37. #### inlevel

    - ##### Description

      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

38. #### 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

39. #### jekyll

    - ##### Description

      If YAML Jekyll HTML template comments should be supported.

    - ##### Type

      boolean

    - ##### Default

      false

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

      YAML Jekyll Support

40. #### 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

41. #### 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

42. #### 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

      text

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

      Auto detect default

43. #### 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

44. #### 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

45. #### mode

    - ##### Description

      The operation to be performed.

    - ##### Type

      string

    - ##### Accepted values

      analysis, beautify, diff, minify, parse

    - ##### Default

      diff

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

      Function

46. #### neverflatten

    - ##### Description

      Prevents flattening of destructured lists in JavaScript.

    - ##### Type

      boolean

    - ##### Default

      false

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

      Never Flatten Destructured Lists

47. #### 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

48. #### nochainindent

    - ##### Description

      If indentation should be ignored for chains of JavaScript methods that are broken onto multiple lines.

    - ##### Type

      boolean

    - ##### Default

      false

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

      Method Chain Indentation

49. #### nodeasync (node-local.js only)

    - ##### Description

      The goal of Pretty Diff version 2 is to have the prettydiff function return a single string of the desired output and write extranous meta data to a global object. Unfortunately, with bulk asynchronous operations, such as readmethod:directory assignments to a shared global object will result in cross-talk. This means to capture and communicate the meta data precisely a new object must be passed in on the options and returned from the function, which returning a Pretty Diff version 1 styled array of [data, meta] where data is the desired string output and meta is the meta data object. If you are not using the node-local.js file for Node.js interaction and the meta data is not important then the prettydiff function will simply return a single desired string.

    - ##### Type

      boolean

    - ##### Default

      false

50. #### nodeerror (node-local.js only)

    - ##### Description

      Sometimes it is informative to log parse errors to the console. This behavior can result in excessive noise and break unit tests though.

    - ##### Type

      boolean

    - ##### Default

      false

51. #### 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

52. #### 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

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

    - ##### Description

      Determines the location of where files should be saved. This is required if the readmethod option has a value of: auto, directory, file, or subdirectory. When the readmethod option has other values, such as screen or filescreen, this option is not used. If the readmethod option has a value of file the value of this option is used to create or overwrite a file at the specified location. For all other readmethod values the value of this option designates the location of a directory.

    - ##### Type

      string

54. #### parseFormat

    - ##### Description

      When in parse mode if the output should be arrays of data types (parallel), arrays of token records (sequential), or an HTML table.

    - ##### Type

      string

    - ##### Accepted values

      parallel, sequential, htmltable

    - ##### Default

      parallel

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

      Parsed Output Format

55. #### parseSpace

    - ##### Description

      If whitespace tokens should be included in the output parse tree. Including whitespace tokens in the parse tree is the more standards conformant approach. Whitespace tokens can be inferred through examination of the lines data facet for a given token and tends to make reading the parse tree more challenging.

    - ##### Type

      boolean

    - ##### Default

      false

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

      Include Whitespace Tokens

56. #### preserve

    - ##### Description

      Determine the number of empty lines to preserve.

    - ##### Type

      number

    - ##### Default

      1

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

      Empty Lines

57. #### qml

    - ##### Description

      Enables QML syntax support in the jspretty.js library. If accessing the jspretty.js library directly without the Pretty Diff application set the option qml to true. Otherwise, this option can be set directly or by providing the value qml to option lang. QML is not supported in minification mode.

    - ##### Type

      boolean

    - ##### Default

      false

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

      (only available in the language selection)

58. #### 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

59. #### 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

60. #### 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

    - ##### Accepted values

      auto, directory, file, filescreen, screen, subdirectory

    - ##### Default

      screen

61. #### 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

62. #### 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

63. #### 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)

64. #### 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)

65. #### 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

66. #### 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

67. #### 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

68. #### 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

69. #### 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

70. #### 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

71. #### 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

72. #### 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

73. #### 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

74. #### 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

75. #### 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

76. #### typescript

    - ##### Description

      If the language is TypeScript this internal option prevents collisions in edge cases that look similar to React JSX format.

    - ##### Type

      boolean

    - ##### Default

      false

77. #### unformatted

    - ##### Description

      A markup only option that applies to modes: beautify, diff, minify, and parse. When set to true this option will preserve the insides of a markup tag.

    - ##### Type

      boolean

    - ##### Default

      false

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

      Do Not Format Inside of Tags

78. #### 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

79. #### 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

80. #### 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

##

### Get the Code

Various options are available for greater portability

- #### biddle

  `biddle install http://prettydiff.com/downloads/prettydiff/prettydiff_latest.zip`

- #### Bower

  `bower install prettydiff`

- #### Github

  `git clone https://github.com/prettydiff/prettydiff.git`

- #### Manually get the code

  - Core application file - http://prettydiff.com/prettydiff.js
  - HTML webtool - http://prettydiff.com/index.xhtml
  - CSS
    - Color Scheme Canvas http://prettydiff.com/css/color_canvas.css
    - Color Scheme Shadow http://prettydiff.com/css/color_shadow.css
    - Color Scheme White http://prettydiff.com/css/color_white.css
    - Documentation http://prettydiff.com/css/documentation.css
    - Global http://prettydiff.com/css/global.css
    - Index http://prettydiff.com/css/index.css
    - Page Specific http://prettydiff.com/css/page_specific.css
    - Reports http://prettydiff.com/css/reports.css
    - Webtool Only http://prettydiff.com/css/webtool_only.css
  - Libraries
    - CSS library - http://prettydiff.com/lib/csspretty.js
    - CSV library - http://prettydiff.com/lib/csvpretty.js
    - diff library - http://prettydiff.com/lib/diffview.js
    - finalFile (HTML template) library - http://prettydiff.com/lib/finalFile.js
    - Global Store http://prettydiff.com/lib/global.js
    - JavaScript library - http://prettydiff.com/lib/jspretty.js
    - Language Settings library - http://prettydiff.com/lib/language.js
    - markup library - http://prettydiff.com/lib/markuppretty.js
    - Options Management library - http://prettydiff.com/lib/options.js
    - custom sort library - http://prettydiff.com/lib/safesort.js
  - API utilities
    - DOM (powers the HTML web tool) - http://prettydiff.com/api/dom.js
    - Node (allows execution on command line with Node.js) - http://prettydiff.com/api/node-local.js

Pretty Diff is no longer published to NPM. For more information please see: https://github.com/prettydiff/prettydiff/issues/291.

### Run the Code

There is increased safety if values are always quoted in command line instructions.

- Run it from a web browser by pointing to the address of the project's index.xhtml file.

- Run it on the command line with Node.js `cd prettydiff` `node api/node-local.js option:value option:value` `` `node api/node-local.js help - prints instructions to the console` `node api/node-local.js version - prints only the version string to the console` `node api/node-local.js list - displays a list of all current settings on the console`

- Run it from a biddle installation `biddle global prettydiff` `prettydiff option:value option:value`

- Run it on the command line with Node.js and Bower installation `cd bower_components/prettydiff` `node api/node-local.js option:value option:value`

- Run it from your own Node application `var prettydiff = require("prettydiff"),` `args = {` `source: "asdf",` `diff : "asdd",` `lang : "text"` `},` `output = prettydiff(args);`

- Run it from your own web application ( ensure the library files are requested into your application) `var global = {},` `args = {` `source: "asdf",` `diff : "asdd",` `lang : "text",` `},` `output = prettydiff(args);`

##

### @source

https://github.com/prettydiff/prettydiff

### @documentation

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 included or met:

- Prettydiff created by Austin Cheney originally on 3 Mar 2009. http://prettydiff.com/
- The use of lib/diffview.js and prettydiff.js must contain the following copyright: `Copyright © 2007, Snowtide Informatics Systems, Inc. All rights reserved. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 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. 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.` `used as diffview function: http://prettydiff.com/lib/diffview.js`
- 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.

##

### 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

### The .prettydiffrc File

A configuration file is available for command line execution via the supplied api/node-local.js file. Two separate formats are accepted:

- JSON
- JavaScript object

The JSON format is easy to write and validate, but it is a static format. If your desired option and settings never change then this is the ideal format.

A second format is available for advanced configurability. Some users require certain features for particular languages, modes, or other heuristics. For example auto-correction might be desired for JavaScript minification, but not XML beautification. This second format is JavaScript code, which allows a user to write and supply options against a set of conditions of their choosing. The code supplied by default in the .prettydiffrc file allows a template by which users can achieve this format directly without worrying about application and delivery concerns.

### 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 mode:beautify, lang:javascript, inchar:"abc"*/`
- `<!--/*prettydiff.com mode: beautify, lang: javascript, inchar: "abc", html: true */-->`

### Web Tool URI Parameters

ace
  If this parameter is provided with a false value the Ace code editor will be discarded in favor of regular HTML textarea elements.
c
  A supported color scheme value. Currently supported values: white (default), shadow, canvas
correct
  When present this parameter forces option correct to a value of true. This parameter does not require a value.
d
  The URI of a textual resource to compare to, which becomes the value of option diff. "?", "&", and "#" characters in the URI value must be URI escaped (percent encoded).
jsscope
  When present this parameter sets the option jsscope to a value of . This parameter does not require a value.
l
  This parameter changes the value for option language if provided a supported value.
m
  This parameter changes the value for option mode if provided a supported value.
s
  The URI of a textual resource to process or compare against, which becomes the value of option source. "?", "&", and "#" characters in the URI value must be URI escaped (percent encoded).

Any defined option name is also supported as a parameter.

Here is an example: `http://prettydiff.com/?s=http://prettydiff.com/prettydiff.js&m=beautify&correct`

### Feature 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

### Additional guides not directly related to the Pretty Diff application

1. Code is Evil
2. The DOM Explained, Quick and Simple
3. A/B Testing for the Web
4. Explaining Closure To A Child
5. Becoming a JavaScript Rock Star (In the Real World)
6. How to write a parser

##

### Contribution Guide

For questions, features, or bug reports please open an issue on Github.

If you wish to propose code changes then follow these steps:

1. Fork the repository on Github.
2. Clone your forked repository to your local machine: `git clone https://github.com/username/prettydiff.git`
3. Create a new branch for your changes: `git checkout -b branchName`
4. Run the unit tests to verify if your changes are breaking things: `node test/lint.js`
5. Open a pull request on Github. Ensure there are comments in the pull request explaining the what the change does and why it is needed. Including additional unit tests with the pull request earns extra love.

### Unit Tests

#### Running the Tests

The unit tests require JSLint as a dev dependency. Run the unit tests with the following commands: `cd prettydiff` `git submodule init` `git submodule update` `node test/lint.js`

The unit test script checks for the latest version of JSLint once per day that it runs.

The unit tests run in phases, which are different kinds of tests. The name and order of the test phases are indicated in an array named order located at the top of the test script file. Alter that array to run only certain types of unit tests.

### New Option Guidance

#### Rapid Experimentation

The easiest way to experiment with adding new options is to arbitrarily add an option and value to the top of the given library. For example, if you wish to add a new JavaScript option then just before the tokenizer include a line of code like: `options.myNewOptionName = true` A new option reference exists that is avilable through out the application that can allow or suppress new logic with minimal regression. This line of code will have to be removed later, but it allows for rapid experimentation.

#### Checklist

The following checklist explains how to expand the documentation and supported APIs of Pretty Diff for new options.

- documentation.xhtml - Define the new option in the documentation options section.
- Web tool (if not a Node.js only option)
  - index.xhtml - Some options are mode specific while others aren't. Options should be added to the appropriate language section of each supported mode.
  - api/dom.js - Add option support to the supported language modes of pd.event.recycle. The supported language modes are defined as functions: dom__event_recycle_beautify, dom__event_recycle_diff, dom__event_recycle_minify, dom__event_recycle_parse, dom__event_recycle_analysis.
- api/options.js

  Extend the following functions in the api/options.js file to define the option application wide.

  - definitions - define the option and provide a simple text description
  - validate - the logic to assign values against accepted criteria
  - pdcomment - only necessary if option is string type with a list of accepted values
  - domops - associate ID names (from HTML) to values for populating the pretty diff comment in the web tool
- The various libraries are written for independent execution, so each gets their own default definition for supported options, such as: jspretty__options. in the lib/jspretty.js file. New options need to be added in these locations where appropriate.

#### Additional Guidance

Keep things alphabetized where possible. Ideal option names are a balance of uniquely and specifically descriptive but also as short as possible. Options should ideally support a single data type, though exceptions can be made. Frequently run the unit tests to determine if the new option causses regression or understand if regression is necessary. Never be afraid to open a Github issue or send an email when further guidance is demanded or questions arise.

##

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. |
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. |
finalFile.js | Austin Cheney | HTML report generator. |
jspretty.js | Austin Cheney Harry Whitfield - QA support | Parses JavaScript code. |
language.js | Austin Cheney | Automatic language detection |
lint.js | Austin Cheney | Unit tests, simulations, and lint automation |
markuppretty.js | Austin Cheney | Parses markup code. |
options.js | Austin Cheney | Options management. |
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. |
safeSort.js | Austin Cheney | A small sorting library. |
Version |