emf 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dae3a082f2aa6e824fdd74fc55ad43f74f05820b610278f9235ad4b7b1d87883
+  data.tar.gz: 1c9d8429f6efca41a04e43c97ca01bff4a39a4f8f3be96a12f0a0672e9e3f52f
+SHA512:
+  metadata.gz: a5f798a4ff947f78eb5062168efd38704dde357094d3570bda0b717f3b18169070e36ee2a336d13875be598e01025c4d222b4a96853d7e6fd754d58633b0aef7
+  data.tar.gz: a20b7b34c3b82ad217711f6e24c292fdc70aa6465751a58f5edbac0d126cdfb4743dd3ed10df8483f0b362ee2042c27ae1c6bbf20a571c1ff00444ce4253fb28

data/LICENSE.txt

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, Ribose Inc.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.adoc

@@ -0,0 +1,136 @@
+= emf: pure-Ruby parser for WMF, EMF, and EMF+ metafiles
+
+`emf` is a clean-room, pure-Ruby parser for the three Microsoft Windows
+metafile formats:
+
+* **WMF** — Windows Metafile (see MS-WMF, kaitai `wmf.ksy`)
+* **EMF** — Enhanced Metafile (see MS-EMF)
+* **EMF+** — Enhanced Metafile Plus (see MS-EMFPLUS; embedded in EMF
+  via `EMR_COMMENT` records)
+
+It reads binary input into an OOP domain model and serialises the model
+back to binary. It is the parsing half of the upcoming `emfsvg` gem
+(EMF <-> SVG transformation). It replaces the FFI-based `emf2svg-ruby`
+wrapper around the GPLv2 `libemf2svg` C library.
+
+== Status
+
+* **EMF**: full parse + byte-identical round-trip on every fixture
+  (186/186 in `spec/fixtures/emf/`, 21/21 in `spec/fixtures/emf-ea/`,
+  1/1 in `spec/fixtures/simple/`).
+* **EMF+**: EMF+ payloads are extracted from EMF carrier records as raw
+  bytes (`Metafile#emf_plus`). Structured EMF+ parsing is TODO
+  (see `TODO.impl/12-14`).
+* **WMF**: detected but not yet parsed (`TODO.impl/07`).
+* **License**: BSD-2-Clause. No GPL obligation.
+
+== Installation
+
+Add to your Gemfile:
+
+  gem "emf", "~> 0.1"
+
+Or install directly:
+
+  gem install emf
+
+Requires Ruby >= 3.1.
+
+== Synopsis
+
+  require "emf"
+
+  # Parse from bytes or a file path
+  metafile = Emf.parse_file("image.emf")
+  metafile.format         # => :emf or :emf_plus
+  metafile.records.length # => 3538
+  metafile.errors.empty?  # => true (no parse errors)
+
+  # Walk records with a visitor
+  stats = Emf::Visitors::Stats.new.visit_all(metafile)
+  puts stats.to_s
+
+  # Serialise back to binary — byte-identical on every fixture
+  bytes = Emf.serialize(metafile)
+
+== Command-line tool
+
+  emf version                  Print version
+  emf info FILE                Header summary + record counts
+  emf dump FILE                Record-by-record dump
+  emf stats FILE               Record-type histogram
+  emf validate FILE            Parse + report errors (exit 0 ok, 1 invalid)
+  emf round-trip FILE [--out]  Re-serialize after parse, compare or write
+
+== Architecture
+
+Three layers, kept strictly separate (MECE):
+
+  binary bytes --[bindata]--> Emr::Binary::*Record (byte-faithful)
+                                     |
+                              Record.from_wire
+                                     v
+                                Model::*Record (semantic OOP, immutable)
+                                     |
+                              Record#to_wire
+                                     v
+                          Emr::Binary::*Record --[bindata]--> binary bytes
+
+* **Wire layer** (`Emf::Emr::Binary::*`): one bindata class per EMR record
+  type, declared by spec. Pure data, no behaviour. Symmetric read/write.
+* **Domain layer** (`Emf::Model::*`): immutable value objects with
+  `attr_reader`, value equality, `accept(visitor)`, `from_wire`, `to_wire`.
+* **Visitor pattern** (`Emf::Model::Visitor`): consumers subclass the base
+  and override only the `visit_*` methods they care about. Adding a record
+  type touches the record's own file plus three lines in `records.rb`
+  (autoload + TYPE_TO_NAME + the file itself) -- no central switch.
+
+=== Constraints honoured throughout
+
+* No `require_relative` and no `require` of internal paths in `lib/` --
+  everything autoloads via the parent-namespace file pattern.
+* No `double()` in specs -- real instances only.
+* No `send` to private methods, no `instance_variable_set`/`get`, no
+  `respond_to?` for type checks.
+* No AI attribution in any commit. All changes go through PRs.
+
+See `docs/architecture.adoc` and `docs/format_notes.adoc` for the deep
+dive, and `TODO.impl/PROGRESS.md` for what's done vs what remains.
+
+=== Reference documentation
+
+The Microsoft specifications are checked in at `reference-docs/` as both
+the original `.docx` files and per-chapter GFM markdown under
+`reference-docs/<spec>/`. The conversion script is
+`scripts/convert_docs.rb` (rubyzip + nokogiri). Re-run when the spec
+revision bumps.
+
+== Development
+
+  git clone https://github.com/claricle/emf
+  cd emf
+  bundle install
+  bundle exec rspec       # ~280 examples across fixtures + units
+  bundle exec rubocop     # clean
+
+The round-trip harness in `spec/emf/round_trip_spec.rb` is the strongest
+correctness signal: it walks every non-corrupted fixture and asserts
+byte-identical parse -> serialise -> parse.
+
+== Roadmap
+
+Full TODO list lives in `TODO.impl/`. Highlights:
+
+* TODO 09 -- finish remaining ~60 EMR wire types (currently 117 of ~122 done)
+* TODO 10 -- semantic domain records (currently WireAdapter for most types)
+* TODO 11 -- 2-pass path association (BEGINPATH <-> FILLPATH/STROKEPATH)
+* TODO 07 -- WMF parser + fixtures
+* TODO 12-14 -- EMF+ wire + domain + parser
+
+== License
+
+BSD-2-Clause. See `LICENSE.txt`.
+
+The gem is a clean-room reimplementation derived from the public
+Microsoft Open Specifications (MS-WMF, MS-EMF, MS-EMFPLUS). No code was
+copied from `libemf2svg` (GPLv2) or `libUEMF` (GPLv2).

data/exe/emf

@@ -0,0 +1,113 @@
+#! /usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "emf"
+
+module Emf
+  module CLI
+    module_function
+
+    def run(argv)
+      command = argv.shift
+      case command
+      when "version", "-v", "--version" then puts "emf #{Emf::VERSION}"
+      when "info" then info(argv)
+      when "dump" then dump(argv)
+      when "validate" then validate(argv)
+      when "stats" then stats(argv)
+      when "round-trip" then round_trip(argv)
+      when "help", "-h", "--help", nil then print_help
+      else
+        warn "emf: unknown command '#{command}' (see `emf help`)"
+        exit 1
+      end
+    end
+
+    def parse_path(argv)
+      path = argv.shift
+      return path if path && !path.empty?
+
+      warn "emf: missing FILE argument"
+      exit 2
+    end
+
+    def info(argv)
+      path = parse_path(argv)
+      mf = Emf.parse_file(path)
+      puts "Format:    #{mf.format}"
+      puts "Records:   #{mf.records.size}"
+      puts "Errors:    #{mf.errors.size}"
+      puts "EMF+:      #{mf.emf_plus ? "present (#{mf.emf_plus.bytesize} bytes)" : 'absent'}"
+      puts "Trailing:  #{mf.trailing.bytesize} bytes"
+      return unless mf.header
+
+      h = mf.header
+      puts "Bounds:    left=#{h.bounds.left} top=#{h.bounds.top} right=#{h.bounds.right} bottom=#{h.bounds.bottom}"
+      puts "Frame:     left=#{h.frame.left} top=#{h.frame.top} right=#{h.frame.right} bottom=#{h.frame.bottom}"
+      puts "Device:    #{h.device_pixels.cx}x#{h.device_pixels.cy} px (#{h.device_mm.cx / 100.0}x#{h.device_mm.cy / 100.0} mm)"
+      puts "nRecords:  #{h.n_records}  nHandles: #{h.n_handles}  nBytes: #{h.n_bytes}"
+    end
+
+    def dump(argv)
+      path = parse_path(argv)
+      mf = Emf.parse_file(path)
+      d = Emf::Visitors::Dump.new
+      d.visit_all(mf)
+      puts d
+    end
+
+    def validate(argv)
+      path = parse_path(argv)
+      mf = Emf.parse_file(path)
+      if mf.errors.empty?
+        puts "OK: #{mf.records.size} records, 0 errors"
+        exit 0
+      else
+        puts "INVALID: #{mf.records.size} records, #{mf.errors.size} errors"
+        mf.errors.first(10).each { |e| puts "  #{e.message}" }
+        exit 1
+      end
+    end
+
+    def stats(argv)
+      path = parse_path(argv)
+      mf = Emf.parse_file(path)
+      s = Emf::Visitors::Stats.new
+      s.visit_all(mf)
+      puts s
+    end
+
+    def round_trip(argv)
+      path = parse_path(argv)
+      original = File.binread(path)
+      reborn = Emf.serialize(Emf.parse(original))
+      out = argv.shift
+      if out
+        File.binwrite(out, reborn)
+        puts "Wrote #{out} (#{reborn.bytesize} bytes)"
+      else
+        puts original == reborn ? "OK: byte-identical round-trip" : "DRIFT: original=#{original.bytesize} reborn=#{reborn.bytesize}"
+      end
+    end
+
+    def print_help
+      puts <<~HELP
+        emf #{Emf::VERSION} — pure-Ruby WMF/EMF/EMF+ parser
+
+        Usage:
+          emf version                  Print the version
+          emf info FILE                Print metafile header and record counts
+          emf dump FILE                Print a record-by-record dump
+          emf validate FILE            Parse and report errors (exit 0 ok, 1 invalid)
+          emf stats FILE               Print record-type histogram
+          emf round-trip FILE [--out]  Serialize after parse, compare or write
+          emf help                     Show this message
+      HELP
+    end
+  end
+end
+
+Emf::CLI.run(ARGV)

data/lib/emf/binary/codec.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "bindata"
+
+module Emf
+  module Binary
+    module Codec
+      module_function
+
+      def utf16le_to_utf8(bytes)
+        bytes.dup.force_encoding("UTF-16LE").encode("UTF-8")
+      end
+
+      def cp1252_to_utf8(bytes)
+        bytes.dup.force_encoding("CP1252").encode("UTF-8")
+      end
+    end
+  end
+end

data/lib/emf/binary/types.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "bindata"
+
+module Emf
+  module Binary
+    # Bindata primitives shared by all three formats (WMF, EMF, EMF+).
+    # Each record type is declared once and used as a `type:` argument in
+    # larger records. See TODO.impl/03-binary-primitives.md.
+    module Types
+      class PointL < BinData::Record
+        endian :little
+        int32 :x
+        int32 :y
+      end
+
+      class PointS < BinData::Record
+        endian :little
+        int16 :x
+        int16 :y
+      end
+
+      class PointD < BinData::Record
+        endian :little
+        double :x
+        double :y
+      end
+
+      class SizeL < BinData::Record
+        endian :little
+        int32 :cx
+        int32 :cy
+      end
+
+      class RectL < BinData::Record
+        endian :little
+        int32 :left
+        int32 :top
+        int32 :right
+        int32 :bottom
+      end
+
+      class RectS < BinData::Record
+        endian :little
+        int16 :left
+        int16 :top
+        int16 :right
+        int16 :bottom
+      end
+
+      class ColorRef < BinData::Record
+        endian :little
+        uint8 :red
+        uint8 :green
+        uint8 :blue
+        uint8 :reserved
+      end
+
+      class XForm < BinData::Record
+        endian :little
+        float :m11
+        float :m12
+        float :m21
+        float :m22
+        float :dx
+        float :dy
+      end
+
+      class PaletteEntry < BinData::Record
+        endian :little
+        uint8 :pe_flags
+        uint8 :pe_red
+        uint8 :pe_green
+        uint8 :pe_blue
+      end
+
+      class LogPalette < BinData::Record
+        endian :little
+        uint16 :pal_version
+        uint16 :pal_num_entries
+        array :pal_pal_entry, type: :palette_entry, initial_length: :pal_num_entries
+      end
+
+      class FileTime < BinData::Record
+        endian :little
+        uint32 :dw_low_date_time
+        uint32 :dw_high_date_time
+      end
+    end
+  end
+end
+
+# Register the primitives so they can be referenced by name (e.g. `rectl :bounds`)
+# inside other BinData records. Bindata resolves types lazily through this registry.
+BinData::RegisteredClasses.register("point_l", Emf::Binary::Types::PointL)
+BinData::RegisteredClasses.register("point_s", Emf::Binary::Types::PointS)
+BinData::RegisteredClasses.register("point_d", Emf::Binary::Types::PointD)
+BinData::RegisteredClasses.register("size_l", Emf::Binary::Types::SizeL)
+BinData::RegisteredClasses.register("rectl", Emf::Binary::Types::RectL)
+BinData::RegisteredClasses.register("rect_s", Emf::Binary::Types::RectS)
+BinData::RegisteredClasses.register("color_ref", Emf::Binary::Types::ColorRef)
+BinData::RegisteredClasses.register("x_form", Emf::Binary::Types::XForm)
+BinData::RegisteredClasses.register("palette_entry", Emf::Binary::Types::PaletteEntry)
+BinData::RegisteredClasses.register("log_palette", Emf::Binary::Types::LogPalette)
+BinData::RegisteredClasses.register("file_time", Emf::Binary::Types::FileTime)

data/lib/emf/binary.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bindata"
+
+module Emf
+  module Binary
+    autoload :Types, "emf/binary/types"
+    autoload :Codec, "emf/binary/codec"
+  end
+end

data/lib/emf/detector.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Emf
+  module Detector
+    APM_MAGIC = 0x9AC6CDD7 # bytes 0xD7 0xCD 0xC6 0x9A, read as uint32 little-endian
+    EMF_SIGNATURE = 1
+    EMF_MAGIC_OFFSET = 0x28
+    EMF_MAGIC = 0x464D4520
+
+    module_function
+
+    def call(bytes)
+      raise FormatError, "input too short (#{bytes.bytesize} bytes)" if bytes.bytesize < 4
+
+      case first_uint32_le(bytes)
+      when APM_MAGIC then :wmf_apm
+      when EMF_SIGNATURE
+        return :emf if looks_like_emf?(bytes)
+        return :wmf_standard if looks_like_wmf_metaheader?(bytes)
+
+        raise FormatError, "unrecognised format (signature=1 but no EMF magic or WMF header)"
+      else
+        return :wmf_standard if looks_like_wmf_metaheader?(bytes)
+
+        raise FormatError, format("unrecognised format (first uint32=0x%08X)", first_uint32_le(bytes))
+      end
+    end
+
+    def looks_like_emf?(bytes)
+      return false unless bytes.bytesize >= EMF_MAGIC_OFFSET + 4
+
+      read_uint32_le(bytes, EMF_MAGIC_OFFSET) == EMF_MAGIC
+    end
+
+    def looks_like_wmf_metaheader?(bytes)
+      return false unless bytes.bytesize >= 18
+
+      mt = read_uint16_le(bytes, 0)
+      hs = read_uint16_le(bytes, 2)
+      [1, 2].include?(mt) && hs == 9
+    end
+
+    def first_uint32_le(bytes)
+      read_uint32_le(bytes, 0)
+    end
+
+    def read_uint32_le(bytes, offset)
+      bytes.getbyte(offset) |
+        (bytes.getbyte(offset + 1) << 8) |
+        (bytes.getbyte(offset + 2) << 16) |
+        (bytes.getbyte(offset + 3) << 24)
+    end
+
+    def read_uint16_le(bytes, offset)
+      bytes.getbyte(offset) | (bytes.getbyte(offset + 1) << 8)
+    end
+  end
+end

data/lib/emf/emf_plus/binary.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Emf
+  module EmfPlus
+    module Binary
+    end
+  end
+end

data/lib/emf/emf_plus/parser.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Emf
+  module EmfPlus
+    module Parser
+      module_function
+
+      def call(_bytes)
+        raise Error, "EMF+ parser not yet implemented — see TODO.impl/14-emfplus-parser.md"
+      end
+    end
+  end
+end

data/lib/emf/emf_plus/serializer.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Emf
+  module EmfPlus
+    module Serializer
+      module_function
+
+      def call(_metafile)
+        raise SerializeError, "EMF+ serializer not yet implemented — see TODO.impl/15-public-api.md"
+      end
+    end
+  end
+end

data/lib/emf/emf_plus.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Emf
+  module EmfPlus
+    autoload :Parser, "emf/emf_plus/parser"
+    autoload :Serializer, "emf/emf_plus/serializer"
+    autoload :Binary, "emf/emf_plus/binary"
+  end
+end

data/lib/emf/emr/binary/header.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "bindata"
+
+module Emf
+  module Emr
+    module Binary
+      # EMF metafile header record. The fixed portion is 88 bytes ending at
+      # szlMillimeters. The remaining fields (cbPixelFormat, offPixelFormat,
+      # bOpenGL, szlMicrometers) are optional — present only when nSize is
+      # 100 or 108. An optional UTF-16LE description string follows at
+      # offDescription for nDescription Unicode chars.
+      class Header < BinData::Record
+        endian :little
+        uint32 :i_type                # 1
+        uint32 :n_size                # total record size in bytes
+        rectl :rcl_bounds             # bounding rectangle in device units
+        rectl :rcl_frame              # bounding rectangle in 0.01 mm units
+        uint32 :d_signature           # 0x464D4520 (" EMF")
+        uint32 :n_version             # 0x00010000 typical
+        uint32 :n_bytes               # metafile size in bytes
+        uint32 :n_records             # total record count
+        uint16 :n_handles             # graphics object count + 1
+        uint16 :s_reserved            # must be 0
+        uint32 :n_description         # UTF-16LE char count of description (0 if none)
+        uint32 :off_description       # byte offset to description from record start
+        uint32 :n_pal_entries         # palette entries (used by EMR_EOF)
+        size_l :szl_device            # reference device size in pixels
+        size_l :szl_millimeters       # reference device size in 0.01 mm
+        # Win95-and-later fields (absent in 88-byte headers).
+        uint32 :cb_pixel_format, onlyif: -> { n_size > 88 }       # PixelFormatDescriptor size, 0 if none
+        uint32 :off_pixel_format, onlyif: -> { n_size > 88 }      # offset to PixelFormatDescriptor
+        uint32 :b_open_gl, onlyif: -> { n_size > 88 }             # nonzero if OpenGL records present
+        # Win98-and-later field (absent in 100-byte headers).
+        size_l :szl_micrometers, onlyif: -> { n_size > 100 } # device size in micrometers
+        # Capture any trailing bytes beyond the declared optional fields.
+        rest :trailing
+      end
+    end
+  end
+end

data/lib/emf/emr/binary/record.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "bindata"
+
+module Emf
+  module Emr
+    module Binary
+      # All EMR records share an 8-byte header: uint32 iType, uint32 nSize.
+      # Subclasses add their own fields after this.
+      class Record < BinData::Record
+        endian :little
+        uint32 :i_type
+        uint32 :n_size
+      end
+    end
+  end
+end

data/lib/emf/emr/binary/records/abort_path.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bindata"
+require "emf/emr/binary/record"
+
+module Emf
+  module Emr
+    module Binary
+      module Records
+        # Control record with no payload (just iType and nSize).
+        class AbortPath < Emf::Emr::Binary::Record
+        end
+      end
+    end
+  end
+end

data/lib/emf/emr/binary/records/alpha_blend.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "bindata"
+require "emf/emr/binary/with_bounds"
+
+module Emf
+  module Emr
+    module Binary
+      module Records
+        # Stub: leading fields per MS-EMF, body captures remaining bytes.
+        class AlphaBlend < Emf::Emr::Binary::WithBounds
+          rest :body
+        end
+      end
+    end
+  end
+end

data/lib/emf/emr/binary/records/angle_arc.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "bindata"
+require "emf/emr/binary/record"
+
+module Emf
+  module Emr
+    module Binary
+      module Records
+        class AngleArc < Emf::Emr::Binary::Record
+          point_l :ptl_center
+          uint32 :n_radius
+          float :start_angle
+          float :sweep_angle
+        end
+      end
+    end
+  end
+end

data/lib/emf/emr/binary/records/arc.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "bindata"
+require "emf/emr/binary/record"
+
+module Emf
+  module Emr
+    module Binary
+      module Records
+        # EMR_ARC: emr + rclBox + ptlStart + ptlEnd (no rclBounds).
+        class Arc < Emf::Emr::Binary::Record
+          rectl :rcl_box
+          point_l :ptl_start
+          point_l :ptl_end
+        end
+      end
+    end
+  end
+end

data/lib/emf/emr/binary/records/arc_to.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "bindata"
+require "emf/emr/binary/record"
+
+module Emf
+  module Emr
+    module Binary
+      module Records
+        # EMR_ARC_TO: emr + rclBox + ptlStart + ptlEnd (no rclBounds).
+        class ArcTo < Emf::Emr::Binary::Record
+          rectl :rcl_box
+          point_l :ptl_start
+          point_l :ptl_end
+        end
+      end
+    end
+  end
+end