bitclust-core 1.3.0 → 1.6.0

data/lib/bitclust/methodentry.rb

@@ -44,7 +44,8 @@ module BitClust
       sort_key() <=> other.sort_key
     end
 
-    KIND_NUM = {:defined => 0, :redefined => 1, :added => 2}
+    KIND_NUM = {:defined => 0, :redefined => 1, :added => 2,
+                :undefined => 3, :nomethod => 4}
 
     def sort_key
       [label(), KIND_NUM[kind()]]
@@ -73,6 +74,14 @@ module BitClust
       methodid2typechar(@id)
     end
 
+    # bitclust#250: 表示専用の typemark。DB のバージョンが 4.0 以降なら
+    # module function の "." を "?." にする(それ以外の typemark は不変)。
+    # typemark 自体(識別子として使う方)は変えない -- URL・spec 文字列・
+    # refsdatabase のアンカーキー等はすべて typemark() 経由のまま
+    def display_typemark
+      NameUtils.display_typemark(typemark(), @db.propget('version'))
+    end
+
     def type_label
       case typemark()
       when '.'  then 'singleton method'
@@ -80,6 +89,7 @@ module BitClust
       when '.#' then 'module function'
       when '::' then 'constant'
       when '$'  then 'variable'
+      else raise "invalid typemark: #{typemark().inspect}"
       end
     end
 
@@ -97,10 +107,17 @@ module BitClust
 
     persistent_properties {
       property :names,           '[String]'
-      property :visibility,      'Symbol'   # :public | :private | :protected
-      property :kind,            'Symbol'   # :defined | :added | :redefined
+      property :visibility,      'Symbol'   ## :public | :private | :protected
+      property :kind,            'Symbol'   ## :defined | :added | :redefined | :undefined | :nomethod
       property :source,          'String'
       property :source_location, 'Location'
+      # 名前別の since/until（bitclust#132）。トークンは
+      # "#{エンコード名}=#{バージョン}" の配列（[String] 型を再利用）で、
+      # 生名の ',' '=' は encodename_url でエスケープ済みなので最後の '='
+      # がバージョンとの区切りになる（バージョン文字列には '=' も ',' も
+      # 現れない前提。fill_since/fill_until で検査する）
+      property :since_by_name,   '[String]'
+      property :until_by_name,   '[String]'
     }
 
     def inspect
@@ -109,7 +126,8 @@ module BitClust
     end
 
     def spec
-      MethodSpec.new(*methodid2specparts(@id))
+      c, t, m, lib = methodid2specparts(@id)
+      MethodSpec.new(c, t, m, lib)
     end
 
     def spec_string
@@ -121,11 +139,29 @@ module BitClust
       "#{t == '$' ? '' : c}#{t}#{m}"
     end
 
+    # bitclust#250: label の表示専用版(module function は 4.0 以降 "?." で
+    # 表示)。label 自身は refsdatabase.rb の [[a:...]] アンカーキーや
+    # `bitclust methods --diff` の突き合わせが literal ".#" 前提で使うので
+    # 変えない -- テンプレート側の実際の表示箇所だけがこちらを呼ぶ
+    def display_label
+      c, t, m, _lib = methodid2specparts(@id)
+      "#{t == '$' ? '' : c}#{display_typemark}#{m}"
+    end
+
     def short_label
       _c, t, m, _lib = methodid2specparts(@id)
       "#{t == '#' ? '' : t}#{m}"
     end
 
+    # bitclust#250: short_label の表示専用版。short_label 自身の唯一の
+    # 呼び出し元(htmlutils.rb の link_to_method)は display_short_label に
+    # 切り替え済みだが、short_label 自体は同じ理由(識別子的な使い方をする
+    # 将来のコードのため)で変えない
+    def display_short_label
+      _c, t, m, _lib = methodid2specparts(@id)
+      "#{t == '#' ? '' : display_typemark}#{m}"
+    end
+
     def index_id
       "#{methodid2typechar(@id)}_#{encodename_fs(name).gsub(/=/, '--')}".upcase
     end
@@ -135,10 +171,79 @@ module BitClust
       names().map {|name| "#{c}#{t}#{name}" }
     end
 
+    # Every name of this entry, formatted the same way as #label (i.e.
+    # without the redundant class prefix on special variables such as $!,
+    # unlike #labels). Used where all aliases of a method need to be listed
+    # together, e.g. the <title> of its page.
+    def title_labels
+      c, t, _m, _lib = methodid2specparts(@id)
+      names().map {|name| "#{t == '$' ? '' : c}#{t}#{name}" }
+    end
+
+    # bitclust#250: title_labels の表示専用版(<title> タグ・見出しで使う)
+    def display_title_labels
+      c, t, _m, _lib = methodid2specparts(@id)
+      names().map {|name| "#{t == '$' ? '' : c}#{display_typemark}#{name}" }
+    end
+
     def name?(name)
       names().include?(name)
     end
 
+    # 名前別 since/until（bitclust#132）。名前ごとに別バージョンで
+    # 追加/削除されうる別名（例: alias）を区別して記録する
+
+    def since_of(name)
+      since_map[name]
+    end
+
+    def until_of(name)
+      until_map[name]
+    end
+
+    def since_map
+      decode_version_tokens(since_by_name)
+    end
+
+    def until_map
+      decode_version_tokens(until_by_name)
+    end
+
+    # name の since が未設定の場合のみ version を追加する。追加したら true、
+    # 既に値があって何もしなければ false を返す
+    def fill_since(name, version)
+      fill_version_token(:since_by_name, :since_of, name, version)
+    end
+
+    # fill_since の until 版
+    def fill_until(name, version)
+      fill_version_token(:until_by_name, :until_of, name, version)
+    end
+
+    private
+
+    def decode_version_tokens(tokens)
+      h = {} #: Hash[String, String]
+      tokens.each do |token|
+        i = token.rindex('=') or raise "must not happen: malformed version token #{token.inspect}"
+        raw_name = decodename_url(token[0...i] || raise)
+        h[raw_name] = token[(i + 1)..] || raise
+      end
+      h
+    end
+
+    def fill_version_token(prop, reader, name, version)
+      if version.include?('=') || version.include?(',')
+        raise ArgumentError, "version must not contain '=' or ',': #{version.inspect}"
+      end
+      return false if __send__(reader, name)
+      token = "#{encodename_url(name)}=#{version}"
+      __send__("#{prop}=", __send__(prop) + [token])
+      true
+    end
+
+    public
+
     def name_match?(re)
       names().any? {|n| re =~ n }
     end
@@ -148,7 +253,7 @@ module BitClust
     end
 
     def public?
-      visibility() != :private
+      visibility() != :private && visibility() != :protected
     end
 
     def protected?
@@ -172,7 +277,11 @@ module BitClust
     end
 
     def private_instance_method?
-      instance_method? and public?
+      instance_method? and private?
+    end
+
+    def protected_instance_method?
+      instance_method? and protected?
     end
 
     def singleton_method?
@@ -209,8 +318,17 @@ module BitClust
       kind() == :undefined
     end
 
+    # 説明のためだけに記載されていて実際には定義されていないメソッド
+    # （ソースの @nomethod メタデータ行で指定する）
+    def nomethod?
+      kind() == :nomethod
+    end
+
     def description
-      source.split(/\n\n+/, 3)[1]
+      paragraphs = source.split(/\n\n+/).drop(1)
+      # {: ...} 属性行や @param などのメタデータ段落は説明文として使わない
+      para = paragraphs.find {|p| !p.start_with?('@', '{:') } || paragraphs.first || ''
+      description_text(para)
     end
   end
 end

data/lib/bitclust/methodid.rb

@@ -66,7 +66,8 @@ module BitClust
   class MethodSpec
 
     def MethodSpec.parse(str)
-      new(*NameUtils.split_method_spec(str))
+      c, t, m = NameUtils.split_method_spec(str)
+      new(c, t, m)
     end
 
     def initialize(c, t, m, library = nil)
@@ -89,8 +90,13 @@ module BitClust
       "#{@klass}#{@type}#{@method}"
     end
 
-    def display_name
-      @type == '$' ? "$#{@method}" : to_s()
+    # version はドキュメント対象の Ruby バージョン(DB の version プロパティ)。
+    # 指定すると module function の typemark を表示用に畳む
+    # (4.0 以降は "?."。NameUtils#display_typemark と同じ規則)
+    def display_name(version = nil)
+      return "$#{@method}" if @type == '$'
+      return "#{@klass}#{NameUtils.display_typemark(_ = @type, version)}#{@method}" if version
+      to_s()
     end
 
     def ==(other)
@@ -182,15 +188,10 @@ module BitClust
     private :tesc
 
     def match?(m)
-      (not @library or m.library.name?(@library)) and
-      (not @klass   or m.klass.name?(@klass)) and
+      (not @library or m.library.name?(@library || raise)) and
+      (not @klass   or m.klass.name?(@klass || raise)) and
       (not @type    or m.typemark == @type) and
-      (not @method  or m.name?(@method))
-    end
-
-    def select_classes(cs)
-      return cs unless @klass
-      expand_ic(cs, @klass, @crecache)
+      (not @method  or m.name?(@method || raise))
     end
 
     def empty?

data/lib/bitclust/methodsignature.rb

@@ -33,7 +33,7 @@ module BitClust
       m = METHOD_SIGNATURE_RE.match(line) or
           raise ParseError, %Q(unknown signature format: "#{line.strip}")
       method, gvar, params, block, type = m.captures
-      new(method || gvar, params && params.strip, block && block.strip, type && type.strip)
+      new(method || gvar || raise, params && params.strip, block && block.strip, type && type.strip)
     end
 
     def initialize(name, params, block, type)
@@ -64,9 +64,15 @@ module BitClust
       when "[]"     # aref
         "self[#{@params}]" + (@type ? " -> #{@type}" : "")
       when "[]="    # aset
-        params = @params.split(',')
-        val = params.pop
-        "self[#{params.join(',').strip}] = #{val.strip}"
+        params = @params&.split(',')
+        if params && params.size >= 2
+          val = params.pop || raise
+          "self[#{params.join(',').strip}] = #{val.strip}"
+        else
+          # Signatures like []=(*idxary) in historic documents cannot be
+          # shaped into "self[...] = ..."; show the raw signature instead
+          to_s()
+        end
       when "`"  # `command`
         "`#{@params}`" + (@type ? " -> #{@type}" : "")
       when /\A\W/   # binary operator

data/lib/bitclust/nameutils.rb

@@ -59,51 +59,55 @@ module BitClust
     def split_method_spec(spec)
       case spec
       when /\AKernel\$/
-        return 'Kernel', '$', $'
+        return ['Kernel', '$', $' || raise]
       else
         m = /\A(#{CLASS_PATH_RE})(#{TYPEMARK_RE})(#{METHOD_NAME_RE})\z/o.match(spec) or
             raise ArgumentError, "wrong method spec: #{spec.inspect}"
-        return *m.captures
+        cname = m[1] || raise
+        # @type var tmark: NameUtils::typemark
+        tmark = _ = m[2] || raise
+        mname = m[3] || raise
+        return [cname, tmark, mname]
       end
     end
 
     def methodid2specstring(id)
-      c, t, m, _lib = *split_method_id(id)
+      c, t, m, _lib = split_method_id(id)
       classid2name(c) + typechar2mark(t) + decodename_url(m)
     end
 
     def methodid2specparts(id)
-      c, t, m, lib = *split_method_id(id)
-      return classid2name(c), typechar2mark(t), decodename_url(m), libid2name(lib)
+      c, t, m, lib = split_method_id(id)
+      [classid2name(c), typechar2mark(t), decodename_url(m), libid2name(lib)]
     end
 
     def methodid2libid(id)
-      _c, _t, _m, lib = *split_method_id(id)
+      _c, _t, _m, lib = split_method_id(id)
       lib
     end
 
     def methodid2classid(id)
-      c, _t, _m, _lib = *split_method_id(id)
+      c, _t, _m, _lib = split_method_id(id)
       c
     end
 
     def methodid2typechar(id)
-      _c, t, _m, _lib = *split_method_id(id)
+      _c, t, _m, _lib = split_method_id(id)
       t
     end
 
     def methodid2typename(id)
-      _c, t, _m, _lib = *split_method_id(id)
+      _c, t, _m, _lib = split_method_id(id)
       typechar2name(t)
     end
 
     def methodid2typemark(id)
-      _c, t, _m, _lib = *split_method_id(id)
+      _c, t, _m, _lib = split_method_id(id)
       typechar2mark(t)
     end
 
     def methodid2mname(id)
-      _c, _t, m, _lib = *split_method_id(id)
+      _c, _t, m, _lib = split_method_id(id)
       decodename_url(m)
     end
 
@@ -121,13 +125,13 @@ module BitClust
       "#{cid}/#{typename2char(t)}.#{encodename_url(name)}.#{libid}"
     end
 
-    @@split_method_id = {}
+    @@split_method_id = {} #: Hash[String, untyped]
 
     # private module function
     def split_method_id(id)
       @@split_method_id[id] ||= begin
         c, rest = id.split("/")
-        [c, *rest.split(%r<[/\.]>, 3)]
+        [c, *rest&.split(%r<[/\.]>, 3)]
       end
     end
 
@@ -142,7 +146,7 @@ module BitClust
     MARK_TO_NAME = NAME_TO_MARK.invert
 
     def typename?(n)
-      NAME_TO_MARK.key?(n)
+      NAME_TO_MARK.key?(_ = n)
     end
 
     def typename2mark(name)
@@ -166,7 +170,7 @@ module BitClust
     CHAR_TO_NAME = NAME_TO_CHAR.invert
 
     def typechar?(c)
-      CHAR_TO_NAME.key?(c)
+      CHAR_TO_NAME.key?(_ = c)
     end
 
     def typename2char(name)
@@ -190,7 +194,7 @@ module BitClust
     CHAR_TO_MARK = MARK_TO_CHAR.invert
 
     def typemark?(m)
-      MARK_TO_CHAR.key?(m)
+      MARK_TO_CHAR.key?(_ = m)
     end
 
     def typechar2mark(char)
@@ -203,24 +207,39 @@ module BitClust
           raise "must not happen: #{mark.inspect}"
     end
 
+    # bitclust#250: Ruby 4.0 以降のドキュメントでは module function の表記を
+    # るりま独自の ".#" から "?." に変える(表示のみ。ソース側は既に "?."
+    # 記法に対応済みで、内部的には従来どおり ".#" に変換される)。
+    #
+    # これは見た目だけの変換であり、method id・URL・spec 文字列など識別子と
+    # して使う ".#" 自体は一切変えない。typemark が '.#' 以外、または version
+    # が不明(nil/空)な場合はそのまま返す。バージョン比較は文字列比較では
+    # なく Gem::Version で行う("10.0" を文字列比較すると "4.0" より小さく
+    # 見えてしまうため)。
+    def display_typemark(mark, version)
+      return mark unless mark == '.#'
+      return mark unless version && !version.empty?
+      Gem::Version.new(version) >= Gem::Version.new('4.0') ? '?.' : mark
+    end
+
     def functionname?(n)
       /\A\w+\z/ =~ n ? true : false
     end
 
     # string -> case-sensitive ID
     def encodename_url(str)
-      str.gsub(/[^A-Za-z0-9_]/n) {|ch| sprintf('=%02x', ch[0].ord) }
+      str.gsub(/[^A-Za-z0-9_]/n) {|ch| sprintf('=%02x', (ch[0] || raise).ord) }
     end
 
     # case-sensitive ID -> string
     def decodename_url(str)
-      str.gsub(/=[\da-h]{2}/ni) {|s| s[1,2].hex.chr }
+      str.gsub(/=[\da-h]{2}/ni) {|s| (s[1,2] || raise).hex.chr }
     end
 
     # string -> encoded string in a rdoc way
     def encodename_rdocurl(str)
       str = str.gsub(/[^A-Za-z0-9_.]/n) {|ch|
-        sprintf('-%02X', ch[0].ord)
+        sprintf('-%02X', (ch[0] || raise).ord)
       }
       str.sub(/\A-/, '')
     end
@@ -232,18 +251,18 @@ module BitClust
 
     # encoded string -> case-sensitive ID (decode only [A-Z])
     def decodeid(str)
-      str.gsub(/-[a-z]/ni) {|s| s[1,1].upcase }
+      str.gsub(/-[a-z]/ni) {|s| (s[1,1] || raise).upcase }
     end
 
     def encodename_fs(str)
       str.gsub(/[^a-z0-9_]/n) {|ch|
-        (/[A-Z]/n =~ ch) ? "-#{ch}" : sprintf('=%02x', ch[0].ord)
+        (/[A-Z]/n =~ ch) ? "-#{ch}" : sprintf('=%02x', (ch[0] || raise).ord)
       }.downcase
     end
 
     def decodename_fs(str)
       str.gsub(/=[\da-h]{2}|-[a-z]/ni) {|s|
-        (/\A-/ =~ s) ? s[1,1].upcase : s[1,2].hex.chr
+        (/\A-/ =~ s) ? (s[1,1] || raise).upcase : (s[1,2] || raise).hex.chr
       }
     end
 

data/lib/bitclust/preprocessor.rb

@@ -8,6 +8,7 @@
 # You can distribute/modify this program under the Ruby License.
 #
 
+require 'bitclust/compat'
 require 'bitclust/parseutils'
 require 'strscan'
 
@@ -40,10 +41,15 @@ module BitClust
 
 
   # Handle pragmas like #@todo, #@include, #@since, etc.
+  #
+  # bitclust#285: prefix は #% が正式(GitHub が #@since 等の @英字 を
+  # ユーザー mention として解釈してしまうため)。旧 prefix #@ も、凍結タグ
+  # (frozen-*)の旧ソースを再取込する場合に備えて引き続き受け付ける。
   class Preprocessor < LineFilter
 
     def self.read(path, params = {})
       if path.respond_to?(:gets)
+        # @type var path: File
         io = wrap(path, params)
       else
         io = wrap(fopen(path, 'r:UTF-8'), params)
@@ -81,36 +87,48 @@ module BitClust
     def next_line(f)
       while line = f.gets
         case line
-        when /\A(?!\#@)/
+        when /\A(?!\#[@%])/
           if current_cond.processing?
             @buf.push line
             break
           end
-        when /\A\#@\#/   # preprocessor comment
+        when /\A\#[@%]\#/   # preprocessor comment
           ;
-        when /\A\#@todo/i
-          @buf.push line.gsub(/\A\#/, '') if current_cond.processing?
-        when /\A\#@include\s*\((.*?)\)/
+        when /\A\#[@%]todo/i
+          # 出力は prefix によらず @todo に正規化する(下流の表示処理は
+          # 従来どおり @todo だけを見ればよい)
+          @buf.push line.sub(/\A\#[@%]/, '@') if current_cond.processing?
+        when /\A\#[@%]include\s*\((.*?)\)/
           next unless current_cond.processing?
           begin
-            file = $1.strip
-            basedir = File.dirname(line.location.file)
-            @buf.concat Preprocessor.process("#{basedir}/#{file}", @params)
+            file = ($1 || raise).strip
+            basedir = File.dirname(line.location.file || raise)
+            path = "#{basedir}/#{file}"
+            # md ツリーのネイティブパース: 断片は .md 拡張子付きで保存されるが
+            # include ターゲットは元式の名前のまま（拡張子なしの pack-template、
+            # .rd 付きの fiddle/2.0/fiddle.lib.rd 等）。md 側の実ファイル名を試す
+            unless File.exist?(path)
+              cand = ["#{path}.md", path.sub(/\.rd\z/, '.md')].find { |c| File.exist?(c) }
+              path = cand if cand
+            end
+            @buf.concat Preprocessor.process(path, @params)
           rescue Errno::ENOENT => _err
             raise WrongInclude, "#{line.location}: \#@include'ed file not exist: #{file}"
           end
-        when /\A\#@since\b/
+        when /\A\#[@%]since\b/
           cond_stmt_begin line, build_cond_by_value(line, 'version >=')
-        when /\A\#@until\b/
+        when /\A\#[@%]until\b/
           cond_stmt_begin line, build_cond_by_value(line, 'version <')
-        when /\A\#@samplecode\b/
+        when /\A\#[@%]version\b/
+          cond_stmt_begin line, build_cond_by_range(line)
+        when /\A\#[@%]samplecode\b/
           samplecode_begin(line, samplecode_description_by_value(line))
-        when /\A\#@if\b/
-          cond_stmt_begin line, line.sub(/\A\#@if/, '').strip
-        when /\A\#@else\s*\z/
+        when /\A\#[@%]if\b/
+          cond_stmt_begin line, line.sub(/\A\#[@%]if/, '').strip
+        when /\A\#[@%]else\s*\z/
           parse_error "no matching \#@if", line  if cond_toplevel?
           cond_invert
-        when /\A\#@end\s*\z/
+        when /\A\#[@%]end\s*\z/
           if samplecode_processing?
             samplecode_end
           else
@@ -123,7 +141,7 @@ module BitClust
       end
       if @buf.empty?
         unless cond_toplevel?
-          parse_error "unterminated \#@if", @last_if
+          parse_error "unterminated \#@if", @last_if || raise
         end
       end
       @buf.shift
@@ -138,8 +156,27 @@ module BitClust
       end
     end
 
+    # 版範囲の省略記法(#285): #%version A...B は半開区間 [A, B)。
+    # Ruby の終端排他 Range リテラルに合わせて3点ドット(.. は終端を含むと
+    # 誤解しやすいため受け付けない)。A... は A 以上、...B は B 未満。
+    # 版はダブルクォート付きでもよい
+    VERSION_LITERAL = /"(\d+(?:\.\d+)*)"|(\d+(?:\.\d+)*)/
+    def build_cond_by_range(line)
+      raw = line.sub(/\A\#[@%]version\b/, '').strip
+      case raw
+      when /\A#{VERSION_LITERAL}\.\.\.#{VERSION_LITERAL}\z/o
+        %Q(version >= "#{$1 || $2}" and version < "#{$3 || $4}")
+      when /\A#{VERSION_LITERAL}\.\.\.\z/o
+        %Q(version >= "#{$1 || $2}")
+      when /\A\.\.\.#{VERSION_LITERAL}\z/o
+        %Q(version < "#{$1 || $2}")
+      else
+        parse_error "wrong version range (expected A...B / A... / ...B)", line
+      end
+    end
+
     def build_cond_by_value(line, left)
-      case ver = line.sub(/\A\#@\w+/, '').strip
+      case ver = line.sub(/\A\#[@%]\w+/, '').strip
       when /\A[\d\.]+\z/
         %Q(#{left} "#{ver}")
       when /\A"[\d\.]+"\z/
@@ -150,7 +187,7 @@ module BitClust
     end
 
     def current_cond
-      @state_stack.last
+      @state_stack.last || raise
     end
 
     def cond_init
@@ -162,13 +199,13 @@ module BitClust
     end
 
     def cond_push(bool)
-      last = @state_stack.last
+      last = @state_stack.last || raise
       @state_stack.push(last.next(bool, :condition))
     end
 
     def cond_invert
-      b = @state_stack.pop.processing?
-      last = @state_stack.last
+      b = (@state_stack.pop || raise).processing?
+      last = @state_stack.last || raise
       @state_stack.push(last.next(!b, :condition))
     end
 
@@ -229,10 +266,10 @@ module BitClust
     def eval_primary(s)
       s.skip(/\s+/)
       if t = s.scan(/\w+/)
-        unless @params.key?(t)
+        unless @params.key?(t) # steep:ignore
           scan_error "database property `#{t}' not exist"
         end
-        @params[t]
+        @params[t] # steep:ignore
       elsif t = s.scan(/".*?"/)
         eval(t)
       elsif t = s.scan(/'.*?'/)
@@ -258,7 +295,7 @@ module BitClust
     end
 
     def samplecode_push(description)
-      last = @state_stack.last
+      last = @state_stack.last || raise
       @state_stack.push(last.next(true, :samplecode))
     end
 
@@ -267,11 +304,11 @@ module BitClust
     end
 
     def samplecode_processing?
-      @state_stack.last.samplecode?
+      (@state_stack.last || raise).samplecode?
     end
 
     def samplecode_description_by_value(line)
-      line.sub(/\A\#@samplecode/, "")
+      line.sub(/\A\#[@%]samplecode/, "")
     end
 
     def scan_error(msg)
@@ -321,10 +358,10 @@ module BitClust
 
     def next_line(f)
       while line = f.gets
-        if /\A\#@include\s*\((.*?)\)/ =~ line
+        if /\A\#[@%]include\s*\((.*?)\)/ =~ line
           begin
-            file = $1.strip
-            basedir = File.dirname(line.location.file)
+            file = ($1 || raise).strip
+            basedir = File.dirname(line.location.file || raise)
             @buf.concat LineCollector.process("#{basedir}/#{file}")
           rescue Errno::ENOENT => _err
             raise WrongInclude, "#{line.location}: \#@include'ed file not exist: #{file}"