atom-beautify/docs/add-languages-and-beautifiers.md

Add Languages and Beautifiers

Please contribute with a Pull Request and add your favourite languages and beautifiers.

Source Code Documentation

Source code documentation can be found at http://glavin001.github.io/atom-beautify/docs/code/ You can use codo to build your own documentation. Simply run codo in the project's directory and it will be generated into docs/code/.

Options Documentation

After you make a change to language or beautifier options you will need to update the options.json file that is created on install.

# Update src/options.json file to have new/changed options
npm run postinstall
# Update documentation to include information about those options
npm run docs

How to add a Language:

1. Create a new Language file in https://github.com/Glavin001/atom-beautify/tree/master/src/languages
2. Configure the new language. Example for JavaScript language: https://github.com/Glavin001/atom-beautify/blob/master/src/languages/javascript.coffee#L8

• name - name of Language
• namespace - used as a prefix for scoping the options, such as option indent_size becomes js_indent_size for JavaScript language with namespace js
• grammars - array of supported grammars. Used with extensions to determine if this file is this language or not. Grammars are prioritized over extensions, such that the grammar JavaScript is recognized before js and the beautifier with the same grammar as the file will be used over another that does not support the grammar and only the extension.
• extensions - array of of extensions, without . (dot), such that .js is js. Used to determine if a file is this language. Useful if there is no supported grammar in Atom for this language.
• options - I'd recommend looking at https://github.com/Glavin001/atom-beautify/blob/master/src/languages/javascript.coffee#L30 for examples.

3. Add the language file to the list of language names. For instance, c-sharp.coffee file becomes c-sharp. See https://github.com/Glavin001/atom-beautify/blob/master/src/languages/index.coffee#L21 Now your Language is available and can be detected and beautifiers can support it.

How to add a Beautifier for a Language

1. Create a new beautifier subclass in https://github.com/Glavin001/atom-beautify/tree/master/src/beautifiers directory
2. Implement beautifier:

• See examples of beautifiers:
  • Prettydiff is a good example of complex options: https://github.com/Glavin001/atom-beautify/blob/master/src/beautifiers/prettydiff.coffee
  • PHP-CS-Fixer is a good example of a CLI beautifier with arguments: https://github.com/Glavin001/atom-beautify/blob/master/src/beautifiers/php-cs-fixer.coffee#L15-L39
• options - the key represents the Language's name. The value could be true (supports all options), false (supports language, with no options), or an object whose keys are option keys and values are complex mappings. If you need to use these, let me know. true is probably what you want.
• The beautify function should return a Promise (use @Promise as shown). The arguments passed are:
  • text - the source code from Atom's Text Editor
  • language - the language's name (JavaScript)
  • options - an object of all of the options in their form as described by your Language definition (see Configure the new language above).
  • context - an object with extra information:
    • filePath - The file path associated with the text being beautified (may be null)

3. Add beautifier to list of beautifierNames: https://github.com/Glavin001/atom-beautify/blob/master/src/beautifiers/index.coffee#L34
4. Add test example files in https://github.com/Glavin001/atom-beautify/tree/master/examples

• You can put your test in nested-jsbeautifyrc directory, https://github.com/Glavin001/atom-beautify/tree/master/examples/nested-jsbeautifyrc
• create a new directory for your tests, named something like JavaScript
• original and expected directory containing files that are named the same. Prefix underscore (_) disables a test. See https://github.com/Glavin001/atom-beautify/tree/master/examples/simple-jsbeautifyrc/php/original for instance.
• change any options you need in your namespace, such as js, in https://github.com/Glavin001/atom-beautify/blob/master/examples/nested-jsbeautifyrc/.jsbeautifyrc
• Run tests in Atom with command Window: Run package spec

I have to go. Let me know if you have any questions!