konjac 0.1.8.7 → 0.1.9

data/README.rdoc

@@ -1,4 +1,4 @@
-= konjac
+= Konjac
 
 A Ruby command-line utility for translating files using a YAML wordlist
 
@@ -18,11 +18,13 @@ following in your terminal:
 
 === Development
 
-With Ruby and {Git}[http://help.github.com/set-up-git-redirect] installed,
-navigate in your command line to a directory of your choice, then run:
+With Ruby, {Git}[http://help.github.com/set-up-git-redirect] and
+{Bundler}[http://gembundler.com/] installed, navigate in your command line to a
+directory of your choice, then run:
 
     git clone git://github.com/brymck/konjac.git
     cd konjac
+    bundle update
     rake install
 
 == Usage
@@ -133,10 +135,25 @@ Run
 Now, obviously that does require some fiddling to make it more grammatical, but
 it's a start (=> <tt>僕は犬が好きだ。</tt>)
 
+== Documentation
+
+Should be simple enough to generate yourself:
+
+    rm -rf konjac
+    git clone git://github.com/brymck/konjac
+    cd konjac
+    bundle update
+    rake rdoc
+    rm -rf !(doc)
+    mv doc/rdoc/* .
+    rm -rf doc
+
 == Name
 
 <em>Hon'yaku</em> means "translation" in Japanese. This utility relies on a
-YAML wordlist. <em>Konnyaku</em> (Japanese for "konjac") rhymes with
-<em>hon'yaku</em> and is a type of yam. Also, Doraemon had something called a
-<em>hon'yaku konnyaku</em> that allowed one to listen to animals. But I
-digress.
+<b>YAM</b>L wordlist. <em>Konnyaku</em> (Japanese for
+"{konjac}[http://en.wikipedia.org/wiki/Konjac]") rhymes with <em>hon'yaku</em>
+and is a type of <b>yam</b>. Also,
+{Doraemon}[http://en.wikipedia.org/wiki/Doraemon] had something called a
+<em>hon'yaku konnyaku</em> that allowed him to speak every language. IIRC it
+worked with animals too. But I digress.

data/Rakefile

@@ -14,6 +14,7 @@ RDoc::Task.new do |rdoc|
   rdoc.options << "-c" << "utf-8"
   rdoc.options << "-g"                   # link to GitHub
   rdoc.options << "-m" << "README.rdoc"  # use README.rdoc as main file
+  rdoc.options << "-v"                   # verbose
 
   rdoc.rdoc_files.include "README.rdoc"
   rdoc.rdoc_files.include "ext/**/*.{c, h, rb}"

data/lib/konjac/cli.rb

@@ -3,13 +3,17 @@ require "trollop"
 require "yaml"
 
 module Konjac
+  # The class containing the command line interface
   module CLI
-    class Color
+    class Color  # :nodoc:
       extend Term::ANSIColor
     end
 
     class << self
+      # A list of valid subcommands
       SUB_COMMANDS = ["add", "edit", "export", "import", "language", "translate"]
+
+      # The banner to displaying when requesting help through the command line
       BANNER = <<-eos
 #{Color.bold { Color.underscore { "KONJAC" } }}
 
@@ -20,6 +24,8 @@ module Konjac
 #{I18n.t(:where_options) % Color.underscore(I18n.t(:options))}
 eos
 
+      # Starts the command line, parsing arguments passed via <tt>ARGV</tt> and
+      # running the respective commands
       def start
         ARGV << "-h" if ARGV.empty?
         global_opts = Trollop::options do
@@ -119,7 +125,8 @@ eos
 
       private
       
-      def translate(files, opts = {})
+      # Parse commands to determine what should be translated and how
+      def translate(files, opts = {})  # :doc:
         to_lang = Language.find(opts[:to]).to_s
 
         if opts[:word]

data/lib/konjac/config.rb

@@ -2,10 +2,13 @@ require "i18n"
 require "yaml"
 
 module Konjac
+  # User settings
   module Config
     class << self
+      # The path to the user's configuration file
       CONFIG_PATH = File.expand_path("~/.konjac/config.yml")
 
+      # Loads the user's settings
       def load
         Utils.verify_file CONFIG_PATH, "--- {}"
         config = YAML.load_file(CONFIG_PATH)
@@ -15,15 +18,19 @@ module Konjac
         save
       end
 
+      # The current interface language
       def language
         I18n.locale
       end
 
+      # Sets the language to use for the interface. Note that this has no
+      # effect in determining the to or from languages to use for translation
       def language=(lang)
         set_language lang, I18n.locale
         save
       end
 
+      # Saves the user configurations
       def save
         File.open(CONFIG_PATH, "w") do |file|
           YAML.dump @opts, file
@@ -32,6 +39,11 @@ module Konjac
 
       private
 
+      # Calculates the language based on the available languages in the gem
+      # locale files versus the supplied parameters, in order. Suggested backup
+      # parameters are the system language (<tt>ENV["LANG"]</tt>), the current
+      # locale (<tt>I18n.locale</tt>), the default locale
+      # (<tt>I18n.default_locale</tt>), etc.
       def set_language(*params)
         I18n.load_path = Dir[File.join(File.dirname(__FILE__), "..", "..", "locales", "*.yml")]
         I18n.default_locale = :en

data/lib/konjac/dictionary.rb

@@ -1,12 +1,27 @@
 require "yaml"
 
 module Konjac
+  # A module for loading and manipulating the user's dictionaries
   module Dictionary
     class << self
-      attr_accessor :from_lang, :to_lang, :dictionaries, :pairs
+      # The most recent language from which to translate
+      attr_accessor :from_lang
+      
+      # The most recent language into which to translated
+      attr_accessor :to_lang
+      
+      # The dictionaries currently in use
+      attr_accessor :dictionaries
+      
+      # The current pairs
+      attr_accessor :pairs
 
+      # A regular expression used to determine whether a string is blank
       BLANK = /^\s*$/
 
+      # Loads the specified languages and dictionaries
+      #
+      #   Dictionary.load :en, :ja, :using => [:dict]
       def load(from_lang, to_lang, opts = {})
         # Allow both symbol and string arguments for languages
         from_lang = from_lang.to_s
@@ -41,6 +56,8 @@ module Konjac
         @pairs
       end
 
+      # Extracts a regular expression and string replacement pair from a term
+      # in the Dictionary, based on the supplied languages and their templates
       def extract_pair_from_term(term, from_lang, to_lang, from_template, to_template)
         if term.has_key?(to_lang)
           # Build to term depending on whether it's a hash for complex
@@ -171,29 +188,16 @@ module Konjac
 
       private
 
-      def parse_language(lang)
-        if @dictionary["languages"].has_key?(lang)
-          return lang
-        else
-          @dictionary["languages"].each do |main, alternatives|
-            return main if alternatives.include?(lang)
-          end
-
-          # If no match is found, give an error message and exit
-          raise Exceptions::InvalidLanguageError.new("No match found for language \"#{lang}\"")
-          exit 1
-        end
-      end
-
       # Caches variables so we can determine later on whether to reload the
       # dictionaries or not
-      def cache_load(from_lang, to_lang, dictionaries)
+      def cache_load(from_lang, to_lang, dictionaries)  # :doc:
         @from_lang    = from_lang
         @to_lang      = to_lang
         @dictionaries = dictionaries
       end
       
-      def load_serialized(from_lang, to_lang, dictionaries)
+      # Loads a marshalled Dictionary
+      def load_serialized(from_lang, to_lang, dictionaries)  # :doc:
         file_name = File.expand_path("~/.konjac/marshal/%s_%s_%s" %
           [from_lang, to_lang, dictionaries.join("_")])
         if File.exists?(file_name)
@@ -203,7 +207,8 @@ module Konjac
         end
       end
 
-      def save_serialized(from_lang, to_lang, dictionaries, pairs)
+      # Saves a marshalled Dictionary
+      def save_serialized(from_lang, to_lang, dictionaries, pairs)  # :doc:
         file_name = File.expand_path("~/.konjac/marshal/%s_%s_%s" %
           [from_lang, to_lang, dictionaries.join("_")])
 
@@ -219,7 +224,7 @@ module Konjac
 
       # Builds a list of dictionaries from the supplied files, defaulting to
       # ~/.konjac/*.yml
-      def build_dictionary(files)
+      def build_dictionary(files)  # :doc:
         dictionary = []
         find_dictionaries(files).each do |dict|
           verify_dictionary_exists dict
@@ -229,9 +234,11 @@ module Konjac
         dictionary
       end
 
-      def find_dictionaries(files)
+      # Finds dictionaries based on the supplied Array
+      def find_dictionaries(files)  # :doc:
         paths = []
         files.each do |file|
+          file = file.to_s
           if file =~ /[\/.]/
             full_path = File.expand_path(file)
           else

data/lib/konjac/exception.rb

@@ -1,4 +1,8 @@
 module Konjac
+  # Konjac was unable to find an applicable file
   class FileNotFoundError < StandardError; end
+
+  # The user has supplied an invalid language and Konjac can't continue to
+  # process the request
   class InvalidLanguageError < StandardError; end
 end

data/lib/konjac/language.rb

@@ -1,7 +1,13 @@
 module Konjac
+  # A class for language lookup
   module Language
     class << self
+      # Languages that don't use spaces. Obviously this is an incomplete list.
       LANGUAGES_WITHOUT_SPACES = [:ar, :he, :ja, :zh]
+
+      # A hash list of languages. The keys are the two-letter ISO codes and the
+      # values are alternative names, including the three-letter ISO code and
+      # the English name
       LIST = {
         :ab => [:abkhazian,           :abk],
         :aa => [:afar,                :aar],
@@ -216,7 +222,13 @@ module Konjac
         :zu => [:zulu,                :zul]
       }
 
-      # Finds the two-letter code for the specified language
+      # Finds the two-letter code for the specified language.
+      #
+      #   Language.find(:english)  # => :en
+      #   Language.find(:eng)      # => :en
+      #   Language.find(:en)       # => :en
+      #   Language.find(:japanese) # => :ja
+      #   Language.find(:klingon)  # => raises Konjac::InvalidLanguageError
       def find(lang)
         # Allow function to accept both symbol and string arguments
         lang = lang.to_sym
@@ -243,7 +255,7 @@ module Konjac
       private
 
       # Convert to underscore case
-      def underscore(str)
+      def underscore(str)  # :doc:
         str.to_s.                              # allow symbols and strings
         gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').  # underscore-delimit caps
         gsub(/([a-z\d])\s?([A-Z])/,'\1_\2').   # underscore-delimit words

data/lib/konjac/tag.rb

@@ -1,17 +1,50 @@
+# coding: utf-8
 module Konjac
+  # A tag containing original text and (if available) its translation, plus the
+  # index of the <w:t> tag extracted from its .docx document
   class Tag
-    attr_accessor :index, :original, :translated
+    # The index of the <w:t> tag in the cleaned-up XML file output by
+    # Konjac::Word.export_docx_tags
+    attr_accessor :index
+    
+    # The original text
+    attr_accessor :original
+      
+    # The translated text
+    attr_accessor :translated
 
+    # Creates a new tag.
+    #
+    #   t = Tag.new(1, "dog", "犬")
     def initialize(index, original, translated)
       @index, @original, @translated = index, original, translated
     end
 
+    # Converts the Tag into a string for use in .konjac files
+    #
+    # <tt>Tag.new(1, "dog", "犬").to_s</tt> will output
+    #
+    #   [[KJ-1]]
+    #   > dog
+    #   犬
+    #
+    # whereas <tt>Tag.new(2, "cat").to_s</tt> will output
+    #
+    #   [[KJ-2]]
+    #   > cat
     def to_s
       "[[KJ-#{index}]]\n> #{original}#{"\n" + translated if translated?}"
     end
 
+    # Whether the tag has been translated
+    #
+    #   dog = Tag.new(1, "dog", "犬")
+    #   dog.translated? # => true
+    #
+    #   cat = Tag.new(1, "cat", "")
+    #   cat.translated? # => false
     def translated?
-      !!translated
+      !translated.nil? && translated != ""
     end
   end
 end

data/lib/konjac/tag_manager.rb

@@ -1,15 +1,24 @@
 module Konjac
+  # A class for managing the tags generated by extraction from {Microsoft
+  # Word}[http://office.microsoft.com/en-us/word/] 2003+ documents
   class TagManager
+    # A list of the Tag objects current being managed
     attr_accessor :tags
 
+    # A regex to match lines that start with <tt>> </tt>, that is, lines that
+    # indicate original text in .konjac files
     STARTS_WITH_CLOSE_TAG = /^\>/
+
+    # Regex for matching index numbers
     KONJAC_TAG = /^\[\[KJ\-(\d+)\]\]/
 
+    # Creates a new TagManager
     def initialize(path)
       @tags = []
       parse_lines File.readlines(path)
     end
 
+    # Parses the lines of a file into Tag objects
     def parse_lines(lines)
       index      = nil
       orig       = nil
@@ -39,10 +48,12 @@ module Konjac
       end
     end
 
+    # A list of all the tags available
     def all
       @tags
     end
 
+    # Finds the <em>nth</em> tag being managed
     def [](index)
       @tags[index]
     end

data/lib/konjac/translator.rb

@@ -1,7 +1,12 @@
 # coding: utf-8
 module Konjac
+  # A class consisting of functions for translation
   module Translator
     class << self
+      # Translates a file or list of files
+      #
+      #   path = Dir[File.expand_path("~/.konjac/test_en.txt")]
+      #   Translator.translate_files path, :en, :ja, :using => [:dict]
       def translate_files(files, from_lang, to_lang, opts = {})
         load_dictionary from_lang, to_lang, opts
         

data/lib/konjac/utils.rb

@@ -1,4 +1,6 @@
 module Konjac
+  # A handful of functions and tools with no other home, primarily for
+  # manipulating file names and paths
   module Utils
     class << self
       # Extracts the two letter language code from a filename

data/lib/konjac/version.rb

@@ -1,3 +1,4 @@
 module Konjac
-  VERSION = "0.1.8.7"
+  # The current version number of Konjac
+  VERSION = "0.1.9"
 end

data/lib/konjac/word.rb

@@ -1,9 +1,10 @@
-# This really needs cleanup
-
 module Konjac
+  # A singleton for dealing with extracting and importing tags from {Microsoft
+  # Word}[http://office.microsoft.com/en-us/word/] 2003+ documents
   module Word
     class << self
-      # Extracts the text content from a Microsoft Word 2003+ Document
+      # Imports the text content of a tag file into a {Microsoft
+      # Word}[http://office.microsoft.com/en-us/word/] 2003+ document
       def import_docx_tags(files)
         sub_files = Utils.parse_files(files, ".docx")
         sub_files.each do |sub_file|
@@ -46,7 +47,8 @@ module Konjac
         end
       end
 
-      # Exports the text content from a Microsoft Word 2003+ Document
+      # Exports the text content of {Microsoft
+      # Word}[http://office.microsoft.com/en-us/word/] 2003+ document
       def export_docx_tags(files, opts = {})
         # Determine whether to attempt translating
         if opts[:from_given] && opts[:to_given]
@@ -117,7 +119,7 @@ module Konjac
         end
       end
 
-      # Opens the .konjac tag files for the specified DOCX files
+      # Opens the .konjac tag files for the specified .docx files
       def edit_docx_tags(files)
         sub_files = Utils.force_extension(files, ".konjac")
         sub_files.each do |sub_file|
@@ -129,13 +131,14 @@ module Konjac
 
       # Performs a comparison between two nodes and accepts them as equivalent
       # if the differences are very minor
-      def compare_nodes(a, b)
+      def compare_nodes(a, b)  # :doc:
         c = clean_hash(xml_node_to_hash(a))
         d = clean_hash(xml_node_to_hash(b))
         c == d
       end
 
-      def xml_node_to_hash(node)
+      # Converts an XML node into a Ruby hash
+      def xml_node_to_hash(node)  # :doc:
         # If we are at the root of the document, start the hash
         if node.element?
           result_hash = {}
@@ -173,18 +176,19 @@ module Konjac
         end
       end
 
-      def prepare(data)
+      # Prepares data according to whether it's string or integer content
+      def prepare(data)  # :doc:
         (data.class == String && data.to_i.to_s == data) ? data.to_i : data
       end
 
       # Delete extraneous attributes for comparison
-      def clean_hash(hash)
+      def clean_hash(hash)  # :doc:
         delete_attribute_or_child hash, :t
         delete_attribute_or_child hash, :rPr, :rFonts, :attributes, :hint
       end
 
       # Get additional information on the node for context in tags file
-      def additional_info(node)
+      def additional_info(node)  # :doc:
         info = []
         info << "hyperlink" if node.parent.parent.name == "hyperlink"
 
@@ -195,9 +199,12 @@ module Konjac
         end
       end
 
-      private
-
-      def delete_attribute_or_child(node, *hierarchy)
+      # Deletes the specified attribute or child node for the supplied node,
+      # following the hierarchy provided
+      #
+      # Delete <tt>hash[:rPr][:rFonts][:attributes][:hint]</tt>:
+      #   delete_attribute_or_child hash, :rPr, :rFonts, :attributes, :hint
+      def delete_attribute_or_child(node, *hierarchy)  # :doc:
         last_member = hierarchy.pop
         
         hierarchy.each do |member|

data/lib/konjac.rb

@@ -4,6 +4,8 @@ autoload :FileUtils, "fileutils"
 autoload :I18n,      "i18n"
 autoload :Nokogiri,  "nokogiri"
 
+# Konjac is a Ruby command-line utility for translating files using a YAML
+# wordlist
 module Konjac
   # Set up autoload for all modules
   autoload :CLI,        "konjac/cli"

data/locales/en.yml

@@ -1,5 +1,5 @@
 en:
-  banner: konjac is a Ruby command-line utility for translating files using a YAML wordlist
+  banner: Konjac is a Ruby command-line utility for translating files using a YAML wordlist
   filenames: filenames
   me: Bryan McKelvey
   options: options

data/locales/ja.yml

@@ -1,5 +1,5 @@
 ja:
-  banner: konjacはYAML辞書でファイルを翻訳するRubyのコマンドライン・ユーティリティです。
+  banner: KonjacはYAML辞書でファイルを翻訳するRubyのコマンドライン・ユーティリティです。
   filenames: ファイル名
   me: ブライアン・マッケルビー
   options: オプション

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: konjac
 version: !ruby/object:Gem::Version
-  version: 0.1.8.7
+  version: 0.1.9
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2012-01-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: i18n
-  requirement: &70230529874200 !ruby/object:Gem::Requirement
+  requirement: &70270392674560 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70230529874200
+  version_requirements: *70270392674560
 - !ruby/object:Gem::Dependency
   name: nokogiri
-  requirement: &70230529873780 !ruby/object:Gem::Requirement
+  requirement: &70270392674140 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70230529873780
+  version_requirements: *70270392674140
 - !ruby/object:Gem::Dependency
   name: sdoc
-  requirement: &70230529873360 !ruby/object:Gem::Requirement
+  requirement: &70270392673660 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70230529873360
+  version_requirements: *70270392673660
 - !ruby/object:Gem::Dependency
   name: term-ansicolor
-  requirement: &70230529872940 !ruby/object:Gem::Requirement
+  requirement: &70270392673220 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70230529872940
+  version_requirements: *70270392673220
 - !ruby/object:Gem::Dependency
   name: trollop
-  requirement: &70230529872460 !ruby/object:Gem::Requirement
+  requirement: &70270392672620 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70230529872460
+  version_requirements: *70270392672620
 - !ruby/object:Gem::Dependency
   name: autotest
-  requirement: &70230529872020 !ruby/object:Gem::Requirement
+  requirement: &70270392672080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +76,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70230529872020
+  version_requirements: *70270392672080
 - !ruby/object:Gem::Dependency
   name: autotest-fsevent
-  requirement: &70230529871480 !ruby/object:Gem::Requirement
+  requirement: &70270392671480 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,10 +87,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70230529871480
+  version_requirements: *70270392671480
 - !ruby/object:Gem::Dependency
   name: autotest-growl
-  requirement: &70230529870940 !ruby/object:Gem::Requirement
+  requirement: &70270392670840 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -98,10 +98,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70230529870940
+  version_requirements: *70270392670840
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &70230529870360 !ruby/object:Gem::Requirement
+  requirement: &70270392630600 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -109,10 +109,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70230529870360
+  version_requirements: *70270392630600
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70230529885720 !ruby/object:Gem::Requirement
+  requirement: &70270392629960 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -120,7 +120,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70230529885720
+  version_requirements: *70270392629960
 description: A Ruby command-line utility for translating files using a YAML wordlist
 email:
 - bryan.mckelvey@gmail.com