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 the next 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. Currently, the project provides some amount of code analysis as an additional product of beautification.
- 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 an 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.
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.
-
api
-
Description
Used internally to decide if some small JavaScript functions need to be included with report output based upon the operating environment.
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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)
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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 -
Default
(empty string) -
Accepted values
quiet, log, any other string
-
-
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
-
-
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
-
-
help (node-local.js only)
-
Description
Displays documenation to the command line or console.
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
mode
-
Description
The operation to be performed. -
Type
string -
Accepted values
beautify, diff, minify, parse -
Default
diff -
As labeled in the HTML tool
Function
-
-
neverflatten
-
Description
Prevents flattening of destructured lists in JavaScript. -
Type
boolean -
Default
false -
As labeled in the HTML tool
Never Flatten Destructured Lists
-
-
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
-
-
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
-
-
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
-
-
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
-
-
output (node-local.js only)
-
Description
Determines the location of where files should be saved. -
Type
string
-
-
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 -
Default
parallel -
Accepted values
parallel, sequential, htmltable -
As labeled in the HTML tool
Parsed Output Format
-
-
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
-
-
preserve
-
Description
Determine the number of empty lines to preserve. -
Type
number -
Default
1 -
As labeled in the HTML tool
Empty Lines
-
-
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
-
-
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
-
-
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
-
-
report (node-local.js only)
-
Description
Determines if a meta data report should be generated. -
Type
boolean -
Default
true
-
-
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
-
-
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
-
-
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)
-
-
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)
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
-
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
-
NPM
Global install, run it anywhere on the command line using global command prettydiff
npm install prettydiff -g
Local install, better for testing and developing the application
npm install prettydiff
-
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
- JavaScript library - http://prettydiff.com/lib/jspretty.js
- markup library - http://prettydiff.com/lib/markuppretty.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
- WSH (allows execution on Windows command line when Node.js is not available) - http://prettydiff.com/api/prettydiff.wsf
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 and global NPM installation
prettydiff option:value option:value
-
Run it on the command line with Node.js and local NPM installation
cd node_modules/prettydiff
node api/node_modules.js option:value option:value
-
Run it on the command line with Node.js and Bower installation
cd bower_components/prettydiff
node api/node_modules.js option:value option:value
-
Run it on the Windows command line with wscript or cscript
cscript api/prettydiff.wsf /option:value /option:value
-
Run it from your own Node application
var prettydiff = require("prettydiff"),
args = {
source: "asdf",
diff : "asdd",
lang : "text"
},
output = prettydiff.api(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);
@documentation
@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:
- 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 api.mode:beautify, api.lang:javascript, api.inchar:"abc"*/
-
<!--/*prettydiff.com api.mode: beautify, api.lang: javascript, api.inchar: "abc", api.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).
Here is an example:
http://prettydiff.com/?s=http://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:
npm install
- 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 run using NPM scripts and require JSLint as a dev dependency.
Run the unit tests with the following commands:
cd node_modules/prettydiff
npm install
npm test
The unit test script checks for the latest version of JSLint each time it runs, so the npm install command only needs to be run once each time a new version of Pretty Diff is installed.
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.
Known Unit Test Problems
-
npm ERR! Cannot read property 'target' of null
This is an unresolved NPM error https://github.com/npm/npm/issues/10686#issuecomment-187254105
New Option Guidance
Rapid Experimentation
The easiest way to experiment with adding new options is to arbitrarily add
an option assign 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:
option.myNewOptionName = true
A new option reference exists that is avilable through out the library 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.
- prettydiff.js - Add new option and default values/type to the options object.
- 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.
- api/dom.js - Add state support by including the option ids to pd.app.options.
- api/prettydiff.js - WSH support (if not a Node.js only option)
- Add a description of the new option to the documentation in outerror function.
- Add functional support to the list of options (near the bottom of the file) usings the convention WScript.Arguments.Named.
- api/node-local.js - Node.js support
- Add option name and a default value/type to the declared options object.
- Add the option to the internal documentation in the pdNodeLocal__error function.
- Add functional support for the new option to the loop near the top of function pdNodeLocal__start.
- 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.
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. | |
lint.js | Austin Cheney | Unit tests, simulations, and lint automation | |
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. | |
Version |