yard 0.7.5 → 0.8.0

data/lib/yard/handlers/ruby/struct_handler_methods.rb

@@ -1,5 +1,7 @@
 # Helper methods to parse @attr_* tags on a class.
 #
+# @deprecated The use of +@attr+ tags are deprecated since 0.8.0 in favour of
+#   the +@!attribute+ directive. This module should not be relied on.
 # @since 0.5.6
 module YARD::Handlers::Ruby::StructHandlerMethods
   include YARD::CodeObjects
@@ -42,8 +44,7 @@ module YARD::Handlers::Ruby::StructHandlerMethods
   # Gets the return type for the member in a nicely formatted string. Used
   # to be injected into auto-generated docstrings.
   #
-  # @param [ClassObject] klass the class whose tags we're searching
-  # @param [String] member the name of the struct member whose return type we need
+  # @param [Tags::Tag] member_tag the tag object to check for types
   # @return [String] the user-declared type of the struct member, or [Object] if
   #   the user did not define a type for this member.
   def return_type_from_tag(member_tag)

data/lib/yard/i18n/pot_generator.rb

@@ -0,0 +1,281 @@
+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. Key is a translation target message and
+      # value is properties of the translation target message. The
+      # properties are added to the msgid entry for the translation
+      # target message. The properties are +:locations+ and
+      # +:comments+.
+      #
+      # +:locations+ is an array of location. Location is an array of
+      # path and line number of the translation target message is
+      # appeared. Each location is prepended +:relative_base_path+
+      # that is passed on creating a +PotGenerator+ instance.
+      #
+      # +:comments+ is an array of comment. All comments are added to
+      # the msgid entry for the translation target message.
+      #
+      # @api private
+      # @return [Hash{String => Hash{:locations => Array<Array[String, Integer]>, :comments => Array<String>}}]
+      attr_reader :messages
+
+      # Creates a POT generator that uses +relative_base_path+ to
+      # generate locations for a msgid.
+      #
+      # @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 = {}
+      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+.
+      #
+      # @return [String] POT format string
+      def generate
+        pot = header
+        sorted_messages = @messages.sort_by do |message, options|
+          sorted_locations = (options[:locations] || []).sort_by do |location|
+            location
+          end
+          sorted_locations.first || []
+        end
+        sorted_messages.each do |message, options|
+          generate_message(pot, message, options)
+        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, options)
+        options[:comments].compact.uniq.each do |comment|
+          pot << "# #{comment}\n" unless comment.empty?
+        end
+        options[:locations].uniq.each do |path, line|
+          pot << "#: #{@relative_base_path}/#{path}:#{line}\n"
+        end
+        escaped_message = escape_message(message)
+        escaped_message = escaped_message.gsub(/\n/, "\\\\n\"\n\"")
+        pot << "msgid \"#{escaped_message}\"\n"
+        pot << "msgstr \"\"\n"
+        pot << "\n"
+        pot
+      end
+
+      def escape_message(message)
+        message.gsub(/(\\|")/) do
+          special_character = $1
+          "\\#{special_character}"
+        end
+      end
+
+      def add_message(text)
+        @messages[text] ||= {:locations => [], :comments => []}
+      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 = add_message(object.group)
+          object.files.each do |path, line|
+            message[:locations] << [path, line]
+          end
+          message[:comments] << 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 = add_message(paragraph.rstrip)
+              object.files.each do |path, line|
+                message[:locations] << [path, (docstring.line || line) + line_no]
+              end
+              message[:comments] << 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 = add_message(key)
+        tag.object.files.each do |file|
+          message[:locations] << file
+        end
+        tag_label = "@#{tag.tag_name}"
+        tag_label << " [#{tag.types.join(', ')}]" if tag.types
+        message[:comments] << tag_label
+      end
+
+      def extract_tag_text(tag)
+        return if tag.text.nil?
+        return if tag.text.empty?
+        message = add_message(tag.text)
+        tag.object.files.each do |file|
+          message[:locations] << file
+        end
+        tag_label = "@#{tag.tag_name}"
+        tag_label << " [#{tag.types.join(', ')}]" if tag.types
+        tag_label << " #{tag.name}" if tag.name
+        message[:comments] << 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 = add_message(value)
+              message[:locations] << [file.filename, line_no]
+              message[:comments] << name
+            when :paragraph
+              paragraph, line_no = *args
+              message = add_message(paragraph.rstrip)
+              message[:locations] << [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,72 @@
+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
+        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*$/
+              in_header = false unless line_no == 1
+            when /^\s*#\s*@(\S+)\s*(.+?)\s*$/
+              name, value = $1, $2
+              yield(:attribute, name, value, line_no)
+            else
+              in_header = false
+              next if line.chomp.empty?
+            end
+            next if in_header
+          end
+
+          case line
+          when /^\s*$/
+            next if paragraph.empty?
+            yield(:paragraph, paragraph.rstrip, paragraph_start_line)
+            paragraph = ""
+          else
+            paragraph_start_line = line_no if paragraph.empty?
+            paragraph << line
+          end
+        end
+        unless paragraph.empty?
+          yield(:paragraph, paragraph.rstrip, paragraph_start_line)
+        end
+      end
+    end
+  end
+end

data/lib/yard/logging.rb

@@ -38,18 +38,14 @@ module YARD
       error "Stack trace:" +
         exc.backtrace[0..5].map {|x| "\n\t#{x}" }.join + "\n"
     end
-    
+
     # Warns that the Ruby environment does not support continuations. Applies
     # to JRuby, Rubinius and MacRuby. This warning will only display once
     # per Ruby process.
-    # 
+    #
+    # @deprecated Continuations are no longer needed by YARD 0.8.0+.
     # @return [void]
     def warn_no_continuations
-      return if CONTINUATIONS_SUPPORTED
-      return if $NO_CONTINUATION_WARNING
-      $NO_CONTINUATION_WARNING = true
-      warn "JRuby/MacRuby/Rubinius do not implement Kernel#callcc and cannot " +
-           "load files in order. You must specify the correct order manually."
     end
 
     # Sets the logger level for the duration of the block

data/lib/yard/options.rb

@@ -0,0 +1,216 @@
+module YARD
+  # Generalized options class for passing around large amounts of options between objects.
+  #
+  # The options class exists for better visibility and documentability of options being
+  # passed through to other objects. Because YARD has parser and template architectures
+  # that are heavily reliant on options, it is necessary to make these option keys easily
+  # visible and understood by developers. Since the options class is more than just a
+  # basic Hash, the subclass can provide aliasing and convenience methods to simplify
+  # option property access, and, if needed, support backward-compatibility for deprecated
+  # key names.
+  #
+  # == Hash and OpenStruct-like Access
+  #
+  # Although the options class allows for Hash-like access (<tt>opts[:key]</tt>), the recommended
+  # mechanism for accessing an option key will be via standard method calls on attributes
+  #
+  # The options class can also act as an open ended key value storage structure (like a
+  # Hash or OpenStruct), and allows for setting and getting of unregistered option keys.
+  # This methodology is not recommended, however, and is only supported for backward
+  # compatibility inside YARD. Whenever possible, developers should define all keys used
+  # by an options class.
+  #
+  # == Declaring Default Values
+  #
+  # Note that the options class can contain default value definitions for certain options,
+  # but to initialize these defaults, {#reset_defaults} must be called manually after
+  # initialization; the options object is always created empty until defaults are applied.
+  #
+  # @abstract Subclasses should define (and document) custom attributes that are expected
+  #   to be made available as option keys.
+  # @example Defining an Options class with custom option keys
+  #   class TemplateOptions < YARD::Options
+  #     # @return [Symbol] the output format to generate templates in
+  #     attr_accessor :format
+  #
+  #     # @return [Symbol] the template to use when generating output
+  #     attr_accessor :template
+  #   end
+  # @example Initializing default option values
+  #   class TemplateOptions < YARD::Options
+  #     def reset_defaults
+  #       super
+  #       self.format = :html
+  #       self.template = :default
+  #       self.highlight = true
+  #       # ...
+  #     end
+  #   end
+  # @example Using +default_attr+ to create default attributes
+  #   class TemplateOptions < YARD::Options
+  #     default_attr :format, :html
+  #     default_attr :template, :default
+  #     default_attr :highlight, true
+  #   end
+  # @example Deprecating an option while still supporting it
+  #   class TemplateOptions < YARD::Options
+  #     # @return [Boolean] if syntax highlighting should be performed on code blocks.
+  #     #   Defaults to true.
+  #     attr_accessor :highlight
+  #
+  #     # @deprecated Use {#highlight} instead.
+  #     # @return [Boolean] if no syntax highlighting should be performs on code blocks.
+  #     #   Defaults to false.
+  #     attr_accessor :no_highlight
+  #     def no_highlight=(value) @highlight = !value end
+  #     def no_highlight; !highlight end
+  #   end
+  class Options
+    # @!macro [attach] yard.default_attr
+    #   @!attribute $1
+    # Defines an attribute named +key+ and sets a default value for it
+    #
+    # @example Defining a default option key
+    #   default_attr :name, 'Default Name'
+    #   default_attr :time, lambda { Time.now }
+    # @param [Symbol] key the option key name
+    # @param [Object, Proc] default the default object value. If the default
+    #   value is a proc, it is executed upon initialization.
+    def self.default_attr(key, default)
+      (@defaults ||= {})[key] = default
+      attr_accessor(key)
+    end
+
+    # Delegates calls with Hash syntax to actual method with key name
+    #
+    # @example Calling on an option key with Hash syntax
+    #   options[:format] # equivalent to: options.format
+    # @param [Symbol, String] key the option name to access
+    # @return the value of the option named +key+
+    def [](key) send(key) end
+
+    # Delegates setter calls with Hash syntax to the attribute setter with the key name
+    #
+    # @example Setting an option with Hash syntax
+    #   options[:format] = :html # equivalent to: options.format = :html
+    # @param [Symbol, String] key the optin to set
+    # @param [Object] value the value to set for the option
+    # @return [Object] the value being set
+    def []=(key, value) send("#{key}=", value) end
+
+    # Updates values from an options hash or options object on this object.
+    # All keys passed should be key names defined by attributes on the class.
+    #
+    # @example Updating a set of options on an Options object
+    #   opts.update(:template => :guide, :type => :fulldoc)
+    # @param [Hash, Options] opts
+    # @return [self]
+    def update(opts)
+      opts = opts.to_hash if Options === opts
+      opts.each do |key, value|
+        self[key] = value
+      end
+      self
+    end
+
+    # Creates a new options object and sets options hash or object value
+    # onto that object.
+    #
+    # @param [Options, Hash] opts
+    # @return [Options] the newly created options object
+    # @see #update
+    def merge(opts)
+      dup.update(opts)
+    end
+
+    # @return [Hash] Converts options object to an options hash. All keys
+    #   will be symbolized.
+    def to_hash
+      opts = {}
+      instance_variables.each do |ivar|
+        name = ivar.to_s.sub(/^@/, '')
+        opts[name.to_sym] = send(name)
+      end
+      opts
+    end
+
+    # Yields over every option key and value
+    # @yield [key, value] every option key and value
+    # @yieldparam [Symbol] key the option key
+    # @yieldparam [Object] value the option value
+    # @return [void]
+    def each(&block)
+      instance_variables.each do |ivar|
+        name = ivar.to_s.sub(/^@/, '')
+        yield(name.to_sym, send(name))
+      end
+    end
+
+    # Inspects the object
+    def inspect
+      "<#{self.class}: #{to_hash.inspect}>"
+    end
+
+    # @return [Boolean] whether another Options object equals the
+    #   keys and values of this options object
+    def ==(other)
+      case other
+      when Options; to_hash == other.to_hash
+      when Hash; to_hash == other
+      else false
+      end
+    end
+
+    # Handles setting and accessing of unregistered keys similar
+    # to an OpenStruct object.
+    #
+    # @note It is not recommended to set and access unregistered keys on
+    #   an Options object. Instead, register the attribute before using it.
+    def method_missing(meth, *args, &block)
+      if meth.to_s =~ /^(.+)=$/
+        log.debug "Attempting to set unregistered key #{$1} on #{self.class}"
+        instance_variable_set("@#{$1}", args.first)
+      elsif args.size == 0
+        log.debug "Attempting to access unregistered key #{meth} on #{self.class}"
+        instance_variable_get("@#{meth}")
+      else
+        super
+      end
+    end
+
+    # Resets all values to their defaults.
+    #
+    # @abstract Subclasses should override this method to perform custom
+    #   value initialization if not using {default_attr}. Be sure to call
+    #   +super+ so that default initialization can take place.
+    # @return [void]
+    def reset_defaults
+      names_set = {}
+      self.class.ancestors.each do |klass| # look at all ancestors
+        defaults = klass.instance_variable_get("@defaults")
+        return unless defaults
+        defaults.each do |key, value|
+          next if names_set[key]
+          names_set[key] = true
+          self[key] = Proc === value ? value.call : value
+        end
+      end
+    end
+
+    # Deletes an option value for +key+
+    #
+    # @param [Symbol, String] key the key to delete a value for
+    # @return [Object] the value that was deleted
+    def delete(key)
+      val = self[key]
+      if instance_variable_defined?("@#{key}")
+        remove_instance_variable("@#{key}")
+      end
+      val
+    end
+
+    unless defined? tap() # only for 1.8.6
+      def tap(&block) yield(self); self end
+    end
+  end
+end