yard 0.6.8 → 0.7.0

data/lib/yard/templates/template.rb

@@ -5,7 +5,7 @@ module YARD
     module Template
       attr_accessor :class, :section
       attr_reader :options
-      
+
       class << self
         # @return [Array<Module>] a list of modules to be automatically included
         #   into any new template module
@@ -16,23 +16,23 @@ module YARD
           klass.extend(ClassMethods)
         end
       end
-      
+
       self.extra_includes = []
-      
+
       include ErbCache
       include Helpers::BaseHelper
       include Helpers::MethodHelper
 
       module ClassMethods
         attr_accessor :path, :full_path
-        
+
         def full_paths
           included_modules.inject([full_path]) do |paths, mod|
             paths |= mod.full_paths if mod.respond_to?(:full_paths)
             paths
           end
         end
-    
+
         def initialize(path, full_paths)
           full_path = full_paths.shift
           self.path = path
@@ -41,11 +41,11 @@ module YARD
           include_parent
           load_setup_rb
         end
-      
+
         # Searches for a file identified by +basename+ in the template's
         # path as well as any mixed in template paths. Equivalent to calling
         # {ClassMethods#find_nth_file} with index of 1.
-        # 
+        #
         # @param [String] basename the filename to search for
         # @return [String] the full path of a file on disk with filename
         #   +basename+ in one of the template's paths.
@@ -53,10 +53,10 @@ module YARD
         def find_file(basename)
           find_nth_file(basename)
         end
-        
+
         # Searches for the nth file (where n = +index+) identified
         # by basename in the template's path and any mixed in template paths.
-        # 
+        #
         # @param [String] basename the filename to search for
         # @param [Fixnum] index the nth existing file to return
         # @return [String] the full path of the nth file on disk with
@@ -70,7 +70,7 @@ module YARD
               n += 1
             end
           end
-          
+
           nil
         end
 
@@ -86,22 +86,22 @@ module YARD
           obj.send(:initialize, *args)
           obj
         end
-      
+
         def run(*args)
           new(*args).run
         end
-      
+
         def T(*path)
           Engine.template(*path)
         end
-        
+
         # Alias for creating a {Section} with arguments
         # @see Section#initialize
         # @since 0.6.0
         def S(*args)
           Section.new(*args)
         end
-      
+
         private
 
         def include_parent
@@ -116,7 +116,7 @@ module YARD
             end
           end
         end
-        
+
         def include_inherited(full_paths)
           full_paths.reverse.each do |full_path|
             include Engine.template!(path, full_path)
@@ -130,12 +130,12 @@ module YARD
           end
         end
       end
-    
+
       def initialize(opts = {})
         @cache, @cache_filename = {}, {}
         @sections, @options = [], {}
         add_options(opts)
-        
+
         extend(Helpers::HtmlHelper) if options[:format] == :html
         extend(Helpers::TextHelper) if options[:format] == :text
         extend(Helpers::UMLHelper) if options[:format] == :dot
@@ -143,11 +143,11 @@ module YARD
 
         init
       end
-    
+
       # Loads a template specified by path. If +:template+ or +:format+ is
       # specified in the {#options} hash, they are prepended and appended
       # to the path respectively.
-      # 
+      #
       # @param [Array<String, Symbol>] path the path of the template
       # @return [Template] the loaded template module
       def T(*path)
@@ -155,9 +155,9 @@ module YARD
         path.push(options[:format]) if options[:format]
         self.class.T(*path)
       end
-    
+
       # Sets the sections (and subsections) to be rendered for the template
-      # 
+      #
       # @example Sets a set of erb sections
       #   sections :a, :b, :c # searches for a.erb, b.erb, c.erb
       # @example Sets a set of method and erb sections
@@ -168,18 +168,18 @@ module YARD
       #   # if they are yielded by the template (see #yieldall)
       # @param [Array<Symbol, String, Template, Array>] args the sections
       #   to use to render the template. For symbols and strings, the
-      #   section will be executed as a method (if one exists), or rendered 
-      #   from the file "name.erb" where name is the section name. For 
-      #   templates, they will have {Template::ClassMethods#run} called on them. 
+      #   section will be executed as a method (if one exists), or rendered
+      #   from the file "name.erb" where name is the section name. For
+      #   templates, they will have {Template::ClassMethods#run} called on them.
       #   Any subsections can be yielded to using yield or {#yieldall}
       def sections(*args)
         @sections = Section.new(nil, *args) if args.size > 0
         @sections
       end
-      
+
       # Initialization called on the template. Override this in a 'setup.rb'
       # file in the template's path to implement a template
-      # 
+      #
       # @example A default set of sections
       #   def init
       #     sections :section1, :section2, [:subsection1, :etc]
@@ -187,10 +187,10 @@ module YARD
       # @see #sections
       def init
       end
-    
+
       # Runs a template on +sects+ using extra options. This method should
       # not be called directly. Instead, call the class method {ClassMethods#run}
-      # 
+      #
       # @param [Hash, nil] opts any extra options to apply to sections
       # @param [Section, Array] sects a section list of sections to render
       # @param [Fixnum] start_at the index in the section list to start from
@@ -211,7 +211,7 @@ module YARD
               value = with_section do
                 run(args.first, section, subsection_index, true, &block)
               end
-              subsection_index += 1 
+              subsection_index += 1
               value
             end
             out << (value || "")
@@ -220,14 +220,14 @@ module YARD
         end
         out
       end
-         
+
       # Yields all subsections with any extra options
-      # 
+      #
       # @param [Hash] opts extra options to be applied to subsections
       def yieldall(opts = nil, &block)
         with_section { run(opts, section, &block) }
       end
-    
+
       # @param [String, Symbol] section the section name
       # @yield calls subsections to be rendered
       # @return [String] the contents of the ERB rendered section
@@ -237,26 +237,26 @@ module YARD
         end
         send(method_name, &block)
       end
-      
+
       # Returns the contents of a file. If +allow_inherited+ is set to +true+,
       # use +{{{__super__}}}+ inside the file contents to insert the contents
       # of the file from an inherited template. For instance, if +templates/b+
       # inherits from +templates/a+ and file "test.css" exists in both directories,
       # both file contents can be retrieved by having +templates/b/test.css+ look
       # like:
-      # 
+      #
       #   {{{__super__}}}
       #   ...
       #   body { css styles here }
       #   p.class { other styles }
-      # 
+      #
       # @param [String] basename the name of the file
       # @param [Boolean] allow_inherited whether inherited templates can
       #   be inserted with +{{{__super__}}}+
       # @return [String] the contents of a file identified by +basename+. All
       #   template paths (including any mixed in templates) are searched for
       #   the file
-      # @see ClassMethods#find_file 
+      # @see ClassMethods#find_file
       # @see ClassMethods#find_nth_file
       def file(basename, allow_inherited = false)
         file = self.class.find_file(basename)
@@ -270,9 +270,9 @@ module YARD
 
         data
       end
-      
+
       # Calls the ERB file from the last inherited template with {#section}.erb
-      # 
+      #
       # @param [Symbol, String] section if provided, uses a specific section name
       # @return [String] the rendered ERB file in any of the inherited template
       #   paths.
@@ -282,36 +282,36 @@ module YARD
         method_name = ErbCache.method_for(filename) { erb_with(IO.read(filename), filename) }
         send(method_name, &block)
       end
-      
+
       def options=(value)
         @options = value
         set_ivars
       end
-      
+
       def inspect
         "Template(#{self.class.path}) [section=#{section.name}]"
       end
-    
+
       protected
-    
+
       def erb_file_for(section)
         "#{section}.erb"
       end
-      
+
       def erb_with(content, filename = nil)
         erb = ERB.new(content, nil, options[:format] == :text ? '<>' : nil)
         erb.filename = filename if filename
         erb
       end
-    
+
       private
-    
+
       def render_section(section, &block)
         section = section.name if section.is_a?(Section)
         case section
         when Section, String, Symbol
           if respond_to?(section)
-            send(section, &block) 
+            send(section, &block)
           else
             erb(section, &block)
           end
@@ -323,37 +323,37 @@ module YARD
       def cache(section)
         content = @cache[section.to_sym]
         return content if content
-      
+
         file = cache_filename(section)
         @cache_filename[section.to_sym] = file
         raise ArgumentError, "no template for section '#{section}' in #{self.class.path}" unless file
         @cache[section.to_sym] = IO.read(file)
       end
-      
+
       def cache_filename(section)
         @cache_filename[section.to_sym] ||=
           self.class.find_file(erb_file_for(section))
       end
-      
+
       def set_ivars
         options.each do |k, v|
           instance_variable_set("@#{k}", v)
         end
       end
-    
+
       def add_options(opts = nil)
         return(yield) if opts.nil? && block_given?
         cur_opts = options if block_given?
-        
+
         self.options = options.merge(opts)
-      
+
         if block_given?
           value = yield
-          self.options = cur_opts 
+          self.options = cur_opts
           value
         end
       end
-      
+
       def with_section(&block)
         sect = section
         value = yield

data/lib/yard/verifier.rb

@@ -1,14 +1,14 @@
 module YARD
   # Similar to a Proc, but runs a set of Ruby expressions using a small
   # DSL to make tag lookups easier.
-  # 
+  #
   # The syntax is as follows:
   # * All syntax is Ruby compatible
   # * +object+ (+o+ for short) exist to access the object being verified
   # * +@TAGNAME+ is translated into +object.tag('TAGNAME')+
   # * +@@TAGNAME+ is translated into +object.tags('TAGNAME')+
   # * +object+ can be omitted as target for method calls (it is implied)
-  # 
+  #
   # @example Create a verifier to check for objects that don't have @private tags
   #   verifier = Verifier.new('!@private')
   #   verifier.call(object) # => true (no @private tag)
@@ -34,30 +34,30 @@ module YARD
     # @return [Array<String>] a list of all expressions the verifier checks for
     # @since 0.5.6
     attr_reader :expressions
-    
+
     def expressions=(value)
       @expressions = value
       create_method_from_expressions
     end
-    
+
     # Creates a verifier from a set of expressions
-    # 
+    #
     # @param [Array<String>] expressions a list of Ruby expressions to
     #   parse.
     def initialize(*expressions)
       @expressions = []
       add_expressions(*expressions)
     end
-    
+
     # Adds a set of expressions and recompiles the verifier
-    # 
+    #
     # @param [Array<String>] expressions a list of expressions
     # @return [void]
     # @since 0.5.6
     def add_expressions(*expressions)
       self.expressions += expressions.flatten
     end
-    
+
     # Passes any method calls to the object from the {#call}
     def method_missing(sym, *args, &block)
       if object.respond_to?(sym)
@@ -68,7 +68,7 @@ module YARD
     end
 
     # Tests the expressions on the object.
-    # 
+    #
     # @note If the object is a {CodeObjects::Proxy} the result will always be true.
     # @param [CodeObjects::Base] object the object to verify
     # @return [Boolean] the result of the expressions
@@ -80,64 +80,64 @@ module YARD
       unmodify_nilclass
       retval
     end
-    
-    # Runs a list of objects against the verifier and returns the subset 
+
+    # Runs a list of objects against the verifier and returns the subset
     # of verified objects.
-    # 
+    #
     # @param [Array<CodeObjects::Base>] list a list of code objects
     # @return [Array<CodeObjects::Base>] a list of code objects that match
     #   the verifier.
     def run(list)
       list.reject {|item| call(item).is_a?(FalseClass) }
     end
-    
+
     protected
-    
+
     # @return [CodeObjects::Base] the current object being tested
     attr_reader :object
     alias o object
-    
+
     private
-    
+
     # @private
     NILCLASS_METHODS = [:type, :method_missing]
-    
+
     # Modifies nil to not throw NoMethodErrors. This allows
     # syntax like object.tag(:return).text to work if the #tag
     # call returns nil, which means users don't need to perform
     # stringent nil checking
-    # 
-    # @return [void] 
+    #
+    # @return [void]
     def modify_nilclass
       NILCLASS_METHODS.each do |meth|
         NilClass.send(:define_method, meth) {|*args| }
       end
     end
-    
+
     # Returns the state of NilClass back to normal
-    # @return [void] 
+    # @return [void]
     def unmodify_nilclass
       NILCLASS_METHODS.each do |meth|
         NilClass.send(:undef_method, meth)
       end
     end
-    
+
     # Creates the +__execute+ method by evaluating the expressions
     # as Ruby code
-    # @return [void] 
+    # @return [void]
     def create_method_from_expressions
       expr = expressions.map {|e| "(#{parse_expression(e)})" }.join(" && ")
-      
+
       instance_eval(<<-eof, __FILE__, __LINE__ + 1)
         def __execute; #{expr}; end
       eof
     end
-    
+
     # Parses a single expression, handling some of the DSL syntax.
-    # 
+    #
     # The syntax "@tag" should be turned into object.tag(:tag),
     # and "@@tag" should be turned into object.tags(:tag)
-    # 
+    #
     # @return [String] the parsed expression
     def parse_expression(expr)
       expr = expr.gsub(/@@(\w+)/, 'object.tags("\1")')