yard 0.6.8 → 0.7.0

data/lib/yard/templates/engine.rb

@@ -2,10 +2,10 @@ require 'ostruct'
 
 module YARD
   module Templates
-    # This module manages all creation, handling and rendering of {Template} 
-    # objects. 
-    # 
-    # * To create a template object at a path, use {template}. 
+    # This module manages all creation, handling and rendering of {Template}
+    # objects.
+    #
+    # * To create a template object at a path, use {template}.
     # * To render a template, call {render}.
     # * To register a template path in the lookup paths, call {register_template_path}.
     module Engine
@@ -14,19 +14,19 @@ module YARD
         attr_accessor :template_paths
 
         # Registers a new template path in {template_paths}
-        # 
+        #
         # @param [String] path a new template path
-        # @return [void] 
+        # @return [void]
         def register_template_path(path)
           template_paths.push path
         end
-        
-        # Creates a template module representing the path. Searches on disk 
-        # for the first directory named +path+ (joined by '/') within the 
-        # template paths and builds a template module for. All other matching 
-        # directories in other template paths will be included in the 
+
+        # Creates a template module representing the path. Searches on disk
+        # for the first directory named +path+ (joined by '/') within the
+        # template paths and builds a template module for. All other matching
+        # directories in other template paths will be included in the
         # generated module as mixins (for overriding).
-        # 
+        #
         # @param [Array<String, Symbol>] path a list of path components
         # @raise [ArgumentError] if the path does not exist within one of the
         #   {template_paths} on disk.
@@ -36,16 +36,16 @@ module YARD
           from_template = path.shift if path.first.is_a?(Template)
           path = path.join('/')
           full_paths = find_template_paths(from_template, path)
-          
+
           path = File.cleanpath(path).gsub('../', '')
           raise ArgumentError, "No such template for #{path}" if full_paths.empty?
           mod = template!(path, full_paths)
 
           mod
         end
-        
+
         # Forces creation of a template at +path+ within a +full_path+.
-        # 
+        #
         # @param [String] path the path name of the template
         # @param [Array<String>] full_paths the full path on disk of the template
         # @return [Template] the template module representing the +path+
@@ -63,12 +63,12 @@ module YARD
 
         # Renders a template on a {CodeObjects::Base code object} using
         # a set of default (overridable) options. Either the +:object+
-        # or +:type+ keys must be provided. 
-        # 
+        # or +:type+ keys must be provided.
+        #
         # If a +:serializer+ key is provided and +:serialize+ is not set to
         # false, the rendered contents will be serialized through the {Serializers::Base}
         # object. See {with_serializer}.
-        # 
+        #
         # @example Renders an object with html formatting
         #   Engine.render(:format => :html, :object => obj)
         # @example Renders without an object
@@ -81,18 +81,18 @@ module YARD
         def render(options = {})
           set_default_options(options)
           mod = template(options[:template], options[:type], options[:format])
-          
+
           if options[:serialize] != false
             with_serializer(options[:object], options[:serializer]) { mod.run(options) }
           else
             mod.run(options)
           end
         end
-        
-        # Passes a set of objects to the +:fulldoc+ template for full documentation generation. 
-        # This is called by {CLI::Yardoc} to most commonly perform HTML 
+
+        # Passes a set of objects to the +:fulldoc+ template for full documentation generation.
+        # This is called by {CLI::Yardoc} to most commonly perform HTML
         # documentation generation.
-        # 
+        #
         # @param [Array<CodeObjects::Base>] objects a list of {CodeObjects::Base}
         #   objects to pass to the template
         # @param [Hash] options (see {render})
@@ -104,7 +104,7 @@ module YARD
         end
 
         # Serializes the results of a block with a +serializer+ object.
-        # 
+        #
         # @param [CodeObjects::Base] object the code object to serialize
         # @param [Serializers::Base] serializer the serializer object
         # @yield a block whose result will be serialize
@@ -119,11 +119,11 @@ module YARD
           end
           output
         end
-        
+
         private
-        
+
         # Sets default options on the options hash
-        # 
+        #
         # @param [Hash] options the options hash
         # @option options [Symbol] :format (:text) the default format
         # @option options [Symbol] :type (nil) the :object's type, if provided
@@ -138,7 +138,7 @@ module YARD
 
         # Searches through the registered {template_paths} and returns
         # all full directories that have the +path+ within them on disk.
-        # 
+        #
         # @param [Template] from_template if provided, allows a relative
         #   path to be specified from this template's full path.
         # @param [String] path the path component to search for in the
@@ -148,7 +148,7 @@ module YARD
         def find_template_paths(from_template, path)
           paths = template_paths.dup
           paths = from_template.full_paths + paths if from_template
-          
+
           paths.inject([]) do |acc, tp|
             full_path = File.cleanpath(File.join(tp, path))
             acc.unshift(full_path) if File.directory?(full_path)
@@ -157,7 +157,7 @@ module YARD
         end
 
         # The name of the module that represents a +path+
-        # 
+        #
         # @param [String] the path toe generate a module name for
         # @return [String] the module name
         def template_module_name(path)
@@ -167,7 +167,7 @@ module YARD
 
       self.template_paths = []
     end
-    
+
     Engine.register_template_path(File.join(YARD::ROOT, '..', 'templates'))
   end
 end

data/lib/yard/templates/erb_cache.rb

@@ -9,7 +9,7 @@ module YARD
         erb = yield.src
         encoding = erb[/\A(#coding[:=].*\r?\n)/, 1] || ''
         module_eval "#{encoding}def #{name}; #{erb}; end", filename
-        
+
         name
       end
 

data/lib/yard/templates/helpers/base_helper.rb

@@ -2,41 +2,41 @@ module YARD::Templates::Helpers
   # The base helper module included in all templates.
   module BaseHelper
     attr_accessor :object, :serializer
-    
+
     # @group Managing Global Template State
-    
-    # An object that keeps track of global state throughout the entire template 
+
+    # An object that keeps track of global state throughout the entire template
     # rendering process (including any sub-templates).
-    # 
+    #
     # @return [OpenStruct] a struct object that stores state
     # @since 0.6.0
     def globals; options[:__globals] end
-    
+
     # @group Running the Verifier
-    
-    # Runs a list of objects against the {Verifier} object passed into the 
+
+    # Runs a list of objects against the {Verifier} object passed into the
     # template 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. If no verifier is supplied, all objects are returned.
     def run_verifier(list)
       options[:verifier] ? options[:verifier].run(list) : list
     end
-    
+
     # @group Escaping Text
-    
+
     # Escapes text. This is used a lot by the HtmlHelper and there should
     # be some helper to "clean up" text for whatever, this is it.
     def h(text)
       text
     end
-    
+
     # @group Linking Objects and URLs
-    
+
     # Links objects or URLs. This method will delegate to the correct +link_+
     # method depending on the arguments passed in.
-    # 
+    #
     # @example Linking a URL
     #   linkify('http://example.com')
     # @example Including docstring contents of an object
@@ -45,14 +45,18 @@ module YARD::Templates::Helpers
     #   linkify('file:README')
     # @example Linking an object by path
     #   linkify('YARD::Docstring')
-    def linkify(*args) 
+    def linkify(*args)
       if args.first.is_a?(String)
         case args.first
         when %r{://}, /^mailto:/
           link_url(args[0], args[1], {:target => '_parent'}.merge(args[2]||{}))
         when /^include:file:(\S+)/
           file = $1
-          if File.file?(file)
+          relpath = File.relative_path(Dir.pwd, File.expand_path(file))
+          if relpath =~ /^\.\./
+            log.warn "Cannot include file from path `#{file}'"
+            ""
+          elsif File.file?(file)
             link_include_file(file)
           else
             log.warn "Cannot find file at `#{file}' for inclusion"
@@ -66,8 +70,17 @@ module YARD::Templates::Helpers
             log.warn "Cannot find object at `#{path}' for inclusion"
             ""
           end
+        when /^render:(\S+)/
+          path = $1
+          if obj = YARD::Registry.resolve(object, path)
+            opts = options.dup
+            opts.delete(:serializer)
+            obj.format(opts)
+          else
+            ''
+          end
         when /^file:(\S+?)(?:#(\S+))?$/
-          link_file($1, args[1] ? args[1] : $1, $2)
+          link_file($1, args[1] ? args[1] : nil, $2)
         else
           link_object(*args)
         end
@@ -75,7 +88,7 @@ module YARD::Templates::Helpers
         link_object(*args)
       end
     end
-    
+
     # Includes an object's docstring into output.
     # @since 0.6.0
     # @param [CodeObjects::Base] object the object to include
@@ -83,7 +96,7 @@ module YARD::Templates::Helpers
     def link_include_object(object)
       object.docstring
     end
-    
+
     # Include a file as a docstring in output
     # @since 0.7.0
     # @param [String] file the filename to include
@@ -93,13 +106,13 @@ module YARD::Templates::Helpers
     end
 
     # Links to an object with an optional title
-    # 
+    #
     # @param [CodeObjects::Base] object the object to link to
     # @param [String] title the title to use for the link
     # @return [String] the linked object
     def link_object(object, title = nil)
       return title if title
-      
+
       case object
       when YARD::CodeObjects::Base, YARD::CodeObjects::Proxy
         object.path
@@ -109,9 +122,9 @@ module YARD::Templates::Helpers
         object
       end
     end
-    
+
     # Links to a URL
-    # 
+    #
     # @param [String] url the URL to link to
     # @param [String] title the optional title to display the link as
     # @param [Hash] params optional parameters for the link
@@ -119,22 +132,23 @@ module YARD::Templates::Helpers
     def link_url(url, title = nil, params = nil)
       url
     end
-    
-    # Links to an extra file 
-    # 
+
+    # Links to an extra file
+    #
     # @param [String] filename the filename to link to
     # @param [String] title the title of the link
     # @param [String] anchor optional anchor
     # @return [String] the link to the file
     # @since 0.5.5
     def link_file(filename, title = nil, anchor = nil)
+      return filename.filename if CodeObjects::ExtraFileObject === filename
       filename
     end
-    
+
     # @group Formatting Object Attributes
-    
+
     # Formats a list of return types for output and links each type.
-    # 
+    #
     # @example Formatting types
     #   format_types(['String', 'Array']) #=> "(String, Array)"
     # @example Formatting types without surrounding brackets
@@ -154,7 +168,7 @@ module YARD::Templates::Helpers
     #   o = MethodObject.new(:root, :to_s)
     #   format_object_type(o) # => "Method"
     # @param [CodeObjects::Base] object the object to retrieve the type for
-    # @return [String] the human-readable formatted {CodeObjects::Base#type #type} 
+    # @return [String] the human-readable formatted {CodeObjects::Base#type #type}
     #   for the object
     def format_object_type(object)
       case object
@@ -164,7 +178,7 @@ module YARD::Templates::Helpers
         object.type.to_s.capitalize
       end
     end
-    
+
     # @example
     #   s = format_object_title ModuleObject.new(:root, :MyModuleName)
     #   s # => "Module: MyModuleName"
@@ -178,9 +192,9 @@ module YARD::Templates::Helpers
         format_object_type(object) + ": " + object.path
       end
     end
-    
+
     # Indents and formats source code
-    # 
+    #
     # @param [String] value the input source code
     # @return [String] formatted source code
     def format_source(value)

data/lib/yard/templates/helpers/filter_helper.rb

@@ -11,12 +11,12 @@ module YARD
       def is_namespace?(object)
         object.is_a?(CodeObjects::NamespaceObject)
       end
-      
+
       # @return [Boolean] whether an object is a class
       def is_class?(object)
         object.is_a?(CodeObjects::ClassObject)
       end
-      
+
       # @return [Boolean] whether an object is a module
       def is_module?(object)
         object.is_a?(CodeObjects::ModuleObject)

data/lib/yard/templates/helpers/html_helper.rb

@@ -6,29 +6,29 @@ module YARD
     module HtmlHelper
       include MarkupHelper
       include HtmlSyntaxHighlightHelper
-      
+
       # @group Escaping Template Data
-    
+
       # Escapes HTML entities
-      # 
+      #
       # @param [String] text the text to escape
       # @return [String] the HTML with escaped entities
       def h(text)
         CGI.escapeHTML(text.to_s)
       end
-    
+
       # Escapes a URL
-      # 
+      #
       # @param [String] text the URL
       # @return [String] the escaped URL
       def urlencode(text)
         CGI.escape(text.to_s)
       end
-      
+
       # @group Converting Markup to HTML
 
       # Turns text into HTML using +markup+ style formatting.
-      # 
+      #
       # @param [String] text the text to format
       # @param [Symbol] markup examples are +:markdown+, +:textile+, +:rdoc+.
       #   To add a custom markup type, see {MarkupHelper}
@@ -38,7 +38,6 @@ module YARD
         return text unless respond_to?(markup_meth)
         return "" unless text
         return text unless markup
-        load_markup_provider(markup)
         html = send(markup_meth, text)
         if html.respond_to?(:encode)
           html = html.force_encoding(text.encoding) # for libs that mess with encoding
@@ -52,16 +51,21 @@ module YARD
         end unless markup == :text
         html
       end
-      
+
       # Converts Markdown to HTML
       # @param [String] text input Markdown text
       # @return [String] output HTML
       # @since 0.6.0
       def html_markup_markdown(text)
         # TODO: other libraries might be more complex
-        markup_class(:markdown).new(text).to_html
+        provider = markup_class(:markdown)
+        if provider.to_s == 'RDiscount'
+          markup_class(:markdown).new(text, :autolink).to_html
+        else
+          markup_class(:markdown).new(text).to_html
+        end
       end
-      
+
       # Converts Textile to HTML
       # @param [String] text the input Textile text
       # @return [String] output HTML
@@ -71,7 +75,7 @@ module YARD
         doc.hard_breaks = false if doc.respond_to?(:hard_breaks=)
         doc.to_html
       end
-      
+
       # Converts RDoc formatting (SimpleMarkup) to HTML
       # @param [String] text the input RDoc formatted text
       # @return [String] output HTML
@@ -81,7 +85,7 @@ module YARD
         doc.from_path = url_for(object) if doc.respond_to?(:from_path=)
         doc.to_html
       end
-      
+
       # Converts plaintext to HTML
       # @param [String] text the input text
       # @return [String] the output HTML
@@ -89,13 +93,13 @@ module YARD
       def html_markup_text(text)
         "<pre>" + text + "</pre>"
       end
-      
+
       # @return [String] the same text with no markup
       # @since 0.6.6
       def html_markup_none(text)
         h(text).gsub(/(?:\r?\n){2}/, '<br/>')
       end
-      
+
       # Converts HTML to HTML
       # @param [String] text input html
       # @return [String] output HTML
@@ -104,21 +108,32 @@ module YARD
         text
       end
       
+      # Highlights Ruby source. Similar to {#html_syntax_highlight}, but
+      # this method is meant to be called from {#htmlify} when markup is
+      # set to "ruby".
+      # 
+      # @param [String] source the Ruby source
+      # @return [String] the highlighted HTML
+      # @since 0.7.0
+      def html_markup_ruby(source)
+        '<pre class="code">' + html_syntax_highlight(source, :ruby) + '</pre>'
+      end
+
       # @return [String] HTMLified text as a single line (paragraphs removed)
       def htmlify_line(*args)
         "<div class='inline'>" + htmlify(*args) + "</div>"
       end
-      
+
       # @group Syntax Highlighting Source Code
-      
+
       # Syntax highlights +source+ in language +type+.
-      # 
+      #
       # @note To support a specific language +type+, implement the method
       #   +html_syntax_highlight_TYPE+ in this class.
-      # 
+      #
       # @param [String] source the source code to highlight
       # @param [Symbol] type the language type (:ruby, :plain, etc). Use
-      #   :plain for no syntax highlighting. 
+      #   :plain for no syntax highlighting.
       # @return [String] the highlighted source
       def html_syntax_highlight(source, type = nil)
         return "" unless source
@@ -131,21 +146,21 @@ module YARD
           type, source = $1, $'
           source = $'
         end
-        
+
         meth = "html_syntax_highlight_#{type}"
         respond_to?(meth) ? send(meth, source) : h(source)
       end
-      
+
       # @return [String] unhighlighted source
       def html_syntax_highlight_plain(source)
         h(source)
       end
-      
+
       # @group Linking Objects and URLs
 
       # Resolves any text in the form of +{Name}+ to the object specified by
       # Name. Also supports link titles in the form +{Name title}+.
-      # 
+      #
       # @example Linking to an instance method
       #   resolve_links("{MyClass#method}") # => "<a href='...'>MyClass#method</a>"
       # @example Linking to a class with a title
@@ -154,42 +169,60 @@ module YARD
       # @return [String] HTML with linkified references
       def resolve_links(text)
         code_tags = 0
-        text.gsub(/<(\/)?(pre|code|tt)|\{(\S+?)(?:\s(.*?\S))?\}(?=[\W<]|.+<\/|$)/m) do |str|
-          closed, tag, name, title, match = $1, $2, $3, $4, $&
+        text.gsub(/<(\/)?(pre|code|tt)|(\\)?\{(?!\})(\S+?)(?:\s([^\}]*?\S))?\}(?=[\W<]|.+<\/|$)/m) do |str|
+          closed, tag, escape, name, title, match = $1, $2, $3, $4, $5, $&
           if tag
             code_tags += (closed ? -1 : 1)
             next str
           end
           next str unless code_tags == 0
-          
+
+          next(match[1..-1]) if escape
+
           next(match) if name[0,1] == '|'
           if object.is_a?(String)
             object
           else
             link = linkify(name, title)
-            if link == name || link == title
+            if (link == name || link == title) && (name+' '+link !~ /\A<a\s.*>/)
               match = /(.+)?(\{#{Regexp.quote name}(?:\s.*?)?\})(.+)?/.match(text)
-              file = (@file ? @file : object.file) || '(unknown)'
+              file = (@file ? @file.filename : object.file) || '(unknown)'
               line = (@file ? 1 : (object.docstring.line_range ? object.docstring.line_range.first : 1)) + (match ? $`.count("\n") : 0)
               log.warn "In file `#{file}':#{line}: Cannot resolve link to #{name} from text" + (match ? ":" : ".")
               log.warn((match[1] ? '...' : '') + match[2].gsub("\n","") + (match[3] ? '...' : '')) if match
             end
-            
+
             link
           end
         end
       end
-      
+
       # (see BaseHelper#link_file)
       def link_file(filename, title = nil, anchor = nil)
-        link_url(url_for_file(filename, anchor), title)
+        if CodeObjects::ExtraFileObject === filename
+          file = filename
+        else
+          contents = File.file?(filename) ? nil : ''
+          file = CodeObjects::ExtraFileObject.new(filename, contents)
+        end
+        return title || file.title unless serializer
+        link_url(url_for_file(file, anchor), title || file.title)
       end
       
+      # (see BaseHelper#link_include_file)
+      def link_include_file(file)
+        unless file.is_a?(CodeObjects::ExtraFileObject)
+          file = CodeObjects::ExtraFileObject.new(file)
+        end
+        file.attributes[:markup] ||= markup_for_file('', file.filename)
+        htmlify(file.contents, file.attributes[:markup] || options[:markup])
+      end
+
       # (see BaseHelper#link_include_object)
       def link_include_object(obj)
         htmlify(obj.docstring)
       end
-    
+
       # (see BaseHelper#link_object)
       def link_object(obj, otitle = nil, anchor = nil, relative = true)
         return otitle if obj.nil?
@@ -205,12 +238,12 @@ module YARD
         end
         return title unless serializer
         return title if obj.is_a?(CodeObjects::Proxy)
-              
+
         link = url_for(obj, anchor, relative)
         link = link ? link_url(link, title, :title => "#{obj.path} (#{obj.type})") : title
         "<span class='object_link'>" + link + "</span>"
       end
-      
+
       # (see BaseHelper#link_url)
       def link_url(url, title = nil, params = {})
         title ||= url
@@ -222,9 +255,9 @@ module YARD
         params[:target] ||= '_parent' if url =~ /^(\w+):\/\//
         "<a #{tag_attrs(params)}>#{title}</a>".gsub(/[\r\n]/, ' ')
       end
-      
+
       # @group URL Helpers
-    
+
       # @param [CodeObjects::Base] object the object to get an anchor for
       # @return [String] the anchor for a specific object
       def anchor_for(object)
@@ -241,9 +274,9 @@ module YARD
           object.to_s
         end
       end
-    
+
       # Returns the URL for an object.
-      # 
+      #
       # @param [String, CodeObjects::Base] obj the object (or object path) to link to
       # @param [String] anchor the anchor to link to
       # @param [Boolean] relative use a relative or absolute link
@@ -251,18 +284,18 @@ module YARD
       def url_for(obj, anchor = nil, relative = true)
         link = nil
         return link unless serializer
-        
+
         if obj.is_a?(CodeObjects::Base) && !obj.is_a?(CodeObjects::NamespaceObject)
           # If the obj is not a namespace obj make it the anchor.
           anchor, obj = obj, obj.namespace
         end
-        
+
         objpath = serializer.serialized_path(obj)
         return link unless objpath
-      
+
         if relative
           fromobj = object
-          if object.is_a?(CodeObjects::Base) && 
+          if object.is_a?(CodeObjects::Base) &&
               !object.is_a?(CodeObjects::NamespaceObject)
             fromobj = fromobj.namespace
           end
@@ -272,67 +305,69 @@ module YARD
         else
           link = objpath
         end
-      
+
         link + (anchor ? '#' + urlencode(anchor_for(anchor)) : '')
       end
-      
+
       # Returns the URL for a specific file
-      # 
-      # @param [String] filename the filename to link to
+      #
+      # @param [String, CodeObjects::ExtraFileObject] filename the filename to link to
       # @param [String] anchor optional anchor
       # @return [String] the URL pointing to the file
       def url_for_file(filename, anchor = nil)
+        return '' unless serializer
         fromobj = object
         if CodeObjects::Base === fromobj && !fromobj.is_a?(CodeObjects::NamespaceObject)
           fromobj = fromobj.namespace
         end
         from = serializer.serialized_path(fromobj)
         if filename == options[:readme]
-          filename = 'index'
+          path = 'index.html'
         else
-          filename = 'file.' + File.basename(filename).gsub(/\.[^.]+$/, '')
+          path = serializer.serialized_path(filename)
         end
-        link = File.relative_path(from, filename)
-        link + '.html' + (anchor ? '#' + urlencode(anchor) : '')
+        link = File.relative_path(from, path)
+        link += (anchor ? '#' + urlencode(anchor) : '')
+        link
       end
-      
+
       # @group Formatting Objects and Attributes
 
       # Formats a list of objects and links them
       # @return [String] a formatted list of objects
       def format_object_name_list(objects)
-        objects.sort_by {|o| o.name.to_s.downcase }.map do |o| 
-          "<span class='name'>" + linkify(o, o.name) + "</span>" 
+        objects.sort_by {|o| o.name.to_s.downcase }.map do |o|
+          "<span class='name'>" + linkify(o, o.name) + "</span>"
         end.join(", ")
       end
-      
+
       # Formats a list of types from a tag.
-      # 
+      #
       # @param [Array<String>, FalseClass] typelist
-      #   the list of types to be formatted. 
-      # 
-      # @param [Boolean] brackets omits the surrounding 
+      #   the list of types to be formatted.
+      #
+      # @param [Boolean] brackets omits the surrounding
       #   brackets if +brackets+ is set to +false+.
-      # 
+      #
       # @return [String] the list of types formatted
       #   as [Type1, Type2, ...] with the types linked
       #   to their respective descriptions.
-      # 
+      #
       def format_types(typelist, brackets = true)
         return unless typelist.is_a?(Array)
-        list = typelist.map do |type| 
+        list = typelist.map do |type|
           type = type.gsub(/([<>])/) { h($1) }
           type = type.gsub(/([\w:]+)/) { $1 == "lt" || $1 == "gt" ? $1 : linkify($1, $1) }
           "<tt>" + type + "</tt>"
         end
         list.empty? ? "" : (brackets ? "(#{list.join(", ")})" : list.join(", "))
       end
-      
+
       # Get the return types for a method signature.
-      # 
+      #
       # @param [CodeObjects::MethodObject] meth the method object
       # @param [Boolean] link whether to link the types
-      # @return [String] the signature types 
+      # @return [String] the signature types
       # @since 0.5.3
       def signature_types(meth, link = true)
         meth = convert_method_to_overload(meth)
@@ -358,19 +393,19 @@ module YARD
         type = "(#{type}) " unless type.empty?
         type
       end
-      
+
       # Formats the signature of method +meth+.
-      # 
+      #
       # @param [CodeObjects::MethodObject] meth the method object to list
       #   the signature of
       # @param [Boolean] link whether to link the method signature to the details view
       # @param [Boolean] show_extras whether to show extra meta-data (visibility, attribute info)
-      # @param [Boolean] full_attr_name whether to show the full attribute name 
+      # @param [Boolean] full_attr_name whether to show the full attribute name
       #   ("name=" instead of "name")
       # @return [String] the formatted method signature
       def signature(meth, link = true, show_extras = true, full_attr_name = true)
         meth = convert_method_to_overload(meth)
-        
+
         type = signature_types(meth, link)
         scope = meth.scope == :class ? "+" : "-"
         name = full_attr_name ? meth.name : meth.name.to_s.gsub(/^(\w+)=$/, '\1')
@@ -399,41 +434,45 @@ module YARD
           title + extras_text
         end
       end
-      
+
       # @group Getting the Character Encoding
-      
+
       # Returns the current character set. The default value can be overridden
       # by setting the +LANG+ environment variable or by overriding this
       # method. In Ruby 1.9 you can also modify this value by setting
       # +Encoding.default_external+.
-      # 
+      #
       # @return [String] the current character set
       # @since 0.5.4
       def charset
-        return 'utf-8' unless RUBY19 || lang = ENV['LANG']
-        if RUBY19
-          lang = Encoding.default_external.name.downcase
+        if @file && RUBY19
+          lang = @file.contents.encoding.to_s
         else
-          lang = lang.downcase.split('.').last
+          return 'utf-8' unless RUBY19 || lang = ENV['LANG']
+          if RUBY19
+            lang = Encoding.default_external.name.downcase
+          else
+            lang = lang.downcase.split('.').last
+          end
         end
         case lang
         when "ascii-8bit", "us-ascii", "ascii-7bit"; 'iso-8859-1'
         else; lang
         end
       end
-      
+
       # @endgroup
-      
+
       private
 
       # Converts a set of hash options into HTML attributes for a tag
-      # 
+      #
       # @param [Hash{String => String}] opts the tag options
       # @return [String] the tag attributes of an HTML tag
       def tag_attrs(opts = {})
         opts.sort_by {|k, v| k.to_s }.map {|k,v| "#{k}=#{v.to_s.inspect}" if v }.join(" ")
       end
-      
+
       # Converts a {CodeObjects::MethodObject} into an overload object
       # @since 0.5.3
       def convert_method_to_overload(meth)
@@ -446,4 +485,4 @@ module YARD
     end
   end
 end
-    
+