ruby_pptx 0.1.0

data/lib/ruby_pptx/opc/constants.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+# Generated by tools/generate_opc_constants.py from python-pptx. Do not edit by hand.
+
+module Pptx
+  module Opc
+    module CONTENT_TYPE
+      ASF = "video/x-ms-asf"
+      AVI = "video/avi"
+      BMP = "image/bmp"
+      DML_CHART = "application/vnd.openxmlformats-officedocument.drawingml.chart+xml"
+      DML_CHARTSHAPES = "application/vnd.openxmlformats-officedocument.drawingml.chartshapes+xml"
+      DML_DIAGRAM_COLORS = "application/vnd.openxmlformats-officedocument.drawingml.diagramColors+xml"
+      DML_DIAGRAM_DATA = "application/vnd.openxmlformats-officedocument.drawingml.diagramData+xml"
+      DML_DIAGRAM_DRAWING = "application/vnd.ms-office.drawingml.diagramDrawing+xml"
+      DML_DIAGRAM_LAYOUT = "application/vnd.openxmlformats-officedocument.drawingml.diagramLayout+xml"
+      DML_DIAGRAM_STYLE = "application/vnd.openxmlformats-officedocument.drawingml.diagramStyle+xml"
+      GIF = "image/gif"
+      INK = "application/inkml+xml"
+      JPEG = "image/jpeg"
+      MOV = "video/quicktime"
+      MP4 = "video/mp4"
+      MPG = "video/mpeg"
+      MS_PHOTO = "image/vnd.ms-photo"
+      MS_VIDEO = "video/msvideo"
+      OFC_CHART_COLORS = "application/vnd.ms-office.chartcolorstyle+xml"
+      OFC_CHART_EX = "application/vnd.ms-office.chartex+xml"
+      OFC_CHART_STYLE = "application/vnd.ms-office.chartstyle+xml"
+      OFC_CUSTOM_PROPERTIES = "application/vnd.openxmlformats-officedocument.custom-properties+xml"
+      OFC_CUSTOM_XML_PROPERTIES = "application/vnd.openxmlformats-officedocument.customXmlProperties+xml"
+      OFC_DRAWING = "application/vnd.openxmlformats-officedocument.drawing+xml"
+      OFC_EXTENDED_PROPERTIES = "application/vnd.openxmlformats-officedocument.extended-properties+xml"
+      OFC_OLE_OBJECT = "application/vnd.openxmlformats-officedocument.oleObject"
+      OFC_PACKAGE = "application/vnd.openxmlformats-officedocument.package"
+      OFC_THEME = "application/vnd.openxmlformats-officedocument.theme+xml"
+      OFC_THEME_OVERRIDE = "application/vnd.openxmlformats-officedocument.themeOverride+xml"
+      OFC_VML_DRAWING = "application/vnd.openxmlformats-officedocument.vmlDrawing"
+      OPC_CORE_PROPERTIES = "application/vnd.openxmlformats-package.core-properties+xml"
+      OPC_DIGITAL_SIGNATURE_CERTIFICATE = "application/vnd.openxmlformats-package.digital-signature-certificate"
+      OPC_DIGITAL_SIGNATURE_ORIGIN = "application/vnd.openxmlformats-package.digital-signature-origin"
+      OPC_DIGITAL_SIGNATURE_XMLSIGNATURE = "application/vnd.openxmlformats-package.digital-signature-xmlsignature+xml"
+      OPC_RELATIONSHIPS = "application/vnd.openxmlformats-package.relationships+xml"
+      PML_COMMENTS = "application/vnd.openxmlformats-officedocument.presentationml.comments+xml"
+      PML_COMMENT_AUTHORS = "application/vnd.openxmlformats-officedocument.presentationml.commentAuthors+xml"
+      PML_HANDOUT_MASTER = "application/vnd.openxmlformats-officedocument.presentationml.handoutMaster+xml"
+      PML_NOTES_MASTER = "application/vnd.openxmlformats-officedocument.presentationml.notesMaster+xml"
+      PML_NOTES_SLIDE = "application/vnd.openxmlformats-officedocument.presentationml.notesSlide+xml"
+      PML_PRESENTATION = "application/vnd.openxmlformats-officedocument.presentationml.presentation"
+      PML_PRESENTATION_MAIN = "application/vnd.openxmlformats-officedocument.presentationml.presentation.main+xml"
+      PML_PRES_MACRO_MAIN = "application/vnd.ms-powerpoint.presentation.macroEnabled.main+xml"
+      PML_PRES_PROPS = "application/vnd.openxmlformats-officedocument.presentationml.presProps+xml"
+      PML_PRINTER_SETTINGS = "application/vnd.openxmlformats-officedocument.presentationml.printerSettings"
+      PML_SLIDE = "application/vnd.openxmlformats-officedocument.presentationml.slide+xml"
+      PML_SLIDESHOW_MAIN = "application/vnd.openxmlformats-officedocument.presentationml.slideshow.main+xml"
+      PML_SLIDE_LAYOUT = "application/vnd.openxmlformats-officedocument.presentationml.slideLayout+xml"
+      PML_SLIDE_MASTER = "application/vnd.openxmlformats-officedocument.presentationml.slideMaster+xml"
+      PML_SLIDE_UPDATE_INFO = "application/vnd.openxmlformats-officedocument.presentationml.slideUpdateInfo+xml"
+      PML_TABLE_STYLES = "application/vnd.openxmlformats-officedocument.presentationml.tableStyles+xml"
+      PML_TAGS = "application/vnd.openxmlformats-officedocument.presentationml.tags+xml"
+      PML_TEMPLATE_MAIN = "application/vnd.openxmlformats-officedocument.presentationml.template.main+xml"
+      PML_VIEW_PROPS = "application/vnd.openxmlformats-officedocument.presentationml.viewProps+xml"
+      PNG = "image/png"
+      SML_CALC_CHAIN = "application/vnd.openxmlformats-officedocument.spreadsheetml.calcChain+xml"
+      SML_CHARTSHEET = "application/vnd.openxmlformats-officedocument.spreadsheetml.chartsheet+xml"
+      SML_COMMENTS = "application/vnd.openxmlformats-officedocument.spreadsheetml.comments+xml"
+      SML_CONNECTIONS = "application/vnd.openxmlformats-officedocument.spreadsheetml.connections+xml"
+      SML_CUSTOM_PROPERTY = "application/vnd.openxmlformats-officedocument.spreadsheetml.customProperty"
+      SML_DIALOGSHEET = "application/vnd.openxmlformats-officedocument.spreadsheetml.dialogsheet+xml"
+      SML_EXTERNAL_LINK = "application/vnd.openxmlformats-officedocument.spreadsheetml.externalLink+xml"
+      SML_PIVOT_CACHE_DEFINITION = "application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheDefinition+xml"
+      SML_PIVOT_CACHE_RECORDS = "application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheRecords+xml"
+      SML_PIVOT_TABLE = "application/vnd.openxmlformats-officedocument.spreadsheetml.pivotTable+xml"
+      SML_PRINTER_SETTINGS = "application/vnd.openxmlformats-officedocument.spreadsheetml.printerSettings"
+      SML_QUERY_TABLE = "application/vnd.openxmlformats-officedocument.spreadsheetml.queryTable+xml"
+      SML_REVISION_HEADERS = "application/vnd.openxmlformats-officedocument.spreadsheetml.revisionHeaders+xml"
+      SML_REVISION_LOG = "application/vnd.openxmlformats-officedocument.spreadsheetml.revisionLog+xml"
+      SML_SHARED_STRINGS = "application/vnd.openxmlformats-officedocument.spreadsheetml.sharedStrings+xml"
+      SML_SHEET = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+      SML_SHEET_MAIN = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"
+      SML_SHEET_METADATA = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheetMetadata+xml"
+      SML_STYLES = "application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml"
+      SML_TABLE = "application/vnd.openxmlformats-officedocument.spreadsheetml.table+xml"
+      SML_TABLE_SINGLE_CELLS = "application/vnd.openxmlformats-officedocument.spreadsheetml.tableSingleCells+xml"
+      SML_TEMPLATE_MAIN = "application/vnd.openxmlformats-officedocument.spreadsheetml.template.main+xml"
+      SML_USER_NAMES = "application/vnd.openxmlformats-officedocument.spreadsheetml.userNames+xml"
+      SML_VOLATILE_DEPENDENCIES = "application/vnd.openxmlformats-officedocument.spreadsheetml.volatileDependencies+xml"
+      SML_WORKSHEET = "application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"
+      SWF = "application/x-shockwave-flash"
+      TIFF = "image/tiff"
+      VIDEO = "video/unknown"
+      WML_COMMENTS = "application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml"
+      WML_DOCUMENT = "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+      WML_DOCUMENT_GLOSSARY = "application/vnd.openxmlformats-officedocument.wordprocessingml.document.glossary+xml"
+      WML_DOCUMENT_MAIN = "application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"
+      WML_ENDNOTES = "application/vnd.openxmlformats-officedocument.wordprocessingml.endnotes+xml"
+      WML_FONT_TABLE = "application/vnd.openxmlformats-officedocument.wordprocessingml.fontTable+xml"
+      WML_FOOTER = "application/vnd.openxmlformats-officedocument.wordprocessingml.footer+xml"
+      WML_FOOTNOTES = "application/vnd.openxmlformats-officedocument.wordprocessingml.footnotes+xml"
+      WML_HEADER = "application/vnd.openxmlformats-officedocument.wordprocessingml.header+xml"
+      WML_NUMBERING = "application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml"
+      WML_PRINTER_SETTINGS = "application/vnd.openxmlformats-officedocument.wordprocessingml.printerSettings"
+      WML_SETTINGS = "application/vnd.openxmlformats-officedocument.wordprocessingml.settings+xml"
+      WML_STYLES = "application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml"
+      WML_WEB_SETTINGS = "application/vnd.openxmlformats-officedocument.wordprocessingml.webSettings+xml"
+      WMV = "video/x-ms-wmv"
+      XML = "application/xml"
+      X_EMF = "image/x-emf"
+      X_FONTDATA = "application/x-fontdata"
+      X_FONT_TTF = "application/x-font-ttf"
+      X_MS_VIDEO = "video/x-msvideo"
+      X_WMF = "image/x-wmf"
+    end
+
+    module NAMESPACE
+      DML_WORDPROCESSING_DRAWING = "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing"
+      OFC_RELATIONSHIPS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+      OPC_CONTENT_TYPES = "http://schemas.openxmlformats.org/package/2006/content-types"
+      OPC_RELATIONSHIPS = "http://schemas.openxmlformats.org/package/2006/relationships"
+      WML_MAIN = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+    end
+
+    module RELATIONSHIP_TARGET_MODE
+      EXTERNAL = "External"
+      INTERNAL = "Internal"
+    end
+
+    module RELATIONSHIP_TYPE
+      AUDIO = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/audio"
+      A_F_CHUNK = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/aFChunk"
+      CALC_CHAIN = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/calcChain"
+      CERTIFICATE = "http://schemas.openxmlformats.org/package/2006/relationships/digital-signature/certificate"
+      CHART = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/chart"
+      CHARTSHEET = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/chartsheet"
+      CHART_COLOR_STYLE = "http://schemas.microsoft.com/office/2011/relationships/chartColorStyle"
+      CHART_USER_SHAPES = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/chartUserShapes"
+      COMMENTS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments"
+      COMMENT_AUTHORS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/commentAuthors"
+      CONNECTIONS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/connections"
+      CONTROL = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/control"
+      CORE_PROPERTIES = "http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties"
+      CUSTOM_PROPERTIES = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/custom-properties"
+      CUSTOM_PROPERTY = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/customProperty"
+      CUSTOM_XML = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/customXml"
+      CUSTOM_XML_PROPS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/customXmlProps"
+      DIAGRAM_COLORS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/diagramColors"
+      DIAGRAM_DATA = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/diagramData"
+      DIAGRAM_LAYOUT = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/diagramLayout"
+      DIAGRAM_QUICK_STYLE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/diagramQuickStyle"
+      DIALOGSHEET = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/dialogsheet"
+      DRAWING = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/drawing"
+      ENDNOTES = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/endnotes"
+      EXTENDED_PROPERTIES = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/extended-properties"
+      EXTERNAL_LINK = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/externalLink"
+      FONT = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/font"
+      FONT_TABLE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/fontTable"
+      FOOTER = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer"
+      FOOTNOTES = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footnotes"
+      GLOSSARY_DOCUMENT = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/glossaryDocument"
+      HANDOUT_MASTER = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/handoutMaster"
+      HEADER = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/header"
+      HYPERLINK = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink"
+      IMAGE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image"
+      MEDIA = "http://schemas.microsoft.com/office/2007/relationships/media"
+      NOTES_MASTER = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/notesMaster"
+      NOTES_SLIDE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/notesSlide"
+      NUMBERING = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering"
+      OFFICE_DOCUMENT = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument"
+      OLE_OBJECT = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/oleObject"
+      ORIGIN = "http://schemas.openxmlformats.org/package/2006/relationships/digital-signature/origin"
+      PACKAGE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/package"
+      PIVOT_CACHE_DEFINITION = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/pivotCacheDefinition"
+      PIVOT_CACHE_RECORDS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/spreadsheetml/pivotCacheRecords"
+      PIVOT_TABLE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/pivotTable"
+      PRES_PROPS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/presProps"
+      PRINTER_SETTINGS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/printerSettings"
+      QUERY_TABLE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/queryTable"
+      REVISION_HEADERS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/revisionHeaders"
+      REVISION_LOG = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/revisionLog"
+      SETTINGS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings"
+      SHARED_STRINGS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/sharedStrings"
+      SHEET_METADATA = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/sheetMetadata"
+      SIGNATURE = "http://schemas.openxmlformats.org/package/2006/relationships/digital-signature/signature"
+      SLIDE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide"
+      SLIDE_LAYOUT = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideLayout"
+      SLIDE_MASTER = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideMaster"
+      SLIDE_UPDATE_INFO = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideUpdateInfo"
+      STYLES = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles"
+      TABLE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/table"
+      TABLE_SINGLE_CELLS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/tableSingleCells"
+      TABLE_STYLES = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/tableStyles"
+      TAGS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/tags"
+      THEME = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme"
+      THEME_OVERRIDE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/themeOverride"
+      THUMBNAIL = "http://schemas.openxmlformats.org/package/2006/relationships/metadata/thumbnail"
+      USERNAMES = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/usernames"
+      VIDEO = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/video"
+      VIEW_PROPS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/viewProps"
+      VML_DRAWING = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/vmlDrawing"
+      VOLATILE_DEPENDENCIES = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/volatileDependencies"
+      WEB_SETTINGS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/webSettings"
+      WORKSHEET_SOURCE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheetSource"
+      XML_MAPS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/xmlMaps"
+    end
+  end
+end

data/lib/ruby_pptx/opc/oxml.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/oxml/element"
+require "ruby_pptx/oxml/content_model"
+require "ruby_pptx/oxml/simple_types"
+require "ruby_pptx/opc/constants"
+
+module Pptx
+  module Opc
+    # Element classes for the two XML formats the packaging layer owns:
+    # `[Content_Types].xml` and the `.rels` items.
+    module Oxml
+      ST = Pptx::Oxml::SimpleTypes
+      Element = Pptx::Oxml::Element
+
+      # Serialize a part's root element as the bytes of a `.xml` file,
+      # including the XML declaration Office expects.
+      #
+      # The declaration is written with single quotes and `standalone="yes"`
+      # to match what python-pptx (and lxml) produce, so packages compare
+      # byte-for-byte.
+      def self.serialize_part_xml(element)
+        node = element.is_a?(Element) ? element.node : element
+        body = node.to_xml(save_with: Nokogiri::XML::Node::SaveOptions::AS_XML |
+                                      Nokogiri::XML::Node::SaveOptions::NO_DECLARATION)
+        %(<?xml version='1.0' encoding='UTF-8' standalone='yes'?>\n#{body})
+      end
+
+      # `<Default>`: the content type for every part with a given extension.
+      class CT_Default < Element
+        tag "ct:Default"
+        required_attr "Extension", type: ST::ST_Extension, as: :extension
+        required_attr "ContentType", type: ST::ST_ContentType, as: :contentType
+      end
+
+      # `<Override>`: the content type for one specific part.
+      class CT_Override < Element
+        tag "ct:Override"
+        required_attr "PartName", type: ST::XsdAnyUri, as: :partName
+        required_attr "ContentType", type: ST::ST_ContentType, as: :contentType
+      end
+
+      # `<Types>`, the root of `[Content_Types].xml`.
+      class CT_Types < Element
+        tag "ct:Types"
+        zero_or_more "ct:Default", as: :default
+        zero_or_more "ct:Override", as: :override
+
+        def self.new_element
+          Element.parse(%(<Types xmlns="#{NAMESPACE::OPC_CONTENT_TYPES}"/>))
+        end
+
+        # Named `*_for` rather than `add_default` / `add_override`: those names
+        # belong to the accessors the content-model macros generate.
+        def add_default_for(ext, content_type)
+          add_default(extension: ext, contentType: content_type)
+        end
+
+        def add_override_for(partname, content_type)
+          add_override(partName: partname.to_s, contentType: content_type)
+        end
+      end
+
+      # `<Relationship>`: one link from a part (or the package) to a target.
+      class CT_Relationship < Element
+        tag "pr:Relationship"
+        required_attr "Id", type: ST::XsdId, as: :rId
+        required_attr "Type", type: ST::XsdAnyUri, as: :reltype
+        required_attr "Target", type: ST::XsdAnyUri, as: :target_ref
+        optional_attr "TargetMode", type: ST::ST_TargetMode,
+                                    default: RELATIONSHIP_TARGET_MODE::INTERNAL, as: :targetMode
+
+        def external? = targetMode == RELATIONSHIP_TARGET_MODE::EXTERNAL
+      end
+
+      # `<Relationships>`, the root of a `.rels` item.
+      class CT_Relationships < Element
+        tag "pr:Relationships"
+        zero_or_more "pr:Relationship", as: :relationship
+
+        def self.new_element
+          Element.parse(%(<Relationships xmlns="#{NAMESPACE::OPC_RELATIONSHIPS}"/>))
+        end
+
+        def add_rel(r_id, reltype, target, is_external: false)
+          target_mode = if is_external
+                          RELATIONSHIP_TARGET_MODE::EXTERNAL
+                        else
+                          RELATIONSHIP_TARGET_MODE::INTERNAL
+                        end
+          add_relationship(rId: r_id, reltype: reltype, target_ref: target, targetMode: target_mode)
+        end
+
+        # Bytes for a `.rels` item, with the XML declaration.
+        def xml_file_bytes = Oxml.serialize_part_xml(self)
+      end
+    end
+  end
+end

data/lib/ruby_pptx/opc/pack_uri.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Pptx
+  module Opc
+    # An absolute part name within an OPC package, e.g. "/ppt/slides/slide1.xml".
+    #
+    # Part names are always rooted at "/" and are *not* filesystem paths: they
+    # are normalised purely lexically, with no reference to the working
+    # directory or to `~`. The package itself has the pseudo part name "/".
+    class PackURI
+      include Comparable
+
+      # Splits a filename stem into its name and optional trailing index, e.g.
+      # "slide21" => ["slide", "21"].
+      FILENAME_RE = /\A([a-zA-Z]+)([0-9]+)?/
+
+      # Resolve +relative_ref+ (as found in a .rels part) against +base_uri+.
+      #
+      #   PackURI.from_rel_ref("/ppt", "slides/slide1.xml") #=> "/ppt/slides/slide1.xml"
+      #   PackURI.from_rel_ref("/ppt/slides", "../media/image1.png") #=> "/ppt/media/image1.png"
+      def self.from_rel_ref(base_uri, relative_ref)
+        new(normalize(join(base_uri, relative_ref)))
+      end
+
+      # Lexically join path segments with "/", ignoring a leading "/" on later
+      # segments the way posixpath.join does not -- we only ever join a base
+      # with a genuinely relative reference.
+      def self.join(*parts)
+        parts.reject { |p| p.nil? || p.empty? }
+             .each_with_index
+             .map { |p, i| i.zero? ? p.chomp("/") : p }
+             .join("/")
+      end
+      private_class_method :join
+
+      # Collapse "." and ".." segments. Leading ".." on an absolute path are
+      # dropped, matching posixpath.abspath.
+      def self.normalize(path)
+        absolute = path.start_with?("/")
+        segments = path.split("/").each_with_object([]) do |seg, acc|
+          case seg
+          when "", "." then next
+          when ".."
+            if acc.empty? || acc.last == ".."
+              acc.push(seg) unless absolute
+            else
+              acc.pop
+            end
+          else acc.push(seg)
+          end
+        end
+        absolute ? "/#{segments.join("/")}" : segments.join("/")
+      end
+      private_class_method :normalize
+
+      # @return [String] the full part name, e.g. "/ppt/slides/slide1.xml"
+      attr_reader :to_s
+
+      def initialize(pack_uri_str)
+        pack_uri_str = pack_uri_str.to_s
+        unless pack_uri_str.start_with?("/")
+          raise ArgumentError, "PackURI must begin with a slash, got #{pack_uri_str.inspect}"
+        end
+
+        @to_s = pack_uri_str.freeze
+        freeze
+      end
+
+      # The directory portion, e.g. "/ppt/slides" for "/ppt/slides/slide1.xml".
+      # The package pseudo part name "/" has itself as its base URI.
+      def base_uri
+        idx = @to_s.rindex("/")
+        idx.zero? ? "/" : @to_s[0...idx]
+      end
+
+      # The extension without its leading period, e.g. "xml". Empty when there
+      # is none.
+      def ext
+        File.extname(filename).delete_prefix(".")
+      end
+
+      # The last segment, e.g. "slide1.xml". Empty for the package itself.
+      def filename
+        @to_s[(@to_s.rindex("/") + 1)..]
+      end
+
+      # The integer suffix of an "array" part name, e.g. 21 for
+      # "/ppt/slides/slide21.xml"; nil for a singleton such as
+      # "/ppt/presentation.xml".
+      #
+      # @return [Integer, nil]
+      def idx
+        stem = File.basename(filename, ".*")
+        return nil if stem.empty?
+
+        match = FILENAME_RE.match(stem)
+        match && match[2] && Integer(match[2], 10)
+      end
+
+      # The part name without its leading slash -- the form used as the Zip
+      # entry name.
+      def member_name = @to_s[1..]
+
+      # A reference to this part relative to +base_uri+, as written into a
+      # .rels part.
+      #
+      #   PackURI.new("/ppt/slideLayouts/slideLayout1.xml").relative_ref("/ppt/slides")
+      #   #=> "../slideLayouts/slideLayout1.xml"
+      def relative_ref(base_uri)
+        return member_name if base_uri == "/"
+
+        from = base_uri.split("/").reject(&:empty?)
+        to   = @to_s.split("/").reject(&:empty?)
+        common = 0
+        common += 1 while common < from.length && common < to.length && from[common] == to[common]
+        (([".."] * (from.length - common)) + to[common..]).join("/")
+      end
+
+      # The part name of the .rels part describing this part's relationships.
+      #
+      #   PackURI.new("/ppt/presentation.xml").rels_uri #=> "/ppt/_rels/presentation.xml.rels"
+      def rels_uri
+        PackURI.new(self.class.send(:join, base_uri, "_rels", "#{filename}.rels"))
+      end
+
+      def <=>(other)
+        other = PackURI.new(other) if other.is_a?(String)
+        return nil unless other.is_a?(PackURI)
+
+        @to_s <=> other.to_s
+      end
+
+      def ==(other) = (self <=> other)&.zero? || false
+      alias eql? ==
+
+      def hash = @to_s.hash
+
+      def to_str = @to_s
+
+      def inspect = "#<Pptx::Opc::PackURI #{@to_s.inspect}>"
+
+      PACKAGE       = new("/")
+      CONTENT_TYPES = new("/[Content_Types].xml")
+    end
+  end
+end