bitclust-core 1.8.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 299762c07571e6e3b72eebe00c9d1e1d520ef9f5c3b68de759adc0c173d2ee18
-  data.tar.gz: beab538e8caec8fb1f7265808adceaa5574b22793dfb11a521651687204416d1
+  metadata.gz: c926bbf2b56a9b2553e97487db023f2ac8aac329ab1af22d2f8b56fa09afc8d5
+  data.tar.gz: 072201ad18fc53aac71ac620388018469fe618299f0af50bc5abf0a553e596ab
 SHA512:
-  metadata.gz: a4d23713bd97acaa6cb98de51e95766c87f09329c0dba4c2b42152838023ec4ce681f1c7f38db582b7e3e20809a2749152da84a74399741dc113ad9251f0875d
-  data.tar.gz: ce441c5b5a4abc9cbef8a46bf9efa2a57a5cae8bdd827c9edf7af095e60bea9c95a85ceee54baa73e850b0a7a4682b1d5afd41ce41e386040e78761ca88038fd
+  metadata.gz: 419ddb1ee1e46be729fc87e957a9aebd56a490810f8134b26617654986b77a5f1aef9b0599ecb7b6c9342dcb57c1417510cf93d9a7169614b36f195f67bd7d43
+  data.tar.gz: d683d676ce9daa86aa4544730f38898eb21ffdcd4e604711b01db22416531fe080685e5b6eddb533cafa8c71b135f7453f20fd42b58771f86faf762a8d7b602e

data/lib/bitclust/markdown_tree.rb

@@ -32,6 +32,11 @@ module BitClust
       new(root).scan
     end
 
+    # 1 ファイル分の front matter と本文の情報（scan が各ファイルで読むもの）
+    def self.file_info(path)
+      new(File.dirname(path)).file_info(File.basename(path))
+    end
+
     attr_reader :libraries, :entities, :fragments, :warnings
 
     def initialize(root)
@@ -87,6 +92,11 @@ module BitClust
       self
     end
 
+    # root 相対の path を 1 ファイルだけ読む
+    def file_info(path)
+      parse_file(path)
+    end
+
     private
 
     def validate(path, info)

data/lib/bitclust/methoddatabase.rb

@@ -216,7 +216,6 @@ module BitClust
       gate[:until] = until_version if until_version
       md_gate_covers?(version, gate)
     end
-    private :md_version_covers?
 
     # membership のゲート（MarkdownTree の since/until/version/except）がこの版を
     # 含むか。version は「その版のみ」、except は「その版以外」（#%version V と
@@ -229,7 +228,6 @@ module BitClust
       return false if (except = gate[:except]) && except.any? { |x| v == Gem::Version.new(x) }
       true
     end
-    private :md_gate_covers?
 
     def refs
       @refs ||= RefsDatabase.load(realpath('refs'))

data/lib/bitclust/subcommands/htmlfile_command.rb

@@ -14,13 +14,17 @@ module BitClust
       def initialize
         super
         @target = nil
+        @library = nil
         @templatedir = srcdir_root + "data/bitclust/template.offline"
         @baseurl = "file://" + srcdir_root.to_s
         @version = RUBY_VERSION
-        @parser.banner = "Usage: #{File.basename($0, '.*')} htmlfile [options] rdfile"
+        @parser.banner = "Usage: #{File.basename($0, '.*')} htmlfile [options] rdfile|mdfile"
         @parser.on('--target=NAME', 'Compile NAME to HTML.') {|name|
           @target = name
         }
+        @parser.on('--library=NAME', 'Library of the Markdown entity file (overrides front matter library:).') {|name|
+          @library = name
+        }
         @parser.on('--[no-]force', '-f', 'Force to use rd_file template.') {|bool|
           @rd_file = bool
         }
@@ -47,7 +51,10 @@ module BitClust
         end
         @capi = options[:capi]
         target_file = argv[0]
-        reject_markdown_source(target_file)
+        if target_file&.end_with?('.md')
+          exec_markdown(target_file, options[:prefix] ? db : nil)
+          return
+        end
         if /refm\/doc\// =~ target_file
           @rd_file = true if @rd_file.nil?
         end
@@ -89,10 +96,68 @@ module BitClust
 
       private
 
-      # 旧 RD ソース(refm)専用なので、Markdown は未対応として案内する
-      def reject_markdown_source(path)
-        return unless path && path.end_with?('.md')
-        error "#{path}: htmlfile は旧 RD ソース(refm)専用で、Markdown(manual/ の .md)には未対応です。manual/ の内容は doctree の rake generate:X.Y と bitclust server(または rake statichtml:X.Y)で確認してください"
+      # Markdown ソース(manual/ の .md)を変換する。パースは source_format が
+      # markdown の dummy DB で行い、描画には real_db があればそれを使う
+      def exec_markdown(path, real_db)
+        require 'bitclust/mdparser'
+        require 'bitclust/markdown_tree'
+        props = { 'version' => @version } #: Database::database_properties
+        db = MethodDatabase.dummy(props)
+        db.properties['source_format'] = 'markdown'
+        screen_db = real_db || db
+        manager = ScreenManager.new(:templatedir => @templatedir,
+                                    :base_url => @baseurl,
+                                    :cgi_url => @baseurl,
+                                    :default_encoding => 'utf-8')
+        @rd_file = true if @rd_file.nil? && %r<(?:\A|/)manual/doc/> =~ path
+        if @rd_file
+          puts manager.doc_screen(markdown_doc_entry(db, path, props), { :database => screen_db }).body
+        elsif @capi
+          fdb = FunctionDatabase.dummy(props)
+          fdb.properties['source_format'] = 'markdown'
+          funcs = MDFunctionParser.new(fdb).parse_file(path, File.basename(path, '.md'), props)
+          unless @target
+            raise NotImplementedError, "generating a C API html without --target=NAME is not implemented yet."
+          end
+          puts manager.entry_screen(lookup(funcs, @target), { :database => screen_db, :target_version => @version }).body
+        else
+          lib = MDParser.new(db).parse_file(path, markdown_libname(db, path), props)
+          entry = @target ? lookup(lib, @target) : lib
+          puts manager.entry_screen(entry, { :database => screen_db, :target_version => @version }).body
+        end
+      rescue ParseError, WriterError => ex
+        error "#{path}: #{ex.message}"
+      end
+
+      # manual/doc/ の md を doc ページにする(MethodDatabase#copy_doc_md と同じ手順)
+      def markdown_doc_entry(db, path, props)
+        rel = path[%r<(?:\A|/)manual/doc/(.+)\.md\z>, 1] || File.basename(path, '.md')
+        entry = DocEntry.new(db, NameUtils.libname2id(rel))
+        title, source = MDParser.split_doc(Preprocessor.read(path, props))
+        entry.title = title
+        entry.source = source
+        entry.source_location = Location.new(path, 1)
+        entry
+      end
+
+      # 所属ライブラリ名。--library > ライブラリルート(type: library)の
+      # name: またはパス(manual/api/ からの相対、無ければファイル名)>
+      # エンティティの library:(この版で生きている先頭の所属)
+      def markdown_libname(db, path)
+        info = MarkdownTree.file_info(path)
+        unless db.md_version_covers?(@version, info[:since], info[:until])
+          $stderr.puts "warning: #{path}: front matter の since/until により Ruby #{@version} には含まれないファイルです"
+        end
+        if (name = @library)
+          return name
+        end
+        if info[:library_file]
+          return info[:name] || path[%r<(?:\A|/)api/(.+)\.md\z>, 1] || File.basename(path, '.md')
+        end
+        memberships = info[:memberships]
+        m = memberships.find {|x| db.md_gate_covers?(@version, x) } || memberships.first
+        return m[:library] if m
+        error "#{path}: front matter に library: がありません。--library=NAME で所属ライブラリを指定してください"
       end
 
       def lookup(lib, key)

data/lib/bitclust/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module BitClust
-  VERSION = "1.8.0"
+  VERSION = "1.9.0"
 end

data/test/test_extract_command.rb

@@ -3,7 +3,6 @@ require 'stringio'
 require 'tmpdir'
 require 'bitclust'
 require 'bitclust/subcommands/extract_command'
-require 'bitclust/subcommands/htmlfile_command'
 
 class TestRdOnlyCommandsRejectMarkdown < Test::Unit::TestCase
   def with_md_file
@@ -32,14 +31,4 @@ class TestRdOnlyCommandsRejectMarkdown < Test::Unit::TestCase
       assert_match(/refm/, msg)
     end
   end
-
-  def test_htmlfile_explains_markdown_is_unsupported
-    with_md_file do |path|
-      cmd = BitClust::Subcommands::HtmlfileCommand.new
-      cmd.parse([path])
-      msg = capture_stderr { assert_raise(SystemExit) { cmd.exec([path], {:prefix => nil, :capi => false}) } }
-      assert_match(/Markdown/, msg)
-      assert_match(/rake generate|bitclust server/, msg)
-    end
-  end
 end

data/test/test_htmlfile_command.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+require 'test/unit'
+require 'stringio'
+require 'tmpdir'
+require 'fileutils'
+require 'bitclust'
+require 'bitclust/subcommands/htmlfile_command'
+
+# htmlfile サブコマンドの Markdown ソース(manual/)の変換。
+#
+# テストリスト:
+# [x] エンティティ md は front matter の library: を所属として変換する
+# [x] library: が多重所属なら、その版で生きている先頭の所属を使う
+# [x] library: が無く --library も無ければエラー
+# [x] --library で所属を指定できる
+# [x] ライブラリルート md(type: library)はファイル名をライブラリ名にする
+# [x] --ruby の版で #%since が解決される
+# [x] manual/doc/ の md は doc ページとして変換する
+# [x] --capi の md は C API として変換する
+# [x] RD ソースは RD として変換する
+class TestHtmlfileCommand < Test::Unit::TestCase
+  FOO_MD = <<~'MD'
+    ---
+    library: foo
+    ---
+    # class Foo < Object
+
+    クラスの説明。
+
+    ## Instance Methods
+
+    ### def bar -> nil
+
+    bar の **説明**。
+
+    #%since 3.4
+    ### def baz -> nil
+
+    baz の説明。
+    #%end
+  MD
+
+  def setup
+    @tmpdir = Dir.mktmpdir
+    @api = File.join(@tmpdir, 'manual', 'api')
+    FileUtils.mkdir_p(File.join(@api, 'foo'))
+  end
+
+  def teardown
+    FileUtils.rm_rf(@tmpdir)
+  end
+
+  def write(rel, content)
+    path = File.join(@tmpdir, rel)
+    FileUtils.mkdir_p(File.dirname(path))
+    File.write(path, content)
+    path
+  end
+
+  def run_htmlfile(args, capi: false)
+    cmd = BitClust::Subcommands::HtmlfileCommand.new
+    argv = args.dup
+    cmd.parse(argv)
+    out = StringIO.new
+    err = StringIO.new
+    orig_out, orig_err = $stdout, $stderr
+    $stdout, $stderr = out, err
+    status = nil
+    begin
+      cmd.exec(argv, {:prefix => nil, :capi => capi})
+    rescue SystemExit => e
+      status = e.status
+    ensure
+      $stdout, $stderr = orig_out, orig_err
+    end
+    [out.string, err.string, status]
+  end
+
+  def test_entity_uses_library_in_front_matter
+    path = write('manual/api/foo/Foo.md', FOO_MD)
+    out, _err, status = run_htmlfile(['--ruby=3.4', '--target=Foo', path])
+    assert_nil(status)
+    assert_match(/class Foo/, out)
+    assert_match(%r{library/foo">library foo<}, out)
+    assert_match(%r{<strong>説明</strong>}, out)
+  end
+
+  def test_entity_uses_first_live_membership
+    path = write('manual/api/foo/Foo.md', <<~'MD')
+      ---
+      library:
+      #%until 3.4
+        - old_foo
+      #%end
+        - foo
+        - foo_ext
+      ---
+      # class Foo < Object
+
+      クラスの説明。
+    MD
+    out, _err, status = run_htmlfile(['--ruby=3.4', '--target=Foo', path])
+    assert_nil(status)
+    assert_match(%r{library/foo">library foo<}, out)
+    out, _err, _status = run_htmlfile(['--ruby=3.3', '--target=Foo', path])
+    assert_match(%r{library/old_foo">library old_foo<}, out)
+  end
+
+  def test_entity_without_library_is_error
+    path = write('manual/api/foo/Foo.md', FOO_MD.sub(/\A---\nlibrary: foo\n---\n/, ''))
+    out, err, status = run_htmlfile(['--target=Foo', path])
+    assert_equal(1, status)
+    assert_equal('', out)
+    assert_match(/library:/, err)
+    assert_match(/--library/, err)
+  end
+
+  def test_library_option_gives_library
+    path = write('manual/api/foo/Foo.md', FOO_MD.sub(/\A---\nlibrary: foo\n---\n/, ''))
+    out, _err, status = run_htmlfile(['--library=bar', '--target=Foo', path])
+    assert_nil(status)
+    assert_match(%r{library/bar">library bar<}, out)
+  end
+
+  def test_library_root_uses_file_name
+    write('manual/api/foo/Foo.md', FOO_MD)
+    path = write('manual/api/net/foo.md', <<~'MD')
+      ---
+      type: library
+      category: Network
+      ---
+      foo ライブラリの **説明**。
+    MD
+    out, _err, status = run_htmlfile([path])
+    assert_nil(status)
+    assert_match(%r{<h1>library net/foo</h1>}, out)
+    assert_match(%r{<strong>説明</strong>}, out)
+  end
+
+  def test_builtin_library_root
+    path = write('manual/api/_builtin.md', "---\ntype: library\n---\n組み込みライブラリ。\n")
+    out, _err, status = run_htmlfile([path])
+    assert_nil(status)
+    assert_match(%r{<title>library _builtin }, out)
+    assert_match(/組み込みライブラリ。/, out)
+  end
+
+  def test_ruby_version_resolves_gates
+    path = write('manual/api/foo/Foo.md', FOO_MD)
+    out, _err, _status = run_htmlfile(['--ruby=3.4', '--target=Foo', path])
+    assert_match(/baz/, out)
+    out, _err, _status = run_htmlfile(['--ruby=3.3', '--target=Foo', path])
+    assert_match(/bar/, out)
+    assert_not_match(/baz/, out)
+  end
+
+  def test_target_method
+    path = write('manual/api/foo/Foo.md', FOO_MD)
+    out, _err, status = run_htmlfile(['--ruby=3.4', '--target=Foo#bar', path])
+    assert_nil(status)
+    assert_match(/bar の <strong>説明<\/strong>/, out)
+    assert_not_match(/baz の説明/, out)
+  end
+
+  def test_doc_page
+    path = write('manual/doc/spec/foo.md', <<~'MD')
+      # Foo の仕様
+
+      本文の **強調**。
+    MD
+    out, _err, status = run_htmlfile([path])
+    assert_nil(status)
+    assert_match(/Foo の仕様/, out)
+    assert_match(%r{本文の <strong>強調</strong>}, out)
+  end
+
+  def test_capi
+    path = write('manual/capi/array.c.md', <<~'MD')
+      ### VALUE rb_foo_new()
+
+      空の **Foo** を作ります。
+
+      ### VALUE rb_foo_bar(VALUE foo)
+
+      bar を返します。
+    MD
+    out, _err, status = run_htmlfile(['--target=rb_foo_new', path], capi: true)
+    assert_nil(status)
+    assert_match(/rb_foo_new/, out)
+    assert_match(%r{空の <strong>Foo</strong> を作ります。}, out)
+    assert_not_match(/bar を返します/, out)
+  end
+
+  def test_rd_source
+    path = write('refm/api/src/foo.rd', <<~'RD')
+      = class Foo < Object
+
+      クラスの説明。
+
+      == Instance Methods
+
+      --- bar -> nil
+
+      bar の説明。
+    RD
+    out, _err, status = run_htmlfile(['--target=Foo', path])
+    assert_nil(status)
+    assert_match(/class Foo/, out)
+    assert_match(/bar の説明。/, out)
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bitclust-core
 version: !ruby/object:Gem::Version
-  version: 1.8.0
+  version: 1.9.0
 platform: ruby
 authors:
 - https://github.com/rurema
@@ -347,6 +347,7 @@ files:
 - test/test_extract_command.rb
 - test/test_functiondatabase.rb
 - test/test_functionreferenceparser.rb
+- test/test_htmlfile_command.rb
 - test/test_include_graph.rb
 - test/test_include_pruner.rb
 - test/test_irb_plugin.rb
@@ -455,6 +456,7 @@ test_files:
 - test/test_extract_command.rb
 - test/test_functiondatabase.rb
 - test/test_functionreferenceparser.rb
+- test/test_htmlfile_command.rb
 - test/test_include_graph.rb
 - test/test_include_pruner.rb
 - test/test_irb_plugin.rb