deg-yard 0.8.7.1

data/lib/yard/i18n/locale.rb

@@ -0,0 +1,74 @@
+module YARD
+  module I18n
+    # +Locale+ is a unit of translation. It has {#name} and a set of
+    # messages.
+    #
+    # @since 0.8.2
+    class Locale
+      class << self
+        # @return [String, nil] the default locale name.
+        # @since 0.8.4
+        attr_accessor :default
+
+        undef default
+        def default
+          @@default ||= nil
+        end
+
+        undef default=
+        def default=(locale)
+          @@default = locale
+        end
+      end
+
+      # @return [String] the name of the locale. It used IETF language
+      #   tag format +[language[_territory][.codeset][@modifier]]+.
+      # @see http://tools.ietf.org/rfc/bcp/bcp47.txt
+      #   BCP 47 - Tags for Identifying Languages
+      attr_reader :name
+
+      # Creates a locale for +name+ locale.
+      #
+      # @param [String] name the locale name.
+      def initialize(name)
+        @name = name
+        @messages = {}
+      end
+
+      # Loads translation messages from +locale_directory+/{#name}.po.
+      #
+      # @param [String] locale_directory the directory path that has
+      #   {#name}.po.
+      # @return [Boolean] +true+ if PO file exists, +false+ otherwise.
+      def load(locale_directory)
+        return false if @name.nil?
+
+        po_file = File.join(locale_directory, "#{@name}.po")
+        return false unless File.exist?(po_file)
+
+        begin
+          require "gettext/tools/poparser"
+          require "gettext/runtime/mofile"
+        rescue LoadError
+          log.warn "Need gettext gem for i18n feature:"
+          log.warn "  gem install gettext"
+          return false
+        end
+
+        parser = GetText::PoParser.new
+        parser.report_warning = false
+        data = GetText::MoFile.new
+        parser.parse_file(po_file, data)
+        @messages.merge!(data)
+        true
+      end
+
+      # @param [String] message the translation target message.
+      # @return [String] translated message. If tarnslation isn't
+      #   registered, the +message+ is returned.
+      def translate(message)
+        @messages[message] || message
+      end
+    end
+  end
+end

data/lib/yard/i18n/message.rb

@@ -0,0 +1,56 @@
+require "set"
+
+module YARD
+  module I18n
+    # +Message+ is a translation target message. It has message ID as
+    # {#id} and some properties {#locations} and {#comments}.
+    #
+    # @since 0.8.1
+    class Message
+      # @return [String] the message ID of the trnslation target message.
+      attr_reader :id
+
+      # @return [Set] the set of locations. Location is an array of 
+      # path and line number where the message is appeared.
+      attr_reader :locations
+
+      # @return [Set] the set of comments for the messages.
+      attr_reader :comments
+
+      # Creates a trasnlate target message for message ID +id+.
+      #
+      # @param [String] id the message ID of the translate target message.
+      def initialize(id)
+        @id = id
+        @locations = Set.new
+        @comments = Set.new
+      end
+
+      # Adds location information for the message.
+      #
+      # @param [String] path the path where the message appears.
+      # @param [Integer] line the line number where the message appears.
+      # @return [void]
+      def add_location(path, line)
+        @locations << [path, line]
+      end
+
+      # Adds a comment for the message.
+      #
+      # @param [String] comment the comment for the message to be added.
+      # @return [void]
+      def add_comment(comment)
+        @comments << comment unless comment.nil?
+      end
+
+      # @param [Message] other the +Message+ to be compared.
+      # @return [Boolean] checks whether this message is equal to another.
+      def ==(other)
+        other.is_a?(self.class) and
+          @id == other.id and
+          @locations == other.locations and
+          @comments == other.comments
+      end
+    end
+  end
+end

data/lib/yard/i18n/messages.rb

@@ -0,0 +1,55 @@
+module YARD
+  module I18n
+    # Acts as a container for {Message} objects.
+    #
+    # @since 0.8.1
+    class Messages
+      include Enumerable
+
+      # Creates a new container.
+      def initialize
+        @messages = {}
+      end
+
+      # Enumerates each {Message} in the container.
+      #
+      # @yieldparam [Message] message the next message object in
+      #   the enumeration.
+      # @return [void]
+      def each(&block)
+        @messages.each_value(&block)
+      end
+
+      # @param [String] id the message ID to perform a lookup on.
+      # @return [Message, nil] a registered message for the given +id+,
+      #   or nil if no message for the ID is found.
+      def [](id)
+        @messages[id]
+      end
+
+      # Registers a {Message}, the mssage ID of which is +id+. If
+      # corresponding +Message+ is already registered, the previously
+      # registered object is returned.
+      #
+      # @param [String] id the ID of the message to be registered.
+      # @return [Message] the registered +Message+.
+      def register(id)
+        @messages[id] ||= Message.new(id)
+      end
+
+      # Checks if this messages list is equal to another messages list.
+      #
+      # @param [Messages] other the container to compare.
+      # @return [Boolean] whether +self+ and +other+ is equivalence or not.
+      def ==(other)
+        other.is_a?(self.class) and
+          @messages == other.messages
+      end
+
+      protected
+
+      # @return [Hash{String=>Message}] the set of message objects
+      attr_reader :messages
+    end
+  end
+end

data/lib/yard/i18n/pot_generator.rb

@@ -0,0 +1,280 @@
+require "stringio"
+
+module YARD
+  module I18n
+    # The +PotGenerator+ generates POT format string from
+    # {CodeObjects::Base} and {CodeObjects::ExtraFileObject}.
+    #
+    # == POT and PO
+    #
+    # POT is an acronym for "Portable Object Template". POT is a
+    # template file to create PO file. The extension for POT is
+    # ".pot". PO file is an acronym for "Portable Object". PO file has
+    # many parts of message ID (msgid) that is translation target
+    # message and message string (msgstr) that is translated message
+    # of message ID. If you want to tranlsate "Hello" in English into
+    # "Bonjour" in French, "Hello" is the msgid ID and "Bonjour" is
+    # msgstr. The extension for PO is ".po".
+    #
+    # == How to extract msgids
+    #
+    # The +PotGenerator+ has two parse methods:
+    #
+    # * {#parse_objects} for {CodeObjects::Base}
+    # * {#parse_files} for {CodeObjects::ExtraFileObject}
+    #
+    # {#parse_objects} extracts msgids from docstring and tags of
+    # {CodeObjects::Base} objects. The docstring of
+    # {CodeObjects::Base} object is parsed and a paragraph is
+    # extracted as a msgid. Tag name and tag text are extracted as
+    # msgids from a tag.
+    #
+    # {#parse_files} extracts msgids from
+    # {CodeObjects::ExtraFileObject} objects. The file content of
+    # {CodeObjects::ExtraFileObject} object is parsed and a paragraph
+    # is extracted as a msgid.
+    #
+    # == Usage
+    #
+    # To create a .pot file by +PotGenerator+, instantiate a
+    # +PotGenerator+ with a relative working directory path from a
+    # directory path that has created .pot file, parse
+    # {CodeObjects::Base} objects and {CodeObjects::ExtraFileObject}
+    # objects, generate a POT and write the generated POT to a .pot
+    # file. The relative working directory path is ".." when the
+    # working directory path is "."  and the POT is wrote into
+    # "po/yard.pot".
+    #
+    # @example Generate a .pot file
+    #   po_file_path = "po/yard.pot"
+    #   po_file_directory_pathname = Pathname.new(po_file_path).directory)
+    #   working_directory_pathname = Pathname.new(".")
+    #   relative_base_path = working_directory_pathname.relative_path_from(po_file_directory_pathname).to_s
+    #   # relative_base_path -> ".."
+    #   generator = YARD::I18n::PotGenerator.new(relative_base_path)
+    #   generator.parse_objects(objects)
+    #   generator.parse_files(files)
+    #   pot = generator.generate
+    #   po_file_directory_pathname.mkpath
+    #   File.open(po_file_path, "w") do |pot_file|
+    #     pot_file.print(pot)
+    #   end
+    # @see http://www.gnu.org/software/gettext/manual/html_node/PO-Files.html
+    #   GNU gettext manual about details of PO file
+    class PotGenerator
+      # Extracted messages.
+      #
+      # @return [Messages]
+      # @since 0.8.1
+      attr_reader :messages
+
+      # Creates a POT generator that uses +relative_base_path+ to
+      # generate locations for a msgid. +relative_base_path+ is
+      # prepended to all locations.
+      #
+      # @param [String] relative_base_path a relative working
+      #   directory path from a directory path that has created .pot
+      #   file.
+      def initialize(relative_base_path)
+        @relative_base_path = relative_base_path
+        @extracted_objects = {}
+        @messages = Messages.new
+      end
+
+      # Parses {CodeObjects::Base} objects and stores extracted msgids
+      # into {#messages}
+      #
+      # @param [Array<CodeObjects::Base>] objects a list of
+      #   {CodeObjects::Base} to be parsed.
+      # @return [void]
+      def parse_objects(objects)
+        objects.each do |object|
+          extract_documents(object)
+        end
+      end
+
+      # Parses {CodeObjects::ExtraFileObject} objects and stores
+      # extracted msgids into {#messages}.
+      #
+      # @param [Array<CodeObjects::ExtraFileObject>] files a list
+      #   of {CodeObjects::ExtraFileObject} objects to be parsed.
+      # @return [void]
+      def parse_files(files)
+        files.each do |file|
+          extract_paragraphs(file)
+        end
+      end
+
+      # Generates POT from +@messages+.
+      #
+      # One PO file entry is generated from a +Message+ in
+      # +@messages+.
+      #
+      # Locations of the +Message+ are used to generate the reference
+      # line that is started with "#: ". +relative_base_path+ passed
+      # when the generater is created is prepended to each path in location.
+      #
+      # Comments of the +Message+ are used to generate the
+      # translater-comment line that is started with "# ".
+      #
+      # @return [String] POT format string
+      def generate
+        pot = header
+        sorted_messages = @messages.sort_by do |message|
+          sorted_locations = message.locations.sort_by do |location|
+            location
+          end
+          sorted_locations.first || []
+        end
+        sorted_messages.each do |message|
+          generate_message(pot, message)
+        end
+        pot
+      end
+
+      private
+      def header
+        <<-'EOH'
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
+# This file is distributed under the same license as the PACKAGE package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: PACKAGE VERSION\n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2011-11-20 22:17+0900\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"Language: \n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+EOH
+      end
+
+      def generate_message(pot, message)
+        message.comments.sort.each do |comment|
+          pot << "# #{comment}\n" unless comment.empty?
+        end
+        message.locations.sort.each do |path, line|
+          pot << "#: #{@relative_base_path}/#{path}:#{line}\n"
+        end
+        escaped_message_id = escape_message_id(message.id)
+        escaped_message_id = escaped_message_id.gsub(/\n/, "\\\\n\"\n\"")
+        pot << "msgid \"#{escaped_message_id}\"\n"
+        pot << "msgstr \"\"\n"
+        pot << "\n"
+        pot
+      end
+
+      def escape_message_id(message_id)
+        message_id.gsub(/(\\|")/) do
+          special_character = $1
+          "\\#{special_character}"
+        end
+      end
+
+      def register_message(id)
+        @messages.register(id)
+      end
+
+      def extract_documents(object)
+        return if @extracted_objects.has_key?(object)
+
+        @extracted_objects[object] = true
+        case object
+        when CodeObjects::NamespaceObject
+          object.children.each do |child|
+            extract_documents(child)
+          end
+        end
+
+        if object.group
+          message = register_message(object.group)
+          object.files.each do |path, line|
+            message.add_location(path, line)
+          end
+          message.add_comment(object.path) unless object.path.empty?
+        end
+
+        docstring = object.docstring
+        unless docstring.empty?
+          text = Text.new(StringIO.new(docstring))
+          text.extract_messages do |type, *args|
+            case type
+            when :paragraph
+              paragraph, line_no = *args
+              message = register_message(paragraph.rstrip)
+              object.files.each do |path, line|
+                message.add_location(path, (docstring.line || line) + line_no)
+              end
+              message.add_comment(object.path) unless object.path.empty?
+            else
+              raise "should not reach here: unexpected type: #{type}"
+            end
+          end
+        end
+        docstring.tags.each do |tag|
+          extract_tag_documents(tag)
+        end
+      end
+
+      def extract_tag_documents(tag)
+        extract_tag_name(tag)
+        extract_tag_text(tag)
+      end
+
+      def extract_tag_name(tag)
+        return if tag.name.nil?
+        return if tag.name.is_a?(String) and tag.name.empty?
+        key = "tag|#{tag.tag_name}|#{tag.name}"
+        message = register_message(key)
+        tag.object.files.each do |path, line|
+          message.add_location(path, line)
+        end
+        tag_label = "@#{tag.tag_name}"
+        tag_label << " [#{tag.types.join(', ')}]" if tag.types
+        message.add_comment(tag_label)
+      end
+
+      def extract_tag_text(tag)
+        return if tag.text.nil?
+        return if tag.text.empty?
+        message = register_message(tag.text)
+        tag.object.files.each do |path, line|
+          message.add_location(path, line)
+        end
+        tag_label = "@#{tag.tag_name}"
+        tag_label << " [#{tag.types.join(', ')}]" if tag.types
+        tag_label << " #{tag.name}" if tag.name
+        message.add_comment(tag_label)
+      end
+
+      def extract_paragraphs(file)
+        File.open(file.filename) do |input|
+          text = Text.new(input, :have_header => true)
+          text.extract_messages do |type, *args|
+            case type
+            when :attribute
+              name, value, line_no = *args
+              message = register_message(value)
+              message.add_location(file.filename, line_no)
+              message.add_comment(name)
+            when :paragraph
+              paragraph, line_no = *args
+              message = register_message(paragraph.rstrip)
+              message.add_location(file.filename, line_no)
+            else
+              raise "should not reach here: unexpected type: #{type}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/i18n/text.rb

@@ -0,0 +1,173 @@
+module YARD
+  module I18n
+    # Provides some convenient features for translating a text.
+    class Text
+      # Creates a text object that has translation related features for
+      # the input text.
+      #
+      # @param [#each_line] input a text to be translated.
+      # @option options [Boolean] :have_header (false) whether the
+      #   input text has header or not.
+      def initialize(input, options={})
+        @input = input
+        @options = options
+      end
+
+      # Extracts translation target messages from +@input+.
+      #
+      # @yield [:attribute, name, value, line_no] the block that
+      #   recieves extracted an attribute in header. It may called many
+      #   times.
+      # @yieldparam [String] name the name of extracted attribute.
+      # @yieldparam [String] value the value of extracted attribute.
+      # @yieldparam [Integer] line_no the defined line number of extracted
+      #   attribute.
+      # @yield [:paragraph, text, start_line_no] the block that
+      #   recieves extracted a paragraph in body. Paragraph is a text
+      #   block separated by one or more empty lines. Empty line is a
+      #   line that contains only zero or more whitespaces. It may
+      #   called many times.
+      # @yieldparam [String] text the text of extracted paragraph.
+      # @yieldparam [Integer] start_line_no the start line number of
+      #   extracted paragraph.
+      # @return [void]
+      def extract_messages
+        parse do |part|
+          line_no = part[:line_no]
+          case part[:type]
+          when :markup, :empty_line
+            # ignore
+          when :attribute
+            yield(:attribute, part[:name], part[:value], part[:line_no])
+          when :paragraph
+            yield(:paragraph, part[:paragraph], part[:line_no])
+          end
+        end
+      end
+
+      # Translates into +locale+.
+      #
+      # @param [Locale] locale the translation target locale.
+      # @return [String] translated text.
+      def translate(locale)
+        translated_text = ""
+        parse do |part|
+          case part[:type]
+          when :markup
+            translated_text << part[:line]
+          when :attribute
+            prefix = "#{part[:prefix]}#{part[:name]}#{part[:infix]}"
+            value = locale.translate(part[:value])
+            suffix = part[:suffix]
+            translated_text << "#{prefix}#{value}#{suffix}"
+          when :paragraph
+            translated_text << locale.translate(part[:paragraph])
+          when :empty_line
+            translated_text << part[:line]
+          else
+            raise "should not reach here: unexpected type: #{type}"
+          end
+        end
+        translated_text
+      end
+
+      private
+
+      def parse(&block)
+        paragraph = ""
+        paragraph_start_line = 0
+        line_no = 0
+        in_header = @options[:have_header]
+
+        @input.each_line do |line|
+          line_no += 1
+          if in_header
+            case line
+            when /^#!\S+\s*$/
+              if line_no == 1
+                emit_markup_event(line, line_no, &block)
+              else
+                in_header = false
+              end
+            when /^(\s*#\s*@)(\S+)(\s*)(.+?)(\s*)$/
+              emit_attribute_event(Regexp.last_match, line_no, &block)
+            else
+              in_header = false
+              if line.strip.empty?
+                emit_empty_line_event(line, line_no, &block)
+                next
+              end
+            end
+            next if in_header
+          end
+
+          case line
+          when /^\s*$/
+            if paragraph.empty?
+              emit_empty_line_event(line, line_no, &block)
+            else
+              paragraph << line
+              emit_paragraph_event(paragraph, paragraph_start_line, line_no,
+                                   &block)
+              paragraph = ""
+            end
+          else
+            paragraph_start_line = line_no if paragraph.empty?
+            paragraph << line
+          end
+        end
+
+        unless paragraph.empty?
+          emit_paragraph_event(paragraph, paragraph_start_line, line_no, &block)
+        end
+      end
+
+      def emit_markup_event(line, line_no)
+        part = {
+          :type => :markup,
+          :line => line,
+          :line_no => line_no,
+        }
+        yield(part)
+      end
+
+      def emit_attribute_event(match_data, line_no)
+        part = {
+          :type => :attribute,
+          :prefix => match_data[1],
+          :name => match_data[2],
+          :infix => match_data[3],
+          :value => match_data[4],
+          :suffix => match_data[5],
+          :line_no => line_no,
+        }
+        yield(part)
+      end
+
+      def emit_empty_line_event(line, line_no)
+        part = {
+          :type => :empty_line,
+          :line => line,
+          :line_no => line_no,
+        }
+        yield(part)
+      end
+
+      def emit_paragraph_event(paragraph, paragraph_start_line, line_no, &block)
+        paragraph_part = {
+          :type => :paragraph,
+          :line_no => paragraph_start_line,
+        }
+        match_data = /(\s*)\z/.match(paragraph)
+        if match_data
+          paragraph_part[:paragraph] = match_data.pre_match
+          yield(paragraph_part)
+          emit_empty_line_event(match_data[1], line_no, &block)
+        else
+          paragraph_part[:paragraph] = paragraph
+          yield(paragraph_part)
+        end
+      end
+    end
+  end
+end