Explore some samples. For any questions, comments, requests, or feedback please join the Pretty Diff mailing list or chat on Gitter. Find Pretty Diff on GitHub.
This tool was originally created to compare minified code by attaching a beautifier and minifier to a file comparison tool. Over the years it has grown into custom language parsers capable of performing a variety of language analysis. This application is 100% vanilla JavaScript and is API independent.
@source http://prettydiff.com/prettydiff.js
@documentation - English http://prettydiff.com/documentation.php
@licstart The following is the entire license notice for Pretty Diff.
This code may not be used or redistributed unless the following conditions are met:
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.
Install the prettydiff package locally
npm install prettydiff Add this following code to your application
var prettydiff = require("prettydiff"), args = { source: "asdf", diff : "asdd", lang : "text", }, output = prettydiff.api(args); Install the prettydiff package globally
npm install prettydiff -g Example of a command line instruction
prettydiff source:"c:\mydirectory\myfile.js" readmethod:"file" diff:"c:\myotherfile.js" cscript prettydiff.wsf /source:"myFile.xml" /mode:"beautify" var args = { source: "asdf", diff : "asdd", lang : "text", }, output = prettydiff(args); The parameters are optional and are provided soley for portability. The parameters may occur in any order. Examples:
Pretty Diff is an application written entirely in JavaScript and expressed as a single function named 'prettydiff()'. This application was originally written as a means to algorithmically difference between two similar pieces of code regardless of minification and other white space differences. The result is a fast difference engine offering many options that allows access to the world's most advanced markup beautification algorithm.
While the Pretty Diff application is expressed as a single function it contains a few libraries. These libraries are a diff engine and a few language parsers for providing beautification and minification. The libraries can be used independently of Pretty Diff. Browse the libraries in the local lib directory.
The Pretty Diff application is completely environment agnostic. It can run on the command line, web browser, or any other environment. All that is required is an appropriate API. Feel free to write your own or use the ones provided in the local API directory.
There is one exception in the Pretty Diff application to complete environmental isolation. At this time the charDecoder.js code is entirely reliant upon DOM access. This library transforms character entity references into literal characters and vise versa. Pretty Diff does not contain a Unicode character map, so this library is reliant upon execution in a web browser, but it does degrade gracefully in other environments.
The Pretty Diff function receives input from a single argument. This argument is a really big object literal that specifies the code to process and options on how to process it. Read about the various options in the Pretty Diff API section of this document.
Pretty Diff hopes to encourage conventions of efficiency, but not at cost to recursion, regression testing, or altered functionality. For example consider the situation of minifying markup. In a typical scenario the practice of code minifcation is to remove all code comments and all white space characters not absolutely necessary for syntax interpretation. If the most impactful form of minification is exercised upon markup the functionality of the code is certainly changed. Consider these two examples:
<p>This is a paragraph with a text field. <input type="text"/></p><p>This is a paragraph with a text field.<input type="text"/></p>The difference between the two examples above is the difference of a single space character between the period and the input tag. In markup white space characters are tokenized when the code is parsed to output by default, and rarely is this default challenged. Tokenized white space means sequential white space characters are converted to a single space character and then sequential space characters are converted to a single space character. This means the presence of some white space characters are completely trivial, while others are not. A single space character separating words of content is not trivial if it is an isolated space. In the above sample the difference of a space separating the input tag from the content is also not trivial since it alters how tokenized content is interpreted.
If markup code were fully minified then all white space characters outside of syntax containers, such as tags, would be removed, thereby making the content illegible. Markup can still be correctly minified, but only when rendering of tokenized white space is fully considered. The opposite of this problem is accidental addition of white space characters from flawed beautification schemes. Consider the following two examples:
<p>This is a statement with a <a href="#">hyperlink</a>.</p><p> This is a statement with a <a href="#"> hyperlink </a> . </p>The differences between the two prior examples is that the second example introduces white space tokens where they do not exist in the first example. In the first example there are no characters between the opening <p> tag and the text or the opening <a> and the text while this is not true of the second example. Therefore these two statements are not similar enough for a logical comparison. A well crafted beautifier, or pretty printer, will take these differences into account so far as to alter the entirety of a code base for easier reading but not at the cost of manipulating how the code is parsed by a given interpreter.
Code must never be minified if it cannot be automatically recovered into an easily readable form and must never be beautified if such beautification changes how the code is parsed. This is the importance of regression. The most extreme form of minification is referred to as obfuscation. Obfuscation removes all code comments and all white space characters not absolutely required for syntax compliance, but goes one step further and changes all variable and command names to the fewest available character length. Pretty Diff considers the practice of obfuscation to be harmful as its practice eliminates the possibility of regression. Without the possibility for regression recursive practices are improbable.
An instantiation of a pattern where the pattern's presence is available in the given instance without regard for multiplication is said to be idempotent. A recursive practice is the ability replicate an action where the replication does not harm the potential of further replication, or the idempotent nature of a pattern, upon or resulting from that action. In the case of Pretty Diff code that begins unminified should be capable of being minified, beautified, minified again, and so on without harm or difference to the functional integrity of the supplied code. Any process that prevents such recursive practices, such as obfuscation, are harmful and must be avoided.
Comments are the regression exception. There is no way to efficiently reduce code while retaining comments and documentation. Pretty Diff strongly recommends that documentation be separated from production code into either a redundant development version or into a separated documentation archive so that it can be preserved apart from the production code.
There is one extremely limited exception to functional interference observed by Pretty Diff. The Cascading Style Sheets language provides a syntax and vocabulary that are limited and fully known. Therefore functional changes can, and are, supplied to CSS code during minification because in this one narrow instance there is no harm to regression. Superior minification can be performed by supplying minor functional changes to the code which be easily and intelligently reversed without error or prior knowledge of the code sample.
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:
The function outputs an array of two indexes. The first array index is always the processed data and the second array index contains some metadata. In the case of the "beautify" and "minify" operations the first index of the output array is the processed source code as text and the second array index is the code report, as seen generated on the client side tool, formatted as HTML. The output from the diff operation returns an HTML table of the actual diff output as the first array index and a some minor metadata about the number of errors in the second array index with both indexes formatted as HTML and neither comprising a complete HTML document. To form the diff output of the prettydiff function into a single HTML document I supply the following extra code from the various files in the api directory:
Node.js is a command line run time. Node.js execution could be the result of a one-time execution or part of a scripted automation process. To execute the prettydiff function with Node.js the following code needs to be added after the prettydiff function. Nothing else needs to occur for compatibility or integration with Node.js.
if(typeof exports!=="string"){exports.api=function(x){"use strict";return prettydiff(x);};}
Some Node.js API files are supplied as part of the Pretty Diff project. An actively maintained API for use on the local file system is supplied as api/node-local.js.
Windows Script Host allows for a JavaScript run time in Windows environments from a command line with output directly returned to the command line or in a debugger window. To execute JavaScript with WSH a file is needed to supply the JavaScript function call, pass arguments from command line into a JavaScript compatible format, and to request dependencies.
An actively maintained API is provided at api/prettydiff.wsf. A WSF file follows basic XML syntax and may allow multiple operations of different languages to execute in tandem so long as each operation is confined to a job tag. The named elements in the example file are used to intercept arguments supplied via command line.
The example file would be operated for HTML compatibility using the following command: cscript prettydiff.wsf /source:"my_source_file.js" /html:true /mode:"beautify"
Writing the output of a WSH task into a file would require an additional ActiveX instruction in the wsh.wsf file or would require the automation of script execution in the context of the PowerShell language.
JavaScript beautification uses the jspretty library. JavaScript is beautified in a manner that conforms to the rules of JSHint and JSLint. jspretty counts unnecessary use of the new keyword in its report summary, which is any use except immediately preceeding one of these global objects:
"ActiveXObject", "ArrayBuffer", "AudioContext", "Canvas", "CustomAnimation", "DOMParser", "DataView", "Date", "Error", "EvalError", "FadeAnimation", "FileReader", "Flash", "Float32Array", "Float64Array", "FormField", "Frame", "Generator", "HotKey", "Image", "Iterator", "Intl", "Int16Array", "Int32Array", "Int8Array", "InternalError", "Loader", "Map", "MenuItem", "MoveAnimation", "Notification", "ParallelArray", "Point", "Promise", "Proxy", "RangeError", "Rectangle", "ReferenceError", "Reflect", "RegExp", "ResizeAnimation", "RotateAnimation", "Set", "SQLite", "ScrollBar", "Set", "Shadow", "StopIteration", "Symbol", "SyntaxError", "Text", "TextArea", "Timer", "TypeError", "URL", "Uint16Array", "Uint32Array", "Uint8Array", "Uint8ClampedArray", "URIError", "WeakMap", "WeakSet", "Web", "Window", "XMLHttpRequest"
An unassigned anonymous function creates the summary report and assigns its output to a variable named summary. Variable summary is not declared within jspretty. It is used as a closure from a higher scope so that it may be externally available and yet still access all the internals of jspretty.
CSS beautification uses csspretty library. A minimalist parser that is capable of quick extension and deep analysis. csspretty is written to supply extended support for the conventions of SCSS and LESS grammars.
CSV typically stands for comma separated values, but in this tool it stands for character separated values. The csvbeauty library takes a sequence of characters and splits the input upon that supplied sequence onto new lines. Prior existing line breaks, if they were quoted, are converted to a space contained by braces: { }. Unquote line breaks are converted into two simultaneous line breaks. If the final character(s) match the user supplied character sequence, after charDecoder processing, then those characters are converted into {|} so that csvmin will know a character sequence must exist at the extreme end of input. Escaped double quote characters, escaped using the formal CSV method by immediately preceeding the characters with an extra double quote character, are converted in a single double quote character to improve ledgibility.
CSV beautification uses charDecoder to decode Unicode character entities. The charDecode library accepts any combination of HTML decimal Unicode entities and Unicode hexidecimal entities. HTML decimal entities must begin with an ampersand and pound character '&#', be immediately followed with between one and six decimals, and be immediately terminated by a semicolon ';'. Examples of accepted HTML entities are:
The Unicode hexidecimal entities must begin with a lowercase u and plus character 'u+', be immediately followed by a four or five digit hexidecimal value, and be immediately terminated by a plus character. Hexidecimal values smaller than four digits must be padded with 0 characters necessary to achieve four digits. Examples of accepted Unicode entities are:
Please be aware that charDecode is reliant upon the interpreting application's HTML character rendering engine to map entity values to character maps, which means if the browser does not support the entity supplied the browser will return a generic character marker instead of the intended character. The content will then be separated in accordance to the rendered sequence value, which means a generic character marker will be used in the separation instead of the character referrenced by the supplied entity. In summary, if your browser has limited support for Unicode characters you must expect equally limited results when using entity references.
Markup beautification uses the markup_beauty library, which operates upon a pattern based logic of referential integrity. This means decisions are made through exposure to the pattern as established so far. Unfortunately, this requires defined logic to consider all possible combinations of patterns.
The markup beautification is based upon syntax conventions only and absolutely not upon vocabulary. The two exceptions are that the contents of a script tag are presumed to be JavaScript if the tag does not contain a type attribute or the type attribute contains one of these values: text/javascript, text/ecmascript, application/javascript, application/x-javascript, application/ecmascript. When the contents of a script tag are presumed as JavaScript they are beautified accordingly. The contents of a style tag are presumed to be CSS if the tag contains a type attribute with a value of text/css or if the type attribute is not present, and those contents are beautified as CSS. The presumed CSS and JavaScript do not inherit indentation from the markup. Since the beautification is not based upon vocabulary any language that uses angle brackets for delimiters should work assuming the conditions of the next paragraph are met. The supplied markup does not have to be valid or well formed by any means.
Content in the markup is represented by whether or not it begins or ends with any whitespace. If content does begin and/or end with whitespace then new line characters are added and the content is indented. This means tags that butt up directly to content are then treated as an extension of that content and are not indented. Singleton tags are expected to be terminated as XML singleton tags, which means a forward slash character prior to its closing angle bracket. If a singleton tag is not properly closed the beautifier believes the tag to be a start tag, which expects an end tag. Singleton tags may represent an indication of content in the form of media or form controls, and so they are indented in the same manner as content.
PHP tags are expected to open with "<?php" and XML parsing declarations are expected to open with "<?xml". Tags that begin with only "<?" are not supported, and so they are believed to be start tags missing a closing tag. This unsupported convention is no longer supported by PHP, even if tolerated, and will generate errors to an XML parser. I don't support this and neither should you.
Start tags expect to receive an end tag. End tags will be indented exactly like their starting pair unless they are directly next to content and the same is true for start tags. The beautification logic is smart enough to compensate and correct itself in adjustment for start tags or end tags that are not indented due to content.
The markup_beauty function also supports nested tags. Some server side processing languages use an XML base tag syntax for application processing, such as JSTL, and allow the direct embedding of HTML and XML tags directly. This following tag is example of something that can be beautified: <c:out value="<strong>variable text output</strong>"/>. The only limitation is that the nested tags must be quoted in either double or single quotes.
The markup_beauty function contains, at its end, an unassigned anonymous function that creates the summary report and assigns its output to a variable named summary. Variable summary is not provided a scope by markup_beauty, because it is meant to be supplied as a closure to markup_beauty. This summary variable must be provided a scope by the consuming application or it will become an implied global, or an undeclared variable error in strict mode.
The markup_summary creates a report of the number of parts comprising the markup, the weight of each of those parts, and a score using a math formula to compute a performance rating that reenforces reliance upon structure and elaboration of content. This function also displays each HTML element making a HTTP request.
The custom built csspretty library is used to analyze and minify JavaScript code. It is also capable of providing some minor auto-correction, such as inserting missing semicolons and curly braces.
The custom built csspretty library is used to analyze and minify CSS code.
CSV typically stands for comma separated values, but in this tool it stands for character separated values. The csvmin library reverts all changes inflicted by the csvbeauty library.
CSV beautification uses charDecoder to decode Unicode character entities. The charDecode library accepts any combination of HTML decimal Unicode entities and Unicode hexidecimal entities. HTML decimal entities must begin with an ampersand and pound character '&#', be immediately followed with between one and six decimals, and be immediately terminated by a semicolon ';'. Examples of accepted HTML entities are:
The Unicode hexidecimal entities must begin with a lowercase u and plus character 'u+', be immediately followed by a four or five digit hexidecimal value, and be immediately terminated by a plus character. Hexidecimal values smaller than four digits must be padded with 0 characters necessary to achieve four digits. Examples of accepted Unicode entities are:
Please be aware that charDecoder is reliant upon the interpreting application's HTML character rendering engine to map entity values to character maps, which means if the browser does not support the entity supplied the browser will return a generic character marker instead of the intended character. The content will then be separated in accordance to the rendered sequence value, which means a generic character marker will be used in the separation instead of the character referrenced by the supplied entity. In summary, if your browser has limited support for Unicode characters you must expect equally limited results when using entity references. csvmin does not revert any changes supplied by the charDecoder library.
Markup is minified using markupmin. This library does little more than tokenize a run of whitespace characters into a single space character and scrubbing of comments. It does, however, preserve whitespace inside ASP and PHP tags and preserve SSI tags. It will also assume the contents of a script tag are JavaScript and minify them according, and also assumes the contents of style tags are CSS and minifies them as such.
The diff engine uses diffview. Originally by Snowtide Informatics Systems. diffview is almost entirely rewritten from scratch so that JavaScript arrays are used to store the dynamic output instead of DOM objects. This change has result in a faster and more extensible application. charcomp is the function used to highlight per character differences.
JavaScript code is beautified with the jspretty library and then compared. CSV is first minified with csvmin and then beautified with csvbeauty. CSS is beautified with the csspretty library and then compared. Markup is beautified using the markup-beautify library. Plain text is compared without any minification or beautification. If code that needs to be compared is not compatible with the other processes then use the plain text mode.
Most parsers generate an Abstract Syntax Tree, instead the libraries used in Pretty Diff generate parallel arrays. This means multiple separate arrays are generated with a one to one relation of values at any given indexes between the arrays.
The parse data is exposed if the mode option has a value of parse. The language CSV is not currently supported in parse mode.
The parse data is always returned as object with two or three properties. This is handy if Pretty Diff is embedded directly in some application and the parse data needs to be immediately available. In other instances the generated object will need to be converted to a string using the JSON.stringify method.
For JavaScript and similar languages, such as React JSX, the jspretty library returns an object containing two arrays associated with the property names: token and types. The token array contains the actual parsed code into atomic fragments called tokens. The types array contains a categorical label that identifies each token into a grouped term.
The jspretty creates some tokens that are not present in the code source. In the case of missing semicolons and missing curly braces the jspretty library will create these tokens in the proper location. The created tokens are pseudo tokens in this form: "x;", "x{", and "x}". If the correct option is used the pseudo tokens are converted to actual code tokens. When the correct option is not used the pseudo tokens will be present in the parsed output, but are removed from the output when the mode option is not "parse".
Here are the supported types:
The csspretty library parses CSS and similar languages, such as: SCSS (Sass) and Less. In the parse mode an object containing two parallel arrays are generated ans assigned to properties: token and types.
The types generated by csspretty are:
All markup type languages are parsed with the markup_beauty library and returns an object containing three parallel arrays. The three arrays are assigned to property names: token, typea, typeb. Two categories of types are present to account for context dependents type classifications.
The HTML5 specification allows for list item elements to contain text content without an end tag. A start tag without a matching end tag would disrupt beautification, so Pretty Diff attempts to identify these instances by use of a pseudo tag: </prettydiffli>. If the option correct the pseudo tags are instantly supplied as </li> tags otherwise the Pretty Diff pseudo tag is removed immediately prior to generating output. The pseudo token logic is only evaluated if the input is HTML.
Types available in typea array:
Types available in typeb array:
| Component | Author(s) | Summary | Revised |
|---|---|---|---|
| charDecoder.js | Austin Cheney | The function that decodes Unicode character entities for csvbeauty.js and csvmin.js. | |
| codemirror.css | CodeMirror team | CSS for the CodeMirror editor. | |
| codemirror.js | CodeMirror team | JavaScript for the CodeMirror editor. | |
| csspretty.js | Austin Cheney | CSS parser. | |
| csvbeauty.js | Austin Cheney | The function that beautifies character sequence values. | |
| csvmin.js | Austin Cheney | The function that minifies 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 CheneyMaria Ramos - Español | This documentation page. | |
| dom.js | Austin Cheney | A supplemental JavaScript file providing DOM access and interaction with the web tool. | |
| jspretty.js | Austin CheneyHarry Whitfield - QA support | Beautifies JavaScript code. | |
| markup_beauty.js | Austin Cheney | Beautifies markup code. | |
| markupmin.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. |
Please send comments, feedback, and requests to [email protected].