bitclust-core 1.2.6 → 1.6.0

data/lib/bitclust/methodentry.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 #
 # bitclust/methodentry.rb
 #
@@ -43,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()]]
@@ -72,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'
@@ -79,6 +89,7 @@ module BitClust
       when '.#' then 'module function'
       when '::' then 'constant'
       when '$'  then 'variable'
+      else raise "invalid typemark: #{typemark().inspect}"
       end
     end
 
@@ -96,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
@@ -108,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
@@ -120,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
@@ -134,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
@@ -147,7 +253,7 @@ module BitClust
     end
 
     def public?
-      visibility() != :private
+      visibility() != :private && visibility() != :protected
     end
 
     def protected?
@@ -171,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?
@@ -204,8 +314,21 @@ module BitClust
       kind() == :redefined
     end
 
+    def undefined?
+      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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 #
 # bitclust/methodid.rb
 #
@@ -65,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)
@@ -88,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)
@@ -181,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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 #
 # bitclust/methodsignature.rb
 #
@@ -32,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)
@@ -63,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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 #
 # bitclust/nameutils.rb
 #
@@ -58,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
 
@@ -120,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
 
@@ -141,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)
@@ -165,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)
@@ -189,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)
@@ -202,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
@@ -231,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/parseutils.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 #
 # bitclust/parseutils.rb
 #