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.
- 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.
Key of terms
- Environment
- Describes where the option is available, such as whether exclusively used with Node or in a browser.
- Type
- The data type of the option's value, such as string, number, or boolean.
- Mode
- Some options are only available in certain modes, such as beautification or minification.
- Lexer
- Some options are only available to certain language groups. Markup specific options, for example, will not work with JavaScript language.
- Default
- The option's default value.
brace_line
Description
If true an empty line will be inserted after opening curly braces and before closing curly braces.Environment
anyType
booleanMode
beautifyLexer
scriptDefault
falseAs labeled in the HTML tool
Brace Lines
brace_padding
Description
Inserts a space after the start of a container and before the end of the container if the contents of that container are not indented; such as: conditions, function arguments, and escaped sequences of template strings.Environment
anyType
booleanMode
beautifyLexer
scriptDefault
falseAs labeled in the HTML tool
Brace Padding
brace_style
Description
Emulates JSBeautify's brace_style option using existing Pretty Diff options.Environment
anyType
stringMode
beautifyLexer
scriptAccepted Values
- collapse
- Sets options.formatObject to 'indent' and options.neverflatten to true.
- collapse-preserve-inline
- Sets options.bracepadding to true and options.formatObject to 'inline'.
- expand
- Sets options.braces to true, options.formatObject to 'indent', and options.neverflatten to true.
- none
- Ignores this option
Default
noneAs labeled in the HTML tool
Brace Style
braces
Description
Determines if opening curly braces will exist on the same line as their condition or be forced onto a new line.Environment
anyType
booleanMode
beautifyLexer
scriptDefault
falseAs labeled in the HTML tool
Style of Indent
color
Description
The color scheme of the reports.Environment
anyType
stringMode
anyLexer
anyAccepted Values
- canvas
- A light brown color scheme
- shadow
- A black and ashen color scheme
- white
- A white and pale grey color scheme
Default
whiteAs labeled in the HTML tool
Color
comm_line
Description
If a blank new line should be forced above comments.Environment
anyType
booleanMode
beautifyLexer
markupDefault
falseAs labeled in the HTML tool
Force an Empty Line Above Comments
comments
Description
This will determine whether comments should always start at position 0 of each line or if comments should be indented according to the code.Environment
anyType
booleanMode
beautifyLexer
anyDefault
falseAs labeled in the HTML tool
Indent Comments
complete_document
Description
Allows a preference for generating a complete HTML document instead of only generating content.Environment
anyType
booleanMode
anyLexer
markupDefault
falseAs labeled in the HTML tool
Generate A Complete HTML File
compressed_css
Description
If CSS should be beautified in a style where the properties and values are minifed for faster reading of selectors.Environment
anyType
booleanMode
beautifyLexer
cssDefault
falseAs labeled in the HTML tool
Compressed CSS
conditional
Description
If true then conditional comments used by Internet Explorer are preserved at minification of markup.Environment
anyType
booleanMode
minifyLexer
markupDefault
falseAs labeled in the HTML tool
IE Comments (HTML Only)
content
Description
This will normalize all string content to 'text' so as to eliminate some differences from the output.Environment
anyType
booleanMode
diffLexer
anyDefault
falseAs labeled in the HTML tool
Ignore Content
correct
Description
Automatically correct some sloppiness in code.Environment
anyType
booleanMode
anyLexer
anyDefault
falseAs labeled in the HTML tool
Fix Sloppy Code
crlf
Description
If line termination should be Windows (CRLF) format. Unix (LF) format is the default.Environment
anyType
booleanMode
anyLexer
anyDefault
falseAs labeled in the HTML tool
Line Termination
css_insert_lines
Description
Inserts new line characters between every CSS code block.Environment
anyType
booleanMode
beautifyLexer
cssDefault
falseAs labeled in the HTML tool
Insert Empty Lines
csv_char
Description
The character to be used as a separator if lang is 'csv'. Any string combination is accepted.Environment
anyType
stringMode
anyLexer
csvDefault
,As labeled in the HTML tool
Character Separator
diff
Description
The code sample to be compared to 'source' option. This is required if mode is 'diff'.Environment
anyType
stringMode
diffLexer
anyDefault
As labeled in the HTML tool
Code to Compare
diff_comments
Description
If true then comments will be preserved so that both code and comments are compared by the diff engine.Environment
anyType
booleanMode
diffLexer
anyDefault
falseAs labeled in the HTML tool
Code Comments
diff_context
Description
This shortens the diff output by allowing a specified number of equivalent lines between each line of difference. This option is only used with diff_format:html.Environment
anyType
numberMode
diffLexer
anyDefault
-1As labeled in the HTML tool
Context Size
diff_format
Description
The format of the output. The command line output format is text, similar to Unix 'diff'.Environment
anyType
stringMode
diffLexer
anyAccepted Values
- html
- An HTML format for embedding in web pages, or as a complete web page if document_complete is true.
- json
- A JSON format.
- text
- Formatted similar to the Unix 'diff' command line utility.
Default
textAs labeled in the HTML tool
Diff Format
diff_label
Description
This allows for a descriptive label for the diff file code of the diff HTML output.Environment
anyType
stringMode
diffLexer
anyDefault
New SampleAs labeled in the HTML tool
Label for Diff Sample
diff_rendered_html
Description
Compares complete HTML documents and injects custom CSS so that the differences display not in the code, but in the rendered page in a browser. This option is currently confined only to markup languages, read_method file, and mode diff. Option diff_format is ignored.Environment
anyType
booleanMode
diffLexer
markupDefault
falseAs labeled in the HTML tool
Compare Rendered HTML
diff_space_ignore
Description
If white space only differences should be ignored by the diff tool.Environment
anyType
booleanMode
diffLexer
anyDefault
falseAs labeled in the HTML tool
Remove White Space
diff_view
Description
This determines whether the diff HTML output should display as a side-by-side comparison or if the differences should display in a single table column.Environment
anyType
stringMode
diffLexer
anyAccepted Values
- inline
- A single column where insertions and deletions are vertically adjacent.
- sidebyside
- Two column comparison of changes.
Default
sidebysideAs labeled in the HTML tool
Diff View Type
else_line
Description
If elseline is true then the keyword 'else' is forced onto a new line.Environment
anyType
booleanMode
beautifyLexer
scriptDefault
falseAs labeled in the HTML tool
Else On New Line
end
Description
Which index of the parse table should the application stop. This option is useful internally when recursively sliding between various libraries. The default value of 0 means to ignore this option.Environment
anyType
numberMode
anyLexer
anyDefault
0As labeled in the HTML tool
End Index
end_comma
Description
If there should be a trailing comma in arrays and objects. Value "multiline" only applies to modes beautify and diff.Environment
anyType
stringMode
beautifyLexer
scriptAccepted Values
- always
- Always ensure there is a tailing comma
- multiline
- Ignore this option
- never
- Remove trailing commas
Default
neverAs labeled in the HTML tool
Indent Comments
end_quietly
Description
A node only option to determine if terminal summary data should be logged to the console.Environment
nodeType
stringMode
anyLexer
anyAccepted Values
- default
- Default minimal summary
- log
- Verbose logging
- quiet
- No extraneous logging
Default
defaultAs labeled in the HTML tool
Log Summary to Console
force_attribute
Description
If all markup attributes should be indented each onto their own line.Environment
anyType
booleanMode
beautifyLexer
markupDefault
falseAs labeled in the HTML tool
Force Indentation of All Attributes
force_indent
Description
Will force indentation upon all content and tags without regard for the creation of new text nodes.Environment
anyType
booleanMode
beautifyLexer
markupDefault
falseAs labeled in the HTML tool
Force Indentation of All Content
format_array
Description
Determines if all array indexes should be indented, never indented, or left to the default.Environment
anyType
stringMode
beautifyLexer
scriptAccepted Values
- default
- Default formatting
- indent
- Always indent each index of an array
- inline
- Ensure all array indexes appear on a single line
Default
defaultAs labeled in the HTML tool
Formatting Arrays
format_object
Description
Determines if all object keys should be indented, never indented, or left to the default.Environment
anyType
stringMode
beautifyLexer
scriptAccepted Values
- default
- Default formatting
- indent
- Always indent each key/value pair
- inline
- Ensure all key/value pairs appear on the same single line
Default
defaultAs labeled in the HTML tool
Formatting Objects
function_name
Description
If a space should follow a JavaScript function name.Environment
anyType
booleanMode
beautifyLexer
scriptDefault
falseAs labeled in the HTML tool
Space After Function Name
help
Description
A node only option to print documentation to the console. The value determines where to wrap text.Environment
nodeType
numberMode
anyLexer
anyDefault
80As labeled in the HTML tool
Help Wrapping Limit
indent_char
Description
The string characters to comprise a single indentation. Any string combination is accepted.Environment
anyType
stringMode
beautifyLexer
anyDefault
As labeled in the HTML tool
Indentation Characters
indent_level
Description
How much indentation padding should be applied to beautification? This option is internally used for code requires switching between libraries.Environment
anyType
numberMode
beautifyLexer
anyDefault
0As labeled in the HTML tool
Indentation Padding
indent_size
Description
The number of 'inchar' values to comprise a single indentation.Environment
anyType
numberMode
beautifyLexer
anyDefault
4As labeled in the HTML tool
Indent Size
jsscope
Description
An educational tool to generate HTML output of JavaScript code to identify scope regions and declared references by color.Environment
anyType
stringMode
beautifyLexer
scriptAccepted Values
- html
- generates HTML output with escaped angle braces and ampersands for embedding as code, which is handy in code producing tools
- none
- prevents use of this option
- report
- generates HTML output that renders in web browsers
Default
noneAs labeled in the HTML tool
JavaScript Scope Identification
language
Description
The lowercase single word common name of the source code's programming language.Environment
anyType
stringMode
anyLexer
anyDefault
autoAs labeled in the HTML tool
Language
language_default
Description
The fallback option if option 'lang' is set to 'auto' and a language cannot be detected.Environment
anyType
stringMode
anyLexer
anyDefault
textAs labeled in the HTML tool
Language Auto-Detection Default
language_name
Description
The formatted proper name of the code sample's language for use in reports read by people.Environment
anyType
stringMode
anyLexer
anyDefault
JavaScriptAs labeled in the HTML tool
Formatted Name of the Code's Language
lexer
Description
This option determines which sets of rules to use in the language parser. If option 'language' has a value of 'auto', which is the default value, this option is ignored.Environment
anyType
stringMode
anyLexer
anyAccepted Values
- markup
- parses languages like XML and HTML
- script
- parses languages with a C style syntax, such as JavaScript
- style
- parses CSS like languages
Default
scriptAs labeled in the HTML tool
Parsing Lexer
list_options
Description
A Node.js only option that writes current option settings to the console.Environment
nodeType
booleanMode
anyLexer
anyDefault
falseAs labeled in the HTML tool
Options List
method_chain
Description
When to break consecutively chained methods and properties onto separate lines. A negative value disables this option. A value of 0 ensures method chains are never broken.Environment
anyType
numberMode
beautifyLexer
scriptDefault
3As labeled in the HTML tool
Method Chains
minify_wrap
Description
Whether minified script should wrap after a specified character width. This option requires a value from option 'wrap'.Environment
anyType
booleanMode
minifyLexer
scriptDefault
falseAs labeled in the HTML tool
Minification Wrapping
mode
Description
The operation to be performed.Environment
anyType
stringMode
anyLexer
anyAccepted Values
- beautify
- beautifies code and returns a string
- diff
- returns either command line list of differences or an HTML report
- minify
- minifies code and returns a string
- parse
- using option 'parseFormat' returns an object with shallow arrays, a multidimensional array, or an HTML report
Default
diffAs labeled in the HTML tool
Mode
never_flatten
Description
If destructured lists in script should never be flattend.Environment
anyType
booleanMode
beautifyLexer
scriptDefault
falseAs labeled in the HTML tool
Never Flatten Destructured Lists
new_line
Description
Insert an empty line at the end of output.Environment
anyType
booleanMode
anyLexer
anyDefault
falseAs labeled in the HTML tool
New Line at End of Code
no_case_indent
Description
If a case statement should receive the same indentation as the containing switch block.Environment
anyType
booleanMode
beautifyLexer
scriptDefault
falseAs labeled in the HTML tool
Case Indentation
no_lead_zero
Description
Whether leading 0s in CSS values immediately preceeding a decimal should be removed or prevented.Environment
anyType
booleanMode
anyLexer
styleDefault
falseAs labeled in the HTML tool
Leading 0s
node_error
Description
A Node.js only option if parse errors should be written to the console.Environment
nodeType
booleanMode
anyLexer
anyDefault
falseAs labeled in the HTML tool
Write Parse Errors in Node
object_sort
Description
Sorts markup attributes and properties by key name in script and style.Environment
anyType
booleanMode
beautifyLexer
anyDefault
falseAs labeled in the HTML tool
Object/Attribute Sort
output
Description
A file path for which to write output. If this option is not specified output will be printed to the shell.Environment
nodeType
stringMode
anyLexer
anyDefault
As labeled in the HTML tool
Output Location
parse_format
Description
Determines the output format for 'parse' mode.Environment
anyType
stringMode
parseLexer
anyAccepted Values
- htmltable
- generates the 'table' type output for the DOM but escapes the HTML tags for rendering as HTML code in a HTML tool
- parallel
- returns an object containing series of parallel arrays
- sequential
- returns an array where each index is a child object containing the parsed token and all descriptive data
- table
- generates a colorful grid of output for either the dom or command line interface
Default
parallelAs labeled in the HTML tool
Parse Format
parse_space
Description
Whether whitespace tokens should be included in markup parse output.Environment
anyType
booleanMode
parseLexer
markupDefault
falseAs labeled in the HTML tool
Retain White Space Tokens in Parse Output
preserve
Description
The maximum number of consecutive empty lines to retain.Environment
anyType
numberMode
beautifyLexer
anyDefault
0As labeled in the HTML tool
Preserve Consecutive New Lines
preserve_comment
Description
Prevent comment reformatting due to option wrap.Environment
anyType
booleanMode
beautifyLexer
anyDefault
falseAs labeled in the HTML tool
Eliminate Word Wrap Upon Comments
quote
Description
If true and mode is 'diff' then all single quote characters will be replaced by double quote characters in both the source and diff file input so as to eliminate some differences from the diff report HTML output.Environment
anyType
booleanMode
diffLexer
anyDefault
falseAs labeled in the HTML tool
Normalize Quotes
quote_convert
Description
If the quotes of script strings or markup attributes should be converted to single quotes or double quotes.Environment
anyType
stringMode
anyLexer
anyAccepted Values
- double
- Converts single quotes to double quotes
- none
- Ignores this option
- single
- Converts double quotes to single quotes
Default
noneAs labeled in the HTML tool
Indent Size
read_method
Description
The option determines how Node.js should receive input. All output will be printed to the shell unless the option 'output' is specified, which will write output to a file.Environment
nodeType
stringMode
anyLexer
anyAccepted Values
- auto
- changes to value subdirectory, file, or screen depending on source resolution
- directory
- process all files in the specified directory only
- file
- reads a file and outputs to a file. file requires option 'output'
- screen
- reads from screen and outputs to screen
- subdirectory
- process all files in a directory and its subdirectories
Default
autoAs labeled in the HTML tool
Read Method
selector_list
Description
If comma separated CSS selectors should present on a single line of code.Environment
anyType
booleanMode
beautifyLexer
styleDefault
falseAs labeled in the HTML tool
Indent Size
semicolon
Description
If true and mode is 'diff' and lang is 'javascript' all semicolon characters that immediately preceed any white space containing a new line character will be removed so as to elimate some differences from the code comparison.Environment
anyType
booleanMode
diffLexer
scriptDefault
falseAs labeled in the HTML tool
Indent Size
source
Description
The source code or location for interpretation. This option is required for all modes.Environment
anyType
stringMode
anyLexer
anyDefault
As labeled in the HTML tool
Source Sample
source_label
Description
This allows for a descriptive label of the source file code for the diff HTML output.Environment
anyType
stringMode
diffLexer
anyDefault
Source SampleAs labeled in the HTML tool
Label for Source Sample
space
Description
Inserts a space following the function keyword for anonymous functions.Environment
anyType
booleanMode
beautifyLexer
scriptDefault
trueAs labeled in the HTML tool
Function Space
space_close
Description
Markup self-closing tags end will end with ' />' instead of '/>'.Environment
anyType
booleanMode
beautifyLexer
markupDefault
falseAs labeled in the HTML tool
Close Markup Self-Closing Tags with a Space
start
Description
The parse table index to start working from. This is internally used for code samples that require switching between different libraries.Environment
anyType
numberMode
anyLexer
anyDefault
0As labeled in the HTML tool
Start Index
styleguide
Description
Provides a collection of option presets to easily conform to popular JavaScript style guides.Environment
anyType
stringMode
beautifyLexer
scriptAccepted Values
- airbnb
- https://github.com/airbnb/javascript
- crockford
- http://jslint.com/
- https://google.github.io/styleguide/jsguide.html
- jquery
- https://contribute.jquery.org/style-guide/js/
- jslint
- http://jslint.com/
- mediawiki
- https://www.mediawiki.org/wiki/Manual:Coding_conventions/JavaScript
- mrdoob
- https://github.com/mrdoob/three.js/wiki/Mr.doob's-Code-Style%E2%84%A2
- none
- Ignores this option
- standard
- https://standardjs.com/
- yandex
- https://github.com/ymaps/codestyle/blob/master/javascript.md
Default
noneAs labeled in the HTML tool
Script Styleguide
summary_only
Description
Node only option to output only number of differences.Environment
nodeType
booleanMode
diffLexer
anyDefault
falseAs labeled in the HTML tool
Output Diff Only Without A Summary
tag_merge
Description
Allows immediately adjacement start and end markup tags of the same name to be combined into a single self-closing tag.Environment
anyType
booleanMode
anyLexer
markupDefault
falseAs labeled in the HTML tool
Merge Adjacent Start and End tags
tag_sort
Description
Sort child items of each respective markup parent element.Environment
anyType
booleanMode
anyLexer
markupDefault
falseAs labeled in the HTML tool
Sort Markup Child Items
ternary_line
Description
If ternary operators in JavaScript (? and :) should remain on the same line.Environment
anyType
booleanMode
beautifyLexer
scriptDefault
falseAs labeled in the HTML tool
Keep Ternary Statements On One Line
text_preserve
Description
If text in the provided markup code should be preserved exactly as provided. This option eliminates beautification and wrapping of text content.Environment
anyType
booleanMode
anyLexer
markupDefault
falseAs labeled in the HTML tool
Preserve Markup Text White Space
top_comments
Description
If mode is 'minify' this determines whether comments above the first line of code should be kept.Environment
anyType
booleanMode
minifyLexer
anyDefault
falseAs labeled in the HTML tool
Retain Comment At Code Start
unformatted
Description
If markup tags should have their insides preserved.Environment
anyType
booleanMode
anyLexer
markupDefault
falseAs labeled in the HTML tool
Markup Tag Preservation
variable_list
Description
If consecutive JavaScript variables should be merged into a comma separated list or if variables in a list should be separated.Environment
anyType
stringMode
anyLexer
scriptAccepted Values
- each
- Ensurce each reference is a single declaration statement.
- list
- Ensure consecutive declarations are a comma separated list.
- none
- Ignores this option.
Default
noneAs labeled in the HTML tool
Variable Declaration Lists
version
Description
A Node.js only option to write the version information to the console.Environment
nodeType
booleanMode
anyLexer
anyDefault
falseAs labeled in the HTML tool
Version
vertical
Description
If lists of assignments and properties should be vertically aligned. This option is not used with the markup lexer.Environment
anyType
booleanMode
beautifyLexer
anyDefault
falseAs labeled in the HTML tool
Vertical Alignment
wrap
Description
Character width limit before applying word wrap. A 0 value disables this option. A negative value concatenates script strings.Environment
anyType
numberMode
anyLexer
anyDefault
0As labeled in the HTML tool
Wrap
Get the Code
Various options are available for greater portability
-
Bower
bower install prettydiff
-
Github
git clone https://github.com/prettydiff/prettydiff.git
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.
@documentation
Prettydiff created by Austin Cheney originally on 3 Mar 2009. https://prettydiff.com/
As of version 2.1.17 Pretty Diff is licensed under CC0. Please see license.txt for additional information.
Precedence
Pretty Diff sets option values according to this order of precedence from highest priority to lowest:
- The styleguide option, which is only used in the jspretty library.
- The Pretty Diff comment.
- The .prettydiffrc file, which is only available to the node-local file (command line Node.js).
- User supplied options
- 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:
https://prettydiff.com/?s=https://prettydiff.com/prettydiff.js&m=beautify&correct
Feature Guides
- Using jsscope to understand scope, inheritance, and scope chains in JavaScript
- Ignoring specified tags from markup beautification
- So its kind of like recursive command line diff, but in JavaScript
- Processing the JSX format from Facebook's React
- Saving colorful JavaScript code samples
- Conforming to popular style guides with the styleguide option
- What Pretty Diff can do to auto-correct some sloppiness in JavaScript.
- Brief overview of the prettydiff.js code architecture
- Native Modules in Pretty Diff
- The .prettydiffrc file
Additional guides not directly related to the Pretty Diff application
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:
- Fork the repository on Github.
- Clone your forked repository to your local machine:
git clone https://github.com/username/prettydiff.git
- Create a new branch for your changes:
git checkout -b branchName
- Run the unit tests to verify if your changes are breaking things:
node test/lint.js
- 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.