Pretty Diff - Documentation

Purpose

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

Pretty Diff was created to compare code samples for various languages regardless of differences in comments, white space, and other factors. Currently, the project operates by beautifying code and then comparing 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 making code easier to read against a variety of settings 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 increased portability. Clearer simple code allows separation of concerns, and cleaner organization.

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, leans on the sparser project which produces parse output as a data table.

Supported Languages

• markup
  • Apache Velocity
  • ASP Inline Expression
  • CFML (ColdFusion Markup Language)
  • Django Inline HTML
  • Dust.js
  • EEX Elixir Templates
  • EJS (Embedded JavaScript) Templates
  • ERB (Embedded Ruby)
  • FreeMarker
  • Genshi
  • Handlebars
  • HTL (HTML Templating Language)
  • HTML
  • Jekyll
  • Jinja
  • JSTL (Java Standard Tag Library)
  • Liquid
  • Mustache
  • Nunjucks
  • SGML
  • SilverStripe
  • Spacebars templates
  • ThymeLeaf
  • Underscore Templates (TPL)
  • Twig
  • Vapor Leaf
  • Vash
  • Volt
  • XML
  • XSLT
• script
  • Flow
  • JavaScript / ECMAScript
  • JSON
  • QML
  • React JSX
  • styled-components
  • styled-jsx
  • TSS (Titanium Style Sheets)
  • TSX
  • TypeScript
• style
  • CSS
  • LESS
  • PostCSS
  • SCSS (Sass)

45 total languages

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.

Get the Code

Various options are available for greater portability

• Github

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

• NPM, Pretty Diff

  Pretty Diff is available on NPM at https://www.npmjs.com/package/prettydiff.

Setup/Run the Application

Setup as a local application

1. git clone https://github.com/prettydiff/prettydiff.git
2. cd prettydiff
3. npm install typescript -g
4. npm install eslint -g
5. npm install
6. tsc --pretty
7. node js/services build

Setup as a global NPM package

1. npm install typescript -g
2. npm install eslint -g
3. npm install prettydiff -g
4. prettydiff build

To get started with the application on the command line try the commands command to see a list of available features and detailed instructions: node js/services commands

To run the application in a web browser with Pretty Diff's HTML execute the server command: node js/services server or simply navigate your browser to the project's index.xhtml file in the local filesystem.

To run the application in a different browser application simply reference or include the built js/browser.js file. See the third party demo for an example.

The .prettydiffrc File

To ease configuration Pretty Diff provides support for a .prettydiffrc file that stores option settings as a sort of saved preferences. The .prettydiffrc file is only used when the application is executed via Node.js via the supplied js/services.js file, but is checked each time the application executes. This file supports two formats: JavaScript logic and JSON. Options api, diff, and source are not supported in the .prettydiffrc file.

Pretty Diff will look for the .prettydiffrc file starting in the directory specified or the directory containing a specified file. If no .prettydiffrc file is present Pretty Diff will check the next higher directory until reaching root. If the option read_method is value screen or auto and resolves to value screen then the starting location to look for the .prettydiffrc file will be the terminal's current working directory.

JSON Format

In order for the options to be accepted by the application the provided options must match a defined option name and the corresponding value must be the proper data type. In the case where an option is string type and accepts a specified set of values the specified value much match one of the supported value names. Here are some examples:

Good {"indent_size": 6, "format_object": "inline"}

Bad {"indent_size": " ", "format_object": "inline"} This is bad, because the "indent_size" option is provided a value with the incorrect data type. It will be ignored from the application, but the specified "format_object" option will be accepted.

Bad {"indent_size": 3, "format_object": "never"} The value for option "format_object" is the correct data type, but that option accepts one of three values and "never" is not a supported value. Pretty Diff will accept the "indent_size" option with value 3, but will ignore the specified "format_object".

JavaScript Format

To give users greater control and flexibility over the application a JavaScript format is also accepted. This will allow users to specify options conditionally. Please start with this following template:

(function rc() { "use strict"; const rclogic = function rc_logic(options) { // edit below this line // edit above this line return options; }; module.exports = rclogic; }());

JavaScript logic that deviates from the template may result in an error causing the Pretty Diff application to no longer run. For security concerns no use of require, import, and no other use of export is permitted. Ignoring these security concerns will cause the file to be ignored. The options must be assigned with conforming value data types exactly as specified under the JSON Format section in order to be accepted. Examples:

(function rc() { "use strict"; const rclogic = function rc_logic(options) { // edit below this line if (options.mode === "beautify" && options.lexer === "style") { options.indent_size = 6; } if (options.source.length > 2500) { options.indent_size = 2; } // edit above this line return options; }; module.exports = rclogic; }());

@source

https://github.com/prettydiff/prettydiff

@documentation

https://prettydiff.com/documentation.xhtml

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 for additional information.

Precedence

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

1. The styleguide option, which is only used in the beautify/script.ts library.
2. The Pretty Diff comment.
3. User supplied options
4. Default option values

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. 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, language:javascript, indent_char:"abc"*/
• <!--prettydiff.com mode: beautify, language: javascript, indent_char: "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.

localstorage

Disables or enables all storage in the browser.

Any defined option name is also supported as a parameter.

Here is an example: https://prettydiff.com/?source=https://duckduckgo.com&mode=beautify&correct=true&localstorage=false

Contribution Guide

For questions, features, or bug reports please open an issue on Github. If you are executing from the command line insert the debug word at the end of your command and Pretty Diff will generate an issue template in markdown format that you can simply copy and paste into Github.

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

1. Fork the repository on Github and then clone down the fork to your local computer.
2. Create a new branch for your changes: git checkout -b branchName
3. Create test units. A pull request will be rejected without tests unless there is a strong expection. The build process employs different kinds of tests.
   • The simulation command runs just the simulation tests. These tests validate features of the command line operation. These tests are stored in the file tests/simulations.ts.
   • The validation command runs the code unit tests that validate the beautification and minification functions. These tests are stored in the tests/formatted and tests/raw directories. A file in the raw directory containing a test unit is compared against a same named file in the formatted directory storing the Pretty Diff output.
   • The diff tests are execution as a part of the simulation tests. The code units for the diff tests are stored in the directories tests/diffbase and tests/diffnew.
   • The parser has its own unit tests that are part of that project. Please see its Github repository: sparser.
4. Run the unit tests to verify if your changes are breaking things: node js/services test
5. Finally, open a pull request on Github or if you are having trouble with the build open a Github issue and ask for help.

Troubleshooting Help

A few helpful tips in case you get stuck.

• If an update to the code breaks the build and the application can no longer build try recompiling from TypeScript and then running the Pretty Diff build again. The command is tsc --pretty.
• Ensure dependencies are up to date. Try running npm update. A version mismatch between Pretty Diff and the parser could result in unpredictable behavior.
• If you need help generating the appropriate details for a Github issue try using the debug feature. Simply run your command on the terminal and add debug or prettydiff_debug to generate an issue template in markdown format.
• When everything seems correct on the Pretty Diff side but the result is still wrong there could be a defect in the parser. Clone the parser as a separate project and run its tests by using the validation command. You could also use the parser's server command to run a frontend in your browser that is easier to read. The parser is at sparser
• If you modify the build code you have to rebuild twice to test the changes. This is because the first build compiles the updated code and the second build executes the updated code.