xmp_toolkit_ruby 0.0.2

data/lib/xmp_toolkit_ruby/plugins/PDF_Handler/resource/mac/PDF_Handler.plist

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleExecutable</key>
+	<string>PDF_Handler</string>
+	<key>CFBundleIdentifier</key>
+	<string>com.xmp.PDF_Handler</string>
+	<key>CFBundleName</key>
+	<string>PDF_Handler</string>
+	<key>CFBundleGetInfoString</key>
+	<string>PDF Handler kBasicVersion, kXMP_Copyright</string>
+	<key>CFBundleShortVersionString</key>
+	<string>PDF Handler kBasicVersion</string>
+	<key>CFBundlePackageType</key>
+	<string>FMWK</string>
+	<key>CFBundleSignature</key>
+	<string>XMP </string>
+	<key>Configuration</key>
+	<string>kConfig</string>
+	<key>FileVersion</key>
+	<string>kBasicVersion</string>
+	<key>ProductName</key>
+	<string>PDF Handler</string>
+	<key>ProductVersion</key>
+	<string>PDF_HANDLER_VERSION</string>
+</dict>
+</plist>

data/lib/xmp_toolkit_ruby/plugins/PDF_Handler/resource/mac/PDF_HandlerPList.h

@@ -0,0 +1,12 @@
+#include "../../../../build/XMP_BuildInfo.h"
+#define PDF_HANDLER_VERSION 1.0
+#if NDEBUG	// Can't use XMP_Environment.h, it seems to mess up the PList compiler.
+	#define kConfig Release
+	#define kDebugSuffix
+	#define kBasicVersion PDF_HANDLER_VERSION
+#else
+	#define kConfig Debug
+	#define kDebugSuffix (debug)
+	#define kBasicVersion PDF_HANDLER_VERSION kDebugSuffix
+#endif
+

data/lib/xmp_toolkit_ruby/plugins/PDF_Handler/resource/win/CopyPDFL.bat

@@ -0,0 +1,14 @@
+@ECHO OFF
+@rem Copy the needed PDFL to the public folder.
+@rem Usage: CopyPDFL <mode> <platform>
+@rem        <mode> is debug or release
+@rem        <platform> is windows or windows_x64. defaults to "windows" (32-bit)
+
+set workingDir=%~dp0%
+set mode=%1
+if "%1" == "" set mode=release
+set platform=%2
+if "%2" == "" set platform=windows
+
+mkdir %workingDir%\..\..\..\public\%platform%\%mode%\PDF_Handler
+xcopy /y /r %workingDir%\..\..\third-party\MiniPDFL\libraries\%platform%\release\MiniPDFL.dll %workingDir%\..\..\..\public\%platform%\%mode%\PDF_Handler

data/lib/xmp_toolkit_ruby/plugins/PDF_Handler/resource/win/PDF_Handler-32.rc

@@ -0,0 +1,8 @@
+
+/////////////////////////////////////////////////////////////////////////////
+//
+// TXT
+//
+
+XMPPLUGINUIDS           TXT                     "../../../resource/txt/XMPPLUGINUIDS-32.txt"
+MODULE_IDENTIFIER       TXT                     "../../../resource/txt/MODULE_IDENTIFIER.txt"

data/lib/xmp_toolkit_ruby/plugins/PDF_Handler/resource/win/PDF_Handler-64.rc

@@ -0,0 +1,8 @@
+
+/////////////////////////////////////////////////////////////////////////////
+//
+// TXT
+//
+
+XMPPLUGINUIDS           TXT                     "../../../resource/txt/XMPPLUGINUIDS-64.txt"
+MODULE_IDENTIFIER       TXT                     "../../../resource/txt/MODULE_IDENTIFIER.txt"

data/lib/xmp_toolkit_ruby/plugins/PDF_Handler/resource/win/PDF_Handler.def

@@ -0,0 +1,9 @@
+; Declares the entry points for the DLL.
+; Highest index: 2 - InitializePlugin2
+
+LIBRARY   PDF_Handler
+
+EXPORTS
+
+	InitializePlugin					@1
+	InitializePlugin2					@2

data/lib/xmp_toolkit_ruby/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module XmpToolkitRuby
+  VERSION = "0.0.2"
+end

data/lib/xmp_toolkit_ruby/xmp_file_format.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module XmpToolkitRuby
+  module XmpFileFormat
+    # Mapping from constant name (as a Symbol) to its 32‐bit hexadecimal value
+    FORMATS = {
+      # Public file formats
+      kXMP_PDFFile: 0x50444620,
+      kXMP_PostScriptFile: 0x50532020,
+      kXMP_EPSFile: 0x45505320,
+      kXMP_JPEGFile: 0x4A504547,
+      kXMP_JPEG2KFile: 0x4A505820,
+      kXMP_TIFFFile: 0x54494646,
+      kXMP_GIFFile: 0x47494620,
+      kXMP_PNGFile: 0x504E4720,
+      kXMP_SWFFile: 0x53574620,
+      kXMP_FLAFile: 0x464C4120,
+      kXMP_FLVFile: 0x464C5620,
+      kXMP_MOVFile: 0x4D4F5620,
+      kXMP_AVIFile: 0x41564920,
+      kXMP_CINFile: 0x43494E20,
+      kXMP_WAVFile: 0x57415620,
+      kXMP_MP3File: 0x4D503320,
+      kXMP_SESFile: 0x53455320,
+      kXMP_CELFile: 0x43454C20,
+      kXMP_MPEGFile: 0x4D504547,
+      kXMP_MPEG2File: 0x4D503220,
+      kXMP_MPEG4File: 0x4D503420,
+      kXMP_MXFFile: 0x4D584620,
+      kXMP_WMAVFile: 0x574D4156,
+      kXMP_AIFFFile: 0x41494646,
+      kXMP_REDFile: 0x52454420,
+      kXMP_ARRIFile: 0x41525249,
+      kXMP_HEIFFile: 0x48454946,
+      kXMP_P2File: 0x50322020,
+      kXMP_XDCAM_FAMFile: 0x58444346,
+      kXMP_XDCAM_SAMFile: 0x58444353,
+      kXMP_XDCAM_EXFile: 0x58444358,
+      kXMP_AVCHDFile: 0x41564844,
+      kXMP_SonyHDVFile: 0x53484456,
+      kXMP_CanonXFFile: 0x434E5846,
+      kXMP_AVCUltraFile: 0x41564355,
+      kXMP_HTMLFile: 0x48544D4C,
+      kXMP_XMLFile: 0x584D4C20,
+      kXMP_TextFile: 0x74657874,
+      kXMP_SVGFile: 0x53564720,
+
+      # Adobe application file formats
+      kXMP_PhotoshopFile: 0x50534420,
+      kXMP_IllustratorFile: 0x41492020,
+      kXMP_InDesignFile: 0x494E4444,
+      kXMP_AEProjectFile: 0x41455020,
+      kXMP_AEProjTemplateFile: 0x41455420,
+      kXMP_AEFilterPresetFile: 0x46465820,
+      kXMP_EncoreProjectFile: 0x4E434F52,
+      kXMP_PremiereProjectFile: 0x5052504A,
+      kXMP_PremiereTitleFile: 0x5052544C,
+      kXMP_UCFFile: 0x55434620,
+
+      # Others
+      kXMP_UnknownFile: 0x20202020
+    }.freeze
+
+    # Inverted mapping from hex value to constant name (Symbol)
+    FORMATS_BY_VALUE = FORMATS.invert.freeze
+
+    class << self
+      # Retrieve the hex value for a given constant name (Symbol or String).
+      #
+      # Example:
+      #   XMPFileFormat.value_for(:kXMP_JPEGFile)  # => 0x4A504547
+      #   XMPFileFormat.value_for("kXMP_PNGFile")  # => 0x504E4720
+      def value_for(name)
+        key = name.is_a?(String) ? name.to_sym : name
+        FORMATS[key]
+      end
+
+      # Retrieve the constant name (Symbol) for a given hex value (Integer).
+      #
+      # Example:
+      #   XMPFileFormat.name_for(0x4D4F5620)  # => :kXMP_MOVFile
+      def name_for(hex_value)
+        FORMATS_BY_VALUE[hex_value]
+      end
+    end
+  end
+end

data/lib/xmp_toolkit_ruby/xmp_file_handler_flags.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module XmpToolkitRuby
+  module XmpFileHandlerFlags
+    # The keys here are Ruby-style snake_case equivalents of the handler flag constants
+    # defined in Adobe's XMP Toolkit SDK (see XMP_Const.h, e.g. kXMPFiles_CanInjectXMP, etc).
+    # For details on what each flag means, refer to the SDK's C++ header documentation.
+    FLAGS = {
+      can_inject_xmp: 0x0000_0001, # kXMPFiles_CanInjectXMP
+      can_expand: 0x0000_0002, # kXMPFiles_CanExpand
+      can_rewrite: 0x0000_0004, # kXMPFiles_CanRewrite
+      prefers_in_place: 0x0000_0008, # kXMPFiles_PrefersInPlace
+      can_reconcile: 0x0000_0010, # kXMPFiles_CanReconcile
+      allows_only_xmp: 0x0000_0020, # kXMPFiles_AllowsOnlyXMP
+      returns_raw_packet: 0x0000_0040, # kXMPFiles_ReturnsRawPacket
+      handler_owns_file: 0x0000_0100, # kXMPFiles_HandlerOwnsFile
+      allows_safe_update: 0x0000_0200, # kXMPFiles_AllowsSafeUpdate
+      needs_read_only_packet: 0x0000_0400, # kXMPFiles_NeedsReadOnlyPacket
+      uses_sidecar_xmp: 0x0000_0800, # kXMPFiles_UsesSidecarXMP
+      folder_based_format: 0x0000_1000, # kXMPFiles_FolderBasedFormat
+      can_notify_progress: 0x0000_2000, # kXMPFiles_CanNotifyProgress
+      needs_preloading: 0x0000_4000, # kXMPFiles_NeedsPreloading
+      needs_local_file_opened: 0x0001_0000 # kXMPFiles_NeedsLocalFileOpened
+    }.freeze
+
+    FLAGS_BY_VALUE = FLAGS.invert.freeze
+
+    class << self
+      # Retrieve the hex value for a given flag name (Symbol or String).
+      # Example: XmpFileHandlerFlags.value_for(:can_inject_xmp) #=> 0x00000001
+      def value_for(name)
+        key = name.is_a?(String) ? name.to_sym : name
+        FLAGS[key]
+      end
+
+      # Retrieve the flag name (Symbol) for a given hex value (Integer).
+      # Example: XmpFileHandlerFlags.name_for(0x00000008) #=> :prefers_in_place
+      def name_for(hex_value)
+        FLAGS_BY_VALUE[hex_value]
+      end
+
+      # Given a bitmask, return an array of all flag names that are set.
+      # Example: XmpFileHandlerFlags.flags_for(0x00000005) #=> [:can_inject_xmp, :can_rewrite]
+      def flags_for(bitmask)
+        FLAGS.select { |_, bit| bitmask.anybits?(bit) }.keys
+      end
+    end
+  end
+end

data/lib/xmp_toolkit_ruby.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require_relative "xmp_toolkit_ruby/version"
+require_relative "xmp_toolkit_ruby/xmp_toolkit_ruby"
+
+require "nokogiri"
+require "rbconfig"
+
+# The `XmpToolkitRuby` module serves as a Ruby interface to Adobe's XMP Toolkit,
+# a native C++ library. This module allows Ruby applications to read and write
+# XMP (Extensible Metadata Platform) metadata from and to various file formats.
+#
+# It handles the initialization and termination of the underlying C++ toolkit,
+# manages paths to necessary plugins (like PDF handlers), processes and cleans
+# XMP XML data, and provides a user-friendly API for XMP operations.
+#
+# Key functionalities include:
+# * Reading XMP metadata from files.
+# * Writing XMP metadata to files, with options to override or update existing data.
+# * Automatic management of the XMP Toolkit's lifecycle.
+# * Platform-aware resolution of plugin paths, with environment variable override.
+# * Parsing and cleaning of XMP packet data.
+# * Mapping of numerical handler flags to descriptive representations.
+#
+# @example Reading XMP from a file
+#   metadata = XmpToolkitRuby.xmp_from_file("path/to/image.jpg")
+#   puts metadata["xmp_data"] # Access the cleaned XMP XML string
+#
+# @example Writing XMP to a file
+#   new_xmp_data = "<x:xmpmeta xmlns:x='adobe:ns:meta/'><rdf:RDF xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#'></rdf:RDF></x:xmpmeta>"
+#   XmpToolkitRuby.xmp_to_file("path/to/image.jpg", new_xmp_data, override: true)
+#
+module XmpToolkitRuby
+  require_relative "xmp_toolkit_ruby/xmp_file_format"
+  require_relative "xmp_toolkit_ruby/namespaces"
+  require_relative "xmp_toolkit_ruby/xmp_file_handler_flags"
+
+  # The `PLUGINS_PATH` constant defines the directory where the XMP Toolkit
+  # should look for its plugins, particularly the PDF handler.
+  # The path is determined based on the current operating system (macOS or Linux)
+  # and system architecture.
+  #
+  # This path can be overridden by setting the `XMP_TOOLKIT_PLUGINS_PATH`
+  # environment variable, which takes precedence if set and not empty.
+  #
+  # If the platform or architecture is unsupported, a warning will be issued,
+  # and the path may be empty, potentially affecting PDF handling capabilities.
+  #
+  # @return [String] The absolute path to the plugins directory.
+  PLUGINS_PATH = if ENV["XMP_TOOLKIT_PLUGINS_PATH"] && !ENV["XMP_TOOLKIT_PLUGINS_PATH"].empty?
+                   ENV["XMP_TOOLKIT_PLUGINS_PATH"]
+                 else
+                   case RUBY_PLATFORM
+                   when /darwin/ # macOS
+                     File.expand_path("./xmp_toolkit_ruby/plugins/PDF_Handler/macintosh/universal/", __dir__)
+                   when /linux/
+                     if RbConfig::CONFIG["host_cpu"] =~ /x86_64|amd64/
+                       File.expand_path("./xmp_toolkit_ruby/plugins/PDF_Handler/i80386linux/i80386linux_x64/", __dir__)
+                     elsif RbConfig::CONFIG["host_cpu"] =~ /i[3-6]86/ # Matches i386, i486, i586, i686
+                       File.expand_path("./xmp_toolkit_ruby/plugins/PDF_Handler/i80386linux/i80386linux/", __dir__)
+                     else
+                       warn "Unsupported Linux architecture for PLUGINS_PATH: #{RbConfig::CONFIG["host_cpu"]}. PDF Handler might not work."
+                       "" # Or some other default
+                     end
+                   else
+                     # Fallback or error for unsupported platforms
+                     warn "Unsupported platform for PLUGINS_PATH: #{RUBY_PLATFORM}. PDF Handler might not work."
+                     "" # Or some other default that makes sense for your application
+                   end
+                 end
+
+  class Error < StandardError; end
+
+  class FileNotFoundError < Error; end
+
+  class << self
+    # Reads XMP metadata from a specified file.
+    #
+    # This method first checks if the file exists and is readable. It then
+    # initializes the XMP Toolkit, reads the XMP data using the native extension,
+    # cleans up the extracted XML, maps handler flags to a descriptive format,
+    # and ensures the toolkit is terminated.
+    #
+    # @param file_path [String] The absolute or relative path to the target file.
+    # @return [Hash] A hash containing the XMP metadata.
+    #   The hash includes:
+    #   - `"begin"`: The value of the `begin` attribute from the `xpacket` processing instruction.
+    #   - `"packet_id"`: The value of the `id` attribute from the `xpacket` processing instruction.
+    #   - `"xmp_data"`: The cleaned XMP XML string (core XMP metadata).
+    #   - `"xmp_data_orig"`: The original, raw XMP data string as returned by the toolkit.
+    #   - `"handler_flags"`: A descriptive representation of the handler flags (e.g., from {XmpFileHandlerFlags}).
+    #   - `"handler_flags_orig"`: The original numerical handler flags from the toolkit.
+    #   Returns an empty hash merged with cleanup and flag mapping results if the native call returns nil.
+    # @raise [FileNotFoundError] If the file does not exist, is not readable, or `file_path` is nil.
+    def xmp_from_file(file_path)
+      check_file! file_path, need_to_read: true, need_to_write: false
+
+      with_init do
+        result = XmpToolkitRuby::XmpToolkit.read_xmp(file_path)
+        result ||= {}
+        result.merge(cleanup_xmp(result["xmp_data"])).merge(map_handler_flags(result["handler_flags"]))
+      end
+    end
+
+    # Writes XMP metadata to a specified file.
+    #
+    # This method checks if the file exists, is readable, and is writable.
+    # It then initializes the XMP Toolkit, writes the provided XMP data
+    # (either as a Hash or an XML String) to the file using the native extension,
+    # and ensures the toolkit is terminated.
+    #
+    # The `override` parameter controls how existing XMP data in the file is handled:
+    # - If `true` (`:override`), existing XMP metadata is completely replaced.
+    # - If `false` (`:upsert`), the new XMP data is merged with existing metadata;
+    #   new properties are added, and existing ones may be updated.
+    #
+    # @param file_path [String] The absolute or relative path to the target file.
+    # @param xmp_data [String] The XMP metadata to write.
+    #   (which will be converted to XML by the native toolkit) or a pre-formatted XML String.
+    # @param override [Boolean] (false) If `true`, existing XMP metadata in the
+    #   file will be replaced. If `false`, the new data will be upserted (merged).
+    # @raise [FileNotFoundError] If the file does not exist, is not readable/writable, or `file_path` is nil.
+    def xmp_to_file(file_path, xmp_data, override: false)
+      check_file! file_path, need_to_read: true, need_to_write: true
+
+      with_init { XmpToolkitRuby::XmpToolkit.write_xmp(file_path, xmp_data, override ? :override : :upsert) }
+    end
+
+    # Ensures the native XMP Toolkit is initialized before executing a block
+    # of code and terminated afterwards. This is crucial for managing the
+    # lifecycle of the underlying C++ library resources.
+    #
+    # This method should wrap any calls to the native `XmpToolkitRuby::XmpToolkit` methods.
+    #
+    # @yield The block of code to execute while the XMP Toolkit is initialized.
+    # @return The result of the yielded block.
+    def with_init(&block)
+      XmpToolkitRuby::XmpToolkit.initialize_xmp
+      block.call
+    ensure
+      XmpToolkitRuby::XmpToolkit.terminate
+    end
+
+    private
+
+    # Parses raw XMP data string to extract `xpacket` processing instruction
+    # attributes and the core XMP XML content.
+    #
+    # The `xpacket` processing instruction contains metadata about the XMP packet itself.
+    # This method isolates these attributes and provides the main XMP XML structure
+    # without these processing instructions.
+    #
+    # @param xmp_data [String, nil] The raw XMP data string, which may include
+    #   `<?xpacket ...?>` processing instructions.
+    # @return [Hash] A hash containing extracted information:
+    #   - `"begin"`: The value of the `begin` attribute from the `xpacket` PI.
+    #   - `"packet_id"`: The value of the `id` attribute from the `xpacket` PI.
+    #   - `"xmp_data"`: The XMP XML content as a string, with `xpacket` PIs removed.
+    #   - `"xmp_data_orig"`: The original, unmodified `xmp_data` string.
+    #   Returns an empty hash if `xmp_data` is nil or empty.
+    # @api private
+    # rubocop: disable Metrics/AbcSize
+    def cleanup_xmp(xmp_data)
+      return {} if xmp_data.nil? || xmp_data.empty?
+
+      doc = Nokogiri::XML(xmp_data)
+      pis = doc.xpath("//processing-instruction('xpacket')")
+
+      begin_pi = pis.find { |pi| pi.content =~ /\Abegin=/ }
+
+      begin_attrs = begin_pi.content.scan(/(\w+)="([^"]*)"/).to_h
+      begin_value = begin_attrs["begin"]
+      packet_id = begin_attrs["id"]
+
+      pis.remove
+      inner_xml = doc.root.to_xml
+
+      {
+        "begin" => begin_value,
+        "packet_id" => packet_id,
+        "xmp_data" => inner_xml,
+        "xmp_data_orig" => xmp_data
+      }
+    end
+
+    # Maps numerical handler flags from the XMP Toolkit to a more descriptive
+    # format, typically an Array of Symbols or Strings.
+    #
+    # This uses `XmpToolkitRuby::XmpFileHandlerFlags.flags_for` to perform the mapping.
+    #
+    # @param handler_flags [Integer, nil] The numerical handler flags returned by
+    #   the native XMP Toolkit.
+    # @return [Hash] A hash containing:
+    #   - `"handler_flags"`: The mapped, descriptive representation of the flags.
+    #   - `"handler_flags_orig"`: The original numerical `handler_flags`.
+    #   Returns an empty hash if `handler_flags` is nil.
+    # @api private
+    def map_handler_flags(handler_flags)
+      return {} if handler_flags.nil?
+
+      handler_flags_mapped = XmpToolkitRuby::XmpFileHandlerFlags.flags_for(handler_flags)
+
+      {
+        "handler_flags" => handler_flags_mapped,
+        "handler_flags_orig" => handler_flags
+      }
+    end
+
+    # rubocop: enable Metrics/AbcSize, Metrics/MethodLength
+
+    # Validates file accessibility before performing read or write operations.
+    #
+    # Checks for:
+    # - Nil file path.
+    # - File existence.
+    # - File readability (if `need_to_read` is true).
+    # - File writability (if `need_to_write` is true).
+    #
+    # @param file_path [String] The path to the file to check.
+    # @param need_to_read [Boolean] (true) Whether the file needs to be readable.
+    # @param need_to_write [Boolean] (false) Whether the file needs to be writable.
+    # @raise [FileNotFoundError] If any of the checks fail.
+    # @return [void]
+    # @api private
+    def check_file!(file_path, need_to_read: true, need_to_write: false)
+      if file_path.nil?
+        raise FileNotFoundError, "File path cannot be nil"
+      elsif !File.exist?(file_path)
+        raise FileNotFoundError, "File not found: #{file_path}"
+      elsif need_to_read && !File.readable?(file_path)
+        raise FileNotFoundError, "File exists but is not readable: #{file_path}"
+      elsif need_to_write && !File.writable?(file_path)
+        raise FileNotFoundError, "File exists but is not writable: #{file_path}"
+      end
+    end
+  end
+end

data/sig/xmp_toolkit_ruby.rbs

@@ -0,0 +1,4 @@
+module XmpToolkitRuby
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

data/tasks/changelog.rake

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+def cliff_installed?
+  system("which git-cliff > /dev/null 2>&1")
+end
+
+namespace :changelog do
+  desc "Generate unreleased section in CHANGELOG.md (requires git-cliff)"
+  task :update_unreleased do
+    unless cliff_installed?
+      puts "🚫 git-cliff is not installed!"
+      puts "👉 Install it here: https://git-cliff.org/docs/installation/"
+      exit 1
+    end
+
+    generated = `git cliff --unreleased`
+
+    changelog_path = "CHANGELOG.md"
+    changelog = File.read(changelog_path)
+
+    updated = changelog.sub(
+      /<!--.*generated\s+by\s+git-cliff\s+start\s+-->(.*?)<!--\s+generated\s+by\s+git-cliff\s+end\s+-->/m,
+      generated.strip
+    )
+
+    File.write(changelog_path, updated)
+    puts "✅ Replaced generated section in CHANGELOG.md"
+  end
+end