ctrl+shift+p filters: :st2 :st3 :win :osx :linux
Browse

Formatter

by bitst0rm ST3

πŸ§œβ€β™€οΈ A Sublime Text plugin to beautify and minify source code: CSS, SCSS, Sass, HTML, XML, SVG,JS,JavaScript, JSON, GraphQL, Markdown, TypeScript, Vue, Lua, YAML, Go, Perl, PHP, Python, Ruby, Rust, Haskell, Dart, Swift, Crystal, Bash, Shell, SQL, CSV, C, C++, C#, Objective-C, D, Java, Pawn, Julia, Proto, LaTeX, D2, Graphviz, Mermaid, PlantUML, etc

Details

Installs

  • Total 127K
  • Win 73K
  • Mac 34K
  • Linux 20K
Jun 18 Jun 17 Jun 16 Jun 15 Jun 14 Jun 13 Jun 12 Jun 11 Jun 10 Jun 9 Jun 8 Jun 7 Jun 6 Jun 5 Jun 4 Jun 3 Jun 2 Jun 1 May 31 May 30 May 29 May 28 May 27 May 26 May 25 May 24 May 23 May 22 May 21 May 20 May 19 May 18 May 17 May 16 May 15 May 14 May 13 May 12 May 11 May 10 May 9 May 8 May 7 May 6 May 5 May 4
Windows 31 40 37 30 38 53 50 43 34 36 28 42 57 58 44 39 36 31 40 54 52 44 48 31 33 46 44 48 48 43 37 44 56 51 53 42 53 24 32 49 56 39 40 39 34 34
Mac 17 27 22 22 31 43 54 34 33 23 30 34 47 43 36 34 18 27 33 42 38 40 42 20 23 26 38 37 36 27 22 23 45 48 36 43 37 14 18 42 27 53 42 30 23 23
Linux 10 31 23 20 23 25 22 19 28 22 25 28 26 30 27 26 22 20 24 21 20 22 24 22 20 15 32 27 19 29 24 25 23 24 28 17 19 12 20 26 32 30 25 30 23 32

Readme

Source
raw.​githubusercontent.​com

πŸ§œβ€β™€οΈ Formatter

Formatter is a simple config-file-driven plugin for Sublime Text 3 & 4 to beautify and minify source code.

Update:

  • Cloning this repo for contribution should be done outside the ST context, as Formatter will automatically remove its .git folder to prevent conflicts with certain built-in features of ST4.

Key features:

  • Supports more than 70 major programming languages.
  • Includes over 80 preset adapters for various plugins.
  • Formats text in various ways:
    • Text-to-Text (Text diagramms, ASCII art, etc.)
    • Text-to-Image (Image diagramms, QR-code images, etc.)
  • Capable to format entire files, single or multiple selections.
  • Capable to format entire folder recursively.
  • Operates more precisely based on syntax scope, not file extension.
  • Works with both saved and unsaved files (buffer).
  • Unified settings across different systems.
  • Supports auto-detect formatting.
  • Supports per-project formatting.
  • Capable to format on Save.
  • Capable to format on Paste.
  • Shared config files available for each 3rd-party plugin.
  • Displays real-time word and character counts.
  • Automatically remembers and restores text position.
  • Customizable and extendable through 2 methods to add your custom plugins:
    • Generic: Adding a portion JSON settings (no coding needed). see Configuration
    • Modules: Integration of your own modules. see Development
  • Zero dependencies for installation.
  • Open source and works offline (security reason).

Limitations:

  • Text-to-Image: Third-party plugins often rely on a headless browser to render images, making the process time-consuming. Consequently:

    • "recursive_folder_format" will not be implemented or is disabled.
    • "new_file_on_format" will not be implemented or is disabled.
    • Third-party plugins must support exporting PNG format as Sublime Text only supports PNG, JPG, and GIF images.
  • Plugins:

    • eslint_d*: Drop support for Eslint v8.57.0+ (using flat config files eslint.config.) untill this upstream bug is fixed: #281

Formatter in action: Text-to-Text…

Formatter

Formatter in action: Text-to-Image…

Formatter

Guides

Plugins

Formatter is useless without third-party plugins. It relies on external plugins in order to format code. These plugins need to be installed by the end-user. This means, Formatter is not responsible for:

  • The quality of formatted code.
  • The speed of the formatting process.

The complete list of supported plugins: Need more? see: Configuration and Development to add your own.

  • This table does not contain the complete languages that each plugin does support. For example, prettydiff supports 45 languages, that would blow up the frame of this list here.
  • Languages such as Svelte or Prisma are not listed here, but can be used through the prettier plugin. deno and dprint should have the similar concept.
  • build-in = do not need to install by end-users.
  • None = mostly standalone binary.
  • Req. = Requirements might not be up-to-date.
Languages Beautify Minify Graphic Req. Config
Angular prettier, prettierd – – Node.js –
Arduino uncrustify[1], clang-format[2], artistic style – – None [1], [2]
Assembly asmfmt, nasmfmt – – None –
Astro prettier, prettierd – – Node.js –
BibTeX bibtex-tidy[1] – – Node.js 12.0+ [1]
C, C++, C#, Objective-C uncrustify[1], clang-format[2], artistic style – – None [1], [2]
Cabal cabal-fmt – – Haskell –
Caddyfile caddy-fmt – – None –
Clojure cljfmt, zprint – – None, (Java) –
CMake cmake-format – – Python –
Crystal crystal tool format – – None –
CSS, SCSS, Sass, Less, SugarSS stylelint[1], js-beautifier, prettier, prettierd, prettydiff[2], csscomb, stylefmt cleancss CLI, prettydiff[2] – Node.js [1], [2]
CSV, TSV, DSV, Text prettytable (build-in), prettydiff[1][2] – – Python, Node.js[2] [1]
D uncrustify[1] – – None [1]
D2 d2 fmt – d2 None –
Dart dart-format – – Dart –
Dhall dhall format – – None –
Dockerfile dockfmt – – None –
Drawio – – draw.io None –
Elixir mix format – – Erlang –
Elm elm-format – – None –
Erlang erlfmt[1], efmt – – rebar3[1], None –
Fortran fprettify – – Python –
Gleam gleam format – – None –
GLSL clang-format[1] – – None [1]
Go gofmt, goimports, gofumpt – – None –
GraphQL prettier, prettierd – – Node.js –
Graphviz – – graphviz None –
Haskell ormolu, fourmolu[1], hindent, stylish-haskell, floskell – – Haskell [1]
HCL hclfmt – – None –
HTML, XHTML, XML js-beautifier, prettier, prettierd, prettydiff[1], html-tidy html-minifier, prettydiff[1] – Node.js [1]
Java google java format[1], uncrustify[2], clang-format[3], artistic style – – Java[1], None [2], [3]
JavaScript eslint, eslint_d, js-beautifier, prettier, prettierd, standard js, standardx js, semistandard js, prettydiff, clang-format[1][2], deno[2], dprint[2], biome[2] terser, prettydiff – Node.js, None[2] [1]
JSON js-beautifier, prettier, prettierd, prettydiff[1], deno[2], topiary[2], dprint[2], biome[2], jsonmax (build-in) prettydiff[1], jsonmin (build-in) – Node.js, None[2] [1]
Julia juliaformatter – – Julia 0.6+ –
Kotlin ktlint – – Java –
LaTeX latexindent – – Perl, None –
Lua stylua, luaformatter – – None –
Markdown prettier, prettierd, deno[1], dprint[1] – – Node.js, None[1] –
Mermaid – – mermaid[1] Node.js [1]
Nginx nginxfmt – – Python 3.4+ –
Nickel topiary – – None –
OCaml ocamlformat, ocp-indent, topiary – – None –
Perl perltidy – – Perl –
Pawn uncrustify[1] – – None [1]
PHP php-cs-fixer[1], php_codesniffer – – PHP 7.4+[1] [1]
Plantuml plantumlascii – plantuml Java –
Proto clang-format[1] – – None[1] [1]
Python ruff, yapf[1], black[1], autopep8, isort, docformatter, pyment python-minifier[2] – Python 3.7+[1] [2]
R styler, formatR[1] – – R [1]
Racket raco fmt – – Racket 8.0+ –
Ruby rubocop[1], rubyfmt, standardrb, rufo[1] – – Ruby[1], None –
Rust rustfmt – – Rust 1.24+ –
Scala scalafmt, scalariform[1] – – None, Java[1] –
Shell, Bash beautysh[1], shfmt, shellcheck shfmt – Python[1], None –
SQL, SQL dialects, PostgreSQL sql-formatter[1], pg_format[2], sqlparse[3] sqlmin (build-in) – Node.js[1], Perl[2], Python 3.6+[3] [1], [2]
Swift apple swift-format, swiftformat – – None –
SVG svgo max svgo min – Node.js –
TableGen clang-format[1] – – None [1]
Terraform terraform fmt – – None –
TextProto clang-format[1] – – None [1]
TOML taplo, topiary, dprint – – None –
TypeScript prettier, prettierd, js-beautifier, ts-standard, prettydiff[1], tsfmt, deno[2], dprint[2], biome[2] prettydiff[1] – Node.js, None[2] [1]
VALA uncrustify[1] – – None [1]
Verilog clang-format[1] – – None [1]
Vue prettier, prettierd, js-beautifier – – Node.js –
YAML prettier, prettierd – – Node.js –
Zig zigfmt – – None –

πŸ’‘ Tips:

  • prettier and stylelint and can collaborate to format CSS

    Config example

    stylelint_rc.json:
    {"extends":["stylelint-config-recommended","stylelint-config-standard"],"plugins":["stylelint-group-selectors","stylelint-no-indistinguishable-colors","@double-great/stylelint-a11y","stylelint-prettier"],"rules":{"plugin/stylelint-group-selectors":true,"plugin/stylelint-no-indistinguishable-colors":true,"a11y/content-property-no-static-value":false,"a11y/font-size-is-readable":false,"a11y/line-height-is-vertical-rhythmed":[true,{"severity":"warning"}],"a11y/media-prefers-color-scheme":false,"a11y/media-prefers-reduced-motion":false,"a11y/no-display-none":false,"a11y/no-obsolete-attribute":[true,{"severity":"warning"}],"a11y/no-obsolete-element":[true,{"severity":"warning"}],"a11y/no-outline-none":false,"a11y/no-spread-text":false,"a11y/no-text-align-justify":false,"a11y/selector-pseudo-class-focus":false,"prettier/prettier":[true,{"parser":"css","printWidth":120,"semi":true,"singleQuote":false,"tabWidth":4,"useTabs":false}]}}
    
    Then in Formatter settings > "stylelint": { ... "args": ["--config-basedir", "/absolute/path/to/javascript/node_modules"] ... }
    

  • prettier and eslint can collaborate to format JS

    Config example

    eslint_rc.json:
    {"env":{"es2022":true,"node":true,"browser":true},"parserOptions":{"ecmaVersion":13,"sourceType":"module","ecmaFeatures":{"jsx":true}},"extends":["../javascript/node_modules/eslint-config-prettier","../javascript/node_modules/eslint-config-airbnb-base"],"plugins":["eslint-plugin-prettier"],"rules":{"prettier/prettier":["error",{"bracketSpacing":true,"jsxSingleQuote":true,"parser":"babel","printWidth":120,"semi":true,"singleQuote":true,"tabWidth":4,"useTabs":false},{"usePrettierrc":false}],"indent":["error",4]}}
    

Installation

  • Using Package Control: run Package Control: Install Package and select Formatter
  • or Download: the latest source from GitHub to your sublime Packages directory and rename it to Formatter
  • Cloning for use is okey, but cloning for contributions like pull requests, it's important to clone outside the ST context as Formatter will auto delete its .git folder to prevent conflict in ST4.

The Packages directory is located in:

  • MacOSX: ~/Library/Application Support/Sublime Text 3/Packages/
  • Linux: ~/.config/sublime-text-3/Packages/
  • Windows: %APPDATA%/Sublime Text 3/Packages/

Configuration

This section is the head of Formatter. While the configuration is easy and self-explained, it still needs a detailed explanation of the underlying principles and context. Hold on for a long text.

Formatter stores third-party plugin config files in:

Sublime Text > Packages > User > formatter.assets > config
  • You can use these files directly or place them in a location of your choice. Formatter provides only a set of default (original) config files to illustrate how it works. You might want to tweak and refine them to fit your needs. The full list of supported options and parameters can be found on plugins dev websites.
  • You can use a different config file format than the default one provided by Formatter. For example, while Formatter typically uses JSON or YAML (prettier_rc.json) by default, you can write your own config in JavaScript format (prettier_rc.js) or any other format supported by third-party plugins.

Note: Do not use files with the suffix .master. as they serve as reference(example) files for your final configuration and could be overwritten by any package updates. Reason: Some exotic plugins do not support input config file, while others do not understand stdio. To overcome this limitation, you will need these example files as reference to configure them.
It is recommended to explore this folder, as it may contain additional config files for the same plugin.

Formatter settings can be accessed from: Preferences > Package Settings > Formatter > Settings

The following setting details - along with their default values and examples - are provided to guide you on how to set it up.

πŸ’‘ Tips:

  • Options are optional: you do not need to take the whole set of options. Take only what you need, but keep the JSON structure intact.
  • You are not forced to use the preset modules. Instead, you can create a new one using a different UID key through either of these methods.
  • Not all syntax highlighting plugins for a specific language exist; syntaxes like "text" or "plain" work just as well as a workaround.

Formatter.sublime-settings

{
    // Enable debug mode to view errors in the console.
    // Accepted values: true (verbose), false, OR "status" (recommended)
    "debug": false,

    // Auto open the console panel whenever formatting fails.
    // This is useful when combined with "debug": "status" or true
    "open_console_on_failure": false,

    // Timeout to abort subprocess in seconds.
    // Default to 10 seconds. Set to false to disable the timeout.
    "timeout": 10,

    // Integrate your custom modules into the Formatter ecosystem.
    // All paths to files and folders must be local.
    "custom_modules": {
        "config": ["/path/to/foo_rc.json", "/path/to/bar_rc.cfg"],
        "modules": ["/path/to/formatter_foo.py", "/path/to/formatter_bar.py"],
        "libs": ["/path/to/foolib", "/path/to/mylib"]
    },

    // Display results in the status bar with the current settings mode info:
    // PUS: Persistent User Settings
    // PQO: Persistent Quick Options
    // TQO: Temporary Quick Options
    "show_statusbar": true,

    // Display a real-time word and character count in the status bar.
    // By default, whitespace is not included in the character count.
    "show_words_count": {
        "enable": true,
        "use_short_label": false,
        "ignore_whitespace_char": true
    },

    // Remember and restore cursor position, selections and bookmarks
    // each time a file is closed and re-opened.
    // This is helpful to resume your work from where you left off.
    // It does not remember the whole session as name might suggest.
    "remember_session": true,

    // Configure the layout when opening new files.
    // This only takes effect if the "new_file_on_format" option is true.
    // Accepted values: "2cols", "2rows", "single" OR false
    "layout": {
        "enable": "2cols",
        "sync_scroll": true
    },

    // A set of directories where executable programs are located.
    // These can be absolute paths to module directories or Python zipfiles.
    // Any environment variables like PATH, PYTHONPATH, GEM_PATH, GOPATH,
    // GOROOT, GOBIN, TMPDIR, WHATEVER, etc. can be added here.
    // This is similar to running 'export PYTHONPATH="/path/to/my/site-packages"'
    // from the terminal. It is temporary, your system environment remains untouched.
    // On Windows, you can use either escaped backslashes (e.g., "C:\\a\\b\\c") or
    // forward slashes (e.g., "C:/a/b/c") as path separators for all other options.
    "environ": {
        "PATH": ["/path/to/erlang@22/bin:$PATH", "$PATH:/path/to/elixir/bin", "/path/to/.cache/rebar3/bin:$PATH"],
        "GEM_PATH": ["${HOME}/to/my/ruby"],
        "PYTHONPATH": ["${packages}/User/MyFolder/python/lib/python3.7/site-packages"],
        "OLALA": ["$HOME/.cabal/bin:$PATH", "~/.olala/bin:$PATH"]
    },

    // This option resolves the syntax conflicts described in "format_on_save".
    // It acts as an override and only applies to the following options:
    // 1. "format_on_save"
    // 2. "format_on_paste"
    // Syntaxes in this option always take precedence over the syntaxes specified there.
    // All syntaxes must be unique without any duplicates.
    "format_on_priority": {
        "enable": false,
        "csscomb": ["css"],
        "jsbeautifier": ["js"]
    },

    // This option enables auto-detect formatting for file using a single command.
    // Configure it here and/or by using the dot files in your working folder.
    // If both methods are used, the config from the dot files will override this embedded one.
    // More about this feature, see README.md > Auto-detect Formatting
    "auto_format": {
        "config": {
            "format_on_save": false,
            "format_on_paste": false
        },
        "json": {
            "uid": "jsbeautifier"
        },
        "html": {
            "uid": "jsbeautifier",
            "exclude_syntaxes": {
                "html": ["markdown"]
            }
        },
        "python": {
            "uid": "autopep8"
        }
    },

    // THIRD-PARTY PLUGINS LEVEL
    // Help: Preferences > Package Settings > Formatter > Modules Info
    "formatters": {
        "examplegeneric": { // GENERIC METHOD
            // Formatter provides 2 methods to add custom plugins:
            // - Generic: this one, you design the bridge yourself. Suitable for simple tasks.
            // - Modules: requires writing Python modules for complex tasks.
            // Note: The Generic method requires a Sublime Text restart after adding or changing
            // the "name" and "type" keys. Also, avoid reusing existing UID keys in JSON.

            // The capitalized Plugin name (REQUIRED!)
            // This will appear in the Sublime menu and other commands.
            "name": "Example Generic",

            // The plugin type (REQUIRED!)
            // This will categorize the plugin. Accepted values:
            // "beautifier", "minifier", "converter", "graphic", or any string of your choice.
            "type": "beautifier",

            // This will activate the "args_extended" option for the graphic type
            // to generate extended files like SVG for download.
            "render_extended": false,

            // The exit code for the third-party plugin (optional, default is 0).
            "success_code": 0,

            // Same as the one in the examplemodule.
            "enable": false,
            // Same as the one in the examplemodule.
            "format_on_save": false,
            // Same as the one in the examplemodule.
            "format_on_paste": false,
            // Same as the one in the examplemodule, but disabled/unused for type graphic.
            "new_file_on_format": false,
            // Same as the one in the examplemodule, but disabled/unused for type graphic.
            "recursive_folder_format": {},
            // Same as the one in the examplemodule.
            "syntaxes": ["css", "html", "js", "php"],
            // Same as the one in the examplemodule.
            "exclude_syntaxes": {},
            // Same as the one in the examplemodule.
            "interpreter_path": ["${HOME}/example/path/to\\$my/php.exe"],
            // Same as the one in the examplemodule.
            "executable_path": ["${HOME}/example/path/to\\$my/php-cs-fixer.phar"],
            // Same as the one in the examplemodule.
            "config_path": {
                "css": "${packages}/User/formatter.assets/config/only_css_rc.json",
                "php": "${packages}/User/formatter.assets/config/only_php_rc.json",
                "default": "${packages}/User/formatter.assets/config/css_plus_js_plus_php_rc.json"
            },

            // Main commands to trigger the formatting process.
            // You can either set the paths directly or use variable substitution for:
            // - "interpreter_path"   : "{{i}}"
            // - "executable_path"    : "{{e}}", "{{e=node}}" (for local executable auto-resolving with runtime type node)
            // - "config_path"        : "{{c}}"
            // - SPECIAL CASE GRAPHIC : "{{o}}" (output PNG image, e.g: "args": [... "--output", "{{o}}"])
            // Variable substitution allows advanced mechanisms such as auto-search path, auto-config, etc.
            // SPECIAL CASE GRAPHIC requirements:
            // 1. The plugin must support exporting PNG format.
            // 2. The hardcoded "{{o}}" MUST ALWAYS be included in "args".
            //    You might regret using your own path instead of "{{o}}" or daring to omit "{{o}}" in this case.
            // In all other cases, output may not be as a file; use "-" or "--" instead.
            "args": ["{{i}}", "{{e=node}}", "--config", "{{c}}", "--basedir", "./example/my/foo", "--"],

            // This is for the SPECIAL CASE GRAPHIC to downloading extended graphic files.
            // To use this, the trigger option "render_extended" above must be activated.
            // Sublime Text only supports PNG, JPG, and GIF images. Formatter uses PNG to display
            // image in view and generates the same image in various formats for you.
            // WARNING: Formatter will loop subprocess to render extended files. This means, process
            // will takes more time. This option might be useful for the final step to production.
            // "key":["value",..], where key is the output file extension, value is the command arguments.
            "args_extended": {
                "svg": ["{{e}}", "--config", "{{c}}", "--blabla-format", "svgv5", "--output", "{{o}}"],
                "pdf": ["{{e}}", "--config", "{{c}}", "--blabla-format", "pdf2001", "--output", "{{o}}"]
            }
        },
        "examplemodule": { // MODULE METHOD
            // Plugin activation.
            // By default, all plugins are disabled and disappear from the menu.
            "enable": false,

            // Auto formatting whenever the current file/view is being saved.
            // This option should be used for plugins with unique syntaxes.
            // For multi plugins with the same syntaxes, the first plugin takes precedence.
            // Remove the identical syntaxes from one of the plugins to avoid conflicts.
            // For example:
            // Plugin A (enabled): syntaxes ["css", "js"]
            // Plugin B (enabled): syntaxes ["html", "css"]
            // In the case you want to use Plugin B with "css", then you should remove
            // the "css" from plugin A or just disable it, as there is no guarantee of the
            // execution order between the two, and determining your favorist is not possible.
            // Solution: Use the "format_on_priority" option to workaround this.
            "format_on_save": false,

            // Auto formatting whenever code is pasted into the current file/view.
            // This option is affected by the same syntax conflict, so its solutions
            // are identical to those mentioned above for the "format_on_save" option.
            "format_on_paste": false,

            // Create a new file containing formatted codes.
            // The value of this option is the suffix of the new file being renamed.
            // Suffix must be of type string. =true, =false and all other types imply =false
            // Note: It will overwrite any existing file that has the same new name in
            // the same location.
            // For example:
            // "new_file_on_format": "min", will create a new file:
            // myfile.raw.js -> myfile.raw.min.js
            "new_file_on_format": false,

            // Recursively format the entire folder with unlimited depth.
            // This option requires an existing and currently opened file
            // to serve as the starting point. Files will be opened and closed.
            // For the sake of convenience, two new folders will be created at
            // the same level as the file, which will contain all failed and
            // successfully formatted files. The "new_file_on_format" option
            // can be used to rename files if needed.
            // The "format_on_save" option above, which applies only to
            // single files, does not take effect here.
            // All none-text files (binary) will be automatically ignored.
            // Note: Placing files directly on the Desktop or elsewhere without
            // enclosing them within a folder can lead to accidental formatting.
            // Any literal "$" must be escaped to "\\$" to distinguish it from
            // the variable expansion "${...}". This important rule applies
            // to the entire content of this settings file!
            "recursive_folder_format": {
                "enable": false,
                "exclude_folders_regex": ["Spotlight-V100", "temp", "cache", "logs", "^_.*foo\\$"],
                "exclude_files_regex": ["^._.*$", ".*bar.exe"],
                "exclude_extensions": ["DS_Store", "localized", "TemporaryItems", "Trashes", "db", "ini", "git", "svn", "tmp", "bak"],
                "exclude_syntaxes": []
            },

            // Syntax support based on the scope name, not file extension.
            // Syntax name is part of the scope name and can be retrieved from:
            // Tools > Developer > Show Scope Name
            // End-users are advised to consult plugin manpages to add more syntaxes.
            "syntaxes": ["css", "html", "js", "php"],

            // Exclude a list of syntaxes for an individual syntax key.
            // A list of excluded syntaxes can be applied to all syntax definitions.
            // In this case, the key must be named: "all".
            // This option is useful to exclude part of the scope selector.
            // For example: text.html.markdown, want html but wish to filter out html.markdown.
            "exclude_syntaxes": {
                "html": ["markdown"],
                "all": ["markdown"]
            },

            // Path to the interpreter to run the third-party plugin.
            // Just for the sake of completeness, but it is unlikely that you will ever need
            // to use this option. Most of the programs you have installed are usually set
            // to run in the global environment, such as Python, Node.js, Ruby, PHP, etc.
            // Formatter is able to detect and automatically set them for you.
            // However, if you do need to use a specific interpreter, you can provide the path.
            // Alternatively, you can set the basename as the interpreter name to search on
            // PATH or local, similar to how it is done with the "executable_path" option.
            "interpreter_path": ["${HOME}/example/path/to\\$my/java.exe"],

            // Path to the third-party plugin executable to process formatting.
            // This option can be either a string or a list of executable paths.
            // - If this option is omitted or set to null, then the global executable
            //   on PATH will be used, OR the local executable if automatically found.
            // - If this option is exactly the basename, then it will be used as the
            //   executable name and searched for on the PATH.
            //   Basename can be with or without dot.extension as both variants are the same.
            //   For example: "fiLe.exe" (Windows only), "fiLe" (Windows + Unix + Linux)
            // System variable expansions like ${HOME}, ${USER} etc. and the Sublime Text
            // specific ${packages} can be used to assign paths.
            // Note: Again, any literal "$" must be escaped to "\\$" to distinguish
            // it from the variable expansion "${...}".
            "executable_path": ["${HOME}/example/path/to\\$my/php-cs-fixer.phar"],

            // Path to the config file for each individual syntaxes.
            // Syntax keys must match those in the "syntaxes" option above.
            // A single config file can be used to assign to all syntaxes.
            // In this case, the key must be named: "default"
            // Note:
            // - You can choose another config file format as the default one
            //   provided by Formatter if the third-party plugin supports it.
            // - Formatter provides a set of default config files under
            //   "formatter.assets/config" folder for your personal use.
            //   Do not use the reference files with suffix '.master.' directly.
            //   These files could be overwritten by any release updates.
            // - Options from this config file always have precedence over
            //   the options from any local project (per-project config dotfile).
            // - Disabling this option will force Formatter to auto resolve
            //   the per-project config dotfile in the file tree to use.
            // To disable this option:
            // 1. Set the config path of this option to null, OR
            // 2. Use the Quick Options: Ignore Config Path, OR
            // 3. Place an '.sublimeformatter.cfgignore.json' file inside
            //    the working root folder. The structure of this file is
            //    descripted in README.md > Auto-detect Formatting
            // Formatter will start to search up the file tree until a
            // '.sublimeformatter.cfgignore' file is found to bypass this option.
            "config_path": {
                "css": "${packages}/User/formatter.assets/config/only_css_rc.json",
                "php": "${packages}/User/formatter.assets/config/only_php_rc.json",
                "default": "${packages}/User/formatter.assets/config/css_plus_js_plus_php_rc.json"
            },

            // Array of additional arguments for the command line.
            "args": ["--basedir", "./example/my/foo", "--show-bar", "yes"],

            // This option is specifically designed for type graphic.
            // It enables SVG image generation for download.
            // Enable it if you need SVG image at the cost of processing time.
            // Unlike the generic method, this method only supports SVG generation.
            "render_extended": false,

            // Manipulate hardcoded command-line arguments.
            // This option allow you to modify hardcoded parameters, values and
            // their positions without digging into the source code.
            // This feature is primarily intended to temporarily fix bugs until
            // an official solution is implemented.
            // Note: Hardcoded args can be changed (rarely) by any release updates.
            // Enable debug mode will help to find all current hardcoded args.
            // Use "args" option above to add, this option to remove or manipulate.
            // Using regex: Again, any literal "$" must be escaped to "\\$" to
            // distinguish it from the variable expansion "${...}". Accepted args:
            // [search, [replace, [index, count, new position]]], where:
            // - search:   @type:str (regex)
            // - replace:  @type:str
            // - index:    @type:int (the number is known as a list index); required!
            // - count:    @type:int (the matching occurrences per index, 0 = all); required!
            // - position: @type:int (move old index pos. to new/old one, -1 = delete index); required!
            "fix_commands": [
                ["--autocorrect", "--autocorrect-all", 4, 0, 4], // no index pos change
                ["^.*?auto.*\\$", "--with", 4, 1, 5], // using escaped "\\$" regex, move index 4 to pos 5
                ["${packages}/to/old", "${packages}/to/new", 3, 0, 3], // variable expansion, no escaped "$"
                ["css", 5, 0, 7], // replace the value in index 5 with "css", move it to pos 7
                [3, 0, 4], // just move index 3 to the new pos 4. (count 0 irrelevant)
                [2, 0, -1], // just delete the index 2. (count 0 irrelevant)
                ["--show-bar", "xxx", 2, 0, -1] // enough bar, pop it out. ("xxx", 2, 0 irrelevant)
            ]
        },
        // -- END of explanation --

        "stylelint": {  // EXAMPLE: MODULE METHOD
            "info": "https://github.com/stylelint/stylelint",
            "enable": true,
            "format_on_paste": false,
            "format_on_save": false,
            "new_file_on_format": false,
            "recursive_folder_format": {
                "enable": false,
                "exclude_folders_regex": ["Spotlight-V100", "temp", "cache", "logs", "^_.*foo\\$"],
                "exclude_files_regex": ["^._.*$", ".*bar.exe"],
                "exclude_extensions": ["DS_Store", "localized", "TemporaryItems", "Trashes", "db", "ini", "git", "svn", "tmp", "bak"],
                "exclude_syntaxes": []
            },
            "syntaxes": ["css", "scss", "sass", "less", "sss", "sugarss"],
            "executable_path": ["${packages}/User/myjs/node_modules/.bin/stylelint"],
            "args": ["--config-basedir", "/path/to/js/node_modules"],
            "config_path": {
                "default": "${packages}/User/formatter.assets/config/stylelint_rc.json"
            }
        },
        "uncrustify": {  // EXAMPLE: GENERIC METHOD: Text-to-Text. Restart ST.
            "name": "Uncrustify",
            "type": "beautifier",
            "success_code": 0,
            "args": ["{{e}}", " --style=file:{{c}} ", "--"],

            "info": "https://github.com/uncrustify/uncrustify",
            "enable": true,
            "format_on_save": false,
            // "new_file_on_format": false, // Add this, if needed
            // "recursive_folder_format": {...} // Add this, if needed
            "syntaxes": ["c", "c++", "cs", "objc", "objc++", "d", "java", "pawn", "vala"],
            "executable_path": ["${HOME}/path/to/bin/uncrustify"],
            "config_path": {
                "objc": "${packages}/User/formatter.assets/config/uncrustify_objc_rc.cfg",
                "objc++": "${packages}/User/formatter.assets/config/uncrustify_objc_rc.cfg",
                "java": "${packages}/User/formatter.assets/config/uncrustify_sun_java_rc.cfg",
                "default": "${packages}/User/formatter.assets/config/uncrustify_rc.cfg"
            }
        },
        "d2": {  // EXAMPLE: GENERIC METHOD: Text-to-Image. Restart ST.
          "name": "D2",
          "type": "graphic",
          "success_code": 0,
          "render_extended": true,

          "info": "https://github.com/terrastruct/d2",
          "enable": true,
          "format_on_save": false,
          "format_on_paste": false,
          "syntaxes": ["d2"],
          "args": ["{{e}}", "--theme", "300", "--dark-theme", "200", "-l", "elk", "--pad", "0", "-", "{{o}}"],
          "args_extended": {
              "svg": ["{{e}}", "--theme", "300", "--dark-theme", "200", "-l", "elk", "--pad", "0", "-", "{{o}}"],
              "pdf": ["{{e}}", "--theme", "300", "--dark-theme", "200", "-l", "elk", "--pad", "0", "-", "{{o}}"]
          },
          "executable_path": "/path/to/bin/d2",
          "config_path": {
              "default": "${packages}/User/formatter.assets/config/d2_rc.yaml"
          }
        },
        ...
    }
}

Auto-detect Formatting

Starting from version 1.4.0, Formatter introduces a configuration mechanism to auto-detect formatter for itself (Special thanks to @midrare for ideas, tests and suggestions). There are 2 methods to achieve this:

  • Using embedded settings in your User Formatter.sublime-settings
  • Placing dot files inside the working folder, similar to per-project basis.

Formatter will start to search up the file tree inside the working folder until a following file is found: .sublimeformatter.json OR .sublimeformatter

.sublimeformatter.json

{
    // Comments are allowed.
    "json": {
        "uid": "jsbeautifier"
    },
    "html": {
        "uid": "jsbeautifier",
        "exclude_syntaxes": {
            "html": ["markdown"]
        }
    },
    "python": {
        "uid": "autopep8"
    }
}

User-specific config options can be set using .sublimeformatter.user.json OR .sublimeformatter-user

.sublimeformatter.user.json

{
    "format_on_save": true,
    "format_on_paste": false
}

To ignore a specific syntax assigned to your User's "config_path": settings, you can use .sublimeformatter.cfgignore.json OR .sublimeformatter.cfgignore
For example, if you prefer to use the standard .prettierrc in your working folder instead of the custom Formatter "config_path":

.sublimeformatter.cfgignore.json

{
    "json": ["jsbeautifier", "deno"],
    "python": ["autopep8"],
    "default": ["scalafmt", "stylelint"]
}

Alternatively, you can embed your auto-detect config within your User Formatter.sublime-settings. In cases where both the dot files and embedded methods coexist, then the config from dot files will take precedence over the embedded one.

Formatter.sublime-settings

{
    "debug": "status",

    "auto_format": {
        "config": {
            "format_on_save": false,
            "format_on_paste": false
        },
        "json": {
            "uid": "jsbeautifier"
        },
        "html": {
            "uid": "jsbeautifier",
            "exclude_syntaxes": {
                "html": ["markdown"]
            }
        },
        "python": {
            "uid": "autopep8"
        }
    },

    "formatters": {}
}

This is a one-command/one-keybinding feature. Both the app and context menu will now indicate whether a current folder is ready for Formatter with a new item: Auto Format File

Per-project Formatting

Formatter is able to add and override any setting on per-project basis using .sublime-project files.
You might want to restart Sublime Text to apply the changes to the .sublime-project file.

.sublime-project

{
    "folders": [
        {
            "path": "/path/to/my/project"
        }
    ],

    "settings": {
        "Formatter": {
            "debug": "status",
            "formatters": {
                "htmltidy": {
                    "format_on_save": true
                },
                "jsbeautifier": {
                    "config_path": {
                        "default": "${HOME}/path/to/new/jsbeautify_rc.json"
                    }
                }
            }
        }
    }
}

Usage

Formatter has been designed to detect the syntax of files according to file scopes, not file extension. In the most cases, Sublime Text already does this job for you when you open a file. For the rest, you must explicit assign the syntax via the syntax menu in the righ-hand bottom corner or via:

Sublime Text > View > Syntax

Setting wrong syntax when formatting code will cause error:

Syntax out of the scope.

Formatting actions can be triggered in different ways:

  • Tools > Command Palette (Cmd+Shift+P or Ctrl+Shift+P) and type Formatter.
  • Tools > Formatter
  • Right-click > Context-Menu > Formatter
  • Preferences > Package Settings > Formatter > Key Bindings

The Quick Options

This feature is designed to help users quickly access and switch between options, without the need to navigate the Settings file. It comprises 3 modes:

  • Temporary Quick Options (TQO): By default, all options are temporary and only take effect during the current Sublime session. They will be automatically reset when you close Sublime.
  • Persistent User Settings (PUS): Clicking the Reset option will reset all current Temporary Quick Options and switch to using your User Settings from Formatter.sublime-settings.
  • Persistent Quick Options (PQO): Clicking the Save option will make all current Temporary Quick Options persistently. This means that closing and reopening Sublime will retain these options. To exit this mode just clicking the Reset option.

Summary:

  • The Reset option is the exclusive method to exit any mode.
  • Clicking on the same selected item will remove it from the list.
  • None of the modes will ever modify your Settings file.
  • The current mode is indicated on the status bar for your reference.

Development:

Starting from version 1.0.6, you now are able to create your own module for a third-party plugin that hasn't yet been integrated into Formatter. This allows you to extend your individual needs. In theory, you can use Formatter as a platform to convert any form of text, as long as third-party plugins operate in a text-to-text manner, such as Text-to-QR code, text-to-ASCII image conversion.

1. Prerequisite:

  1. Create a config file specific to your third-party plugin if needed. Config files for third-party plugins must be placed in the following folder:

    Formatter > config
    
  2. Activate the debug mode with the secret key dev in your Formatter settings. The dev key should never be used in a production environment.

Formatter.sublime-settings

{
    "debug": true,  // controls printing error messages
    "dev": true     // controls modules reloading to update modified files
    ...
}

2. Creating a module:

Developing a module for Formatter is straightforward. All you need to do is creating a python file with just a few lines of code as below:

  1. Create a file with the file name pattern formatter_thisismyfirstpluginmodule.py inside the Formatter > modules folder. Ensure to follow these conventions:
  • Create only one file per plugin in the Formatter > modules folder:
    • All functions and other necessary components should reside inside this file.
  • The file name is all lowercase and contains only alphanumeric characters (no spaces or underscores):
    • Prefix: formatter_ (indicating that it's a module for a third-party plugin)
    • Suffix: thisismyfirstpluginmodule (serving as the unique Formatter ID, also known as uid)
    • Extension: .py
  • External libraries that the third-party plugin relies on should be placed in the folder: Formatter > libs
    • Libraries must not contain proprietary elements, including the LICENSE file or license notices.
    • No communication over the Internet.
  1. The content of this module file should follow the structure outlined below:

formatter_thisismyfirstpluginmodule.py

INTERPRETERS = []                                           # optional: fallback list of interpreter names
EXECUTABLES = []                                            # REQUIRED: fallback list of executable names
DOTFILES = []                                               # optional: names list of the per-project config dotfiles
MODULE_CONFIG = {}                                          # REQUIRED: template to create several sublime config files

class ThisismyfirstpluginmoduleFormatter(common.Module):    # REQUIRED: the Capitalized of uid and the Capitalized word "Formatter", nothing else!
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)                   # REQUIRED: initialize the module APIs from common.Module

    def get_cmd(self):                                      # optional: get commands, e.g get the "config_path", "executable_path" etc...

    def format(self):                                       # REQUIRED: the entry point, predefined function name exact as written

Details as an example:

import logging                                              # REQUIRED: logging system for debugging this file
from ..core import common                                   # REQUIRED: a collection of APIs to assist in running this file

log = logging.getLogger(__name__)                           # REQUIRED: logger setup
INTERPRETERS = ['node']                                     # optional: case-sensitive fallback names (without extension) if interpreter is not found
EXECUTABLES = ['terser']                                    # optional: case-sensitive fallback names (without extension) if executable is not found
DOTFILES = ['.terser.json']                                 # optional: to auto-resolve the per-project config dotfile if "config_path" is disabled
MODULE_CONFIG = {                                           # REQUIRED: template to create several sublime config files
    'source': 'https://thirdparty-plugin.com',              # REQUIRED: info on where the user can download the plugin
    'name': 'My First Plugin',                              # REQUIRED: a Capitalized plugin name of your choice, preferably short and comprehensive
    'uid': 'thisismyfirstpluginmodule',                     # REQUIRED: must match the suffix of "formatter_thisismyfirstpluginmodule.py"
    'type': 'minifier',                                     # REQUIRED: "beautifier" OR "minifier" OR "converter" OR "graphic",
                                                            #           OR any string of your choice (for private purposes).
    'syntaxes': ['js', 'html'],                             # REQUIRED: array of syntaxes, obtained from: Tools > Developer > Show Scope Name
    'exclude_syntaxes': {                                   # optional: blacklist syntaxes per syntax or None to omit it.
        'html': ['markdown']
    },
    "interpreter_path": ["/path/to/bin/node"],              # optional: use an empty string "" to include this key in config files or None to omit it
    "executable_path": ["/path/to/bin/terser"],             # optional: use an empty string "" to include this key in config files or None to omit it
    'args': None,                                           # optional: an array ['arg1', 'args2', ...] to include this key in config files or None to omit it
    'config_path': {                                        # optional: a dictionary to include this key in config files or None to omit it
        'js': 'my_first_plugin_js_rc.json'                  # optional: a key-value pair or just omit it. See Formatter.sublime-settings for explanation
        'default': 'my_first_plugin_rc.json'                # optional: a key-value pair or just omit it. See Formatter.sublime-settings for explanation
    },
    'comment': 'build-in, no executable'                    # optional: a single short comment, limited to 200 chars or just omit it
}


class ThisismyfirstpluginmoduleFormatter(common.Module):    # REQUIRED: the Capitalized of uid and the Capitalized word "Formatter", nothing else!
    def __init__(self, *args, **kwargs):                    # REQUIRED: initialization
        super().__init__(*args, **kwargs)                   # REQUIRED: initialize the module APIs from common.Module

    def get_cmd(self):                                      # optional: get commands e.g get the "config_path", "executable_path" etc...
        cmd = self.get_combo_cmd(runtime_type='node')       # See API below
        if not cmd:
            return None

        path = self.get_config_path()                       # See API below
        if path:
            cmd.extend(['--config-file', path])             # an array of args to run the third-party plugin

        cmd.extend(['--compress', '--mangle', '--'])

        # cmd.extend(['--output', self.get_output_image()]) # REQUIRED: only for special case of "type": "graphic"

        log.debug('Command: %s', cmd)                       # REQUIRED: to debug the input command
        cmd = self.fix_cmd(cmd)                             # REQUIRED: to finally process the "fix_commands" option, just right before the return

        return cmd

    def format(self):                                       # REQUIRED: the entry point, predefined function name exact as written
        cmd = self.get_cmd()
        if not self.is_valid_cmd(cmd):                      # REQUIRED: is command ok?
            return None

        try:
            exitcode, stdout, stderr = self.exec_cmd(cmd)   # REQUIRED: process command

            if exitcode > 0:                                # REQUIRED: please consult the plugin documentation for the exit codes
                self.print_exiterr(exitcode, stderr)
            else:
                # if self.is_render_extended():             # is render extended mode activated?
                #     cmd = self.all_png_to_svg_cmd(cmd)
                #     try:
                #         self.exec_cmd(cmd)                # REQUIRED: only for special case of "type": "graphic" to generate SVG image.
                #     except Exception as e:
                #         log.error('Error: %s', e)

                return stdout                               # REQUIRED: return the formatted code on success
        except OSError:
            self.print_oserr(cmd)

        return None                                         # REQUIRED: return None to indicate failure

That's all. Happy coding o_O

Restart Sublime Text.
New keys will be automatically created in the Default settings.
Do not forget to update/adjust your User settings:
Preferences > Package Settings > Formatter > Settings

3. Integrating modules:

You have the choice to either submit a pull request or integrate your modules yourself using:

Formatter.sublime-settings

"custom_modules": {
        "config": ["/path/to/foo_rc.json", "/path/to/bar_rc.cfg"],
        "modules": ["/path/to/formatter_foo.py", "/path/to/formatter_bar.py"],
        "libs": ["/path/to/foolib", "/path/to/mylib"]
    },

4. API:

The entire set of Formatter API can be found in the file: core > common.py
Responsible for handling plugin modules is the class: class Module(object):

  • Essentially for the def get_cmd(self) function:
# This alias method combines get_interpreter() and get_executable().
# Set runtime_type=(None|'node'|'python'|'perl'|'ruby') to enable local executable search.
# Currently, only None and 'node' are functional. All others are placeholders for future use.
cmd = self.get_iprexe_cmd(runtime_type=None)

# This alias method just extends get_iprexe_cmd() with get_args().
cmd = self.get_combo_cmd(runtime_type=None)

# Get the interpreter path or None.
interpreter = self.get_interpreter()

# Get the executable path or None.
# Set runtime_type=(None|'node'|'python'|'perl'|'ruby') to enable local executable search.
executable = self.get_executable(runtime_type=None)

# Get the input arguments "args" from the User settings or None.
args = self.get_args()

# Get the input "config_path" from the User settings or
# the path of the per-project config dotfile if found or None.
path = self.get_config_path()

# Get the current text content in view or the current selected text.
text = self.get_text_from_region(self.region)

# Get the detected syntax of the current file or None.
syntax = self.get_assigned_syntax()

# Get the path to the output PNG image. Applicable only to the special case of type: graphic
output_image = self.get_output_image()

# Get a dictionary of file path components:
# {'path':, 'cwd':, 'base':, 'stem':, 'suffix':, 'ext':} or None.
components = self.get_pathinfo()

# Create and get the temp file path.
# Useful for plugins lacking a built-in mechanism to fix files inplace.
tmp_file = self.create_tmp_file(suffix=None)

# Remove temp file.
self.remove_tmp_file(tmp_file)

# To finally process the "fix_commands" option, just right before exec_cmd().
cmd = self.fix_cmd(cmd)
  • Essentially for the def format(self) function:
# To quickly test the command.
is_valid = self.is_valid_cmd(cmd)

# To replace cmd list items to generate SVG file for download.
# It is applicable only to the special case of type: graphic.
# Note: extended_cmd MUST be executed right before return stdout (=success)!
extended_cmd = self.ext_png_to_svg_cmd(cmd)  # replace extension .png -> .svg
extended_cmd = self.all_png_to_svg_cmd(cmd)  # replace all occurred png -> svg

# To process the formatting with all input (fixed) arguments.
# stdout as PIPE. 99% of plugins use this way.
exitcode, stdout, stderr = self.exec_cmd(cmd)

# stdout as file. 1% are just retarded.
exitcode, stdout, stderr = self.exec_cmd(cmd, outfile='/path/to/save/outfile')

# To print formatting exit error.
self.print_exiterr(exitcode, stderr)

# To print executing commands error.
self.print_oserr(cmd)

License

MIT