inochi 0.2.0 → 0.3.0

data/doc/intro.erb

@@ -1,6 +1,6 @@
 <% chapter "Introduction" do %>
   <% project_summary do %>
-    **<%= $project %>** is an infrastructure for [RubyGems](http://www.rubygems.org)-based software projects that encourages good documentation, reduces programming effort, and automates common tasks.
+    **<%= $project %>** is an infrastructure for [RubyGems](http://www.rubygems.org)-based software projects that encourages good documentation and reduces programming effort by automating common tasks.
   <% end %>
 
   **<%= $project %>** is exciting because:
@@ -22,27 +22,21 @@
   * [hoe](http://seattlerb.rubyforge.org/hoe/)
   * [newgem](http://newgem.rubyforge.org)
   * [Mr Bones](http://codeforpeople.rubyforge.org/bones/)
-
-  <!--
-      Say goodbye to the days of manually requiring libraries:
-
-        require File.join(File.dirname(__FILE__), 'project', 'library')
-
-      With **<%= $project %>** you can require any library in your project:
-
-        require 'project/library'
-  -->
+  * [Gemify](http://gitorious.org/projects/gemify/)
+  * [Jeweler](http://technicalpickles.github.com/jeweler/)
+  * [GemMake](https://simonmenke.github.com/gm/)
+  * [SimpleGem](http://github.com/reagent/simple-gem/tree/master)
 
   <% paragraph "Etymology" do %>
     In the past, software development was thought to be like mathematical modeling or building construction:  the assembly of inanimate objects.  Nowadays, it is thought to be more like gardening: the cultivation of life!
 
     In this manner, I consider this project not as a generator of skeletons or as a builder of scaffolds, but as a *giver of life*.  That is why I named this project "inochi", the Japanese word for *life*.
 
-    Happy gardening!
+    Happy cultivation!
   <% end %>
 
   <% section "Logistics" do %>
-    * <%= xref "history", "Release notes" %> --- history of project releases.
+    * <%= xref "History", "Release notes" %> --- history of project releases.
     * [Source code](http://github.com/sunaku/<%= $program %>) --- obtain via [Git](http://git.or.cz) or browse online.
     * [API reference](api/index.html) --- documentation for source code.
     * [Project home](<%= $website %>) --- the **<%= $project %>** project home page.
@@ -99,5 +93,11 @@
   <% section "Credits" do %>
     <%= $logo = "![project logo](#{$program}.png)".to_inline_xhtml %>
     <%# include README #%>
+
+    **<%= $project %>** is made possible by
+    <%= xref "History", "contributions" %>
+    from users like you:
+
+    * Florian Gilcher
   <% end %>
-<% end %>
+<% end %>

data/doc/setup.erb

@@ -2,18 +2,17 @@
   <% section "Requirements" do %>
     Your system needs the following software to run **<%= $project %>**.
 
-    | Software                                         | Description               | Notes                                                               |
-    | --------                                         | -----------               | -----                                                               |
-    | [Ruby](http://ruby-lang.org)                     | Ruby language interpreter | Version 1.8.6 or 1.8.7 is required.                                 |
-    | [RubyGems](http://rubygems.org)                  | Ruby packaging system     | Version 1.x.x is required.                                          |
-    | [<%= ERBook::PROJECT %>](<%= ERBook::WEBSITE %>) | <%= ERBook::TAGLINE %>    | Version <%= ERBook::VERSION.series %> is required.                  |
-    | [Lynx](http://lynx.isc.org)                      | Text-mode web browser     | Version 2.8.6 or newer is required to convert HTML into plain text. |
+    | Software                        | Description               | Notes                                                               |
+    | --------                        | -----------               | -----                                                               |
+    | [Ruby](http://ruby-lang.org)    | Ruby language interpreter | Version 1.8.6 or 1.8.7 is required.                                 |
+    | [RubyGems](http://rubygems.org) | Ruby packaging system     | Version 1.x.x is required.                                          |
+    | [Lynx](http://lynx.isc.org)     | Text-mode web browser     | Version 2.8.6 or newer is required to convert HTML into plain text. |
   <% end %>
 
   <% section "Installation" do %>
     You can install **<%= $project %>** by running this command:
 
-        gem install <%= ERBook::PROGRAM %> <%= $program %>
+        gem install -f <%= $program %>
 
     To check whether the installation was sucessful, run this command:
 
@@ -47,6 +46,8 @@
 
       * <tt>index.erb</tt> --- source of this user manual.
 
+    * <tt>lang/</tt> --- translations of language phrases.
+
     * <tt>LICENSE</tt> --- copyright notice and legal conditions.
   <% end %>
 <% end %>

data/doc/usage.erb

@@ -1,3 +1,5 @@
+<% yaml_addr = "http://yaml.kwiki.org/?YamlInFiveMinutes" %>
+
 <% part "Usage" do %>
   <% section "Command-line interface" do %>
     When you run this command:
@@ -312,7 +314,7 @@
         <% paragraph "Units and tests" do %>
           Every Ruby source file in your project's <tt>lib/</tt> directory is considered to be a **unit**.  Likewise, every Ruby source file in your project's <tt>test/</tt> is considered to be a **test**.
 
-          As a result, your project's <tt>test/</tt> directory structure *mirrors* the structure of your project's <tt>lib/</tt> directory.  For example, if your project has a <tt>lib/foo/bar.rb</tt> unit, then <tt>test/foo/bar.rb</tt> would be its the corresponding test.
+          As a result, your project's <tt>test/</tt> directory structure *mirrors* the structure of your project's <tt>lib/</tt> directory.  For example, if your project has a <tt>lib/foo/bar.rb</tt> unit, then <tt>test/foo/bar.rb</tt> would be its corresponding test.
         <% end %>
 
         <% paragraph "Test execution" do %>
@@ -326,7 +328,7 @@
 
           As for the details of test execution:
 
-          * Tests are executed by the [minitest] library, which allows you to write unit tests in a combination of styles: traditional TDD, modern BDD, alternative rSpec BDD, and mock-based validation styles.
+          * Tests are executed by the [minitest] library, which allows you to write unit tests in a combination of styles: traditional xUnit TDD, alternative rSpec BDD, and mock-based validation styles.
 
           * Within each test, test cases are executed in random order.  This is the default behavior of the [minitest] library.
 
@@ -344,13 +346,116 @@
         <% end %>
       <% end %>
 
-      <% section "Publish your project" do %>
-        This command performs all of the automated steps described in the following sections:
+      <% section "Translate your project" do %>
+        <% phrases_file = "<tt>lang/phrases.yaml</tt>" %>
+
+        Although English is the *lingua franca* of today, your project's users may prefer to interact with it in their native language.  **<%= $project %>** makes it easy to translate your project and also makes it easy for users to correct and contribute translations to your project.
+
+        <% section "Language phrases" do %>
+          **<%= $project %>** equips your project module with a `PHRASES` constant (see the [`Inochi::Phrases` class](api/Inochi/Phrases.html)) which provides access to translations of language phrases used in your project.
+
+          The [`Inochi::Phrases#[]` method](api/Inochi/Phrases.html#[]-instance_method) translates a given language phrase into the user's preferred language, which is automatically inferred from their environment, but may be explictly overridden by the user via the <tt>--locale</tt> option of <%= xref "Run project executable", "your project's main executable" %>:
+
+          <code>
+          your_project::PHRASES['Have a nice day!']
+          </code>
+
+          If there is no <%= xref "Translation files", "translation file" %> for the user's preferred language, or it does not define a translation for a particular language phrase, then the language phrase will be used untranslated:
+
+          <code>
+          your_project::PHRASES['No translation for this']
+          #=> 'No translation for this'
+          </code>
+
+          <% paragraph "Parameterizing language phrases" do %>
+            Language phrases can be parameterized using [`printf` format placeholders](http://en.wikipedia.org/wiki/Printf#printf_format_placeholders) to ease translation:
+
+            <code>
+            your_project::PHRASES['Good afternoon, %s.', user_name]
+            your_project::PHRASES['You are %d years old.', user_age]
+            </code>
+          <% end %>
+
+          <% paragraph "Explicit translation into a language" do %>
+            If a language phrase must be translated into a specific language, regardless of the user's preference, you can invoke the respective method (whose name is the same as the [ISO-639 language code](http://en.wikipedia.org/wiki/ISO_639) of the language into which you wish to translate) on your `PHRASES` object:
+
+            <code>
+            # explictly translate into Japanese (ja)
+            your_project::PHRASES.ja('Goodbye %s!', user_name)
+
+            # explictly translate into French (fr)
+            your_project::PHRASES.fr('Farewell %s!', user_name)
+            </code>
+          <% end %>
+        <% end %>
+
+        <% section "Translation files" do %>
+          Translation files are [YAML documents](<%= yaml_addr %>) that reside in your project's <tt>lang/</tt> directory.  They provide translations for <%= xref "Language phrases", "language phrases" %> used in your project.
+
+          For example, suppose that your language phrases are written in English, the <tt>lang/es.yaml</tt> (Spanish) translation file would appear like this:
+
+          <pre>
+          #
+          # (this is a comment)
+          #
+          # language phrase : translation
+          #
+          Hello %s! : ¡Hola %s!
+          Money : Dinero
+          Ticket : Tarjeta
+          See you later %s! : ¡Hasta la vista %s!
+          "%s: Quickly, please!" : "%s: ¡Rápidamente, por favor!"
+          </pre>
+
+          On each line, the original language phrase (as used in your project) appears first, then a single semicolon (:), followed by the translation.
+
+          Also, notice that if a language phrase contains a semicolon, then the entire phrase must be enclosed in quotation marks.  The same rule applies to its corresponding translation.
+        <% end %>
+
+        <% section "Extracting language phrases" do %>
+          <pre>
+          # rake lang:dump
+          <%= verbatim `rake lang:dump` %>
+          </pre>
+
+          The above command exercises your project's code and extracts all *utilized* language phrases into the <%= phrases_file %> file.  Continue reading to learn how this is accomplished.
+
+          <% paragraph "Dynamic analysis" do %>
+            Because Ruby is a dynamically interpreted language, the easiest way to extract language phrases is to evaluate the code that defines them and keep track of which phrases are defined.
+
+            But how can **<%= $project %>** exercise all Ruby code in your project?  The answer is through *unit tests*.  Because unit tests already exercise your project's code, **<%= $project %>** can use them to reach and extract all language phrases from your project.
+
+            However, note that if your unit tests *do not* exercise a part of your project that defines language phrases, then those phrases *will not* be extracted by **<%= $project %>**.
+
+            This gives you extra motivation to improve the coverage of your test suite---at least to the point where all code that defines language phrases is covered.
+          <% end %>
 
+          <% paragraph "Static analysis" do %>
+            In a future release, I plan to extract language phrases through static analysis of Ruby code.  This approach will supplement the current practice of reaching language phrases through unit tests.
+
+            Patches are welcome! :-)
+          <% end %>
+        <% end %>
+
+        <% section "Translating language phrases" do %>
+          After you have extracted all language phrases from your project (either manually or via <%= xref "Extracting language phrases" %>) into the <%= phrases_file %> file, **<%= $project %>** can automatically translate them into various languages using the [Yahoo! BabelFish translation service](http://babelfish.yahoo.com):
+
+          <pre>
+          # rake lang:conv from=LANGUAGE_CODE
+          <%= verbatim `rake lang:conv from=LANGUAGE_CODE 2>&1` %>
+          </pre>
+
+          Notice that you must specify the language in which your phrases are written, via the <tt>from=</tt> parameter.  **<%= $project %>** cannot determine this automatically.
+        <% end %>
+      <% end %>
+
+      <% section "Publish your project" do %>
         <pre>
         # rake pub
         </pre>
 
+        The above command performs all automated steps described in the following sections.
+
         <% section "Build a RubyGem" do %>
           Build a RubyGem by running:
 
@@ -391,7 +496,7 @@
 
             <% logins_file = "~/.config/inochi/logins.yaml" %>
 
-            This information is expected to be stored in a <tt><%= logins_file %></tt> file (this location can be overridden by passing the `:logins_file` option to the [`Inochi.rake()` method](api/Inochi.html#rake-class_method)), where <tt>~</tt> denotes the path to your home directory.  This file is a [YAML](http://www.yaml.org) document containing the following parameters:
+            This information is expected to be stored in a <tt><%= logins_file %></tt> file (this location can be overridden by passing the `:logins_file` option to the [`Inochi.rake()` method](api/Inochi.html#rake-class_method)), where <tt>~</tt> denotes the path to your home directory.  This file is a [YAML document](<%= yaml_addr %>) containing the following parameters:
 
             <code lang="yaml">
             www.ruby-forum.com:

data/lib/inochi.rb

@@ -1,9 +1,18 @@
+require 'rubygems'
+
+module Inochi
+end
+
 $LOAD_PATH << File.dirname(__FILE__)
-require 'inochi/inochi'
+require 'inochi/init'
+require 'inochi/main'
+require 'inochi/rake'
+require 'inochi/book'
+require 'inochi/util'
 
 Inochi.init :Inochi,
-  :version => '0.2.0',
-  :release => '2009-01-25',
+  :version => '0.3.0',
+  :release => '2009-02-12',
   :website => 'http://snk.tuxfamily.org/lib/inochi',
   :tagline => 'Gives life to RubyGems-based software',
   :require => {
@@ -11,8 +20,10 @@ Inochi.init :Inochi,
     'rubyforge'   => '~> 1',              # for publishing gems to RubyForge
     'mechanize'   => '~> 0',              # for automating web browsing
     'trollop'     => '~> 1',              # for parsing command-line options
+    'erbook'      => '~> 6',              # for processing the user manual
     'launchy'     => '~> 0',              # for launching a web browser
     'yard'        => nil,                 # for generating API documentation
     'addressable' => '~> 2',              # for parsing URIs properly
     'minitest'    => ['>= 1.3.1', '< 2'], # for unit testing
+    'babelfish'   => '~> 0',              # for human language translation
   }

data/lib/inochi/book.rb

@@ -0,0 +1,84 @@
+class << Inochi
+  ##
+  # Provides a common configuration for the project's user manual:
+  #
+  # * Assigns the title, subtitle, date, and authors for the document.
+  #
+  #   You may override these assignments by reassigning these
+  #   document parameters AFTER this method is invoked.
+  #
+  #   Refer to the "document parameters" for the XHTML
+  #   format in the "erbook" user manual for details.
+  #
+  # * Provides the project's configuration as global variables in the document.
+  #
+  #   For example, <%= $version %> is the same as
+  #   <%= project_module::VERSION %> in the document.
+  #
+  # * Defines a "project_summary" node for use in the document.  The body
+  #   of this node should contain a brief introduction to the project.
+  #
+  # * Defines a "project_history" node for use in the document.  The body
+  #   of this node should contain other nodes, each of which represent a
+  #   single set of release notes for one of the project's releases.
+  #
+  # It is assumed that this method is called
+  # from within the Inochi.rake() environment.
+  #
+  # @param [Symbol] project_symbol
+  #   Name of the Ruby constant which serves
+  #   as a namespace for the entire project.
+  #
+  # @param [ERBook::Document::Template] book_template
+  #   The eRuby template which serves as the documentation for the project.
+  #
+  def book project_symbol, book_template
+    project_module = fetch_project_module(project_symbol)
+
+    # provide project constants as global variables to the user manual
+    project_module::INOCHI.each_pair do |param, value|
+      eval "$#{param} = value", binding
+    end
+
+    # set document parameters for the user manual
+    $title    = project_module::DISPLAY
+    $subtitle = project_module::TAGLINE
+    $feeds    = { File.join(project_module::DOCSITE, 'ann.xml') => :rss }
+    $authors  = Hash[
+      *project_module::AUTHORS.map do |name, addr|
+        # convert raw e-mail addresses into URLs for the erbook XHTML format
+        addr = "mailto:#{addr}" unless addr =~ /^\w+:/
+
+        [name, addr]
+      end.flatten
+    ]
+
+    book_template.extend Manual
+  end
+
+  module Manual
+    ##
+    # Defines a brief summary of this project.
+    #
+    def project_summary
+      raise ArgumentError, 'block must be given' unless block_given?
+
+      node do
+        $project_summary_node = @nodes.last
+        yield
+      end
+    end
+
+    ##
+    # Contains release notes for all project releases.
+    #
+    def project_history
+      raise ArgumentError, 'block must be given' unless block_given?
+
+      node do
+        $project_history_node = @nodes.last
+        yield
+      end
+    end
+  end
+end

data/lib/inochi/init.rb

@@ -0,0 +1,239 @@
+require 'yaml'
+
+class << Inochi
+  ##
+  # Establishes your project in Ruby's runtime environment by defining
+  # the project module (which serves as a namespace for all code in the
+  # project) and providing a common configuration for the project module:
+  #
+  # * Adds the project lib/ directory to the Ruby load path.
+  #
+  # * Defines the INOCHI constant in the project module.  This constant
+  #   contains the effective configuration parameters (@see project_config).
+  #
+  # * Defines all configuration parameters as constants in the project module.
+  #
+  # This method must be invoked from immediately within (that is, not from
+  # within any of its descendant directories) the project lib/ directory.
+  # Ideally, this method would be invoked from the main project library.
+  #
+  # @param [Symbol] project_symbol
+  #   Name of the Ruby constant which serves
+  #   as a namespace for the entire project.
+  #
+  # @param [Hash] project_config
+  #   Project configuration parameters:
+  #
+  #   [String] :project =>
+  #     Name of the project.
+  #
+  #     The default value is the value of the project_symbol parameter.
+  #
+  #   [String] :tagline =>
+  #     An enticing, single line description of the project.
+  #
+  #     The default value is an empty string.
+  #
+  #   [String] :website =>
+  #     URL of the published project website.
+  #
+  #     The default value is an empty string.
+  #
+  #   [String] :docsite =>
+  #     URL of the published user manual.
+  #
+  #     The default value is the same value as the :website parameter.
+  #
+  #   [String] :program =>
+  #     Name of the main project executable.
+  #
+  #     The default value is the value of the :project parameter
+  #     in lowercase and CamelCase converted into snake_case.
+  #
+  #   [String] :version =>
+  #     Version of the project.
+  #
+  #     The default value is "0.0.0".
+  #
+  #   [String] :release =>
+  #     Date when this version was released.
+  #
+  #     The default value is the current time.
+  #
+  #   [String] :display =>
+  #     How the project name should be displayed.
+  #
+  #     The default value is the project name and version together.
+  #
+  #   [String] :install =>
+  #     Path to the directory which contains the project.
+  #
+  #     The default value is one directory above the parent
+  #     directory of the file from which this method was called.
+  #
+  #   [Hash] :require =>
+  #     The names and version constraints of ruby gems required by
+  #     this project.  This information must be expressed as follows:
+  #
+  #     * Each hash key must be the name of a ruby gem.
+  #
+  #     * Each hash value must be either +nil+, a single version number
+  #       requirement string (see Gem::Requirement) or an Array thereof.
+  #
+  #     The default value is an empty Hash.
+  #
+  # @return [Module] The newly configured project module.
+  #
+  def init project_symbol, project_config = {}
+    project_module = fetch_project_module(project_symbol)
+
+    # this method is not re-entrant
+      @already_seen ||= []
+      return project_module if @already_seen.include? project_module
+      @already_seen << project_module
+
+    # put project on Ruby load path
+      project_file = File.expand_path(first_caller_file)
+      project_libs = File.dirname(project_file)
+      $LOAD_PATH << project_libs unless $LOAD_PATH.include? project_libs
+
+    # supply configuration defaults
+      project_config[:project] ||= project_symbol.to_s
+      project_config[:tagline] ||= ''
+      project_config[:version] ||= '0.0.0'
+      project_config[:release] ||= Time.now.strftime('%F')
+      project_config[:website] ||= ''
+      project_config[:docsite] ||= project_config[:website]
+      project_config[:display] ||= "#{project_config[:project]} #{project_config[:version]}"
+      project_config[:program] ||= calc_program_name(project_symbol)
+      project_config[:install] ||= File.dirname(project_libs)
+      project_config[:require] ||= {}
+
+    # establish gem version dependencies and
+    # sanitize the values while we're at it
+      src = project_config[:require].dup
+      dst = project_config[:require].clear
+
+      src.each_pair do |gem_name, version_reqs|
+        gem_name     = gem_name.to_s
+        version_reqs = [version_reqs].flatten.compact
+
+        dst[gem_name] = version_reqs
+        gem gem_name, *version_reqs
+      end
+
+    # make configuration parameters available as constants
+      project_config[:inochi]  = project_config
+      project_config[:phrases] = Phrases.new project_config[:install]
+      project_config[:version].extend Version
+
+      project_config.each_pair do |param, value|
+        project_module.const_set param.to_s.upcase, value
+      end
+
+    project_module
+  end
+
+  module Version
+    # Returns the major number in this version.
+    def major
+      to_s[/^\d+/]
+    end
+
+    # Returns a string describing any version with the current major number.
+    def series
+      "#{major}.x.x"
+    end
+
+    # Returns a Gem::Requirement expression.
+    def requirement
+      "~> #{major}"
+    end
+  end
+
+  ##
+  # Interface to translations of human text used in a project.
+  #
+  class Phrases
+    def initialize project_install_dir
+      # load language translations dynamically
+        lang_dir = File.join(project_install_dir, 'lang')
+
+        @phrases_by_language = Hash.new do |cache, language|
+          # store the phrase upon failure so that
+          # the phrases() method will know about it
+          phrases = Hash.new {|h,k| h[k] = nil }
+
+          lang_file = File.join(lang_dir, "#{language}.yaml")
+          lang_data = YAML.load_file(lang_file) rescue nil
+          phrases.merge! lang_data if lang_data
+
+          cache[language] = phrases
+        end
+
+      # detect user's preferred locale
+      self.locale = ENV['LC_ALL'] || ENV['LC_MESSAGES'] || ENV['LANG']
+    end
+
+    # The locale into which the #[] method will translate phrases.
+    attr_reader :locale
+
+    def locale= locale
+      @locale = locale.to_s
+
+      # extract the language portion of the locale
+      language  = @locale[/^[[:alpha:]]+/].to_s
+      @language = language =~ /^(C|POSIX)?$/i ? :en : language.downcase.to_sym
+    end
+
+    ##
+    # Returns all phrases that underwent (or
+    # attempted) translation via this object.
+    #
+    def phrases
+      @phrases_by_language.values.map {|h| h.keys }.flatten.uniq.sort
+    end
+
+    ##
+    # Translates the given phrase into the target
+    # locale (see #locale and #locale=) and then
+    # substitutes the given placeholder arguments
+    # into the translation (see Kernel#sprintf).
+    #
+    # If a translation is not available for the given phrase,
+    # then the given phrase will be used as-is, untranslated.
+    #
+    def [] phrase, *words
+      translate @language, phrase, *words
+    end
+
+    ##
+    # Provides access to translations in any language, regardless
+    # of the target locale (see #locale and #locale=).
+    #
+    # For example, you can access Japanese translations via
+    # the #jp method even if the target locale is French.
+    #
+    def method_missing meth, *args
+      # ISO 639 language codes come in alpha-2 and alpha-3 forms
+      if meth.to_s =~ /^[a-z]{2,3}$/
+        translate meth, *args
+      else
+        super
+      end
+    end
+
+    private
+
+    ##
+    # Translates the given phrase into the given language and then substitutes
+    # the given placeholder arguments into the translation (see Kernel#sprintf).
+    #
+    # If the translation is not available, then
+    # the given string will be used instead.
+    #
+    def translate language, phrase, *words
+      (@phrases_by_language[language][phrase.to_s] || phrase).to_s % words
+    end
+  end
+end