rails / thor

Thor is a toolkit for building powerful command-line interfaces.

Thor

Description

Thor is a simple and efficient tool for building self-documenting command line utilities. It removes the pain of parsing command line options, writing "USAGE:" banners, and can also be used as an alternative to the Rake build tool. The syntax is Rake-like, so it should be familiar to most Rake users.

Please note: Thor, by design, is a system tool created to allow seamless file and url access, which should not receive application user input. It relies on open-uri, which combined with application user input would provide a command injection attack vector.

Installation

gem install thor

Usage and documentation

Please see the wiki for basic usage and other documentation on using Thor. You can also checkout the official homepage.

Contributing

If you would like to help, please read the CONTRIBUTING file for suggestions.

License

Released under the MIT License. See the LICENSE file for further details.

thor's Issues

running specs in gem

Packaging thor for a Fedora submission and would like to run the specs as part of the build process. The stumbling block seems to be some key files are missing from the gem, eg:

mkent@fortaleza:~/git/thor/spec (master)$ find -type f | grep -v \.rb | grep -v sandbox
./fixtures/bundle/main.thor
./fixtures/doc/README
./fixtures/doc/components/.empty_directory
./fixtures/group.thor
./fixtures/invoke.thor
./fixtures/script.thor
./fixtures/task.thor
./spec.opts

Would it be possible to include these in the gem?

Thor ArgumentError spec's that accept InvocationError

The commit hedgehog/thor@b406cb6 is part of resolving #12.
This patch exposes two spec's that incorrectly accept InvocationError although they claim to expect ArgumentError.
After applying the patch cited, running thor spec's reveals:

ArgumentError in 'Thor::Runner#start does not swallow Thor ArgumentError'
'animal' was called incorrectly. Are you sure it has arity equals to 0?
/usr/src/thor/spec/runner_spec.rb:88:
/usr/src/thor/spec/spec_helper.rb:29:in `capture'
/usr/src/thor/spec/runner_spec.rb:88:

ArgumentError in 'Thor#start raises an error if a required param is not provided'
'animal' was called incorrectly. Are you sure it has arity equals to 0?
/usr/src/thor/spec/thor_spec.rb:115:
/usr/src/thor/spec/spec_helper.rb:29:in `capture'
/usr/src/thor/spec/thor_spec.rb:115:

run and in_root not working

example: http://gist.github.com/328329
Thor gem v 0.13.4

I'm trying to write some simple tasks with thor with no luck. See the above gist which tries to start and stop nginx. When I execute shell commands like cat #{nginx_pid_path} it works but when I try to use thor actions like run or in_root, I get errors (below). Why does action say() work, but run() does not?

: thor nginx:stop
/Users/jhancock/mhd/mhd.thor:17:in `stop': undefined method `run' for #<Thor::Sandbox::Nginx:0x7e675c> (NoMethodError)
from /usr/local/ruby-191-p243/lib/ruby/gems/1.9.1/gems/thor-0.13.4/lib/thor/task.rb:33:in `run'
from /usr/local/ruby-191-p243/lib/ruby/gems/1.9.1/gems/thor-0.13.4/lib/thor/invocation.rb:109:in `block in invoke'
from /usr/local/ruby-191-p243/lib/ruby/gems/1.9.1/gems/thor-0.13.4/lib/thor/invocation.rb:116:in `call'
from /usr/local/ruby-191-p243/lib/ruby/gems/1.9.1/gems/thor-0.13.4/lib/thor/invocation.rb:116:in `invoke'
from /usr/local/ruby-191-p243/lib/ruby/gems/1.9.1/gems/thor-0.13.4/lib/thor.rb:137:in `block in start'
from /usr/local/ruby-191-p243/lib/ruby/gems/1.9.1/gems/thor-0.13.4/lib/thor/base.rb:378:in `start'
from /usr/local/ruby-191-p243/lib/ruby/gems/1.9.1/gems/thor-0.13.4/lib/thor.rb:124:in `start'
from /usr/local/ruby-191-p243/lib/ruby/gems/1.9.1/gems/thor-0.13.4/lib/thor/runner.rb:34:in `method_missing'
from /usr/local/ruby-191-p243/lib/ruby/gems/1.9.1/gems/thor-0.13.4/lib/thor/task.rb:33:in `run'
from /usr/local/ruby-191-p243/lib/ruby/gems/1.9.1/gems/thor-0.13.4/lib/thor/task.rb:13:in `run'
from /usr/local/ruby-191-p243/lib/ruby/gems/1.9.1/gems/thor-0.13.4/lib/thor/invocation.rb:109:in `block in invoke'
from /usr/local/ruby-191-p243/lib/ruby/gems/1.9.1/gems/thor-0.13.4/lib/thor/invocation.rb:116:in `call'
from /usr/local/ruby-191-p243/lib/ruby/gems/1.9.1/gems/thor-0.13.4/lib/thor/invocation.rb:116:in `invoke'
from /usr/local/ruby-191-p243/lib/ruby/gems/1.9.1/gems/thor-0.13.4/lib/thor.rb:137:in `block in start'
from /usr/local/ruby-191-p243/lib/ruby/gems/1.9.1/gems/thor-0.13.4/lib/thor/base.rb:378:in `start'
from /usr/local/ruby-191-p243/lib/ruby/gems/1.9.1/gems/thor-0.13.4/lib/thor.rb:124:in `start'
from /usr/local/ruby-191-p243/lib/ruby/gems/1.9.1/gems/thor-0.13.4/bin/thor:6:in `<top (required)>'
from /usr/local/ruby/bin/thor:19:in `load'
from /usr/local/ruby/bin/thor:19:in `<main>'

Create better documentation.

Thor::Actions#apply fails for paths with spaces.

URI(path).is_a?(URI::HTTP) at lib/thor/actions.rb:198 is failing with paths like /Users/user/Projects/Project with Spaces/ as input with a URI::InvalidURIError: bad URI(is not URI?) exception.

Feature Request: brace expansion argument (bash style)

Add option:

:brace_expansion => true/false

to

argument()  # applies just to this argument

When true the following syntax is supported

thor task a{1..3} arg2 
# equivalent to 
thor task a1 a2 a3 arg2

Example behaviors

a{1..3}{x..z}          # a1x a1y a1z a2x a2y a2z a3x a3y a3z
a{{a..c},b{1..3}}     # aa ab ac ab1 ab2 ab3
\\{X..d}         # \X \Y \Z \[ \ \] \^ \_ \` \a \b \c \d
{1..3}{x..z}", "      # 1x, 1y, 1z, 2x, 2y, 2z, 3x, 3y, 3z

Other behaviors people think will be useful?

More importantly: Does anyone know of a ruby library that has already implemented this?

Broken in ruby 1.9.2

Thor does not work with ruby 1.9.2. It works fine on ruby 1.9.1 and 1.8.7.

ruby --version
ruby 1.9.2dev (2009-09-07 trunk 24787) [i386-darwin10.2.0]
thor
could not find Thor class or task 'help'

Arbitrary code execution

Hi!

I just noticed:

Thor allows the execution of arbitrary code via any Thorfile. Just run
thor instance_eval "p 12"
This will cause thor to call the "instance_eval task" of the Thor object in that Thorfile.
Pretty devastating...
I'd suggest, thor limits the access to builtin functions via tasks, e.g. by using something like this little snippet here I found a while ago:
[http://snippets.dzone.com/posts/show/1873]
That would remove all the 'evil' method calls from the thor object.

Greetz!

Thor::Runner needs to be improved

I created a thor task to generate a new thor task project and one to create a skeleton ruby project.
In both cases I have a templates dir with the template files for the template statement.
They both run fine locally, but when I install the gem, only the thor file itself seems to be installed, not its templates dir. This seems a reasonable default, but how do I then force thor to deploy other files/dirs as part of the thor task?
I think I might instead have to build a generator gem with binaries? Seems like thor is only suitable in the simplest cases?

errors when loading Thorfiles do not include stacktrace

Whenever errors/exceptions are encountered, only the error's type and message are displayed, excluding any sort of line information. For example, I had an uninitialized constant because I forgot to do a require, and I get this message:

WARNING: unable to load thorfile "/Users/technicalpickles/code/active/bedazzle/Thorfile": uninitialized constant Bedazzle::Build

I probably figure out this one just by looking at the code in Thorfile, but sometimes the error originates from code outside the code, and then it's basically impossible to debug.

It's a pretty easy fix to change thor to raise the error instead of putsing it. But the question remains, would this be acceptable for thor to do?

help output: Order default runtime options

Sometimes the output is:

Runtime options:
  -p, [--pretend]  # Run but do not make any changes
  -q, [--quiet]    # Supress status output
  -s, [--skip]     # Skip files that already exist
  -f, [--force]    # Overwrite files that already exist

Other times:

Runtime options:
  -s, [--skip]     # Skip files that already exist
  -p, [--pretend]  # Run but do not make any changes
  -q, [--quiet]    # Supress status output
  -f, [--force]    # Overwrite files that already exist

thor -T

I get this returned to me when asking for the Thor tasks.

[21:22][adamstacoviak@AS-MBP15:~/Code/OS/Thor/Thor-Gem(master)]$ thor -T
WARNING: unable to load thorfile "/Users/adamstacoviak/Code/OS/Thor/Thor-Gem/Thorfile": no such file to load -- rdoc/task

[21:25][adamstacoviak@AS-MBP15:~/Code/OS/Thor/Thor-Gem(master)]$ gem list rspec

*** LOCAL GEMS ***

rspec (1.2.9, 1.2.2)
rspec-rails (1.2.2)

invoking a group task w/ required option results in error

invoking a group task w/ required option results in an error: "no value provided for required options"
However, when the option is marked an not required, option is passed and accessible:

invoke "my:group:task", ["some_argument"], :required_option => "value" #=> will raise: no value provided for required options '--required-option'

Do not use white by default in invocations status

Thor::Runner.start missing namespaces.

The list task in Thor::Runner doesn't print any namespaces just task names when $thor_runner is not true (e.g. another application).

For example:

module Foo
  class Bar < Thor
    desc 'bar', 'Bar'
    def bar
    end
  end

  class Baz < Thor
    desc 'baz', 'Baz'
    def baz
    end
  end
end

thor -T prints:

foo:bar
-------
thor foo:bar:bar  # Bar

foo:baz
-------
thor foo:baz:baz  # Baz

But calling Thor::Runner.start %w{-T} inside a script say 'test' will print:

foo:bar
-------
test bar  # Bar

foo:baz
-------
test baz  # Baz

This is a little confusing if you have tasks named the same thing in different namespaces.

Thor should allow namespaces to be turned off

If you are writing a command line utility based on Thor, you don't need Thor to include information about the namespace when it prints usage and errors. For example:

$ bundle foo
The bundler:c_l_i namespace doesn't have a 'foo' task

It seems like it should work like this instead:

$ bundle foo
There is no 'foo' task

It would be very nice to have a way to tell Thor::Task that I don't want namespaces to be mentioned in messages.

Thor task should use banner from instance

Make task usage and description optional? (no "desc" for task)

Currently Thor only makes tasks out of methods described with "desc", and prints a warning for public methods without a description. Would it be possible to make "desc" optional, and make all public methods tasks (albeit with empty descriptions), without printing a warning?

A frequent use case is to create Thorfiles for private use where the method name is sufficient as documentation. Having to add the "desc" lines with empty usage and description is a nuisance when one wants to create small and compact Thorfiles.

Broken link to Thor::Actions documentation

The link to the RDoc documentation of Thor::Actions is broken. It's in the section "Actions".

task :my_task => :environment do

this isn't a bug, more a usage question - but I can't find any google group for this...

is there a way to include the Rails environment into Thor tasks, classes, etc similar to the rake method (in title)

Allow thor to explode when an invalid option is given

Improve Windows compatibility

As Thor will be an important part of Rails 3, compatibility with Windows should be taken in consideration.

In the following gist you will find diff/patches to be applied over master that fix file operation and also increase the compatibility with Ruby 1.9.

http://gist.github.com/267357

On a side note, I noticed a lot of specs depends on successfully execution of previous one, making impossible ensure specs are doing what it suppose to (try executing with reverse options).

Cheers!

Undefined method camelize

When running the thor example newgem, I am getting

(erb):3:in template': undefined methodcamelize' for ...

Adding a default task breaks invocation behavior

Adding a default task (hedgehog/thor@d2d9d3c) breaks the invocation behavior.

The error report is

1)
Thor::InvocationError in 'Thor::Invocation#invoke invokes the default task if none is given to a Thor class'
'default' was called incorrectly. Call as 'b:default'
/usr/src/thor/spec/invocation_spec.rb:24:
/usr/src/thor/spec/spec_helper.rb:29:in `capture'
/usr/src/thor/spec/invocation_spec.rb:24:

and

2)
Thor::InvocationError in 'Thor::Invocation#invoke accepts a class as argument without a task to invoke'
'default' was called incorrectly. Call as 'b:default'
/usr/src/thor/spec/invocation_spec.rb:30:
/usr/src/thor/spec/spec_helper.rb:29:in `capture'
/usr/src/thor/spec/invocation_spec.rb:30:

This error remains even if the spec is changed to:
it "invokes the default task if none is given to a Thor class" do
content = capture(:stdout){ A.new.invoke("b:default") }
content.must =~ /Tasks/
content.must =~ /LAST_NAME/
end

Version number from rubygems is 0.9.9

Can't figure out why the version number in rubyforge is not even tagged here, tell me if you need any help...

destination_root not used by template function

Is there a reason why Thor::Actions::template does not use the destination_root for its destination argument? I thought it would since the documentation says: "relative path to the destination".

Am I misunderstanding the usage of template, or should one explicity pass in File.join(destination_root, filename) as the destination parameter?

Refactored and improved install and list tasks with better deployment features etc.

I have started to refactor the 'install' task in a major way, as it is getting too complex as it is.
Now it also allows for deploying tasks and their templates to special repositories, so as to allow development to be distinct from the deployed task and have all templates used in one location.

The deploy feature could be combined with my github_repo gem and github_thor_tasks, to deploy tasks and templates to a github repo instead ;)

I have also refactored and improved the 'list' task to display task groups correctly with their namespace.

See http://github.com/kristianmandrup/thor

PS: Install refactoring not completely tested yet...

Can't create a task without usage and description

Rake allows you to create "hidden" tasks which are pretty much tasks without descriptions. You can still invoke them but they don't show up in the task list (rake -T). I have a need for a non-printable task, is there a supported way to accomplish this?

Add parameter dependency chain

It would be great to define dependencies between options, such as:

class_option :generate_migration, :type => :boolean
class_option :table, :type => :string :desc => 'Database table in which to operate', :depends => [:generate_migration]
class_option :add_columns, :type => :hash, :desc => 'Columns to add to table', :depends => [:table, :generate_migration]

Actually, the last example uses [:table, :generate_migration] just to illustrate, since :table itself depends already on :generate_migrations. Alternatively, :depends could also accept a symbol or string in case of a single dependency.

Additionally, an :assumes option would be also interesting. Suppose this statement:

class_option :table, :type => :string :desc => 'Database table in which to operate', :assumes => {:generate_migration => true}

In this case, passing a table option would assume generate_migration is set to true.

Feature request: roll back/forward, similar to migrations

Running a generator results in updates to a project much like updates to a DB schema from migrations. It is often the case that you want to undo the result of a generator, fx rename or delete.
Why not have all the project affecting actions as Commands, with up and down methods?

Example: template could default to call Template.up which would also log the command in a command log (in the project) to be rolled back, in this case calling Template.down would delete the resulting file. I'll try to develop such a solution this week - spec driven this time!

Allow a block to be given to directory

Inject into file from template

Would it be okay to add an option (or a new method) in order to inject content to a file/class but from an ERB rendered template?

Console redirection fails on 1.9.x

Running specs in Ruby 1.9 fails due console redirection (mock of $stdin and replacement of $stdout)

This is not an issue on 1.8.6 or 1.8.7

Can't get external command output when using the run command

Thor::Actions#run returns the command output but, unlike Kernel#system, it doesn't do so until the command has finished returning. That means I cannot see the output of commands such as 'mongod' or 'tail -f'.

Windows platform color codes and path issues.

On windows you need the win32console gem for the color codes to show up.

Also there is an error with the home path.
util.rb
212c212
< File.join(user_home, ".thor")
---
> File.join(user_home, ".thor").gsub('', '/')

default_app

Would it make sense to allow a default application to be specified like "default_app 'myapp'"? This way invoking thor without any arguments at all could default to a specific app and task (instead of listing available tasks), like rake.

Subcommands with $thor_runner=false breaks help

I was working on a project that is using thor as a CLI. Since I'm not using the thor runner, I set $thor_runner to false so that I wouldn't see the namespaces. However, whenever I started using subcommands, I noticed that it wasn't displaying the primary command.

With "$thor_runner = false" I get:
~/Dev/slimgem/bin > ./slim
Tasks:
./slim help [COMMAND] # Describe subcommands or one specific subcommand
./slim help [TASK] # Describe available tasks or one specific task
./slim init # Creates a gem project using the active snapset.
./slim init # Creates a snapset.
./slim snapset # Allows the management of snapsets.

Without messing with $thor_runner I get:

~/Dev/slimgem/bin > ./slim help
Tasks:
  ./slim slimgem:c_l_i:help [TASK]             # Describe available tasks or ...
  ./slim slimgem:c_l_i:init                    # Creates a gem project using ...
  ./slim slimgem:c_l_i:snapset                 # Allows the management of sna...
  ./slim slimgem:c_l_i:snapset:help [COMMAND]  # Describe subcommands or one ...
  ./slim slimgem:c_l_i:snapset:init            # Creates a snapset.

The desired result would be:
~/Dev/slimgem/bin > ./slim help
Tasks:
./slim help [TASK] # Describe available tasks or ...
./slim init # Creates a gem project using ...
./slim snapset # Allows the management of sna...
./slim snapset help [COMMAND] # Describe subcommands or one ...
./slim snapset init # Creates a snapset.

Too many 'usage' methods.

This make debugging a more of a pita than it needs to be:

• usage:task.rb
  • usage:option.rb
  • usage:argument.rb

and to round it out...

• hsh.usage

Fine if you restain employing these methods to their declared files,
but when they are intertwined thoughout Thor it means that
reading << understanding code.

No way to nicely change default task?

Hi there,

I'd love to use thor in my application, but I'd need it to do a default task when invoked without parameters. ATM it displays the help message in that case.
I was wondering, if there was a way of doing that nicely, since I may have overlooked it.

Right now, I'm doing this quick little workaround:
map 'help' => :real_help
def help _args
list(_args)
end
which will call the list() function when there were no arguments specified and the real_help function, whenever the the help command was given explicitly.

It would be really nice to be able to do something like
map :default => :list
or something similar to change the default task more nicely. My solution is quite hacky after all g

Anyways, thanks for this really great program, I'm definitely enjoying it.
Keep up the good work!

Uninitialized constant Thor::Group when running thor commands

Hi,

Just installed Thor and when I try "thor list" or "thor installed" I get the following error:

/Users/mhfs/.rvm/gems/ruby-1.8.7-p248/gems/thor-0.13.0/lib/thor/runner.rb:258:in `display_klasses': uninitialized constant Thor::Group (NameError)
from /Users/mhfs/.rvm/gems/ruby-1.8.7-p248/gems/thor-0.13.0/lib/thor/runner.rb:147:in `list'
from /Users/mhfs/.rvm/gems/ruby-1.8.7-p248/gems/thor-0.13.0/lib/thor/task.rb:32:in `send'
from /Users/mhfs/.rvm/gems/ruby-1.8.7-p248/gems/thor-0.13.0/lib/thor/task.rb:32:in `run'
from /Users/mhfs/.rvm/gems/ruby-1.8.7-p248/gems/thor-0.13.0/lib/thor/invocation.rb:108
from /Users/mhfs/.rvm/gems/ruby-1.8.7-p248/gems/thor-0.13.0/lib/thor/invocation.rb:115:in `call'
from /Users/mhfs/.rvm/gems/ruby-1.8.7-p248/gems/thor-0.13.0/lib/thor/invocation.rb:115:in `invoke'
from /Users/mhfs/.rvm/gems/ruby-1.8.7-p248/gems/thor-0.13.0/lib/thor.rb:137:in `start'
from /Users/mhfs/.rvm/gems/ruby-1.8.7-p248/gems/thor-0.13.0/lib/thor/base.rb:369:in `start'
from /Users/mhfs/.rvm/gems/ruby-1.8.7-p248/gems/thor-0.13.0/lib/thor.rb:124:in `start'
from /Users/mhfs/.rvm/gems/ruby-1.8.7-p248/gems/thor-0.13.0/bin/thor:8
from /Users/mhfs/.rvm/gems/ruby-1.8.7-p248/bin/thor:19:in `load'
from /Users/mhfs/.rvm/gems/ruby-1.8.7-p248/bin/thor:19

Thanks,
Marcelo

paths to look for .thor files in is hardcoded

i'd like to be able to add to the array of glob patterns that thor looks for .thor files in. maybe a case for an ENV var in Thor::Util#globs_for(path) or a CLI option or something. currently, it's being limited to "#{path}", "#{path}/tasks", or "#{path}/lib/tasks".

default_task doesn't work when using RakeCompat

Not sure why, but the default_task doesn't work on this file: http://gist.github.com/328012

I made it based on actual thor Thorfile, but if you have any suggestions to improve that file, I'm all ears. :)

thor has a zero return code when task isn't found

(I hope this is the right place to submit issues. If it's not I'd be happy to resubmit in the appropriate place)

$ thor task doesnt exist
The thor:runner namespace doesn't have a `task' task
$ echo $?
0

This is an unsuccessful case, and the return code ought to be nonzero.

Inject

Hi,

it's possible in inject_into_file prevent to re-insert two times the same thing?

That's it's what I need to do for each inject:

          if options[:destroy] || !File.read(..).include?(...)
            inject_into_file ...,  "...", :after => ...
          end

Missing example of how to use the packaging system for dirs with main.thor

Diving into the install task, it is clear that there is an option to install a directory instead of a single thor task, where the thor file is expected to be called main.thor.

I have not been able to find any examples or tutorials/guides for how to use this feature.

Thor::Actions#apply fails for paths with spaces.

URI(path).is_a?(URI::HTTP) at lib/thor/actions.rb:198 is failing with paths like /Users/user/Projects/Project with Spaces/ as input with a URI::InvalidURIError: bad URI(is not URI?) exception.

feed the template path to instance_eval in apply action

http://github.com/wycats/thor/blob/master/lib/thor/actions.rb#L183
feeding path will ease debugging of template a bit.
instance_eval(open(path).read, path)

"super called outside of method" exception with Thor 0.12.3.

I've been using Thor::Group and Thor::Actions to write custom generators for a project, "ronin-gen":http://github.com/postmodern/ronin-gen. As of Thor 0.12.3 I've noticed a strange exception being raised only under Ruby 1.8.7-p249. This exception is not raised under Ruby 1.9.1-p376 and all specs pass.

An example from the specs of ronin-gen:

NoMethodError in 'Ronin::Generators::Platform::Overlay before(:all)'
super called outside of method
/usr/lib64/ruby/gems/1.8/gems/thor-0.12.3/lib/thor/task.rb:32:in `send'
/usr/lib64/ruby/gems/1.8/gems/thor-0.12.3/lib/thor/task.rb:32:in `run'
/usr/lib64/ruby/gems/1.8/gems/thor-0.12.3/lib/thor/invocation.rb:108:in `invoke'
/usr/lib64/ruby/gems/1.8/gems/thor-0.12.3/lib/thor/task.rb:106:in `map'
/usr/lib64/ruby/gems/1.8/gems/thor-0.12.3/lib/thor/core_ext/ordered_hash.rb:75:in `each'
/usr/lib64/ruby/gems/1.8/gems/thor-0.12.3/lib/thor/invocation.rb:117:in `map'
/usr/lib64/ruby/gems/1.8/gems/thor-0.12.3/lib/thor/invocation.rb:117:in `invoke'
./spec/generators/platform/overlay_spec.rb:20:

Thor should not steal ARGV

Underscores in method_options symbol names are ignored

eg method_options :name => :required, :repos => :string, :version_control => :boolean, :no_doc_type => :boolean, :no_pdf => :boolean, :unabridged => :boolean

The only options parsed are the ones without underscores. This used to work in 0.9.9. Any suggestions on how to use underscores in options?