Skip to content

Commit

Permalink
Polish the README.
Browse files Browse the repository at this point in the history 
* Enable colored code snippets
* prefix console commands with $
* Add Google group and IRC channel
* Surround Guard RegEx with ^ and $
* Enhanced options section
  • Loading branch information
@netzpirat
netzpirat committed Jun 10, 2011
1 parent 6200a2f commit be2e97a
Showing 1 changed file with 84 additions and 39 deletions.
123 changes: 84 additions & 39 deletions README.md
View file
Expand Up @@ -6,26 +6,34 @@ Guard::CoffeeScript compiles you CoffeeScripts automatically when files are modi

Tested on MRI Ruby 1.8.7, 1.9.2 and the latest versions of JRuby & Rubinius.

If you have any questions please join us on our [Google group](http://groups.google.com/group/guard-dev) or on `#guard` (irc.freenode.net).

## Install

Please be sure to have [Guard](https://github.com/guard/guard) installed before continue.
Please be sure to have [Guard](https://github.com/guard/guard) installed.

Install the gem:

gem install guard-coffeescript
```bash
$ gem install guard-coffeescript
```

Add it to your `Gemfile`, preferably inside the development group:

gem 'guard-coffeescript'
```ruby
gem 'guard-coffeescript'
```

Add guard definition to your `Guardfile` by running this command:

guard init coffeescript
```bash
$ guard init coffeescript
```

## JSON

The JSON library is also required but is not explicitly stated as a gem dependency. If you're on Ruby 1.8 you'll need
to install the json or json_pure gem. On Ruby 1.9, JSON is included in the standard library.
to install the `json` or `json_pure` gem. On Ruby 1.9, JSON is included in the standard library.

## CoffeeScript

Expand All @@ -44,20 +52,24 @@ JavaScript Core is packaged with Mac OS X.

### V8

To use CoffeeScript on V8, simple add `therubyracer` to your Gemfile. The Ruby Racer acts as a bridge between Ruby
To use CoffeeScript on V8, simple add `therubyracer` to your `Gemfile`. The Ruby Racer acts as a bridge between Ruby
and the V8 engine, that will be automatically installed by the Ruby Racer.

group :development do
gem 'therubyracer'
end
```ruby
group :development do
gem 'therubyracer'
end
```

### Mozilla Rhino

If you're using JRuby, you can embed the Mozilla Rhino runtime by adding `therubyrhino` to your Gemfile:
If you're using JRuby, you can embed the Mozilla Rhino runtime by adding `therubyrhino` to your `Gemfile`:

group :development do
gem 'therubyrhino'
end
```ruby
group :development do
gem 'therubyrhino'
end
```

### Microsoft Windows Script Host

Expand All @@ -79,87 +91,120 @@ and you don't have to specify a watch regular expression.

### Standard Ruby gem

guard 'coffeescript', :input => 'coffeescripts', :output => 'javascripts'
```ruby
guard 'coffeescript', :input => 'coffeescripts', :output => 'javascripts'
```

### Rails 3.1 app

guard 'coffeescript', :input => 'app/assets/javascripts'
```ruby
guard 'coffeescript', :input => 'app/assets/javascripts'
```

## Options

There following options can be passed to Guard::CoffeeScript:

:input => 'coffeescripts' # Relative path to the input directory, default: nil
:output => 'javascripts' # Relative path to the output directory, default: input directory
:bare => true # Compile without the top-level function wrapper, default: false
:shallow => true # Do not create nested output directories, default: false
:hide_success => true # Disable successful compilation messages, default: false
```ruby
:input => 'coffeescripts' # Relative path to the input directory
# default: nil

:output => 'javascripts' # Relative path to the output directory
# default: the path given with the :input option

:bare => true # Compile without the top-level function wrapper
# default: false

:shallow => true # Do not create nested output directories
# default: false

:hide_success => true # Disable successful compilation messages
# default: false
```

### Nested directories

The guard detects by default nested directories and creates these within the output directory. The detection is based on the match
The Guard detects by default nested directories and creates these within the output directory. The detection is based on the match
of the watch regular expression:

A file

/app/coffeescripts/ui/buttons/toggle_button.coffee
```bash
/app/coffeescripts/ui/buttons/toggle_button.coffee
```

that has been detected by the watch

watch(%r{app/coffeescripts/(.+\.coffee)})
```ruby
watch(%r{^app/coffeescripts/(.+\.coffee)$})
```

with an output directory of

:output => 'public/javascripts/compiled'
```ruby
:output => 'public/javascripts/compiled'
```

will be compiled to

public/javascripts/compiled/ui/buttons/toggle_button.js
```bash
public/javascripts/compiled/ui/buttons/toggle_button.js
```

Note the parenthesis around the `.+\.coffee`. This enables Guard::CoffeeScript to place the full path that was matched inside the
parenthesis into the proper output directory.

This behavior can be switched off by passing the option `:shallow => true` to the guard, so that all JavaScripts will be compiled
This behavior can be switched off by passing the option `:shallow => true` to the Guard, so that all JavaScripts will be compiled
directly to the output directory.

### Multiple source directories

The Guard short notation

guard 'coffeescript', :input => 'app/coffeescripts', :output => 'public/javascripts/compiled'
```ruby
guard 'coffeescript', :input => 'app/coffeescripts', :output => 'public/javascripts/compiled'
```

will be internally converted into the standard notation by adding `(.+\.coffee)` to the `input` option string and create a Watcher
that is equivalent to:

guard 'coffeescript', :output => 'public/javascripts/compiled' do
watch(%r{app/coffeescripts/(.+\.coffee)})
end
```ruby
guard 'coffeescript', :output => 'public/javascripts/compiled' do
watch(%r{^app/coffeescripts/(.+\.coffee)$})
end
```

To add a second source directory that will be compiled to the same output directory, just add another watcher:

guard 'coffeescript', :input => 'app/coffeescripts', :output => 'public/javascripts/compiled' do
watch(%r{lib/coffeescripts/(.+\.coffee)})
end
```ruby
guard 'coffeescript', :input => 'app/coffeescripts', :output => 'public/javascripts/compiled' do
watch(%r{lib/coffeescripts/(.+\.coffee)})
end
```

which is equivalent to:

guard 'coffeescript', :output => 'public/javascripts/compiled' do
watch(%r{app/coffeescripts/(.+\.coffee)})
watch(%r{lib/coffeescripts/(.+\.coffee)})
end
```ruby
guard 'coffeescript', :output => 'public/javascripts/compiled' do
watch(%r{app/coffeescripts/(.+\.coffee)})
watch(%r{lib/coffeescripts/(.+\.coffee)})
end
```

## Development

- Source hosted at [GitHub](https://github.com/netzpirat/guard-coffeescript)
- Report issues/Questions/Feature requests on [GitHub Issues](https://github.com/netzpirat/guard-coffeescript/issues)
- Report issues and feature requests on [GitHub Issues](https://github.com/netzpirat/guard-coffeescript/issues)

Pull requests are very welcome! Make sure your patches are well tested.

For questions please join us on our [Google group](http://groups.google.com/group/guard-dev) or on `#guard` (irc.freenode.net).

## Contributors

* [Aaron Jensen](https://github.com/aaronjensen)
* [Patrick Ewing](https://github.com/hoverbird)
* [Andrew Assarattanakul](https://github.com/vizjerai)
* [Patrick Ewing](https://github.com/hoverbird)

## Acknowledgment

Expand Down

0 comments on commit be2e97a

Please sign in to comment.