valscion/plugin-ruby

Prettier Ruby Plugin

Prettier for Ruby

@prettier/plugin-ruby is a prettier plugin for the Ruby programming language and its ecosystem. prettier is an opinionated code formatter that supports multiple languages and integrates with most editors. The idea is to eliminate discussions of style in code review and allow developers to get back to thinking about code design instead.

For example, the below code segment:

        d=[30644250780,9003106878,
    30636278846,66641217692,4501790980,
 671_24_603036,131_61973916,66_606629_920,
   30642677916,30643069058];a,s=[],$*[0]
      s.each_byte{|b|a<<("%036b"%d[b.
         chr.to_i]).scan(/\d{6}/)}
          a.transpose.each{ |a|
            a.join.each_byte{\
             |i|print i==49?\
               ($*[1]||"#")\
                 :32.chr}
                   puts
                    }

when run through @prettier/plugin-ruby will generate:

d = [
  30_644_250_780,
  9_003_106_878,
  30_636_278_846,
  66_641_217_692,
  4_501_790_980,
  671_24_603036,
  131_61973916,
  66_606629_920,
  30_642_677_916,
  30_643_069_058
]
a, s = [], $*[0]
s.each_byte { |b| a << ('%036b' % d[b.chr.to_i]).scan(/\d{6}/) }
a.transpose.each do |a|
  a.join.each_byte { |i| print i == 49 ? ($*[1] || '#') : 32.chr }
  puts
end

Getting started

To run prettier with the Ruby plugin, you're going to need ruby (version 2.5 or newer) and node (version 8.3 or newer). If you're integrating with a project that is not already using prettier, you should use the Ruby gem. Otherwise you can use the npm package directly.

Note that currently the editor integrations work best with the npm package, as most of the major editor plugins expect a node_modules directory. You can get them to work with the Ruby gem, but it requires manually configuring the paths.

This plugin currently supports formatting the following kinds of files:

• All varieties of Ruby source files (e.g., *.rb, *.gemspec, Gemfile, etc.)
• RBS type language files - requires having the rbs gem in your gem path
• HAML template language files - requires having the haml gem in your gem path

Ruby gem

Add this line to your application's Gemfile:

gem 'prettier'

And then execute:

bundle

Or install it yourself as:

gem install prettier

The rbprettier executable is now installed and ready for use:

bundle exec rbprettier --write '**/*'

npm package

If you're using the npm CLI, then add the plugin by:

npm install --save-dev prettier @prettier/plugin-ruby

Or if you're using yarn, then add the plugin by:

yarn add --dev prettier @prettier/plugin-ruby

The prettier executable is now installed and ready for use:

./node_modules/.bin/prettier --write '**/*'

Configuration

Below are the options (from src/plugin.js) that @prettier/plugin-ruby currently supports:

API Option	CLI Option	Default	Description
printWidth	--print-width	80	Same as in Prettier (see prettier docs).
requirePragma	--require-pragma	false	Same as in Prettier (see prettier docs).
rubyArrayLiteral	--ruby-array-literal	true	When possible, favor the use of string and symbol array literals.
rubyHashLabel	--ruby-hash-label	true	When possible, uses the shortened hash key syntax, as opposed to hash rockets.
rubyModifier	--ruby-modifier	true	When it fits on one line, allows while and until statements to use the modifier form.
rubySingleQuote	--ruby-single-quote	true	When double quotes are not necessary for interpolation, prefers the use of single quotes for string literals.
rubyToProc	--ruby-to-proc	false	When possible, convert blocks to the more concise Symbol#to_proc syntax.
tabWidth	--tab-width	2	Same as in Prettier (see prettier docs).
trailingComma	--trailing-comma	"none"	Same as in Prettier (see prettier docs). "es5" is equivalent to true.

Any of these can be added to your existing prettier configuration file. For example:

{
  "rubySingleQuote": false
}

Or, they can be passed to prettier as arguments:

bundle exec rbprettier --ruby-single-quote false --write '**/*'

Usage with RuboCop

RuboCop and Prettier for Ruby serve different purposes, but there is overlap with some of RuboCop's functionality.

Prettier provides a RuboCop configuration file to disable the rules which clash. To enable, add the following config at the top of your project's .rubocop.yml:

Ruby gem

inherit_gem:
  prettier: rubocop.yml

npm package

inherit_from:
  - node_modules/@prettier/plugin-ruby/rubocop.yml

Usage with an editor

For supported editor integrations, you should follow the instructions for installing the integration, then install the npm version of this plugin as a development dependency of your project. For most integrations, that should be sufficient. For convenience, the instructions for integrating with VSCode are used as an example below:

• Install the Prettier - Code Formatter extension.
• Add the npm @prettier/plugin-ruby package to your project as described above.
• Configure in your settings.json (formatOnSave is optional):

{
  "[ruby]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  }
}

Refer to this issue if you're having difficulties.

Contributing

Check out our contributing guide. Bug reports and pull requests are welcome on GitHub at https://github.com/prettier/plugin-ruby.

You can support prettier/plugin-ruby on OpenCollective. Your organization's logo will show up here with a link to your website.

License

The package is available as open source under the terms of the MIT License.