bitclust-core 1.3.0 → 1.6.0

data/lib/bitclust/entity_splitter.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require 'bitclust/include_graph'
+require 'bitclust/whole_file_gate'
+
+module BitClust
+  # マルチエンティティ RD のエンティティ単位分割（O3）。
+  #
+  # 「ヘッダ関係（include/extend/alias）を持つエンティティは自分のファイルを持ち、
+  # 関係は front matter に一元化する」ため、関係を持つマルチエンティティファイルを
+  # エンティティ単位のセグメントへ分割する。関係を持たない束ね（Errno 族等）は
+  # 分割しない（判断はオーケストレータが行う。ここは純テキスト変換）。
+  #
+  # 分割の前処理として、スコープ定数（スコープ内で常に真/偽）の版ゲートのうち
+  # エンティティ H1 を包むものを解決する。版で改名されたエンティティ
+  # （thread/Mutex, Net::HTTPURITooLong 等の #@since/#@else H1 ペア）が
+  # スコープ内の単一 H1 に収束する（旧名は活き枝の alias 行として残っている）。
+  module EntitySplitter
+    H1_RE = /\A=(?!=)\s*(?:class|module|object|reopen|redefine)\s+(\S+)/
+    GATE_OPEN_RE = /\A\#@(since|until|if)\s*(.*)$/
+    BLOCK_OPEN_RE = /\A\#@(?:since|until|if|samplecode)\b/
+    BLANK_RE = /\A\s*\z/
+
+    module_function
+
+    # スコープ定数（スコープ内で常に真/偽）な版ゲートのうち、エンティティ H1 を
+    # 含むブロックを解決する。活きている枝の内容（再帰的に解決）を残し、
+    # ゲート行と死んだ枝を落とす。スコープ内で真偽が変わるゲートと、
+    # H1 を含まないゲート（散文の版分岐・gated relations）は触らない。
+    def resolve_header_gates(src, scope)
+      lines = src.lines
+      out = [] #: Array[String]
+      i = 0
+      while i < lines.length
+        line = lines[i]
+        truth = constant_truth(line, scope)
+        if !truth.nil? && (block = parse_block(lines, i)) &&
+           contains_entity_h1?(block[:body] + block[:else_body])
+          active = truth ? block[:body] : block[:else_body]
+          resolved = resolve_header_gates(active.join, scope).lines
+          if resolved.empty? && out.last =~ BLANK_RE && lines[block[:next]] =~ BLANK_RE
+            i = block[:next] + 1   # ブロックごと消えた場合は後続の空行を1つ畳む
+          else
+            i = block[:next]
+          end
+          out.concat(resolved)
+        else
+          out << line
+          i += 1
+        end
+      end
+      out.join
+    end
+
+    # ゲート行のスコープ定数評価: 常真なら true、常偽なら false、
+    # 定数でない／ゲートでないなら nil。
+    # #@if は「version >= "X"（X <= 下限）」形のみ常真と証明できる
+    def constant_truth(line, scope)
+      cond = gate_condition(line)
+      return nil unless cond
+      if cond.kind == :if
+        WholeFileGate.provably_true_if?(cond.version, scope) ? true : nil
+      elsif scope.always?(cond)
+        true
+      elsif scope.never?(cond)
+        false
+      end
+    end
+
+    # samplecode の内容を除いて、エンティティ H1 行を含むか
+    def contains_entity_h1?(lines)
+      code = 0
+      lines.each do |l|
+        case l
+        when /\A\#@samplecode\b/ then code += 1
+        when /\A\#@end\b/ then code -= 1 if code > 0
+        when H1_RE then return true if code.zero?
+        end
+      end
+      false
+    end
+
+    # エンティティ単位のセグメント列 [[エンティティ名, テキスト], ...] を返す。
+    # 境界は深さ0の H1 行、または最初の内容行が H1 の版ゲートブロック
+    # （スコープ内ゲート付きエンティティ。ブロック全体が1セグメント）。
+    # 先頭に H1 以外の内容がある場合（ライブラリ概要部）は name=nil の
+    # ベースセグメントとして返す。連結すると入力に一致する。
+    def segments(src)
+      lines = src.lines
+      # [行index, エンティティ名, ゲート付きか]
+      boundaries = [] #: Array[[Integer, String?, bool]]
+      depth = 0
+      lines.each_with_index do |line, i|
+        case line
+        when BLOCK_OPEN_RE
+          if depth.zero? && line =~ /\A\#@(?:since|until|if)\b/ &&
+             (name = first_h1_name(lines, i + 1))
+            boundaries << [i, name, true]
+          end
+          depth += 1
+        when /\A\#@end\b/
+          depth -= 1
+        when H1_RE
+          boundaries << [i, $1, false] if depth.zero?
+        end
+      end
+      # ゲート付き H1 境界は、ゲートがセグメント全体を包む場合のみ分割境界にする。
+      # H1 と見出しだけがゲートされ内容がゲートの外にある形（syslog の旧構造）を
+      # 単独ファイル化すると、ゲートが偽の版で自立パースできない
+      # （旧世界では直前エンティティの内容として付く）ため、直前セグメントに残す
+      boundaries = boundaries.each_with_index.select { |(start, _, gated), idx|
+        next true unless gated
+        stop = idx + 1 < boundaries.length ? boundaries[idx + 1][0] : lines.length
+        gate_wraps_segment?(lines, start, stop)
+      }.map { |(start, name, _), _| [start, name] } #: Array[[Integer, String?]]
+      return nil if boundaries.empty?
+      if (lines[0...(boundaries.first || raise)[0]] || raise).all? { |l| l =~ BLANK_RE }
+        boundaries[0] = [0, boundaries[0][1]]   # 先頭の空行は最初のセグメントへ
+      else
+        boundaries.unshift([0, nil])            # ライブラリ概要部（ベースセグメント）
+      end
+
+      boundaries.each_with_index.map do |(start, name), idx|
+        stop = idx + 1 < boundaries.length ? boundaries[idx + 1][0] : lines.length
+        [name, (lines[start...stop] || raise).join]
+      end
+    end
+
+    # start のゲート開き行に対応する #@end がセグメント終端（末尾の空行は許容）に
+    # あるか。ゲートがセグメント全体を包むときのみ真
+    def gate_wraps_segment?(lines, start, stop)
+      depth = 0
+      close = nil #: Integer?
+      (start...stop).each do |i|
+        case lines[i]
+        when BLOCK_OPEN_RE then depth += 1
+        when /\A\#@end\b/
+          depth -= 1
+          if depth.zero?
+            close = i
+            break
+          end
+        end
+      end
+      return false unless close
+      (lines[(close + 1)...stop] || raise).all? { |l| l =~ BLANK_RE }
+    end
+
+    # エンティティ名 → 出力ファイル名（拡張子なし）。既存の命名規約に合わせ :: → __
+    def entity_filename(name)
+      name.gsub('::', '__')
+    end
+
+    # いずれかのエンティティの H1 直後のヘッダ領域（関係行・#@・空行が続く範囲）に
+    # include/extend/alias があるか。本文中やコード例の同名行は数えない
+    def header_relations?(src)
+      in_header = false
+      src.each_line do |line|
+        if line =~ H1_RE
+          in_header = true
+        elsif in_header
+          case line
+          when /\A(?:include|extend|alias)\s+\S/ then return true
+          when /\A\#@/, BLANK_RE then nil
+          else in_header = false
+          end
+        end
+      end
+      false
+    end
+
+    def gate_condition(line)
+      return nil unless line =~ GATE_OPEN_RE
+      # Preprocessor は #@since "1.8.5" のクォート形式も受理する
+      IncludeGraph::Condition.new(($1 || raise).to_sym, ($2 || raise).strip.delete_prefix('"').delete_suffix('"'))
+    end
+
+    # i のゲート開始行から対応を取り、{body:, else_body:, next:} を返す。
+    # body/else_body は枝の行列、next は #@end の次の行 index。対応が取れなければ nil
+    def parse_block(lines, i)
+      depth = 0
+      body = [] #: Array[String]
+      else_body = [] #: Array[String]
+      current = body
+      j = i
+      while j < lines.length
+        line = lines[j]
+        case line
+        when BLOCK_OPEN_RE
+          depth += 1
+          current << line unless j == i
+        when /\A\#@else\b/
+          if depth == 1
+            current = else_body
+          else
+            current << line
+          end
+        when /\A\#@end\b/
+          depth -= 1
+          return { body: body, else_body: else_body, next: j + 1 } if depth.zero?
+          current << line
+        else
+          current << line
+        end
+        j += 1
+      end
+      nil
+    end
+
+    def first_content_is_h1?(branch_lines)
+      first = branch_lines.find { |l| l !~ BLANK_RE }
+      first =~ H1_RE ? true : false
+    end
+
+    # i 以降の最初の非空行が H1 ならその名前を返す
+    def first_h1_name(lines, i)
+      first = (lines[i..] || raise).find { |l| l !~ BLANK_RE }
+      first =~ H1_RE ? $1 : nil
+    end
+  end
+end

data/lib/bitclust/entry.rb

@@ -113,11 +113,11 @@ module BitClust
         when 'LibraryEntry'   then "restore_library(h['#{@name}'])"
         when 'ClassEntry'     then "restore_class(h['#{@name}'])"
         when 'MethodEntry'    then "restore_method(h['#{@name}'])"
-        when '[String]'       then "h['#{@name}'].split(/,(?=.)/)"
+        when '[String]'       then "(h['#{@name}'] || '').split(/,(?=.)/)"
         when '[LibraryEntry]' then "restore_libraries(h['#{@name}'])"
         when '[ClassEntry]'   then "restore_classes(h['#{@name}'])"
         when '[MethodEntry]'  then "restore_methods(h['#{@name}'])"
-        when 'Location'       then "h['#{@name}']&.tap { |loc| break if loc.empty?; break Location.new(*loc.split(?:)) }"
+        when 'Location'       then "h['#{@name}']&.tap { |loc| break if loc.empty?; break Location.new(loc.split(?:).first, nil) }"
         else
           raise "must not happen: @type=#{@type.inspect}"
         end
@@ -135,7 +135,7 @@ module BitClust
         when '[LibraryEntry]' then "serialize_entries(@#{@name})"
         when '[ClassEntry]'   then "serialize_entries(@#{@name})"
         when '[MethodEntry]'  then "serialize_entries(@#{@name})"
-        when 'Location'       then "@#@name.to_s"
+        when 'Location'       then "(@#{@name} && @#{@name}.file).to_s"
         else
           raise "must not happen: @type=#{@type.inspect}"
         end
@@ -150,6 +150,46 @@ module BitClust
       @db = db
     end
 
+    # description 等、コンパイラを通さない表示テキスト。
+    # md ソースの DB では旧経路と同じ表示形（rd インライン形式）へ戻す
+    def display_text(text)
+      return text unless text
+      if @db.properties['source_format'] == 'markdown'
+        # LibraryEntry#require（ライブラリ関係の登録）が Kernel#require を
+        # 隠蔽するため、ファイルロードは Kernel を明示する
+        Kernel.require 'bitclust/markdown_to_rrd'
+        ::BitClust::MarkdownToRRD.restore_description(text)
+      else
+        text
+      end
+    end
+    private :display_text
+
+    # BitClust::RDCompiler::BracketLink と同等の正規表現(/n なし)
+    BracketLink = /\[\[[\w-]+?:[!-~]+?(?:\[\] )?\]\]/
+
+    # meta description など、コンパイラを通さずマークアップも解釈されない
+    # 場所に使うテキスト。非 ASCII 文字間の改行は削除し(ブラウザでは
+    # 空白扱いになり日本語文中に不自然な空白が見えるため)、残りの改行は
+    # 空白に変換、ブラケットリンクはリンク先名のみにする
+    def description_text(text)
+      text = display_text(text)
+      return text unless text
+      # module function の ".#" は表示専用なので、DB バージョンが 4.0 以降なら
+      # "?." で表示する(RDCompiler#display_spec と同じ #250/#282 の規則。
+      # ここは可視ページを通さない meta description 用の経路なので、bracket_link
+      # と同じ変換を独立に適用する必要がある。spec・URL・アンカーキーは不変)
+      version = @db&.propget('version')
+      text = text.split("\n").map(&:strip).join("\n")
+        .gsub(/(\P{ascii})\n(?=\P{ascii})/) { $1 || raise }
+        .tr("\n", ' ')
+      text.gsub(BracketLink) {|link|
+        label = ((link[2..-3] || raise).split(':', 2).last || raise).rstrip
+        label.include?('.#') ? label.sub('.#', NameUtils.display_typemark('.#', version)) : label
+      }
+    end
+    private :description_text
+
     def type_id
       self.class.type_id
     end
@@ -189,11 +229,11 @@ module BitClust
     end
 
     def restore_library(id)
-      LibraryEntry.load(@db, id)
+      LibraryEntry.load(@db, id) # steep:ignore
     end
 
     def restore_class(id)
-      id.empty? ? nil : ClassEntry.load(@db, id)
+      id.empty? ? nil : ClassEntry.load(@db, id) # steep:ignore
     end
 
     def restore_libraries(str)
@@ -210,7 +250,7 @@ module BitClust
 
     def restore_entries(str, klass)
       return [] if str.nil?
-      str.split(',').map {|id| klass.load(@db, id) }
+      str.split(',').map {|id| klass.load(@db, id) }  # steep:ignore
     end
 
     def serialize_entry(x)
@@ -227,7 +267,7 @@ module BitClust
 
     def path_string(path)
       i = path.index(name())
-      (path[i..-1] + [name()]).join(' -> ')
+      ((path[i..-1] || raise) + [name()]).join(' -> ')
     end
     private :path_string
 

data/lib/bitclust/functiondatabase.rb

@@ -53,6 +53,18 @@ module BitClust
       @dirty_functions.clear
     end
 
+    # C API の Markdown ツリー（manual/capi）を直接パースして更新する（M3）。
+    # filename は旧経路と同じ「eval.c」等（basename から .md を除いた形）
+    def update_by_markdowntree(md_root)
+      check_transaction
+      require 'bitclust/mdparser'
+      # 描画層（screen.rb）が MDCompiler を選択するためのマーカー
+      propset 'source_format', 'markdown'
+      Dir.glob(File.join(md_root, '*.md')).sort.each do |path|
+        MDFunctionParser.new(self).parse_file(path, File.basename(path, '.md'), properties())
+      end
+    end
+
     def update_by_file(path, filename)
       check_transaction
       FunctionReferenceParser.new(self).parse_file(path, filename, properties())
@@ -69,7 +81,7 @@ module BitClust
     def open_function(id)
       check_transaction
       if exist?("function/#{id}")
-        f = load_function(id)
+        f = load_function(id) || raise
         f.clear
       else
         f = (@functionmap[id] ||= FunctionEntry.new(self, id))

data/lib/bitclust/functionentry.rb

@@ -52,6 +52,10 @@ module BitClust
     remove_method :name
     alias name id
     alias label id
+    # bitclust#250: MethodEntry の display_label と同じインターフェースを
+    # 満たすためのエイリアス。関数には module function の概念(typemark)が
+    # ないので単に label と同じ(変換なし)
+    alias display_label label
 
     alias macro? macro
     alias private? private
@@ -79,7 +83,7 @@ module BitClust
     end
 
     def description
-      source.split(/\n\n+/, 2)[0].strip
+      description_text(source.split(/\n\n+/, 2)[0].strip)
     end
   end
 end

data/lib/bitclust/functionreferenceparser.rb

@@ -61,7 +61,7 @@ module BitClust
         f.name = h.name
         f.params = h.params
         f.source = body.join('')
-        f.source_location = body[0]&.location&.tap {|loc| break Location.new(@path, loc.line - 1) }
+        f.source_location = body[0]&.location && Location.new(@path, nil)
       }
     end
 
@@ -71,9 +71,9 @@ module BitClust
       raise ParseError, "syntax error: #{header.inspect}" unless m
       h.macro = m[1] ? true : false
       h.private = m[2] ? true : false
-      h.type = m[3].strip
-      h.name = m[4]
-      h.params = m[5].strip if m[5]
+      h.type = m[3]&.strip || raise
+      h.name = m[4] || raise
+      h.params = m[5]&.strip if m[5]
       h
     end
 

data/lib/bitclust/generators/epub.rb

@@ -61,6 +61,7 @@ module BitClust
         ]
         argv << "--fs-casesensitive" if @fs_casesensitive
         argv << "--quiet" unless @verbose
+        # @type var options: Subcommand::options
         options = {
           :prefix => @prefix,
           :capi   => @capi,
@@ -71,7 +72,7 @@ module BitClust
       end
 
       def generate_contents_opf(epub_directory)
-        items = []
+        items = [] #: Array[{:id => String, :path => Pathname}]
         glob_relative_path(epub_directory, "#{CONTENTS_DIR_NAME}/class/*.xhtml").each do |path|
           items << {
             :id => decodename_package(path.basename(".*").to_s),
@@ -79,7 +80,13 @@ module BitClust
           }
         end
         items.sort_by!{|item| item[:path] }
-        contents = ERB.new(File.read(@templatedir + "contents"), nil, "-").result(binding)
+        template = (@templatedir + "contents").read
+        if ::ERB.instance_method(:initialize).parameters.last.first == :key
+          erb = ::ERB.new(template, trim_mode: '-')
+        else
+          erb = ::ERB.new(template, nil, "-") # steep:ignore UnexpectedPositionalArgument
+        end
+        contents = erb.result(binding)
         File.open(epub_directory + "contents.opf", "w") do |f|
           f.write contents
         end
@@ -94,7 +101,7 @@ module BitClust
       end
 
       def glob_relative_path(path, pattern)
-        relative_paths = []
+        relative_paths = [] #: Array[Pathname]
         absolute_path_to_search = Pathname.new(path).realpath
         Dir.glob(absolute_path_to_search + pattern) do |absolute_path|
           absolute_path = Pathname.new(absolute_path)

data/lib/bitclust/htmlutils.rb

@@ -21,7 +21,7 @@ module BitClust
 
     # make method anchor from MethodEntry
     def link_to_method(m, specp = false)
-      label = specp ? m.label : m.short_label
+      label = specp ? m.display_label : m.display_short_label
       a_href(@urlmapper.method_url(methodid2specstring(m.id)), label)
     end