bitclust-core 1.2.6 → 1.6.0

data/lib/bitclust/rdcompiler.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 #
 # bitclust/rdcompiler.rb
 #
@@ -13,6 +14,8 @@ require 'bitclust/htmlutils'
 require 'bitclust/textutils'
 require 'bitclust/messagecatalog'
 require 'bitclust/syntax_highlighter'
+require 'bitclust/version_badges'
+require 'rouge'
 require 'stringio'
 
 module BitClust
@@ -23,17 +26,16 @@ module BitClust
     include HTMLUtils
     include TextUtils
     include Translatable
+    include VersionBadges
 
     def initialize(urlmapper, hlevel = 1, opt = {})
       @urlmapper = urlmapper
       @catalog = opt[:catalog]
       @hlevel = hlevel
       @type = nil
-      @library = nil
-      @class = nil
       @method = nil
       @option = opt.dup
-      init_message_catalog(@catalog)
+      init_message_catalog(@catalog || MessageCatalog.new({}, 'C'))
     end
 
     def compile(src)
@@ -79,10 +81,10 @@ module BitClust
         when /\A---/
           entry_chunk
         when /\A=+/
-          headline @f.gets
+          headline @f.gets || raise
         when /\A(\s+)\*\s/, /\A(\s+)\(\d+\)\s/
           @item_stack = []
-          item_list($1.size)
+          item_list(($1 || raise).size)
           raise "@item_stack should be empty. #{@item_stack.inspect}" unless @item_stack.empty?
         when %r<\A//emlist(?:\[(?:[^\[\]]+?)?\]\[\w+?\])?\{>
           emlist
@@ -90,8 +92,12 @@ module BitClust
           dlist
         when /\A\s+\S/
           list
+        when /\A@see\b/
+          # findings#1: doc/lib ページの @see もメソッドエントリと同じく
+          # SEE_ALSO として解釈する（従来は段落テキストだった）
+          see
         else
-          if @f.peek.strip.empty?
+          if @f.peek&.strip&.empty?
             @f.gets
           else
             paragraph
@@ -106,23 +112,35 @@ module BitClust
       end
     end
 
+    # シグネチャ行に続くメソッド属性行({: ...}。直前のシグネチャ行に束縛)
+    METHOD_ATTRIBUTE_LINE_RE = /\A\{:.*\}[ \t]*$/
+
     def entry_chunk
       @out.puts '<dl>' if @option[:force]
       first = true
-      @f.while_match(/\A---/) do |line|
-        method_signature(line, first)
-        first = false
+      attrs = [] #: Array[String]
+      while @f.next?
+        if /\A---/ =~ @f.peek
+          method_signature(@f.gets || raise, first)
+          first = false
+        elsif !first && METHOD_ATTRIBUTE_LINE_RE =~ @f.peek
+          # メソッド属性行は本文には描画しない(undef のみ後でメッセージ)
+          attrs.concat attribute_tokens(@f.gets)
+        else
+          break
+        end
       end
-      props = {}
+      props = {} #: Hash[String?, String?]
       @f.while_match(/\A:/) do |line|
         k, v = line.sub(/\A:/, '').split(':', 2)
-        props[k.strip] = v.strip
+        props[k&.strip] = v&.strip
       end if @type == :method
       @out.puts %Q(<dd class="#{@type.to_s}-description">)
+      undef_message if attrs.include?('undef')
       while @f.next?
         case @f.peek
         when /\A===+/
-          headline @f.gets
+          headline @f.gets || raise
         when /\A==?/
           if @option[:force]
             break
@@ -133,7 +151,7 @@ module BitClust
           break
         when /\A(\s+)\*\s/, /\A(\s+)\(\d+\)\s/
           @item_stack = []
-          item_list($1.size)
+          item_list(($1 || raise).size)
           raise "@item_stack should be empty. #{@item_stack.inspect}" unless @item_stack.empty?
         when /\A:\s/
           dlist
@@ -141,14 +159,16 @@ module BitClust
           emlist
         when /\A\s+\S/
           list
-        when /@see/
+        when /\A@see\b/
+          # findings#3: 無アンカーの /@see/ は行の途中に @see を含む
+          # 本文行を吸ってしまう（@todo も同様）
           see
-        when /@todo/
+        when /\A@todo\b/
           todo
         when /\A@[a-z]/
           entry_info
         else
-          if @f.peek.strip.empty?
+          if @f.peek&.strip&.empty?
             @f.gets
           else
             entry_paragraph
@@ -160,9 +180,9 @@ module BitClust
     end
 
     def headline(line)
-      level = @hlevel + (line.slice(/\A=+/).size - 3)
+      level = @hlevel + (line.slice(/\A=+/)&.size.to_i - 3)
       label = line.sub(/\A=+(\[a:(.*?)\])?/, '').strip
-      frag = $2 if $2 and not $2.empty?
+      frag = $2 if $2 and not ($2 || raise).empty?
       line h(level, escape_html(label), frag)
     end
 
@@ -171,7 +191,9 @@ module BitClust
       "<h#{level} #{name}>#{label}</h#{level}>"
     end
 
-    def item_list(level = 0, indent = true)
+    ITEM_RE = /\A(\s+)(?:\*\s|\(\d+\))/
+
+    def item_list(level = 0)
       open_tag = nil
       close_tag = nil
       case @f.peek
@@ -182,11 +204,9 @@ module BitClust
         open_tag  = "<ol>"
         close_tag = "</ol>"
       end
-      if indent
-        line open_tag
-        @item_stack.push(close_tag)
-      end
-      @f.while_match(/\A(\s+)(?:\*\s|\(\d+\))/) do |line|
+      line open_tag
+      @item_stack.push(close_tag)
+      @f.while_match(ITEM_RE) do |line|
         string "<li>"
         @item_stack.push("</li>")
         string compile_text(line.sub(/\A(\s+)(?:\*|\(\d+\))/, '').strip)
@@ -195,15 +215,14 @@ module BitClust
             nl
             string compile_text(cont.strip)
           end
+        end
+        if (m = ITEM_RE.match(@f.peek)) && level < (m[1] || raise).size
+          item_list(($1 || raise).size)
           line @item_stack.pop # current level li
-        elsif /\A(\s+)(?:\*\s|\(\d+\))/ =~ @f.peek and level < $1.size
-          item_list($1.size)
-          line @item_stack.pop # current level ul or ol
-        elsif /\A(\s+)(?:\*\s|\(\d+\))/ =~ @f.peek and level > $1.size
+          break if ITEM_RE =~ @f.peek and level > ($1 || raise).size
+        elsif m && level > (m[1] || raise).size
           line @item_stack.pop # current level li
-          line @item_stack.pop # current level ul or ol
-          line @item_stack.pop # previous level li
-          item_list($1.size, false)
+          break
         else
           line @item_stack.pop # current level li
         end
@@ -256,8 +275,8 @@ module BitClust
       line '</dd>'
     end
 
-    def dt(s)
-      "<dt>#{s}</dt>"
+    def dt(s, id = nil)
+      id ? %Q(<dt id="#{escape_html(id)}">#{s}</dt>) : "<dt>#{s}</dt>"
     end
 
     def stop_on_syntax_error?
@@ -265,31 +284,48 @@ module BitClust
       @option[:stop_on_syntax_error]
     end
 
+    # lang 指定付きコードブロックのハイライト HTML を返す。
+    # ruby(rb などの Rouge 上の alias を含む)は構文チェックを兼ねる
+    # Ripper ベースの SyntaxHighlighter、その他の言語は Rouge を使う。
+    # Rouge が知らない言語はエスケープのみ(従来この経路と ruby の構文
+    # エラー時フォールバックはエスケープされずに出力されていたのを修正)。
+    # invalid: true(md の ```ruby invalid)は構文として完全でないコードの
+    # 印で、Ripper の構文チェックをせず Rouge の lexer で色付けする(#251)
+    def highlight_source(src, lang, caption, invalid: false)
+      lexer = ::Rouge::Lexer.find(lang)
+      if lexer && lexer.tag == 'ruby' && !invalid
+        begin
+          filename = (caption&.size || 0) > 2 ? caption : @f.name or raise
+          BitClust::SyntaxHighlighter.new(src, filename).highlight
+        rescue BitClust::SyntaxHighlighter::Error => ex
+          $stderr.puts ex.message
+          exit(false) if stop_on_syntax_error?
+          escape_html(src)
+        end
+      elsif lexer
+        ::Rouge::Formatters::HTML.new.format(lexer.lex(src))
+      else
+        escape_html(src)
+      end
+    end
+
     def emlist
       command = @f.gets
       if %r!\A//emlist\[(?<caption>[^\[\]]+?)?\]\[(?<lang>\w+?)\]! =~ command
-        line "<pre class=\"highlight #{lang}\">"
+        # @type var caption: String?
+        # @type var lang: String
+        # caption は pre 内の absolute 配置ではなく、pre の上に密着した
+        # タブとして描画する(pre 内だと編集・貼り付けで先頭行と重なる)
         line "<span class=\"caption\">#{escape_html(caption)}</span>" if caption
-        line "<code>"
-        src = ""
+        # <code> の直後に改行を入れると pre の内容の先頭に余計な空行として
+        # 表示される(pre 開始タグ直後の改行と違いブラウザは無視しない)
+        # ため、コード本体は <code> に直接続ける(#254)
+        string "<pre class=\"highlight #{lang}\"><code>"
+        src = +""
         @f.until_terminator(%r<\A//\}>) do |line|
           src << line
         end
-        if lang == "ruby"
-          begin
-            filename = (caption&.size || 0) > 2 ? caption : @f.name
-            string BitClust::SyntaxHighlighter.new(src, filename).highlight
-          rescue BitClust::SyntaxHighlighter::Error => ex
-            $stderr.puts ex.message
-            if stop_on_syntax_error?
-              exit(false)
-            else
-              string src
-            end
-          end
-        else
-          string src
-        end
+        string highlight_source(src, lang, caption)
         line '</code></pre>'
       else
         line '<pre>'
@@ -302,7 +338,7 @@ module BitClust
 
     def list
       lines = unindent_block(canonicalize(@f.break(/\A\S/)))
-      while lines.last.empty?
+      while lines.last&.empty?
         lines.pop
       end
       line '<pre>'
@@ -327,7 +363,7 @@ module BitClust
     end
 
     def see
-      header = @f.gets
+      header = @f.gets or raise
       header.slice!(/\A\@\w+/)
       body = [header] + @f.span(/\A\s+\S/)
       line '<p>'
@@ -336,7 +372,7 @@ module BitClust
     end
 
     def todo
-      header = @f.gets
+      header = @f.gets or raise
       header.slice!(/\A\@\w+/)
       body = header
       line '<p class="todo">'
@@ -344,12 +380,25 @@ module BitClust
       line '</p>'
     end
 
+    def attribute_tokens(attr_line)
+      (attr_line || '')[/\A\{:(.*)\}/, 1].to_s.strip.split(/\s+/)
+    end
+
+    # {: undef} 属性付きエントリのメッセージ。ページを見に来た人向け
+    # (statichtml は undefined エントリを skip するので server 等の動的経路用)。
+    # nomethod は説明が本文に書かれている前提のマーカーなので何も描画しない
+    def undef_message
+      line '<p>'
+      line 'このメソッドは定義されていません。'
+      line '</p>'
+    end
+
     def entry_info
       line '<dl>'
       while @f.next? and /\A\@(?!see)\w+|\A$/ =~ @f.peek
-        header = @f.gets
+        header = @f.gets or raise
         next if /\A$/ =~ header
-        cmd = header.slice!(/\A\@\w+/)
+        cmd = header.slice!(/\A\@\w+/) or raise
         @f.ungets(header)
         case cmd
         when '@param', '@arg'
@@ -385,9 +434,10 @@ module BitClust
       string %Q(<dt class="method-heading")
       string %Q( id="#{@method.index_id}") if first
       string '><code>'
-      string @method.klass.name + @method.typemark if @opt
+      string @method.klass.name + @method.display_typemark if @opt
       string escape_html(sig.friendly_string)
       string '</code>'
+      string heading_version_badges(@method, sig.name, first) if @method
       if first
         string '<span class="permalink">['
         string a_href(@urlmapper.method_url(methodid2specstring(@method.id)), "permalink")
@@ -395,7 +445,9 @@ module BitClust
         string rdoc_link(@method.id, @option[:database].properties["version"])
         if @option[:edit_base_url] && @method.source_location
           string ']['
-          string a_href(@urlmapper.edit_url(@method.source_location), 'edit')
+          # @type var urlmapper: ::BitClust::Subcommands::StatichtmlCommand::URLMapperEx
+          urlmapper = _ = @urlmapper
+          string a_href(urlmapper.edit_url(@method.source_location), 'edit')
         end
         string ']</span>'
       end
@@ -406,54 +458,68 @@ module BitClust
     end
 
     BracketLink = /\[\[[\w-]+?:[!-~]+?(?:\[\] )?\]\]/n
+    # BitClust には ISO/JIS へのリンク機能がないため、[[ISO:8601]]/[[JIS:X 0301]] は
+    # リンクにせず平文で表示する (rurema/bitclust#236)。引数に空白を含む JIS も拾う。
+    StandardRef = /\[\[(?:ISO|JIS):[!-~][!-~ ]*?\]\]/n
     NeedESC = /[&"<>]/
 
     def compile_text(str)
       escape_table = HTMLUtils::ESC
-      str.gsub(/(#{NeedESC})|(#{BracketLink})/o) {
-        if    char = $1 then escape_table[char]
-        elsif tok  = $2 then bracket_link(tok[2..-3])
-        elsif tok  = $3 then seems_code(tok)
+      str.gsub(/(#{NeedESC})|(#{StandardRef})|(#{BracketLink})/o) {
+        # @type var char: '&' | '"' | '<' | '>'
+        if    char = _ = $1 then escape_table[char]
+        elsif tok  = $2 then standard_ref(tok[2..-3] || raise)
+        elsif tok  = $3 then bracket_link(tok[2..-3] || raise)
         else
           raise 'must not happen'
         end
       }
     end
 
+    def standard_ref(link)
+      # 例: "ISO:8601" -> "ISO 8601", "JIS:X 0301" -> "JIS X 0301"
+      type, _arg = link.split(':', 2)
+      arg = _arg&.strip or raise
+      escape_html("#{type} #{arg}")
+    end
+
     def bracket_link(link, label = nil, frag = nil)
       type, _arg = link.split(':', 2)
-      arg = _arg.rstrip
+      arg = _arg&.rstrip or raise
+      # link_checker(bitclust/link_checker.rb)が指定されているときは
+      # 参照を検証用に記録する。描画には影響しない
+      @option[:link_checker]&.note_ref(type || raise, arg)
       case type
       when 'lib'
         protect(link) {
           case arg
           when '/', '_index'
-            label = 'All libraries'
+            label = _('Library Index')
           when '_builtin'
-            label = 'Builtin libraries'
+            label = _('Builtin Library')
           end
           library_link(arg, label, frag)
         }
       when 'c'
         protect(link) { class_link(arg, label, frag) }
       when 'm'
-        protect(link) { method_link(complete_spec(arg), label || arg, frag) }
+        protect(link) { method_link(complete_spec(arg), label || display_spec(arg), frag) }
       when 'f'
         protect(link) {
           case arg
           when '/', '_index'
-            arg, label = '', 'All C API'
+            arg, label = '', _('Function Index')
           end
           function_link(arg, label || arg, frag)
         }
       when 'd'
         protect(link) { document_link(arg, label, frag) }
       when 'ref'
-        protect(link) { reference_link(arg) }
+        protect(link) { reference_link(arg, label) }
       when 'url'
         direct_url(arg)
       when 'man'
-        man_link(arg)
+        man_link(arg, label)
       when 'rfc', 'RFC'
         rfc_link(arg)
       when 'ruby-list', 'ruby-dev', 'ruby-ext', 'ruby-talk', 'ruby-core'
@@ -475,37 +541,51 @@ module BitClust
       %Q(<a class="external" href="#{escape_html(url)}">#{escape_html(url)}</a>)
     end
 
-    def reference_link(arg)
+    # label はラベル付き参照(MDCompiler#ref_md_link)からの表示テキスト
+    # 上書き。指定時は refs テーブルからのセクションラベル計算を行わない
+    def reference_link(arg, label = nil)
       case arg
-      when /(\w+):(.*)\#(\w+)\z/
+      when /(\w+):(.*)\#([-\w]+)\z/
+        # @type var type: String
+        # @type var name: String
+        # @type var frag: String
         type, name, frag = $1, $2, $3
-        case type
-        when 'lib'
-          title, t, id = name, LibraryEntry.type_id.to_s, name
-        when 'c'
-          title, t, id = name, ClassEntry.type_id.to_s,   name
-        when 'm'
-          title, t, id = name, MethodEntry.type_id.to_s,  name
-        when 'd'
-          title, t, id = @option[:database].get_doc(name).title, DocEntry.type_id.to_s, name
-        else
-          raise "must not happen"
+        unless label
+          # @type var title: String
+          # @type var t: String
+          # @type var id: String
+          case type
+          when 'lib'
+            title, t, id = name, LibraryEntry.type_id.to_s, name
+          when 'c'
+            title, t, id = name, ClassEntry.type_id.to_s,   name
+          when 'm'
+            # 表示側(title)のみ display_spec で畳む。id は refs テーブルの
+            # キーなので記載どおり(bitclust#282)
+            title, t, id = display_spec(name), MethodEntry.type_id.to_s, name
+          when 'd'
+            title, t, id = @option[:database].get_doc(name).title, DocEntry.type_id.to_s, name
+          else
+            raise "must not happen"
+          end
+          label = @option[:database].refs[t, id, frag]
+          label = title + '/' + label if label and name
         end
-        label = @option[:database].refs[t, id, frag]
-        label = title + '/' + label if label and name
         bracket_link("#{type}:#{name}", label, frag)
-      when /\A(\w+)\z/
-        e = @option[:entry]
-        frag = $1
-        type = e.type_id.to_s
-        label = @option[:database].refs[type, e.name, frag] || frag
+      when /\A([-\w]+)\z/
+        frag = $1 || raise
+        unless label
+          e = @option[:entry]
+          type = e.type_id.to_s
+          label = @option[:database].refs[type, e.name, frag] || frag
+        end
         a_href('#' + frag, label)
       else
         raise "must not happen"
       end
     end
 
-    BLADE_URL = 'http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/%s/%s'
+    BLADE_URL = 'https://blade.ruby-lang.org/%s/%s'
 
     def blade_link(ml, num)
       url = sprintf(BLADE_URL, ml, num)
@@ -543,10 +623,12 @@ module BitClust
       end
     end
 
-    def man_link(spec)
-      m = /([\w\.\/]+)\((\w+)\)/.match(spec) or return escape_html(spec)
-      url = man_url(m[2], escape_html(m[1])) or return escape_html(spec)
-      %Q(<a class="external" href="#{escape_html(url)}">#{escape_html("#{m[1]}(#{m[2]})")}</a>)
+    # label はラベル付き参照(MDCompiler#ref_md_link)からの表示テキスト
+    # 上書き。リンクにできない spec ではラベルをプレーン表示に使う
+    def man_link(spec, label = nil)
+      m = /([\w\.\/]+)\((\w+)\)/.match(spec) or return escape_html(label || spec)
+      url = man_url(m[2], escape_html(m[1] || raise)) or return escape_html(label || spec)
+      %Q(<a class="external" href="#{escape_html(url)}">#{escape_html(label || "#{m[1]}(#{m[2]})")}</a>)
     end
 
     BUGS_URL = "https://bugs.ruby-lang.org/issues/%s"
@@ -558,8 +640,14 @@ module BitClust
 
     def rdoc_url(method_id, version)
       cname, tmark, mname, _libname = methodid2specparts(method_id)
-      tchar = typemark2char(tmark) == 'i' ? 'i' : 'c'
-      cname = cname.split(".").first
+      cname = cname.split(".").first || raise
+      # rdoc は Kernel のモジュール関数(rb_define_global_function 由来)を
+      # private インスタンスメソッドとして掲載しているため i にする
+      if typemark2char(tmark) == 'i' || (cname == "Kernel" && tmark == '.#')
+        tchar = 'i'
+      else
+        tchar = 'c'
+      end
       cname = cname.gsub('::', '/')
       id = "method-#{tchar}-#{encodename_rdocurl(mname)}"
 
@@ -579,6 +667,19 @@ module BitClust
       end
     end
 
+    # bitclust#282: [[m:...]] のデフォルトラベル(参照の記載文字列)は表示
+    # 専用なので、module function の ".#" は DB バージョンが 4.0 以降なら
+    # "?." で表示する(#250/#277 の display_typemark と同じ選択規則。
+    # Markdown ソースの [m:Kernel?.x] も inline 復元時に ".#" へ正規化されて
+    # ここに来るため、どちらの表記で書かれていても見出し表記と一致する)。
+    # spec・URL・アンカーキーは不変。明示ラベル(label 引数)には触れない
+    def display_spec(spec)
+      return spec unless spec.include?('.#')
+      db = @option[:database]
+      version = db ? db.propget('version') : nil
+      spec.sub('.#', NameUtils.display_typemark('.#', version))
+    end
+
     def seems_code(text)
       # FIXME
       escape_html(text)

data/lib/bitclust/refsdatabase.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 #
 # bitclust/refsdatabase.rb
 #
@@ -11,17 +12,21 @@ module BitClust
   class RefsDatabase
     def self.load(src)
       if src.respond_to?(:to_str)
+        # @type var src: _ToStr
         buf = fopen(src.to_str, 'r:UTF-8'){|f| f.read}
       elsif src.respond_to?(:to_io)
+        # @type var src: _ToIO
         buf = src.to_io.read
       else
+        # @type var src: _Reader
         buf = src.read
       end
 
       refs = self.new
-      buf.each_line{|l|
+      buf&.each_line{|l|
         if /((?:\\,|[^,])+),((?:\\,|[^,])+),((?:\\,|[^,])+),((?:\\,|[^,])+)\n/ =~ l
-          type, id, linkid, desc = [$1, $2, $3, $4].map{|e| e.gsub(/\\(.)/){|s| $1 == ',' ? ',' : s } }
+          type, id, linkid, desc = [$1, $2, $3, $4].map{|e| e&.gsub(/\\(.)/){|s| $1 == ',' ? ',' : s } }
+          type || raise; id || raise; linkid || raise; desc || raise
           refs[type, id, linkid] = desc
         end
       }
@@ -42,15 +47,18 @@ module BitClust
 
     def save(s)
       if s.respond_to?(:to_str)
+        # @type var s: _ToStr
         path = s.to_str
         io = fopen(path, 'w:UTF-8')
       elsif s.respond_to?(:to_io)
+        # @type var s: _ToIO
         io = s.to_io
       else
         io = s
       end
+      # @type var io: IO
 
-      @h.each{|k, v|
+      @h.sort.each{|k, v|
         io.write(  [k, v].flatten.map{|e| e.gsub(/,/, '\\,') }.join(',') + "\n" )
       }
       io.close
@@ -58,11 +66,19 @@ module BitClust
 
     def extract(entry)
       entry.source.each_line{|l|
-        if /\A={1,6}\[a:(\w+)\] *(.*)/ =~ l
-          entry.labels.each{|name|
-            self[entry.class.type_id, name, $1] = $2
-          }
-        end
+        anchor, label =
+          if /\A={1,6}\[a:([-\w]+)\] *(.*)/ =~ l
+            [$1, $2]
+          elsif /\A\#{1,6} +(.*?) *\{#([-\w]+)\}\s*\z/ =~ l
+            # md ソース: 「### 見出し {#anchor}」形式（M3 ネイティブパース）。
+            # ラベルは rd 表示形へ戻す（\` エスケープ解除等。pattern_matching）
+            Kernel.require 'bitclust/markdown_to_rrd'
+            [$2, ::BitClust::MarkdownToRRD.restore_description($1 || raise)]
+          end
+        next unless anchor
+        entry.labels.each{|name|
+          self[entry.class.type_id, name, anchor || raise] = label || raise
+        }
       }
     end
   end