Thanks for installing Sublime CodeFormatter! Below are some quick notes to get you
started with the plugin.

CodeFormatter
=============


CodeFormatter is a Sublime Text 2/3 plugin that supports format (beautify) source code.


CodeFormatter has support for the following languages:

* PHP - By phpfmt
* JavaScript/JSON - By JSBeautifier
* HTML - By JSBeautifier
* CSS - By JSBeautifier
* SCSS - By Nishutosh Sharma
* Python - By [ruff](https://docs.astral.sh/ruff/formatter/)
* Visual Basic/VBScript


Sponsors
-----
No sponsors yet.. :(

If you like the software, don't forget to donate to further development of it!

[![PayPal donate button](https://www.paypalobjects.com/webstatic/en_US/btn/btn_donate_pp_142x27.png)](https://www.paypal.com/cgi-bin/webscr?cmd=_xclick&business=akalongman@gmail.com&item_name=Donation to Sublime Text - CodeFormatter&item_number=1&no_shipping=1 "Donate to this project using Paypal")


Installing
----------
**With the Package Control plugin:** The easiest way to install CodeFormatter is through Package Control, which can be found at this site: http://wbond.net/sublime_packages/package_control

Once you install Package Control, restart Sublime Text and bring up the Command Palette (`Command+Shift+P` on OS X, `Control+Shift+P` on Linux/Windows). Select "Package Control: Install Package", wait while Package Control fetches the latest package list, then select CodeFormatter when the list appears. The advantage of using this method is that Package Control will automatically keep CodeFormatter up to date with the latest version.

**Without Git:** Download the latest source from [GitHub](https://github.com/akalongman/sublimetext-codeformatter) and copy the CodeFormatter folder to your Sublime Text "Packages" directory.

**With Git:** Clone the repository in your Sublime Text "Packages" directory:

    git clone https://github.com/akalongman/sublimetext-codeformatter.git CodeFormatter


The "Packages" directory is located at:

* OS X:

        ST2: ~/Library/Application Support/Sublime Text 2/Packages/
        ST3: ~/Library/Application Support/Sublime Text 3/Packages/

* Linux:

        ST2: ~/.config/sublime-text-2/Packages/
        ST3: ~/.config/sublime-text-3/Packages/

* Windows:

        ST2: %APPDATA%/Sublime Text 2/Packages/
        ST3: %APPDATA%/Sublime Text 3/Packages/


## Formatter-specific notes
Following are notes specific to individual formatters that you should be aware of:
### PHP
PHP - Used phpfmt (https://github.com/phpfmt/fmt) by Carlos Cirello and Shaked Klein Orbach.

Getting and installing PHP - http://www.php.net/manual/en/install.general.php

You must install 5.6 or above

On Linux/OSx after installation of package, you must set chmod +x to file fmt.phar in folder %PACKAGESDIR%/CodeFormatter/codeformatter/lib/phpbeautifier

You can list all available transformations from Command Palette: CodeFormatter: Show PHP Transformations

Language specific options:
```js
   "codeformatter_php_options":
    {
        "syntaxes": "php", // Syntax names which must process PHP formatter
        "php_path": "", // Path for PHP executable, e.g. "/usr/lib/php" or "C:/Program Files/PHP/php.exe". If empty, uses command "php" from system environments
        "format_on_save": false, // Format on save
        "psr1": false, // Activate PSR1 style
        "psr1_naming": false, // Activate PSR1 style - Section 3 and 4.3 - Class and method names case
        "psr2": true, // Activate PSR2 style
        "indent_with_space": 4, // Use spaces instead of tabs for indentation
        "enable_auto_align": true, // Enable auto align of = and =>
        "visibility_order": true, // Fixes visibiliy order for method in classes - PSR-2 4.2
        "smart_linebreak_after_curly": true, // Convert multistatement blocks into multiline blocks

        // Enable specific transformations. Example: ["ConvertOpenTagWithEcho", "PrettyPrintDocBlocks"]
        // You can list all available transformations from command palette: CodeFormatter: Show PHP Transformations
        "passes": [],

        // Disable specific transformations
        "exclude": []
    }
```



### Javascript/JSON
Javascript/JSON - used [JSBeautifier] (http://jsbeautifier.org/) by Einar Lielmanis

Language specific options:
```js
    "codeformatter_js_options":
    {
        "syntaxes": "javascript,json", // Syntax names which must process JS formatter
        "format_on_save": false, // Format on save
        "indent_size": 4, // indentation size
        "indent_char": " ", // Indent character
        "indent_with_tabs": false, // Indent with one tab (overrides indent_size and indent_char options)
        "eol": "\n", // EOL symbol
        "preserve_newlines": false, // whether existing line breaks should be preserved,
        "max_preserve_newlines": 10, // maximum number of line breaks to be preserved in one chunk
        "space_in_paren": false, // Add padding spaces within paren, ie. f( a, b )
        "space_in_empty_paren": false, // Add padding spaces within paren if parent empty, ie. f(  )
        "e4x": false, // Pass E4X xml literals through untouched
        "jslint_happy": false, // if true, then jslint-stricter mode is enforced. Example function () vs function()
        "brace_style": "collapse", // "collapse" | "expand" | "end-expand". put braces on the same line as control statements (default), or put braces on own line (Allman / ANSI style), or just put end braces on own line.
        "keep_array_indentation": false, // keep array identation.
        "keep_function_indentation": false, // keep function identation.
        "eval_code": false, // eval code
        "unescape_strings": false, // Decode printable characters encoded in xNN notation
        "wrap_line_length": 0, // Wrap lines at next opportunity after N characters
        "break_chained_methods": false, // Break chained method calls across subsequent lines
        "end_with_newline": false, // Add new line at end of file
        "comma_first": false // Add comma first
    }
```

### HTML
HTML - used custom python port, please use it with caution, feature in early beta

Language specific options:
```js
    "codeformatter_html_options":
    {
        "syntaxes": "html,asp,xml", // Syntax names which must process HTML formatter
        "format_on_save": false, // Format on save
        "indent_size": 4, // indentation size
        "indent_char": " ", // Indentation character
        "indent_with_tabs": false, // Indent with one tab (overrides indent_size and indent_char options)
        "preserve_newlines": false, // Preserve existing line-breaks
        "max_preserve_newlines": 10, // Maximum number of line-breaks to be preserved in one chunk
        "indent_tags": "html|head|body|div|nav|ul|ol|dl|li|table|thead|tbody|tr|th|td|blockquote|select|form|option|optgroup|fieldset|legend|label|header|section|aside|footer|figure|video|datalist|keygen|audio|embed|source|track|output|article|bdi|details|dialog|figcaption|main|mark|menuitem|meter|nav|progress|rp|rt|ruby|summary|time|wbr" // List of tags (defaults to indent) that should be reformatted. Example "div|p|li|table"
    }
```

### CSS
CSS - used [JSBeautifier] (http://jsbeautifier.org/) by Einar Lielmanis and Style Css by Harutyun Amirjanyan

Language specific options:
```js
    "codeformatter_css_options":
    {
        "syntaxes": "css,less", // Syntax names which must process CSS formatter
        "format_on_save": false, // Format on save
        "indent_size": 4, // Indentation size
        "indent_char": " ", // Indentation character
        "indent_with_tabs": false, // Indent with one tab (overrides indent_size and indent_char options)
        "selector_separator_newline": false, // Add new lines after selector separators
        "end_with_newline": false, // Add new line of end in file
        "newline_between_rules": false, // Add new line between rules
        "eol": "\n" // EOL symbol
    }
```
### SCSS
SCSS - Simply modified the CSS formatter module as per the response from scss-lint (Gives way to modify further)

Language specific options:
```js
    "codeformatter_scss_options":
    {
        "syntaxes": "scss", // Indentation size
        "indent_size": 2, // Indentation size
        "format_on_save": false, // Format on save
        "indent_char": " ", // Indentation character
        "indent_with_tabs": false, // Indent with one tab (overrides indent_size and indent_char options)
        "selector_separator_newline": true, // Add new lines after selector separators
        "newline_between_rules": true, // Add new line between rules
        "end_with_newline": true // Add new line of end in file
    }
```

### Python
Python - used [ruff](https://docs.astral.sh/ruff/formatter/)

Language specific options:
```js
    "codeformatter_python_options":
    {
        "syntaxes": "python", // Syntax names which must process Python formatter
        "format_on_save": false, // Format on save. Either a boolean (true/false) or a string regexp tested on filename. Example : "^((?!.min.|vendor).)*$"
        "ruff_path": "" // Path to the ruff executable. If empty, uses "ruff" from PATH
    }
```

Style comes from the project's ruff configuration: the closest `.ruff.toml`, `ruff.toml` or `pyproject.toml` with a `[tool.ruff]` section above the file. CodeFormatter has no Python style options of its own. Files that this configuration excludes are left unchanged: its `exclude` list (by default ruff's own list, such as `.venv`, `dist` and `node_modules`), its `extend-exclude` list, and its `[tool.ruff.format] exclude` list (`[format]` in a `ruff.toml`).

For a buffer that was never saved, ruff looks for a configuration upward from Sublime Text's working directory, which is usually not the project folder, and otherwise falls back to its user-level configuration or its defaults. Save the file inside the project to format it with the project's style.

If you format Python files with another package, set `"syntaxes": ""` in `codeformatter_python_options` so CodeFormatter leaves them alone.

Installing ruff:

* macOS: `brew install ruff`
* Debian/Ubuntu: `sudo apt install pipx`, then `pipx install ruff`, then `pipx ensurepath`, then log out and back in so that Sublime Text started from the desktop sees `~/.local/bin`
* Other Linux: `curl -LsSf https://astral.sh/ruff/install.sh | sh`
* Windows (PowerShell): `powershell -c "irm https://astral.sh/ruff/install.ps1 | iex"`
* WSL: if Sublime Text runs inside WSL, install ruff inside WSL with the Linux steps. If Windows Sublime Text edits files under `\\wsl.localhost`, install ruff on Windows with the Windows steps. A ruff installed only inside WSL cannot be used by Windows Sublime Text.

Restart Sublime Text after installing ruff, and open a new terminal before running `which ruff` or `where.exe ruff` below, because a program that is already running keeps the `PATH` it started with.

Sublime Text started from the macOS Dock may not see the same `PATH` as your terminal, so it may not find ruff. In that case, or whenever CodeFormatter reports that ruff is not found, set `ruff_path` to the output of `which ruff` in a terminal. On Windows, run `where.exe ruff` (in PowerShell or the Command Prompt) and use the first line it prints. Write that path with forward slashes or doubled backslashes, because a single backslash starts an escape sequence in the settings file: `"ruff_path": "C:/Users/you/.local/bin/ruff.exe"` or `"ruff_path": "C:\\Users\\you\\.local\\bin\\ruff.exe"`. Copy the whole `codeformatter_python_options` block into `Settings - User` and change `ruff_path` there, because a block that holds only `ruff_path` replaces the default block, which drops `syntaxes` and turns Python formatting off.

### Visual Basic/VBScript
Visual Basic/VBScript - used custom approach using the HTML beautifier as a guide

Language specific options:
```js
    "codeformatter_vbscript_options":
    {
        "syntaxes": "vbscript", // Syntax names which must process VBScript formatter
        "format_on_save": false, // Format on save
        "indent_size": 1, // indentation size
        "indent_char": "\t", // Indentation character
        "indent_with_tabs": true, // Indent with one tab (overrides indent_size and indent_char options)
        "preserve_newlines": true, // Preserve existing line-breaks
        "max_preserve_newlines": 10, // Maximum number of line-breaks to be preserved in one chunk
        "opening_tags": "^(Function .*|Sub .*|If .* Then|For .*|Do While .*|Select Case.*)", // List of keywords which open a new block
        "middle_tags": "^(Else|ElseIf .* Then|Case .*)$", // List of keywords which divide a block, but neither open or close the block
        "closing_tags": "(End Function|End Sub|End If|Next|Loop|End Select)$" // List of keywords which close an open block
    }
```

Usage
-----
Tools -> Command Palette (`Cmd+Shift+P` or `Ctrl+Shift+P`) and type `Format Code`.

You can set up your own key combo for this, by going to Preferences -> Key Bindings - User, and adding a command in that huge array: `{ "keys": ["ctrl+alt+f"], "command": "code_formatter" },`. Default keybinding is `ctrl+alt+f`. You can use any other key you want, thought most of them are already taken.

TODO
-----
Add other languages support:
* Perl
* Ruby

Pull requests are welcome.

Troubleshooting
---------------
If you like living on the edge, please report any bugs you find on the [CodeFormatter issues](https://github.com/akalongman/sublimetext-codeformatter/issues) page.
