hiki2md 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd9f235518be1faf5230ff7f4739a1fb311727ded398fe7c44f24b459c3ec3a0
-  data.tar.gz: 47ae584b929f160ae9a680994dfebdacfc1fe12e7c9cb52470ae900fc0d8482a
+  metadata.gz: 4fc18ad51b63a8dde11dfe5ea4c04e4e8347e21457670edc8200acdaa125e8e9
+  data.tar.gz: f0bf7d53ac1bfd7a71a643ae9354f781fab199a29a07ea8225399831808ab2fb
 SHA512:
-  metadata.gz: b0e0d03d869dfd64587ae2b782e56d6bf5fa88e4bb8bd0eba6736b00ff06c5f0b929e41577fdbeb4cdb3a01e272400b94e95ddf3633c2ad7a3be6f7d3e37d8be
-  data.tar.gz: 98c7f8cda9a0d088cf26c4a4d23e340f5fbcb7b23e3cfe6e47794170166c6511c6c8324f798d9a07e8ea2a2f227c03670670b9f91fce4a6d8c07c58a65994727
+  metadata.gz: 147c40644b389860b2f9b0868235571ebd95ab005d6873910a4c54849d6a6f625619bf439e1679da0894a7908c9766fcc05d11f14f571d283492206bb19750b8
+  data.tar.gz: 61dd0a68d793fafa4c5320e72c3bd9c4f5f88288e5566686d2abbf56fe9bc734861de8bf75b70556f6d6477bda01ceda9f14a7d7830d4d6e1d5534774f7cc6e3

data/.travis.yml

@@ -1,4 +1,6 @@
 language: ruby
+dist: jammy
 rvm:
-  - 2.2.3
-before_install: gem install bundler -v 1.10.6
+  - 3.1
+  - 3.4
+before_install: gem install bundler -v 2.6.8

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    hiki2md (0.1.3)
+    hiki2md (0.3.1)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -6,6 +6,8 @@ Converter of Hiki to Markdown.
 
 ## Installation
 
+Hiki2md requires Ruby 2.2 or newer.
+
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -22,7 +24,97 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Ruby
+
+```ruby
+require "hiki2md"
+
+converter = Hiki2md.new(
+  interwiki_map: {
+    "Google" => "https://www.google.com/search?q=",
+    "Issues" => "https://example.com/issues/$1"
+  },
+  use_wiki_name: true,
+  preserve_plugins: false
+)
+
+markdown = converter.convert(hiki_source)
+```
+
+Internal page links receive a `.md` extension. InterWiki values either have
+the encoded page name appended, or can contain `$1` where the page name should
+be inserted.
+
+### Command line
+
+```console
+$ hiki2md [options] input.hiki
+```
+
+Options:
+
+- `--interwiki-map PATH`: load InterWiki prefixes from a YAML mapping.
+- `--[no-]wiki-name`: enable or disable automatic WikiName links.
+- `--preserve-plugins`: retain plugins as escaped Markdown text instead of
+  removing them.
+- `-E`, `--input-encoding ENCODING`: override the detected source encoding.
+
+The command writes UTF-8 Markdown. It automatically recognizes BOM-marked
+Unicode input and the common Hiki encodings UTF-8, EUC-JP, Windows-31J, and
+ISO-2022-JP. Since legacy encodings can be ambiguous, use
+`--input-encoding` to specify the source explicitly when needed:
+
+```console
+$ hiki2md --input-encoding EUC-JP TextFormattingRules.ja
+```
+
+### Supported Hiki syntax
+
+The converter targets Hiki's default style and emits GitHub Flavored Markdown
+(GFM).
+
+| Hiki | Output |
+| --- | --- |
+| `!` through `!!!!!` | headings 2 through 6 |
+| `*` / `#` | nested unordered / ordered lists |
+| `''text''` / `'''text'''` | emphasis / strong emphasis |
+| `==text==` / double-backtick text | strikethrough / inline code |
+| `[[Page]]` / `[[label\|target]]` | page, URL, and InterWiki links |
+| image URLs | Markdown images, including basename or labeled alt text |
+| leading space or tab, `<<<` ... `>>>` | fenced code blocks |
+| `""` | recursive blockquotes |
+| `:term:description` | HTML definition lists |
+| `\|\|cell` | raw HTML tables |
+| `----` | horizontal rules |
+| `// comment` | removed comments |
+
+Hiki permits tables without a header row, while GFM pipe tables require one.
+All Hiki tables are therefore emitted as raw HTML so ordinary `td` cells,
+explicit `!` header cells, and `^` / `>` row and column spans retain their
+meaning.
+
+Hiki plugins are executable Ruby extensions and cannot be converted
+generically. Plugin calls are removed by default. Use `preserve_plugins: true`
+or `--preserve-plugins` to keep them as escaped Markdown text for manual
+migration. Plugin-looking text inside preformatted blocks is always kept
+literally.
+
+### Version 0.3 output changes
+
+Version 0.3 favors the rendered meaning of Hiki over preserving the exact
+Markdown source produced by 0.2. In particular, all tables now use raw HTML,
+ordered-list indentation follows CommonMark, and Markdown-looking source text
+is escaped when Hiki treats it as plain text. The legacy public `make_matrix`
+and `make_table` helpers retain their 0.2 behavior.
+
+Lists deeper than 100 levels use raw HTML to keep output growth bounded.
+Uniform blockquotes may be arbitrarily deep; blocks containing more than 100
+distinct quote depths raise `ArgumentError` instead of risking stack or CPU
+exhaustion.
+
+See Hiki's
+[TextFormattingRules](https://hikiwiki.org/en/TextFormattingRules.html) for
+the source syntax.
 
 ## Development
 
@@ -40,4 +132,3 @@ The gem is available as open source under the terms of the [MIT License](http://
 ## Inspired by
 
 https://github.com/masasuzu/p5-App-hiki2md
-

data/exe/hiki2md

@@ -3,7 +3,88 @@ require 'hiki2md'
 require 'optparse'
 require 'yaml'
 
+module Hiki2mdCommand
+  class InputEncodingError < StandardError; end
+
+  BOM_ENCODINGS = [
+    [[0x00, 0x00, 0xfe, 0xff].pack('C*'), Encoding::UTF_32],
+    [[0xff, 0xfe, 0x00, 0x00].pack('C*'), Encoding::UTF_32],
+    [[0xfe, 0xff].pack('C*'), Encoding::UTF_16],
+    [[0xff, 0xfe].pack('C*'), Encoding::UTF_16],
+    [[0xef, 0xbb, 0xbf].pack('C*'), Encoding::UTF_8]
+  ].freeze
+  AUTO_ENCODINGS = [
+    Encoding::UTF_8,
+    Encoding::EUC_JP,
+    Encoding::Windows_31J
+  ].freeze
+
+  module_function
+
+  def read_source(path, requested_encoding = nil)
+    bytes = File.binread(path)
+    encoding = if requested_encoding.nil? || requested_encoding.casecmp('auto').zero?
+                 detect_encoding(bytes)
+               else
+                 find_encoding(requested_encoding)
+               end
+
+    unless encoding
+      raise InputEncodingError,
+            "#{path}: unable to detect input encoding; " \
+            "use --input-encoding ENCODING"
+    end
+
+    source = bytes.dup.force_encoding(encoding)
+    unless source.valid_encoding?
+      raise InputEncodingError,
+            "#{path}: invalid byte sequence in #{encoding.name}"
+    end
+
+    source.encode(Encoding::UTF_8).sub(/\A\uFEFF/, '')
+  rescue Encoding::InvalidByteSequenceError,
+         Encoding::UndefinedConversionError => error
+    raise InputEncodingError,
+          "#{path}: cannot convert #{encoding.name} to UTF-8: #{error.message}"
+  end
+
+  def detect_encoding(bytes)
+    bom = BOM_ENCODINGS.find { |marker, _encoding| bytes.start_with?(marker) }
+    return bom[1] if bom
+
+    if iso_2022_jp?(bytes) && decodable_as?(bytes, Encoding::ISO_2022_JP)
+      return Encoding::ISO_2022_JP
+    end
+
+    AUTO_ENCODINGS.find { |encoding| decodable_as?(bytes, encoding) }
+  end
+
+  def iso_2022_jp?(bytes)
+    bytes.include?("\e$") || bytes.include?("\e(")
+  end
+
+  def decodable_as?(bytes, encoding)
+    source = bytes.dup.force_encoding(encoding)
+    source.valid_encoding? && begin
+      source.encode(Encoding::UTF_8)
+      true
+    rescue Encoding::InvalidByteSequenceError,
+           Encoding::UndefinedConversionError
+      false
+    end
+  end
+
+  def find_encoding(name)
+    Encoding.find(name)
+  rescue ArgumentError
+    raise InputEncodingError, "unknown input encoding: #{name}"
+  end
+end
+
 interwiki_map = {}
+use_wiki_name = true
+preserve_plugins = false
+input_encoding = nil
 
 OptionParser.new do |opts|
   opts.banner = "Usage: hiki2md [options] <file>"
@@ -15,6 +96,22 @@ OptionParser.new do |opts|
       raise IOError.new("InterWiki map file not found: #{path}")
     end
   end
+
+  opts.on("--[no-]wiki-name", "Enable or disable WikiName autolinking") do |enabled|
+    use_wiki_name = enabled
+  end
+
+  opts.on("--preserve-plugins", "Keep Hiki plugins as escaped Markdown text") do
+    preserve_plugins = true
+  end
+
+  opts.on(
+    "-E",
+    "--input-encoding ENCODING",
+    "Source encoding (default: auto)"
+  ) do |encoding|
+    input_encoding = encoding
+  end
 end.parse!
 
 if ARGV.size != 1
@@ -27,5 +124,17 @@ if !File.exist?(input_file)
   raise IOError.new("no exist #{input_file}")
 end
 
-hiki2md = Hiki2md.new(interwiki_map: interwiki_map)
-puts hiki2md.convert(File.read(input_file))
+hiki2md = Hiki2md.new(
+  interwiki_map: interwiki_map,
+  use_wiki_name: use_wiki_name,
+  preserve_plugins: preserve_plugins
+)
+
+begin
+  source = Hiki2mdCommand.read_source(input_file, input_encoding)
+rescue Hiki2mdCommand::InputEncodingError => error
+  warn "hiki2md: #{error.message}"
+  exit 1
+end
+
+puts hiki2md.convert(source)

data/hiki2md.gemspec

@@ -12,6 +12,7 @@ Gem::Specification.new do |spec|
   spec.summary       = %q{Converter of Hiki to Markdown}
   spec.homepage      = "http://github.com/kdmsnr/hiki2md"
   spec.license       = "MIT"
+  spec.required_ruby_version = ">= 2.2.0"
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   spec.bindir        = "exe"

data/lib/hiki2md/version.rb

@@ -1,3 +1,3 @@
 class Hiki2md
-  VERSION = "0.2.0"
+  VERSION = "0.3.1"
 end