bitclust-core 1.6.1 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c50953e0ecaf38a9d4c6187b22eaccedd4b9f52029bb638e026fbbfc655d8a2
-  data.tar.gz: c5ce94f2931f5472651e6bd425c766ba19b9ff4acc87d8fd5ae8e57f384db3d6
+  metadata.gz: 299762c07571e6e3b72eebe00c9d1e1d520ef9f5c3b68de759adc0c173d2ee18
+  data.tar.gz: beab538e8caec8fb1f7265808adceaa5574b22793dfb11a521651687204416d1
 SHA512:
-  metadata.gz: 4766a837042d881e63e96264338d7e04aa6e10e63db1b2ff22ca0e53e6f6e97f766efadbe9c1a6ff8c4b89bfac996eb4c060c9b9abfd8c4aff420c57a987a3f7
-  data.tar.gz: e64091ccdeddf09ed18339d2be46af88abc28c6d9aaf6ae9da888c4125c5ab47b526c315d9f630e76389258fe56f950600b1265d42c10d98a2d595b3892f02d8
+  metadata.gz: a4d23713bd97acaa6cb98de51e95766c87f09329c0dba4c2b42152838023ec4ce681f1c7f38db582b7e3e20809a2749152da84a74399741dc113ad9251f0875d
+  data.tar.gz: ce441c5b5a4abc9cbef8a46bf9efa2a57a5cae8bdd827c9edf7af095e60bea9c95a85ceee54baa73e850b0a7a4682b1d5afd41ce41e386040e78761ca88038fd

data/Rakefile

@@ -21,6 +21,7 @@ namespace :test do
     sh 'qjs', 'test/js/test_run.mjs'
     sh 'qjs', 'test/js/test_script.mjs'
     sh 'qjs', 'test/js/test_search.mjs'
+    sh 'qjs', 'test/js/test_version_switcher.mjs'
   end
 end
 

data/data/bitclust/catalog/ja_JP.UTF-8

@@ -7,7 +7,7 @@ Added/Redefined Methods
 All Classes
 クラス一覧
 All Functions
-関数一覧
+C API 関数一覧
 All Libraries
 ライブラリ一覧
 Ancestor Methods
@@ -51,7 +51,7 @@ File
 FileFormat
 ファイルフォーマット
 Function Index
-関数一覧
+C API 関数一覧
 Index
 目次
 I/O
@@ -112,6 +112,8 @@ Text
 テキスト
 Thread
 スレッド
+This is a list of functions provided by the Ruby C API for developing Ruby itself and C extension libraries. These functions cannot be called directly from Ruby programs.
+Ruby の C API(C 言語 API)の関数の一覧です。Ruby 本体や拡張ライブラリの開発に使うもので、Ruby プログラムから直接呼び出す関数ではありません。
 This reference manual is for a version of Ruby that is no longer maintained.
 このマニュアルは既にメンテナンスが終了したバージョンの Ruby を対象としています。
 Undefined Methods for Explanation

data/data/bitclust/template/class-index

@@ -29,5 +29,4 @@
     end
     headline_pop
 %>
-</ul>
 

data/data/bitclust/template/function-index

@@ -8,6 +8,7 @@
     headline_init
 %>
 <%= headline(_("Function Index")) %>
+<p><%= _('This is a list of functions provided by the Ruby C API for developing Ruby itself and C extension libraries. These functions cannot be called directly from Ruby programs.') %></p>
 <table class="entries functions">
 <%
     headline_push

data/data/bitclust/template/layout

@@ -13,6 +13,7 @@
   <link rel="search" type="application/opensearchdescription+xml" title="<%= _('Ruby %s Reference Manual', ruby_version()) %>" href="<%=h opensearchdescription_url() %>">
 <% if run_ruby_wasm_url %>
   <meta name="rurema-run-ruby-wasm" content="<%=h run_ruby_wasm_url %>">
+  <meta name="rurema-run-help" content="<%=h document_url('help') %>#run">
   <script type="module" src="<%=h custom_js_url('js/run.js') %>"></script>
 <% end %>
 </head>

data/data/bitclust/template.epub/class

@@ -24,20 +24,20 @@
 <% end %>
 
 <% unless @entry.extended.empty? %>
-<br>extend: <%= @entry.extended.map {|c| class_link(c.name) }.join(', ') %>
+<br />extend: <%= @entry.extended.map {|c| class_link(c.name) }.join(', ') %>
 <% end %>
 <% unless @entry.aliases.empty? %>
-<br>aliases: <%=h @entry.aliases.map{|c| c.name}.join(', ') %>
+<br />aliases: <%=h @entry.aliases.map{|c| c.name}.join(', ') %>
 <% end %>
 <% unless @entry.dynamically_included.empty? %>
-<br> dynamic include:
+<br /> dynamic include:
  <%= @entry.dynamically_included.map{|m|
        class_link(m.name) + " (by " + library_link(m.library.name) + ")"
      }.join(", ")
  %>
 <% end %>
 <% unless @entry.dynamically_extended.empty? %>
-<br> dynamic extend:
+<br /> dynamic extend:
  <%= @entry.dynamically_extended.map{|m|
        class_link(m.name) + " (by " + library_link(m.library.name) + ")"
      }.join(", ")
@@ -72,7 +72,7 @@
   entries.each do |m|
     m.names.each do |mname|
 %>
-<a href="#<%= m.index_id %>"><%= "#{prefix}#{mname}" %></a>
+<a href="#<%= m.index_id %>"><%= escape_html "#{prefix}#{mname}" %></a>
 <%
     end
   end

data/data/bitclust/template.epub/class-index

@@ -25,4 +25,3 @@
     end
     headline_pop
 %>
-</ul>

data/data/bitclust/template.epub/contents

@@ -8,15 +8,18 @@
   </metadata>
   <manifest>
     <item id="toc" properties="nav" href="nav.xhtml" media-type="application/xhtml+xml" />
-    <item id="index" href="OEBPS/doc/index.html" media-type="application/xhtml+xml" />
-<% items.each do |item| -%>
-    <item id="<%= item[:id] %>" href="<%= item[:path] %>" media-type="application/xhtml+xml" />
+    <item id="index" href="OEBPS/doc/index.xhtml" media-type="application/xhtml+xml" />
+<% class_items.each do |item| -%>
+    <item id="<%= item[:id] %>" href="<%= item[:path] %>" media-type="<%= item[:media_type] %>" />
+<% end -%>
+<% other_items.each do |item| -%>
+    <item id="<%= item[:id] %>" href="<%= item[:path] %>" media-type="<%= item[:media_type] %>" />
 <% end -%>
   </manifest>
   <spine>
     <itemref idref="toc" />
     <itemref idref="index" />
-<% items.each do |item| -%>
+<% class_items.each do |item| -%>
     <itemref idref="<%= item[:id] %>" />
 <% end -%>
   </spine>

data/data/bitclust/template.epub/layout

@@ -2,10 +2,10 @@
 <!DOCTYPE html>
 <html lang="ja-JP">
 <head>
-  <meta http-equiv="Content-Type" content="text/html; charset=<%=h charset() %>">
-  <meta http-equiv="Content-Language" content="ja-JP">
-  <link rel="stylesheet" type="text/css" href="<%=h css_url() %>">
-  <link rel="icon" type="image/png" href="<%=h favicon_url() %>">
+  <meta http-equiv="Content-Type" content="text/html; charset=<%=h charset() %>" />
+  <meta http-equiv="Content-Language" content="ja-JP" />
+  <link rel="stylesheet" type="text/css" href="<%=h css_url() %>" />
+  <link rel="icon" type="image/png" href="<%=h favicon_url() %>" />
   <title><%=h @title %> (Ruby <%=h ruby_version %>)</title>
 </head>
 <body>

data/data/bitclust/template.offline/class-index

@@ -54,5 +54,4 @@
     end
     headline_pop
 %>
-</ul>
 </main>

data/data/bitclust/template.offline/function-index

@@ -36,6 +36,7 @@
 </header>
 
 <main>
+<p><%= _('This is a list of functions provided by the Ruby C API for developing Ruby itself and C extension libraries. These functions cannot be called directly from Ruby programs.') %></p>
 <table class="entries functions">
 <%
     headline_push

data/data/bitclust/template.offline/layout

@@ -21,8 +21,10 @@
 <script src="<%=h custom_js_url('js/search_ranker.js') %>"></script>
 <script src="<%=h custom_js_url('js/search_controller.js') %>"></script>
 <script src="<%=h custom_js_url('js/search_init.js') %>"></script>
+<script defer src="<%=h custom_js_url('js/version_switcher.js') %>"></script>
 <% if run_ruby_wasm_url %>
 <meta name="rurema-run-ruby-wasm" content="<%=h run_ruby_wasm_url %>">
+<meta name="rurema-run-help" content="<%=h document_url('help') %>#run">
 <script type="module" src="<%=h custom_js_url('js/run.js') %>"></script>
 <% end %>
 </head>
@@ -35,6 +37,7 @@
 <% end %>
 <div id="rurema-topbar">
   <div id="rurema-brand"><%= manual_home_link %></div>
+  <div id="version-switcher"></div>
   <div id="search-section" role="search">
     <input id="search-field" type="text" autocomplete="off" spellcheck="false"
            placeholder="クラス・メソッドを検索 (/)"

data/lib/bitclust/classentry.rb

@@ -452,7 +452,7 @@ module BitClust
     end
 
     def description
-      description_text(source.split(/\n\n+/, 2)[0].strip)
+      description_text(source.split(/\n\n+/, 2)[0].to_s.strip)
     end
 
     def clear_cache

data/lib/bitclust/docentry.rb

@@ -84,7 +84,7 @@ module BitClust
     end
 
     def description
-      description_text(source.split(/\n\n/, 2)[0].strip)
+      description_text(source.split(/\n\n/, 2)[0].to_s.strip)
     end
   end
 end

data/lib/bitclust/functionentry.rb

@@ -83,7 +83,7 @@ module BitClust
     end
 
     def description
-      description_text(source.split(/\n\n+/, 2)[0].strip)
+      description_text(source.split(/\n\n+/, 2)[0].to_s.strip)
     end
   end
 end

data/lib/bitclust/generators/epub.rb

@@ -24,11 +24,17 @@ module BitClust
 
       CONTENTS_DIR_NAME = 'OEBPS'
 
+      # StatichtmlCommand が出力ルートに書く 2 行のリダイレクト用スタブ
+      # (<meta http-equiv="refresh"> と <a>)。ルート要素が無く XHTML として
+      # 整形式でない。EPUB の入口は nav.xhtml なのでスタブは同梱せず削除する
+      INDEX_STUB_NAME = 'index.xhtml'
+
       def generate
         make_epub_directory do |epub_directory|
           contents_directory = epub_directory + CONTENTS_DIR_NAME
           copy_static_files(epub_directory)
           generate_xhtml_files(contents_directory)
+          remove_index_stub(contents_directory)
           generate_contents_opf(epub_directory)
           pack_epub(epub_directory)
         end
@@ -71,15 +77,45 @@ module BitClust
         cmd.exec(argv, options)
       end
 
+      # manifest に id="index" で固定的に載せる doc/index ページの href
+      # (epub_directory 相対)。other_items からは除いて二重掲載を避ける
+      INDEX_PATH = Pathname.new("#{CONTENTS_DIR_NAME}/doc/index.xhtml")
+
+      MEDIA_TYPES = {
+        '.xhtml' => 'application/xhtml+xml',
+        '.css'   => 'text/css',
+        '.js'    => 'application/javascript',
+        '.png'   => 'image/png',
+        '.jpg'   => 'image/jpeg',
+        '.jpeg'  => 'image/jpeg',
+        '.gif'   => 'image/gif',
+        '.svg'   => 'image/svg+xml',
+      }.freeze
+
       def generate_contents_opf(epub_directory)
-        items = [] #: Array[{:id => String, :path => Pathname}]
+        class_items = [] #: Array[{:id => String, :path => Pathname, :media_type => String}]
         glob_relative_path(epub_directory, "#{CONTENTS_DIR_NAME}/class/*.xhtml").each do |path|
-          items << {
-            :id => decodename_package(path.basename(".*").to_s),
-            :path => path
+          class_items << {
+            :id => "class-#{decodename_package(path.basename(".*").to_s)}",
+            :path => path,
+            :media_type => media_type_for(path),
           }
         end
-        items.sort_by!{|item| item[:path] }
+        class_items.sort_by!{|item| item[:path] }
+
+        excluded_paths = class_items.map{|item| item[:path] } + [INDEX_PATH]
+        other_items = [] #: Array[{:id => String, :path => Pathname, :media_type => String}]
+        oebps_file_paths(epub_directory).each do |path|
+          next if excluded_paths.include?(path)
+
+          other_items << {
+            :id => manifest_id_for(path),
+            :path => path,
+            :media_type => media_type_for(path),
+          }
+        end
+        other_items.sort_by!{|item| item[:path] }
+
         template = (@templatedir + "contents").read
         if ::ERB.instance_method(:initialize).parameters.last.first == :key
           erb = ::ERB.new(template, trim_mode: '-')
@@ -92,6 +128,34 @@ module BitClust
         end
       end
 
+      # OEBPS 配下の通常ファイル全部(method/library/doc/function ページと、
+      # statichtml がコピーした CSS・画像)を epub_directory 相対で返す。
+      # class ページも含む(呼び出し側で class_items と重複排除する)
+      def oebps_file_paths(epub_directory)
+        glob_relative_path(epub_directory, "#{CONTENTS_DIR_NAME}/**/*").select do |relative_path|
+          (epub_directory + relative_path).file?
+        end
+      end
+
+      def media_type_for(path)
+        MEDIA_TYPES[path.extname.downcase] || 'application/octet-stream'
+      end
+
+      # class ページ以外("OEBPS/method/Array/i/each.xhtml" 等)の manifest
+      # item id。XML の NCName として妥当で一意になるよう、使えない文字は "-" に
+      # 置き換え、ディレクトリ境界は "--" にして encodename 由来の "-" と
+      # 区別する
+      def manifest_id_for(path)
+        relative = path.to_s.sub(%r{\A#{Regexp.escape(CONTENTS_DIR_NAME)}/}, "")
+        segments = relative.split("/").map{|segment| segment.gsub(/[^A-Za-z0-9_.-]/, "-") }
+        "item-#{segments.join('--')}"
+      end
+
+      def remove_index_stub(contents_directory)
+        stub_path = contents_directory + INDEX_STUB_NAME
+        FileUtils.rm_f(stub_path.to_s, :verbose => @verbose) if stub_path.file?
+      end
+
       def pack_epub(epub_directory)
         epub_filename = @outputdir + @filename
         Dir.chdir(epub_directory.to_s) do

data/lib/bitclust/irb.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+#
+# irb からるりま(Ruby リファレンスマニュアル)を引く refe コマンド。
+# ~/.irbrc に `require "bitclust/irb"` と書くと irb に `refe` コマンドが
+# 登録される。検索対象の DB は refe コマンドと同じ場所(bitclust setup が
+# 作る設定ファイル)から探し、DB が無ければ docs.ruby-lang.org の検索索引と
+# Markdown 配信から取得する(BitClust::Remote)。
+
+require 'stringio'
+require 'bitclust'
+require 'bitclust/searcher'
+
+module BitClust
+  module Irb
+    USAGE = <<~USAGE
+      Usage: refe <pattern>
+
+      例:
+        refe String#gsub     インスタンスメソッド
+        refe Array.new       特異メソッド
+        refe Comparable      クラス・モジュール
+        refe each            名前だけでの検索(該当が複数なら一覧)
+
+      DB が無い場合は docs.ruby-lang.org から取得します(1 日キャッシュ)。
+      `bitclust setup` で DB を作ると手元で検索できます。
+    USAGE
+
+    # pattern を検索して整形済みテキストを io へ書く。db が nil なら
+    # 既定の場所から探し、そこにも無ければ remote(省略時は
+    # Remote.default。nil ならフォールバックしない)で検索する。
+    # 検索の失敗は例外にせず io へメッセージを書く(irb セッションを
+    # 止めないため)
+    def self.lookup(pattern, io: $stdout, db: nil, remote: Remote.default)
+      words = pattern.to_s.split
+      if words.empty?
+        io.puts USAGE
+        return
+      end
+      view = TerminalView.new(Plain.new,
+                              { describe_all: false, line: false, encoding: nil },
+                              io: io)
+      searcher = Searcher.new
+      searcher.remote = remote
+      searcher.run_query(db, words, view)
+    rescue BitClust::UserError => err
+      io.puts err.message
+    end
+
+    begin
+      require 'irb/command'
+    rescue LoadError
+      # irb が無い(または irb < 1.13 で公開コマンド API が無い)環境では
+      # コマンド登録だけを諦め、Irb.lookup は使えるままにする
+    else
+      class RefeCommand < ::IRB::Command::Base
+        category 'Documentation'
+        description 'るりま(Ruby リファレンスマニュアル)を検索して表示します'
+        help_message USAGE
+
+        def execute(arg)
+          content = StringIO.new
+          BitClust::Irb.lookup(arg, io: content)
+          if ::IRB.const_defined?(:Pager)
+            ::IRB::Pager.page_content(content.string)
+          else
+            $stdout.puts content.string
+          end
+        end
+      end
+
+      ::IRB::Command.register(:refe, RefeCommand)
+    end
+  end
+end

data/lib/bitclust/markdown_bridge.rb

@@ -134,12 +134,17 @@ module BitClust
         reopen_only = members[path][:kinds].all? { |kind, _| %w[reopen redefine].include?(kind) }
         [reopen_only ? 1 : 0, path]
       end
-      "\n" + sorted.map { |path|
-        m = members[path][:memberships].find { |mm| mm[:library] == libname } || raise
-        inc = "\#@include(#{relative(emitted[path], base)})\n"
-        inc = "\#@since #{m[:since]}\n#{inc}\#@end\n" if m[:since]
-        inc = "\#@until #{m[:until]}\n#{inc}\#@end\n" if m[:until]
-        inc
+      # 同じライブラリへの membership が複数ある（#%version A...B の #%else =
+      # A 未満と B 以上）ときは、それぞれのゲートで include サイトを繰り返す
+      "\n" + sorted.flat_map { |path|
+        members[path][:memberships].select { |mm| mm[:library] == libname }.map { |m|
+          inc = "\#@include(#{relative(emitted[path], base)})\n"
+          inc = "\#@since #{m[:since]}\n#{inc}\#@end\n" if m[:since]
+          inc = "\#@until #{m[:until]}\n#{inc}\#@end\n" if m[:until]
+          inc = "\#@if (version == \"#{m[:version]}\")\n#{inc}\#@end\n" if m[:version]
+          (m[:except] || []).each { |x| inc = "\#@if (version != \"#{x}\")\n#{inc}\#@end\n" }
+          inc
+        }
       }.join
     end