Permalink
Browse files

Move the interactor shorthand alias examples to the README.

 We should try to avoid to much noise from Guard about a specific
 preferred setup.

 Thanks @rking for https://gist.github.com/da7f4b2f8465a3d75cd4
  • Loading branch information...
1 parent 2cf660a commit 707a1b0b25ee6ab19be48346405059c63bef2c81 @netzpirat netzpirat committed Sep 26, 2012
Showing with 19 additions and 11 deletions.
  1. +16 −0 README.md
  2. +3 −11 lib/guard/interactor.rb
View
@@ -445,11 +445,27 @@ to your `Gemfile.
You can also disable the interactions completely by running Guard with the `--no-interactions` option.
+### Customizations
+
Further Guard specific customizations can be made in `~/.guardrc` that will be evaluated prior the Pry session is
started. This allows you to make use of the Pry plugin architecture to provide custom commands and extend Guard for
your own needs and distribute as a gem. Please have a look at the [Pry Wiki](https://github.com/pry/pry/wiki) for more
information.
+#### Shorthand commands
+
+If you like to have shorthand commands for the built in Guard commands, you can define aliases in your `~/.guardrc`
+file like this:
+
+```Ruby
+%w(help reload change show notification pause exit).each do |command|
+ Pry.commands.alias_command command[0].chr, command
+end
+Pry.commands.block_command /^$/, 'Hit Enter to run all tests' do
+ Pry.run_command 'all'
+end
+```
+
### Signals
You can also interact with Guard by sending POSIX signals to the Guard process (all but Windows and JRuby).
View
@@ -24,23 +24,15 @@ def initialize
Pry.config.history.file = HISTORY_FILE
Pry.config.hooks.add_hook :when_started, :load_guard_rc do
- if File.exist? File.expand_path GUARD_RC
- load GUARD_RC
- else
- example_guard_rc_url = 'https://gist.github.com/da7f4b2f8465a3d75cd4'
- Pry.output.puts <<-EOT
-- No ~/.guardrc found, so commands will be more verbose.
-(See tersifying example at #{example_guard_rc_url} )
- EOT
- end
+ load GUARD_RC if File.exist? File.expand_path GUARD_RC
end
Pry.config.prompt = [
proc do |target_self, nest_level, pry|
- "[#{pry.input_array.size}] #{ ::Guard.listener.paused? ? 'pause' : 'guard' }(#{Pry.view_clip(target_self)})#{":#{nest_level}" unless nest_level.zero?}> "
+ "[#{ pry.input_array.size }] #{ ::Guard.listener.paused? ? 'pause' : 'guard' }(#{ Pry.view_clip(target_self) })#{":#{ nest_level }" unless nest_level.zero? }> "
end,
proc do |target_self, nest_level, pry|
- "[#{pry.input_array.size}] #{ ::Guard.listener.paused? ? 'pause' : 'guard' }(#{Pry.view_clip(target_self)})#{":#{nest_level}" unless nest_level.zero?}* "
+ "[#{ pry.input_array.size }] #{ ::Guard.listener.paused? ? 'pause' : 'guard' }(#{ Pry.view_clip(target_self) })#{":#{ nest_level }" unless nest_level.zero? }* "
end
]
end

4 comments on commit 707a1b0

The reason I made that output show interactively is because I think the users that are used to the short commands are going to get this version and be puzzled about what happened.

Contributor

netzpirat replied Sep 27, 2012

Yes, I understand that reason and I think we're not at the end of the discussion how to solve it in the best way for Guard users. What I can say from my time as Guard maintainer is, that many people don't like verbose messages that acts as guardian for something. We've discussed many Guard messages (bundler, deprecations, etc.) over and over on the issue tracker.

I'm thinking of making the shorthand commands enabled by default and either provide information in the README on how to unalias the shorthand commands or even better, provide a command to enable/disable the aliases. This would give "normal" users the known behavior of the interactor, but would allow "power" users to switch them off for a debug session. Another solution that comes to mind would be that guard init installs a default ~/.guardrc, but this would not catch existing users with existing projects.

I'd like to hear your thought on this.

Upgrade Experience

I think the basic user impression of the new interactor is merely that it has a funky prompt. Everything else should be smooth and familiar.

So, yes, I advocate having the default commands be there.

Commands vs. Code Conflict

In general, with Pry, you have this competition between wanting short commands and wanting to be able to express Ruby. If a command parse succeeds on a line, that line is considered a command, not a line to eval. There are a few things that mitigate this problem for the Guard interactor case:

  1. The interactor pry prompt doesn't load your system's code, so it's not like it doubles as a rails c. Therefore, though it's handy to sketch out bits of Ruby, it's not trying to be the projects main REPL.
  2. You can still get the Pry parser to give you your eval by making slightly more complex input. So if there's an r command and variable both, you can still see the variable with something like ;r. This is maybe a bit unintuitive, but I think most users can figure it out (or do x = r and examine x instead).

Unaliasing/uncommanding is definitely possible

E.g. look at the ,, toggle command

For this case, though, I don't know if people will want that.

It would probably be best to just have a "don't add the commands" line for
~/.guardrc's.

By the way

Have you used pry-rescue like this (or plymouth) to automatically REPL upon test failures?

It's superawesome. IMO it's the way of the future. But there are some guard-related issues that need to be hammered out, I guess on a separate Issue.

The foremost of which is, when you have a pry prompt sitting there on a failing test, then you edit the files, at that point Guard is inactive, so you have to manually switch back to that pry and manually ^d it, then after that maybe Guard does the right thing. It's actually a pretty busted process at this point.

But it's a related topic, so I'm starting the question here.

Contributor

netzpirat replied Sep 28, 2012

I think the basic user impression of the new interactor is merely that it has a funky prompt.

That made me smile, it's so true.

Everything else should be smooth and familiar. ... it's not trying to be the projects main REPL

Again, you hit the nail on its head. Guard adds now the aliases by default and creates commands to run all of a single group or a plugin. So the user experience is the same as before.

I really like to play with pry-rescue, but I currently work mostly on the frontend with CoffeeScript and guard-jasmine. But time will change that again... But anyway, start/stop Pry in a thread is currently very unreliable and needs some more work to make it a smooth experience.

Please sign in to comment.