arrolio 0.1.0

data/exe/arrolio2pdf

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'arrolio'
+
+input = ARGV[0]
+output = ARGV[1] || 'out.pdf'
+flavor_dir = ARGV[2] || ENV.fetch('ARROLIO_FLAVOR_DIR', nil)
+
+unless input && File.exist?(input)
+  warn 'usage: arrolio2pdf <input.xml> [output.pdf] [flavor_dir]'
+  warn '       (or set ARROLIO_FLAVOR_DIR env var)'
+  exit 2
+end
+
+unless flavor_dir && Dir.exist?(flavor_dir)
+  warn "error: flavor directory not found: #{flavor_dir.inspect}"
+  warn '       pass it as the 3rd argument or set ARROLIO_FLAVOR_DIR'
+  exit 2
+end
+
+xml = File.read(input)
+Arrolio::ConfigDrivenPipeline.render(
+  xml,
+  io: output,
+  flavor_dir: File.expand_path(flavor_dir),
+  input_path: File.expand_path(input)
+)
+puts "wrote #{output} (#{File.size(output)} bytes)"

data/lib/arrolio/asset_resolver.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Arrolio
+  class AssetResolver
+    attr_reader :base_dirs
+
+    def initialize(base_dirs:)
+      @base_dirs = Array(base_dirs).map { |directory| File.expand_path(directory.to_s) }.freeze
+      freeze
+    end
+
+    def resolve(source)
+      return source if source.nil? || source.empty?
+      return source if absolute?(source)
+
+      @base_dirs.each do |base_dir|
+        candidate = File.join(base_dir, source)
+        return candidate if File.exist?(candidate)
+      end
+      source
+    end
+
+    def self.from_input_path(input_path, extra: [])
+      directories = []
+      directories << File.dirname(File.expand_path(input_path)) if input_path
+      directories.concat(Array(extra))
+      new(base_dirs: directories)
+    end
+
+    private
+
+    def absolute?(source)
+      source.start_with?('/', 'http://', 'https://')
+    end
+  end
+end

data/lib/arrolio/color.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Arrolio
+  # Color value object. Parses CSS/XSL color specifications and
+  # provides normalized RGB components for the renderer. Supports:
+  # hex (#RGB, #RRGGBB), rgb(r,g,b), rgb(r%,g%,b%), named colors.
+  #
+  # The renderer calls +to_render+ to get the format pdfrb expects:
+  # +Float+ for grayscale, +[:rgb, r, g, b]+ for color.
+  class Color
+    attr_reader :red, :green, :blue, :alpha
+
+    # Named colors from the SVG/CSS specification subset commonly
+    # used in XSL-FO documents.
+    NAMED_COLORS = {
+      'black' => [0, 0, 0],
+      'white' => [255, 255, 255],
+      'red' => [255, 0, 0],
+      'green' => [0, 128, 0],
+      'blue' => [0, 0, 255],
+      'yellow' => [255, 255, 0],
+      'cyan' => [0, 255, 255],
+      'magenta' => [255, 0, 255],
+      'gray' => [128, 128, 128],
+      'grey' => [128, 128, 128],
+      'silver' => [192, 192, 192],
+      'maroon' => [128, 0, 0],
+      'purple' => [128, 0, 128],
+      'olive' => [128, 128, 0],
+      'navy' => [0, 0, 128],
+      'teal' => [0, 128, 128]
+    }.freeze
+
+    def initialize(red:, green:, blue:, alpha: 1.0)
+      @red = clamp01(red.to_f)
+      @green = clamp01(green.to_f)
+      @blue = clamp01(blue.to_f)
+      @alpha = clamp01(alpha.to_f)
+      freeze
+    end
+
+    # Factory: parse any supported color specification.
+    def self.parse(spec)
+      return spec if spec.is_a?(self)
+      return nil if spec.nil? || spec.to_s.empty?
+
+      case spec.to_s.downcase
+      when /\A#([0-9a-f])([0-9a-f])([0-9a-f])\z/
+        new(red: Regexp.last_match(1).to_i(16) * 17 / 255.0,
+            green: Regexp.last_match(2).to_i(16) * 17 / 255.0,
+            blue: Regexp.last_match(3).to_i(16) * 17 / 255.0)
+      when /\A#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})\z/
+        new(red: Regexp.last_match(1).to_i(16) / 255.0,
+            green: Regexp.last_match(2).to_i(16) / 255.0,
+            blue: Regexp.last_match(3).to_i(16) / 255.0)
+      when /\Argb\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\)\z/
+        new(red: Regexp.last_match(1).to_i / 255.0,
+            green: Regexp.last_match(2).to_i / 255.0,
+            blue: Regexp.last_match(3).to_i / 255.0)
+      when /\Argb\(\s*([\d.]+)%\s*,\s*([\d.]+)%\s*,\s*([\d.]+)%\s*\)\z/
+        new(red: Regexp.last_match(1).to_f / 100.0,
+            green: Regexp.last_match(2).to_f / 100.0,
+            blue: Regexp.last_match(3).to_f / 100.0)
+      else
+        parse_named(spec.to_s.downcase)
+      end
+    end
+
+    def self.parse_named(name)
+      return nil unless NAMED_COLORS.key?(name)
+
+      r, g, b = NAMED_COLORS[name]
+      new(red: r / 255.0, green: g / 255.0, blue: b / 255.0)
+    end
+    private_class_method :parse_named
+
+    # Returns the format pdfrb's canvas expects: +[:rgb, r, g, b]+.
+    def to_render
+      [:rgb, @red, @green, @blue]
+    end
+
+    def grayscale?
+      @red == @green && @green == @blue
+    end
+
+    def to_grayscale_float
+      (0.299 * @red) + (0.587 * @green) + (0.114 * @blue)
+    end
+
+    def ==(other)
+      other.is_a?(self.class) &&
+        red == other.red && green == other.green &&
+        blue == other.blue && alpha == other.alpha
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, red, green, blue, alpha].hash
+    end
+
+    private
+
+    def clamp01(v)
+      v.clamp(0.0, 1.0)
+    end
+  end
+end

data/lib/arrolio/column_set.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Arrolio
+  # A multi-column frame that splits a region's width into N equal
+  # columns. The engine flows content column-by-column: when one
+  # column overflows, content moves to the next column; when all
+  # columns overflow, the page breaks. This is the foundation for
+  # multi-column body text (e.g., 2-column technical specs).
+  #
+  # Usage in layout spec YAML:
+  #   page_templates:
+  #     body:
+  #       columns: 2
+  #       column_gap: 6mm
+  class ColumnSet
+    attr_reader :column_count, :gap, :total_width, :total_height
+
+    def initialize(column_count:, gap:, total_width:, total_height:)
+      @column_count = column_count.to_i
+      @gap = gap.to_f
+      @total_width = total_width.to_f
+      @total_height = total_height.to_f
+      freeze
+    end
+
+    # Width of a single column (total - gaps) / count.
+    def column_width
+      return @total_width if @column_count <= 1
+
+      (@total_width - (@gap * (@column_count - 1))) / @column_count
+    end
+
+    # X position of column at +index+ (0-based).
+    def column_x(index)
+      return 0.0 if @column_count <= 1
+
+      index * (column_width + @gap)
+    end
+
+    # Enumerate each column as a [x, width] pair.
+    def each_column
+      return enum_for(:each_column) unless block_given?
+
+      @column_count.times { |i| yield(column_x(i), column_width) }
+    end
+
+    def single_column?
+      @column_count <= 1
+    end
+
+    def ==(other)
+      other.is_a?(self.class) &&
+        column_count == other.column_count &&
+        gap == other.gap &&
+        total_width == other.total_width &&
+        total_height == other.total_height
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, column_count, gap, total_width, total_height].hash
+    end
+  end
+end

data/lib/arrolio/composer.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Arrolio
+  # Placeholder. TODO.complete/24 will build the real facade.
+  class Composer
+    def initialize(**_opts); end
+
+    def write(_target, io: nil); end
+  end
+end

data/lib/arrolio/config_driven_pipeline.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Arrolio
+  class ConfigDrivenPipeline
+    attr_reader :flavor_dir, :layout_spec, :adapter_rules, :flow_rules, :manifest, :strict
+
+    def self.render(xml, io:, flavor_dir:, input_path: nil,
+                    extra_image_dirs: [], logo_path: nil, metadata: {},
+                    strict: false)
+      new(
+        flavor_dir: flavor_dir,
+        input_path: input_path,
+        extra_image_dirs: extra_image_dirs,
+        logo_path: logo_path,
+        strict: strict
+      ).render(xml, io: io, metadata: metadata)
+    end
+
+    def initialize(flavor_dir:, input_path: nil, extra_image_dirs: [],
+                   logo_path: nil, strict: false)
+      @flavor_dir = File.expand_path(flavor_dir)
+      @input_path = input_path
+      @extra_image_dirs = Array(extra_image_dirs)
+      @logo_path = logo_path
+      @strict = strict
+      @manifest = load_manifest
+      @layout_spec = load_layout_spec
+      @adapter_rules = load_yaml('adapter_rules.yml')
+      @flow_rules = load_yaml('flow_rules.yml')
+    end
+
+    def render(xml, io:, metadata: {})
+      adapter = GenericAdapter.new(rules: @adapter_rules, layout_spec: @layout_spec)
+      document = adapter.convert(xml)
+      document_metadata = document.metadata.merge(metadata.transform_keys(&:to_sym))
+      register_fonts
+
+      resolver = AssetResolver.from_input_path(
+        @input_path,
+        extra: @extra_image_dirs + [@flavor_dir]
+      )
+      flowables = GenericFlowBuilder.new(
+        layout_spec: @layout_spec,
+        rules: @flow_rules,
+        asset_resolver: resolver
+      ).build(document)
+      engine = Engine::Paged.new(layout_spec: @layout_spec, flowables: flowables)
+      pages = engine.layout
+      populate_toc(pages, engine.context)
+
+      Renderer::Pdf.new.render(
+        pages,
+        io: io,
+        logo_path: @logo_path,
+        metadata: document_metadata,
+        font_paths: @layout_spec.font_paths,
+        context: engine.context,
+        layout_spec: @layout_spec
+      )
+    end
+
+    private
+
+    def load_manifest
+      Flavor::Manifest.load(@flavor_dir)
+    rescue FlavorError => e
+      Arrolio::Logger.debug "no manifest loaded for #{@flavor_dir}: #{e.message}"
+      nil
+    end
+
+    def load_yaml(filename)
+      path = File.join(@flavor_dir, filename)
+      YAML.safe_load_file(path, aliases: true) || {}
+    end
+
+    def load_layout_spec
+      source = load_yaml('layout_spec.yml')
+      source['font_paths'] = resolved_font_paths(source['font_paths'] || {})
+      LayoutSpec::Loader.build_from_hash(source)
+    end
+
+    def resolved_font_paths(paths)
+      paths.to_h do |name, path|
+        resolved = path.to_s.start_with?('/') ? path : File.join(@flavor_dir, path.to_s)
+        [name, resolved]
+      end
+    end
+
+    def register_fonts
+      FontMetrics::Registry.register_ttf_all(@layout_spec.font_paths, strict: @strict)
+    end
+
+    def populate_toc(pages, context)
+      entries = context&.heading_entries
+      return unless entries&.any?
+
+      toc_rules = @flow_rules['toc'] || {}
+      toc_flowables = TocBuilder.build_flowables(context, @layout_spec, rules: toc_rules)
+      return if toc_flowables.empty?
+
+      toc_page_index = pages.index { |page| page.template_role == :preface }
+      return unless toc_page_index
+
+      toc_page = pages[toc_page_index]
+      region = toc_page.regions[:body]
+      return unless region
+
+      toc_rules_full = @flow_rules['toc'] || {}
+      toc_top_offset = (toc_rules_full['top_offset'] || 40).to_f
+
+      cursor_y = region.y + region.height - toc_top_offset
+      new_boxes = []
+      toc_flowables.each do |flowable|
+        flowable.height(region.width, context)
+        boxes, consumed = flowable.emit(region.x, cursor_y, region.width, context)
+        new_boxes.concat(boxes)
+        cursor_y -= consumed
+      end
+
+      updated_region = Output::Region.new(
+        name: region.name,
+        x: region.x,
+        y: region.y,
+        width: region.width,
+        height: region.height,
+        placed_boxes: region.placed_boxes + new_boxes
+      )
+      updated_page = Output::Page.new(
+        number: toc_page.number,
+        template_name: toc_page.template_name,
+        template_role: toc_page.template_role,
+        page_size: toc_page.page_size,
+        regions: toc_page.regions.merge(body: updated_region),
+        header_text: toc_page.header_text,
+        footer_text: toc_page.footer_text,
+        header_align: toc_page.header_align,
+        footer_align: toc_page.footer_align
+      )
+      pages[toc_page_index] = updated_page
+    end
+  end
+end

data/lib/arrolio/content/bibliography_item.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module Content
+    # A single bibliography entry: citation tag (e.g. "[Smith2020]")
+    # and a formatted reference Paragraph. Renders with a
+    # hanging-indent so wrapped lines align under the text, not the
+    # citation tag.
+    class BibliographyItem
+      attr_reader :tag, :formattedref, :id, :style_id
+
+      def initialize(formattedref:, tag: nil, id: nil, style_id: :bibitem)
+        @tag = tag
+        @formattedref = formattedref
+        @id = id&.to_s
+        @style_id = style_id.to_sym
+        freeze
+      end
+
+      def text
+        @formattedref.is_a?(Paragraph) ? @formattedref.text : @formattedref.to_s
+      end
+
+      def empty?
+        @tag.nil? && (@formattedref.nil? || (@formattedref.is_a?(Paragraph) && @formattedref.empty?))
+      end
+
+      def ==(other)
+        other.is_a?(self.class) &&
+          tag == other.tag &&
+          formattedref == other.formattedref &&
+          id == other.id &&
+          style_id == other.style_id
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, tag, formattedref, id, style_id].hash
+      end
+    end
+  end
+end

data/lib/arrolio/content/builder.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module Content
+    class Builder
+      attr_reader :metadata, :sections
+
+      def self.build(metadata: {}, **opts, &block)
+        builder = new(metadata: metadata, **opts)
+        block&.call(builder)
+        builder.to_document
+      end
+
+      def initialize(metadata: {})
+        @metadata = metadata
+        @sections = []
+      end
+
+      def section(title = nil, number: nil, level: 1, id: nil,
+                  style_id: :section_body, title_style_id: nil, &block)
+        sb = SectionBuilder.new(title: title, number: number, level: level, id: id,
+                                style_id: style_id, title_style_id: title_style_id)
+        block&.call(sb)
+        @sections << sb.build
+        self
+      end
+
+      def to_document
+        Document.new(metadata: @metadata, sections: @sections)
+      end
+    end
+
+    class SectionBuilder
+      attr_reader :title, :level, :number, :id, :style_id, :title_style_id
+
+      def initialize(title:, number:, level:, id:, style_id:, title_style_id:)
+        @title = title
+        @number = number
+        @level = level
+        @id = id
+        @style_id = style_id
+        @title_style_id = title_style_id
+        @children = []
+      end
+
+      def paragraph(text = nil, style_id: :body, id: nil, &block)
+        runs = block ? ParagraphBuilder.new.runs(&block) : [InlineRun.new(text.to_s, style_id: :inline)]
+        @children << Paragraph.new(runs, style_id: style_id, id: id)
+        self
+      end
+
+      def list(items, kind: :bullet, style_id: :list, id: nil)
+        @children << List.new(items, kind: kind, style_id: style_id, id: id)
+        self
+      end
+
+      def table(header: [], body: [], column_widths: nil, style_id: :table, id: nil)
+        @children << Table.new(header: header, body: body,
+                               column_widths: column_widths, style_id: style_id, id: id)
+        self
+      end
+
+      def section(title = nil, **opts, &block)
+        opts[:level] ||= @level + 1
+        sub = SectionBuilder.new(title: title, number: opts[:number],
+                                 level: opts[:level], id: opts[:id],
+                                 style_id: opts.fetch(:style_id, @style_id),
+                                 title_style_id: opts[:title_style_id])
+        block&.call(sub)
+        @children << sub.build
+        self
+      end
+
+      def build
+        Section.new(title: @title, level: @level, number: @number, id: @id,
+                    children: @children, style_id: @style_id, title_style_id: @title_style_id)
+      end
+    end
+
+    class ParagraphBuilder
+      def initialize
+        @runs = []
+      end
+
+      def text(str, style_id: :inline)
+        @runs << InlineRun.new(str.to_s, style_id: style_id)
+      end
+
+      def strong(str)
+        @runs << InlineRun.new(str.to_s, style_id: :strong)
+      end
+
+      def em(str)
+        @runs << InlineRun.new(str.to_s, style_id: :em)
+      end
+
+      def link(str, href)
+        @runs << InlineRun.new(str.to_s, style_id: :link, href: href)
+      end
+
+      def runs
+        return @runs unless block_given?
+        yield self
+        @runs
+      end
+    end
+  end
+end

data/lib/arrolio/content/document.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'arrolio/error'
+
+module Arrolio
+  module Content
+    class Document
+      attr_reader :metadata, :sections, :preface, :bibliography, :cover,
+                  :style_id, :footnotes
+
+      def self.build(metadata: {}, **opts, &block)
+        Builder.build(metadata: metadata, **opts, &block)
+      end
+
+      def initialize(metadata: {}, sections: [], preface: [], bibliography: [],
+                     cover: nil, style_id: :document, footnotes: [])
+        @metadata = metadata.to_h.freeze
+        @sections = validate_sections(Array(sections), field: :sections).freeze
+        @preface = validate_sections(Array(preface), field: :preface).freeze
+        @bibliography = validate_sections(Array(bibliography), field: :bibliography).freeze
+        @cover = cover
+        @style_id = style_id.to_sym
+        @footnotes = Array(footnotes).freeze
+        freeze
+      end
+
+      def title = @metadata[:title] || @metadata['title']
+      def docidentifier = @metadata[:docidentifier] || @metadata['docidentifier']
+      def edition = @metadata[:edition] || @metadata['edition']
+
+      def ==(other)
+        other.is_a?(self.class) &&
+          metadata == other.metadata && sections == other.sections &&
+          preface == other.preface && bibliography == other.bibliography &&
+          cover == other.cover && style_id == other.style_id &&
+          footnotes == other.footnotes
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, metadata, sections, preface, bibliography, cover,
+         style_id, footnotes].hash
+      end
+
+      private
+
+      def validate_sections(array, field:)
+        array.each do |item|
+          next if item.is_a?(Section)
+
+          raise ::Arrolio::ContentError.new(
+            "#{field} must contain only Content::Section instances; got #{item.class}",
+            node: item
+          )
+        end
+        array
+      end
+    end
+  end
+end

data/lib/arrolio/content/example.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module Content
+    # A semantic example group. Same shape as Note but carries the
+    # :example style_id by default so the flow builder can apply the
+    # XSL's `example-body-style` margin-left to the body Paragraphs.
+    class Example
+      attr_reader :label, :body, :id, :style_id
+
+      def initialize(body:, label: '', id: nil, style_id: :example)
+        @label = label.to_s
+        @body = Array(body).freeze
+        @id = id&.to_s
+        @style_id = style_id.to_sym
+        freeze
+      end
+
+      def body_text
+        @body.map do |node|
+          node.is_a?(Paragraph) ? node.text : node.to_s
+        end.join(' ')
+      end
+
+      def empty?
+        @body.empty? || @body.all? { |node| node.is_a?(Paragraph) && node.empty? }
+      end
+
+      def ==(other)
+        other.is_a?(self.class) &&
+          label == other.label &&
+          body == other.body &&
+          id == other.id &&
+          style_id == other.style_id
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, label, body, id, style_id].hash
+      end
+    end
+  end
+end

data/lib/arrolio/content/figure_group.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module Content
+    # A figure group: optional Image plus optional caption Paragraph.
+    # Replaces the previous flat [Image, Paragraph] emission from
+    # convert_figure. The flow builder renders the group as a
+    # keep-together unit so the caption never lands on a different
+    # page from the image.
+    class FigureGroup
+      attr_reader :image, :caption, :id, :style_id
+
+      def initialize(image: nil, caption: nil, id: nil, style_id: :figure)
+        @image = image
+        @caption = caption
+        @id = id&.to_s
+        @style_id = style_id.to_sym
+        freeze
+      end
+
+      def empty?
+        @image.nil? && (@caption.nil? || (@caption.is_a?(Paragraph) && @caption.empty?))
+      end
+
+      def ==(other)
+        other.is_a?(self.class) &&
+          image == other.image &&
+          caption == other.caption &&
+          id == other.id &&
+          style_id == other.style_id
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, image, caption, id, style_id].hash
+      end
+    end
+  end
+end