{"id":31,"date":"2009-07-31T16:22:36","date_gmt":"2009-07-31T19:22:36","guid":{"rendered":"http:\/\/blog.plataformatec.com.br\/?p=31"},"modified":"2010-04-22T14:57:45","modified_gmt":"2010-04-22T17:57:45","slug":"creating-your-own-generators-with-thor","status":"publish","type":"post","link":"https:\/\/blog.plataformatec.com.br\/2009\/07\/creating-your-own-generators-with-thor\/","title":{"rendered":"Creating your own generators with Thor"},"content":{"rendered":"<p>This summer I was selected with <a id=\"h_og\" title=\"Josh Peek\" href=\"http:\/\/joshpeek.com\/\">Josh Peek<\/a>, <a id=\"wjz_\" title=\"Emilio Tagua\" href=\"http:\/\/miloops.com\/\">Emilio Tagua<\/a> and <a id=\"dnx3\" title=\"Nelson Crespo\" href=\"http:\/\/ecin.tumblr.com\/\">Nelson Crespo<\/a> to work with Rails on Google Summer of Code (GSoC), which Nelson  named as the <a id=\"v9w6\" title=\"Rails Summer Quartet\" href=\"http:\/\/socghop.appspot.com\/org\/home\/google\/gsoc2009\/rails\">Rails Summer Quartet<\/a>. \ud83d\ude42<\/p>\n<p>Here, at <a href=\"http:\/\/www.plataformatec.com.br\/\" target=\"_blank\">Plataforma<\/a>, we use a set of tools on our projects, which includes <a href=\"http:\/\/github.com\/josevalim\/inherited_resources\" target=\"_blank\">Inherited Resources<\/a>, <a href=\"http:\/\/github.com\/carlosbrando\/remarkable\" target=\"_blank\">Remarkable<\/a> and <a href=\"http:\/\/github.com\/justinfrench\/formtastic\">Formtastic<\/a>. At some point, we were planning on creating generators for each of those tools but still they couldn&#8217;t play along. If I wanted a generator that uses all three projects, I needed to create a inherited_remarkable_formtastic generator which is not DRY at all.<\/p>\n<p>For example, for those who wants to use Datamapper with Rspec, they need to call &#8220;ruby script\/generate dm_rspec_model&#8221; instead of &#8220;ruby script\/generate model&#8221;. Since Rails 3.0 is moving towards agnosticism, my GSoC proposal was exactly bring it to rails generators.<\/p>\n<h3>1. So, what about Thor?!<\/h3>\n<p>One day before the official coding period start, I was staring at <a id=\"nxn_\" title=\"this Thor post\" href=\"http:\/\/yehudakatz.com\/2008\/05\/12\/by-thors-hammer\/\">this Thor post<\/a> by Yehuda Katz. <a href=\"http:\/\/github.com\/wycats\/thor\" target=\"_blank\">Thor<\/a> is a rake replacement with support to options parsing:<\/p>\n<pre lang=\"rails\">class Speak < Thor\r\n  desc \"name\", \"the name to say hello to\"\r\n  method_options :loudly => false\r\n\r\n  def hello(name)\r\n    name.upcase! if options[:loudly]\r\n    puts \"Hello #{name}\"\r\n  end\r\nend<\/pre>\n<p>And then can be invoked as:<\/p>\n<pre lang=\"ruby\">> thor speak:hello jose\r\nHello jose\r\n\r\n> thor speak:hello jose \u2013-loudly\r\nHello JOSE<\/pre>\n<p>At that point, I realized that a generator is nothing more than a scripting task (like rake or thor) with some extra methods which makes the creation and copy of files easy. Thor had several features which convinced me that it was the best solution to build generators on top of:<\/p>\n<ul>\n<li>It has a powerful options parser;<\/li>\n<li>Thor classes can be inherited and all tasks from the class are copied to the child;<\/li>\n<li>Thor classes are self contained. The example above can be invoked straight from your ruby code as Speak.new.hello(&#8220;jose&#8221;).<\/li>\n<\/ul>\n<p>Then I was able to create a ROADMAP to Thor:<\/p>\n<ul>\n<li>Add actions like copy_file, template, empty_directory to Thor;<\/li>\n<li>Move all user input and output logic to its own class, so anyone can customize it;<\/li>\n<li>Extend even more Thor options parser to add support to hashes (as in Rails name:string age:integer on generators) and arrays;<\/li>\n<li>Add an invocation mechanism, so I can invoke one task from another Thor task.<\/li>\n<\/ul>\n<h3>2. An example<\/h3>\n<p>Let&#8217;s see an example on how you can create your own generators with Thor. For example, a generators that stubs out a new gem structure:<\/p>\n<pre lang=\"rails\">class NewgemGenerator < Thor::Group\r\n  include Thor::Actions\r\n\r\n  # Define arguments and options\r\n  argument :name\r\n  class_option :test_framework, :default => :test_unit\r\n\r\n  def self.source_root\r\n    File.dirname(__FILE__)\r\n  end\r\n\r\n  def create_lib_file\r\n    create_file \"#{name}\/lib\/#{name}.rb\" do\r\n      \"class #{name.camelize}\\nend\"\r\n    end\r\n  end\r\n\r\n  def create_test_file\r\n    test = options[:test_framework] == \"rspec\" ? :spec : :test\r\n    create_file \"#{name}\/#{test}\/#{name}_#{test}.rb\"\r\n  end\r\n\r\n  def copy_licence\r\n    if yes? \"Use MIT license?\"\r\n      # Make a copy of the MITLICENSE file at the source root\r\n      copy_file \"MITLICENSE\", \"#{name}\/MITLICENSE\"\r\n    else\r\n      say \"Shame on you\u2026\", :red\r\n    end\r\n  end\r\nend<\/pre>\n<p>You can see from the example above that we are inheriting from Thor::Group and not Thor. In Thor, each method corresponds to a task, which can be invoked on its own. In Thor::Group, you invoke all tasks at once, in the order they are declared. This is interesting because you split your script\/generator into several methods. It improves readability and allows anyone to inherit from your generator and change just one step in the process.<\/p>\n<p>The next step, on lines 4 and 5, is to define arguments and options for the class. Arguments are required to be given right after the executable while options are given with switches. The newgem above can be invoked as:<\/p>\n<pre lang=\"bash\">newgem remarkable<\/pre>\n<p>And it will create two files: &#8220;remarkable\/lib\/remarkable.rb&#8221;, &#8220;remarkable\/test\/remarkable_test.rb&#8221; and prompt the user (with the use of the method <em>yes?<\/em>) if we wants to copy the MITLICENSE. If you want to change the test framework, you can give it as an option:<\/p>\n<pre lang=\"bash\">newgem remarkable --test-framework=rspec<\/pre>\n<p>Now it generates &#8220;remarkable\/lib\/remarkable.rb&#8221; and &#8220;remarkable\/spec\/remarkable_spec.rb&#8221;.<\/p>\n<p>The generation methods are kept into the Thor::Actions module, which is included on top of our class. It holds all the scripting methods, which are: <em>copy_file<\/em>,<em> create_file<\/em>,<em> directory<\/em>,<em> empty_directory<\/em>,<em> get<\/em>,<em> inject_into_file<\/em> and <em>template<\/em>. All those actions can be revoked, so Thor knows how to do and undo the process (like in script\/generate and script\/destroy).<\/p>\n<p>Even more, some of Rails templates methods was moved to Thor, like: <em>inside<\/em>,<em> run<\/em>,<em> run_ruby_script<\/em>,<em> gsub_file<\/em>,<em> append_file <\/em>and<em> prepend_file<\/em>. So whenever creating scripts with Thor, those methods will be available to make your life easier.<\/p>\n<p>Finally, all user iteration methods are handled by Thor::Shell classes by <em>say<\/em>,<em> ask<\/em>,<em> yes? <\/em>and<em> no?<\/em> methods. Thor ships with two Shell implementations: Basic and Color. If you mantain an IDE for Rails, you can build your own shell and make the user interaction through it.<\/p>\n<h3>3. What is more?<\/h3>\n<p>Thor is used as base in Rails::Generators, where Rails extend it to provide Rails specific functionalities, as hooks for ORM, Test framework and so on. This will be my talk subject on <a id=\"p631\" title=\"Rails Summit Latin America\" href=\"http:\/\/railssummit.locaweb.com.br\/en\/pages\/speakers\">Rails Summit Latin America<\/a>, 13th October, in S\u00e3o Paulo, Brazil.<\/p>\n<p>If you can join us or not, be sure to grab our RSS feed and keep on checking, we will discuss about it here too.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>This summer I was selected with Josh Peek, Emilio Tagua and Nelson Crespo to work with Rails on Google Summer of Code (GSoC), which Nelson named as the Rails Summer Quartet. \ud83d\ude42 Here, at Plataforma, we use a set of tools on our projects, which includes Inherited Resources, Remarkable and Formtastic. At some point, we &#8230; <a class=\"read-more-link\" href=\"https:\/\/blog.plataformatec.com.br\/2009\/07\/creating-your-own-generators-with-thor\/\">\u00bb<\/a><\/p>\n","protected":false},"author":4,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"ngg_post_thumbnail":0,"footnotes":""},"categories":[1],"tags":[10,7,60,9],"aioseo_notices":[],"jetpack_sharing_enabled":true,"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/blog.plataformatec.com.br\/wp-json\/wp\/v2\/posts\/31"}],"collection":[{"href":"https:\/\/blog.plataformatec.com.br\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.plataformatec.com.br\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.plataformatec.com.br\/wp-json\/wp\/v2\/users\/4"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.plataformatec.com.br\/wp-json\/wp\/v2\/comments?post=31"}],"version-history":[{"count":16,"href":"https:\/\/blog.plataformatec.com.br\/wp-json\/wp\/v2\/posts\/31\/revisions"}],"predecessor-version":[{"id":912,"href":"https:\/\/blog.plataformatec.com.br\/wp-json\/wp\/v2\/posts\/31\/revisions\/912"}],"wp:attachment":[{"href":"https:\/\/blog.plataformatec.com.br\/wp-json\/wp\/v2\/media?parent=31"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.plataformatec.com.br\/wp-json\/wp\/v2\/categories?post=31"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.plataformatec.com.br\/wp-json\/wp\/v2\/tags?post=31"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}