carve-hexapdf 0.1.0

data/lib/carve/hexapdf/style_map.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Carve
+  module Hexapdf
+    # Hierarchical style resolver for renderer properties.
+    class StyleMap
+      def self.deep_freeze(value)
+        case value
+        when Hash
+          value.each_value { |entry| deep_freeze(entry) }
+        when Array
+          value.each { |entry| deep_freeze(entry) }
+        end
+        value.freeze
+      end
+      private_class_method :deep_freeze
+
+      DEFAULTS = deep_freeze({
+        "base" => { font: "Times" },
+        "heading" => { margin: [10, 0, 6] },
+        "heading.1" => { font_size: 22 },
+        "heading.2" => { font_size: 18 },
+        "heading.3" => { font_size: 15 },
+        "heading.4" => { font_size: 13 },
+        "heading.5" => { font_size: 12 },
+        "heading.6" => { font_size: 11 },
+        "paragraph" => { margin: [0, 0, 8] },
+        "code" => { font: "Courier" },
+        "code.block" => {
+          font_size: 9,
+          margin: [2, 0, 8],
+          box: { background_color: "f2f2f2", padding: 6 },
+        },
+        "code.inline" => {},
+        "quote" => {
+          box: { margin: [2, 0, 8], padding: [4, 10], background_color: "f7f7f7" },
+        },
+        "admonition" => {
+          box: { margin: [2, 0, 8], padding: [6, 10], background_color: "eef3fb" },
+          title_margin: [0, 0, 4],
+        },
+        "list" => { item_spacing: 3, content_indentation: 18 },
+        "definition_list" => { box: { margin: [0, 0, 8] }, definition_indent: 16 },
+        "table" => { font_size: 10, cell_padding: 4, margin: [2, 0, 8] },
+        "table.header" => {},
+        "table.caption" => { font_size: 9, margin: [0, 0, 8] },
+        "figure.caption" => { font_size: 9, margin: [2, 0, 8], text_align: :center },
+        # A composite figure (PART 9 section 4c). :column_gap and
+        # :min_column_width are read by the renderer rather than by HexaPDF:
+        # they decide whether a `.columns-N` hint is honored or the panels
+        # stack.
+        "figure.group" => {
+          box: { margin: [2, 0, 8] },
+          column_gap: 18,
+          min_column_width: 90,
+        },
+        "figure.group.caption" => { font_size: 9, margin: [4, 0, 0], text_align: :center },
+        "footnote" => { font_size: 9, margin: [0, 0, 3] },
+        "link" => { fill_color: "hp-blue" },
+        "highlight" => { background_color: "fff3a3" },
+        "image" => { margin: [2, 0, 8] },
+        "math" => { font_size: 11, margin: [4, 0, 8], box: { padding: 4 } },
+        "thematic_break" => { height: 2, margin: [8, 0, 8], background_color: "cccccc" },
+      })
+
+      def initialize(styles = nil)
+        @user = normalize(styles || {})
+        @memo = {}
+      end
+
+      def resolve(key)
+        normalized = normalize_key(key)
+        validate_key!(normalized)
+        @memo[normalized] ||= chain_for(normalized).each_with_object({}) do |part, resolved|
+          merge_entry!(resolved, DEFAULTS[part]) if DEFAULTS.key?(part)
+          merge_entry!(resolved, @user[part]) if @user.key?(part)
+        end.freeze
+      end
+
+      def user_set?(key, property = nil)
+        normalized = normalize_key(key)
+        return false unless @user.key?(normalized)
+        return true if property.nil?
+
+        @user[normalized].key?(property)
+      end
+
+      def user_set_in_chain?(key, property)
+        chain_for(normalize_key(key)).any? { |part| user_set?(part, property) }
+      end
+
+      private
+
+      def normalize(styles)
+        unless styles.respond_to?(:each_pair)
+          raise ArgumentError, "styles must be a Hash-like object"
+        end
+
+        styles.each_pair.with_object({}) do |(key, value), out|
+          normalized = normalize_key(key)
+          validate_key!(normalized)
+          out[normalized] = normalize_entry(value, normalized)
+        end
+      end
+
+      def normalize_key(key)
+        key.to_s
+      end
+
+      def normalize_entry(value, key)
+        unless value.respond_to?(:each_pair)
+          raise ArgumentError, "style entry #{key.inspect} must be a Hash-like object"
+        end
+
+        value.each_pair.with_object({}) do |(property, property_value), out|
+          out[property.to_sym] = property_value.is_a?(Hash) ? normalize_property_hash(property_value) : property_value
+        end
+      end
+
+      def normalize_property_hash(hash)
+        hash.each_pair.with_object({}) { |(key, value), out| out[key.to_sym] = value }
+      end
+
+      def validate_key!(key)
+        return if DEFAULTS.key?(key)
+        return if key.match?(/\Aheading\.\d+\z/)
+        # Admonition kinds are an open vocabulary (any word the parser accepts,
+        # including hyphenated ones), so accept any dot-free suffix.
+        return if key.match?(/\Aadmonition\.[^\s.]+\z/)
+
+        raise ArgumentError, "unknown style key: #{key.inspect}"
+      end
+
+      def chain_for(key)
+        chain = []
+        current = key
+        loop do
+          chain << current
+          break if current == "base"
+
+          current = current.include?(".") ? current.rpartition(".").first : "base"
+        end
+        chain.reverse
+      end
+
+      def merge_entry!(target, source)
+        return unless source
+
+        source.each_pair do |key, value|
+          target[key] = if key == :box && value.is_a?(Hash)
+                          (target[key] || {}).merge(value)
+                        else
+                          value
+                        end
+        end
+      end
+    end
+  end
+end

data/lib/carve/hexapdf/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Carve
+  module Hexapdf
+    VERSION = "0.1.0"
+  end
+end

data/lib/carve/hexapdf.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "hexapdf"
+require "carve"
+
+require_relative "hexapdf/version"
+require_relative "hexapdf/style_map"
+require_relative "hexapdf/renderer"
+
+module Carve
+  # Render Carve markup to PDF using the pure-Ruby HexaPDF layout engine.
+  #
+  #   pdf_bytes = Carve::Hexapdf.render("# Hello *world*")
+  #   Carve::Hexapdf.render_file("# Report", "out.pdf")
+  #
+  # The Carve source is parsed with +Carve.parse+ (from the carve-lang gem) and
+  # the resulting AST is walked by {Renderer}, which drives a
+  # HexaPDF::Composer. Bold/italic map to font variants, inline code to a
+  # monospace font, links to colored runs with URI overlays; block nodes map to
+  # HexaPDF text/list/table/container/image boxes.
+  #
+  # NOTE ON LICENSING: HexaPDF is dual-licensed AGPL-3.0 / commercial. Software
+  # that is distributed or offered over a network while depending on HexaPDF
+  # must comply with the AGPL or hold a HexaPDF commercial license. This gem
+  # (MIT) only bridges to it; your use of HexaPDF is governed by HexaPDF's own
+  # terms.
+  module Hexapdf
+    class << self
+      # Render Carve +source+ to a PDF and return the document as a binary
+      # String.
+      #
+      # Options:
+      #   page_size::   HexaPDF page size (default +:A4+).
+      #   margin::      page margin in points (default 45).
+      #   base_font::   proportional font family (default "Times").
+      #   code_font::   monospace font family (default "Courier").
+      #   link_color::  fill color for links (default "hp-blue").
+      #   styles::      hierarchical style map for PDF output.
+      #   renderers::   Hash of callables that turn math / diagram source into
+      #                 raster images, so those constructs render as images
+      #                 instead of degrading to source. Keys:
+      #                 +:math+ -> callable(tex, display_bool);
+      #                 +:mermaid+ / +:graphviz+ / +:chart+ -> callable(source).
+      #                 Return PNG/JPG bytes as a String, or a Hash with
+      #                 +:bytes+ and optional +:width+/+:height+ (points) to
+      #                 control the drawn size; anything else degrades the
+      #                 construct to its monospace source.
+      def render(source, **opts)
+        render_ast(::Carve.parse(source), **opts)
+      end
+
+      # Render an already-parsed Carve AST Hash (see +Carve.parse+) to PDF
+      # bytes. Useful when the AST is inspected or transformed before render.
+      def render_ast(ast, page_size: :A4, margin: 45, base_font: nil,
+                     code_font: nil, link_color: nil,
+                     highlight_color: nil, styles: nil, renderers: nil)
+        composer = ::HexaPDF::Composer.new(page_size: page_size, margin: margin)
+        Renderer.new(composer, base_font: base_font, code_font: code_font,
+                     link_color: link_color, highlight_color: highlight_color,
+                     styles: styles, renderers: renderers).render_document(ast)
+        composer.write_to_string
+      end
+
+      # Render Carve +source+ and write the PDF to +path+. Returns +path+.
+      def render_file(source, path, **opts)
+        File.binwrite(path, render(source, **opts))
+        path
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: carve-hexapdf
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- markup-carve
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: carve-lang
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+- !ruby/object:Gem::Dependency
+  name: hexapdf
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: |-
+  Parse Carve markup (via the carve-lang gem) and render it to a laid-out PDF
+  using HexaPDF's document composition engine. Carve block nodes map to
+  HexaPDF text/list/table/container/image boxes; inline nodes map to styled
+  text runs (bold/italic font variants, monospace code, colored links).
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/carve/hexapdf.rb
+- lib/carve/hexapdf/renderer.rb
+- lib/carve/hexapdf/style_map.rb
+- lib/carve/hexapdf/version.rb
+homepage: https://github.com/markup-carve/carve-hexapdf
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/markup-carve/carve-hexapdf
+  source_code_uri: https://github.com/markup-carve/carve-hexapdf
+  bug_tracker_uri: https://github.com/markup-carve/carve-hexapdf/issues
+  changelog_uri: https://github.com/markup-carve/carve-hexapdf/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.20
+signing_key:
+specification_version: 4
+summary: Render the Carve markup language to PDF via the pure-Ruby HexaPDF engine.
+test_files: []