nitfr 1.0.0

data/lib/nitfr/docdata.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "date"
+
+module NITFr
+  # Represents the docdata section of an NITF document head
+  #
+  # Docdata contains document metadata including IDs, dates,
+  # urgency, and other management information.
+  class Docdata
+    attr_reader :node
+
+    def initialize(node)
+      @node = node
+    end
+
+    # Get the document ID
+    #
+    # @return [String, nil] the doc-id value
+    def doc_id
+      @doc_id ||= xpath_first("doc-id")&.attributes&.[]("id-string")
+    end
+
+    # Get the issue date
+    #
+    # @return [Date, nil] the parsed issue date
+    def issue_date
+      @issue_date ||= parse_date("date.issue")
+    end
+
+    # Get the release date
+    #
+    # @return [Date, nil] the parsed release date
+    def release_date
+      @release_date ||= parse_date("date.release")
+    end
+
+    # Get the expiration date
+    #
+    # @return [Date, nil] the parsed expire date
+    def expire_date
+      @expire_date ||= parse_date("date.expire")
+    end
+
+    # Get urgency level (1-8, 1 being most urgent)
+    #
+    # @return [Integer, nil] the urgency value
+    def urgency
+      @urgency ||= xpath_first("urgency")&.attributes&.[]("ed-urg")&.to_i
+    end
+
+    # Get the document copyright information
+    #
+    # @return [Hash] copyright details
+    def copyright
+      @copyright ||= parse_copyright
+    end
+
+    # Get the copyright holder
+    #
+    # @return [String, nil] the copyright holder
+    def copyright_holder
+      copyright[:holder]
+    end
+
+    # Get the copyright year
+    #
+    # @return [String, nil] the copyright year
+    def copyright_year
+      copyright[:year]
+    end
+
+    # Get document scope information
+    #
+    # @return [String, nil] the doc-scope
+    def doc_scope
+      @doc_scope ||= xpath_first("doc-scope")&.attributes&.[]("scope")
+    end
+
+    # Get series information
+    #
+    # @return [Hash] series details
+    def series
+      @series ||= parse_series
+    end
+
+    # Get editorial status/management info
+    #
+    # @return [Hash] management status
+    def management_status
+      @management_status ||= parse_management_status
+    end
+
+    # Get the fixture identifier
+    #
+    # @return [String, nil] the fixture value
+    def fixture
+      @fixture ||= xpath_first("fixture")&.attributes&.[]("fix-id")
+    end
+
+    # Get all identified content (subjects, organizations, people, etc.)
+    #
+    # @return [Hash] categorized identified content
+    def identified_content
+      @identified_content ||= parse_identified_content
+    end
+
+    # Get subject codes/topics
+    #
+    # @return [Array<String>] array of subjects
+    def subjects
+      identified_content[:subjects] || []
+    end
+
+    # Get location codes
+    #
+    # @return [Array<String>] array of locations
+    def locations
+      identified_content[:locations] || []
+    end
+
+    # Get organization codes
+    #
+    # @return [Array<String>] array of organizations
+    def organizations
+      identified_content[:organizations] || []
+    end
+
+    # Get person codes
+    #
+    # @return [Array<String>] array of people
+    def people
+      identified_content[:people] || []
+    end
+
+    private
+
+    def xpath_first(path)
+      REXML::XPath.first(node, path)
+    end
+
+    def xpath_match(path)
+      REXML::XPath.match(node, path)
+    end
+
+    def parse_date(element_name)
+      date_node = xpath_first(element_name)
+      return nil unless date_node
+
+      norm = date_node.attributes["norm"]
+      return nil unless norm
+
+      Date.parse(norm)
+    rescue Date::Error
+      nil
+    end
+
+    def parse_copyright
+      copyright_node = xpath_first("doc.copyright")
+      return {} unless copyright_node
+
+      {
+        holder: copyright_node.attributes["holder"],
+        year: copyright_node.attributes["year"]
+      }.compact
+    end
+
+    def parse_series
+      series_node = xpath_first("series")
+      return {} unless series_node
+
+      {
+        name: series_node.attributes["series.name"],
+        part: series_node.attributes["series.part"]&.to_i,
+        total: series_node.attributes["series.totalpart"]&.to_i
+      }.compact
+    end
+
+    def parse_management_status
+      status_node = xpath_first("ed-msg")
+      return {} unless status_node
+
+      {
+        info: status_node.attributes["info"],
+        message_type: status_node.attributes["msg-type"]
+      }.compact
+    end
+
+    def parse_identified_content
+      id_node = xpath_first("identified-content")
+      return {} unless id_node
+
+      {
+        subjects: REXML::XPath.match(id_node, "classifier[@type='subject']").map { |c| c.text&.strip }.compact,
+        locations: REXML::XPath.match(id_node, "location").map { |l| l.text&.strip }.compact,
+        organizations: REXML::XPath.match(id_node, "org").map { |o| o.text&.strip }.compact,
+        people: REXML::XPath.match(id_node, "person").map { |p| p.text&.strip }.compact
+      }
+    end
+  end
+end

data/lib/nitfr/document.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module NITFr
+  # Represents a parsed NITF document
+  #
+  # The Document class is the main entry point for working with NITF content.
+  # It provides access to all parts of the NITF structure including head and body.
+  #
+  # @note This parser does not process external entities (DTD references) for security.
+  #   REXML by default does not expand external entities, which protects against XXE attacks.
+  class Document
+    attr_reader :xml_doc, :head, :body
+
+    # Create a new Document from an NITF XML string
+    #
+    # @param xml [String] the NITF XML content
+    # @raise [ParseError] if the XML is malformed
+    # @raise [InvalidDocumentError] if the document is not valid NITF
+    def initialize(xml)
+      @xml_doc = parse_xml(xml)
+      validate_nitf!
+      parse_content
+    end
+
+    # Get the document's title from the head section
+    #
+    # @return [String, nil] the document title
+    def title
+      head&.title
+    end
+
+    # Get the main headline text
+    #
+    # @return [String, nil] the primary headline
+    def headline
+      body&.headline&.primary
+    end
+
+    # Get all headline levels
+    #
+    # @return [Headline, nil] the headline object with all levels
+    def headlines
+      body&.headline
+    end
+
+    # Get the byline information
+    #
+    # @return [Byline, nil] the byline object
+    def byline
+      body&.byline
+    end
+
+    # Get all paragraphs from the body content
+    #
+    # @return [Array<Paragraph>] array of paragraph objects
+    def paragraphs
+      body&.paragraphs || []
+    end
+
+    # Get the full text content of the article
+    #
+    # @return [String] concatenated paragraph text
+    def text
+      @text ||= paragraphs.map(&:text).join("\n\n")
+    end
+
+    # Get all media objects (images, etc.) from the document
+    #
+    # @return [Array<Media>] array of media objects
+    def media
+      body&.media || []
+    end
+
+    # Get document metadata from docdata
+    #
+    # @return [Docdata, nil] the docdata object
+    def docdata
+      head&.docdata
+    end
+
+    # Get the document ID
+    #
+    # @return [String, nil] the document ID
+    def doc_id
+      docdata&.doc_id
+    end
+
+    # Get the issue date
+    #
+    # @return [Date, nil] the issue date
+    def issue_date
+      docdata&.issue_date
+    end
+
+    # Get the NITF version from the root element
+    #
+    # @return [String, nil] the NITF version
+    def version
+      nitf_root.attributes["version"]
+    end
+
+    # Get the change date from the root element
+    #
+    # @return [String, nil] the change date
+    def change_date
+      nitf_root.attributes["change.date"]
+    end
+
+    # Get the change time from the root element
+    #
+    # @return [String, nil] the change time
+    def change_time
+      nitf_root.attributes["change.time"]
+    end
+
+    # Check if this is a valid NITF document
+    #
+    # @return [Boolean] true if valid NITF
+    def valid?
+      !nitf_root.nil?
+    end
+
+    # Return raw XML string
+    #
+    # @return [String] the original XML
+    def to_xml
+      @xml_doc.to_s
+    end
+
+    private
+
+    # Parse XML string into REXML document
+    #
+    # REXML does not expand external entities by default, which protects against:
+    # - XXE (XML External Entity) attacks
+    # - Billion Laughs (entity expansion) attacks
+    #
+    # Security settings are configured at module load time in lib/nitfr.rb
+    #
+    # @param xml [String] the XML content
+    # @return [REXML::Document] the parsed document
+    def parse_xml(xml)
+      REXML::Document.new(xml)
+    rescue REXML::ParseException => e
+      raise ParseError, "Failed to parse XML: #{e.message}"
+    end
+
+    def validate_nitf!
+      return if nitf_root
+
+      raise InvalidDocumentError, "Document does not appear to be valid NITF (missing <nitf> root element)"
+    end
+
+    def nitf_root
+      @nitf_root ||= begin
+        # Use direct root access for better performance when nitf is the root element
+        root = @xml_doc.root
+        return root if root&.name == "nitf"
+
+        # Fall back to XPath search for nested nitf elements
+        REXML::XPath.first(@xml_doc, "//nitf")
+      end
+    end
+
+    def parse_content
+      head_node = REXML::XPath.first(nitf_root, "head")
+      body_node = REXML::XPath.first(nitf_root, "body")
+
+      @head = Head.new(head_node) if head_node
+      @body = Body.new(body_node) if body_node
+    end
+  end
+end

data/lib/nitfr/errors.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module NITFr
+  # Base error class for NITFr
+  class Error < StandardError; end
+
+  # Raised when XML parsing fails
+  class ParseError < Error; end
+
+  # Raised when the document is not valid NITF
+  class InvalidDocumentError < Error; end
+end

data/lib/nitfr/head.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module NITFr
+  # Represents the head section of an NITF document
+  #
+  # The head contains metadata about the document including title,
+  # document data, publication information, and revision history.
+  class Head
+    attr_reader :node
+
+    def initialize(node)
+      @node = node
+    end
+
+    # Get the document title
+    #
+    # @return [String, nil] the title text
+    def title
+      @title ||= xpath_first("title")&.text&.strip
+    end
+
+    # Get document metadata
+    #
+    # @return [Docdata, nil] the docdata object
+    def docdata
+      @docdata ||= begin
+        docdata_node = xpath_first("docdata")
+        Docdata.new(docdata_node) if docdata_node
+      end
+    end
+
+    # Get publication data
+    #
+    # @return [Hash] publication metadata
+    def pubdata
+      @pubdata ||= parse_pubdata
+    end
+
+    # Get revision history
+    #
+    # @return [Array<Hash>] array of revision entries
+    def revision_history
+      @revision_history ||= parse_revision_history
+    end
+
+    # Get metadata keywords
+    #
+    # @return [Array<String>] array of keywords
+    def keywords
+      @keywords ||= xpath_match("meta[@name='keywords']").map { |n| n.attributes["content"] }.compact
+    end
+
+    # Get all meta tags as a hash
+    #
+    # @return [Hash<String, String>] meta name => content pairs
+    def meta
+      @meta ||= xpath_match("meta").each_with_object({}) do |n, hash|
+        name = n.attributes["name"]
+        hash[name] = n.attributes["content"] if name
+      end
+    end
+
+    private
+
+    def xpath_first(path)
+      REXML::XPath.first(node, path)
+    end
+
+    def xpath_match(path)
+      REXML::XPath.match(node, path)
+    end
+
+    def parse_pubdata
+      pubdata_node = xpath_first("pubdata")
+      return {} unless pubdata_node
+
+      {
+        type: pubdata_node.attributes["type"],
+        date_publication: pubdata_node.attributes["date.publication"],
+        name: pubdata_node.attributes["name"],
+        issn: pubdata_node.attributes["issn"],
+        volume: pubdata_node.attributes["volume"],
+        number: pubdata_node.attributes["number"],
+        edition: pubdata_node.attributes["edition.name"],
+        position_section: pubdata_node.attributes["position.section"],
+        position_sequence: pubdata_node.attributes["position.sequence"]
+      }.compact
+    end
+
+    def parse_revision_history
+      xpath_match("revision-history").map do |rev|
+        {
+          comment: rev.attributes["comment"],
+          name: rev.attributes["name"],
+          function: rev.attributes["function"],
+          norm: rev.attributes["norm"]
+        }.compact
+      end
+    end
+  end
+end

data/lib/nitfr/headline.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module NITFr
+  # Represents headline information from an NITF document
+  #
+  # NITF supports multiple headline levels (hl1, hl2) as well as
+  # headline (alternate headline) elements.
+  class Headline
+    attr_reader :node
+
+    def initialize(node)
+      @node = node
+    end
+
+    # Get the primary headline (hl1)
+    #
+    # @return [String, nil] the main headline text
+    def primary
+      @primary ||= xpath_first("hl1")&.text&.strip
+    end
+    alias hl1 primary
+
+    # Get the secondary headline (hl2)
+    #
+    # @return [String, nil] the secondary headline text
+    def secondary
+      @secondary ||= xpath_first("hl2")&.text&.strip
+    end
+    alias hl2 secondary
+
+    # Get all headline levels as an array
+    #
+    # @return [Array<String>] array of headline texts in order
+    def all
+      @all ||= [primary, secondary].compact
+    end
+
+    # Get the full headline text (all levels joined)
+    #
+    # @return [String] combined headline text
+    def to_s
+      all.join(" - ")
+    end
+
+    # Check if headline exists
+    #
+    # @return [Boolean] true if any headline text exists
+    def present?
+      !primary.nil? || !secondary.nil?
+    end
+
+    private
+
+    def xpath_first(path)
+      REXML::XPath.first(node, path)
+    end
+  end
+end

data/lib/nitfr/media.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module NITFr
+  # Represents a media element from an NITF document
+  #
+  # Media elements can represent images, audio, video, or other
+  # multimedia content embedded in the article.
+  class Media
+    attr_reader :node
+
+    def initialize(node)
+      @node = node
+    end
+
+    # Get the media type (image, audio, video, etc.)
+    #
+    # @return [String, nil] the media type
+    def type
+      node.attributes["media-type"]
+    end
+
+    # Check if this is an image
+    #
+    # @return [Boolean] true if media type is image
+    def image?
+      type == "image"
+    end
+
+    # Check if this is audio
+    #
+    # @return [Boolean] true if media type is audio
+    def audio?
+      type == "audio"
+    end
+
+    # Check if this is video
+    #
+    # @return [Boolean] true if media type is video
+    def video?
+      type == "video"
+    end
+
+    # Get the caption text
+    #
+    # @return [String, nil] the caption
+    def caption
+      @caption ||= xpath_first("media-caption")&.text&.strip
+    end
+
+    # Get the producer/credit information
+    #
+    # @return [String, nil] the producer/credit
+    def producer
+      @producer ||= xpath_first("media-producer")&.text&.strip
+    end
+    alias credit producer
+
+    # Get all media references (different formats/sizes)
+    #
+    # @return [Array<Hash>] array of reference info
+    def references
+      @references ||= xpath_match("media-reference").map do |ref|
+        {
+          source: ref.attributes["source"],
+          mime_type: ref.attributes["mime-type"],
+          coding: ref.attributes["coding"],
+          width: ref.attributes["width"]&.to_i,
+          height: ref.attributes["height"]&.to_i,
+          alternate_text: ref.attributes["alternate-text"],
+          name: ref.attributes["name"]
+        }.compact
+      end
+    end
+
+    # Get the primary/first reference
+    #
+    # @return [Hash, nil] the first reference
+    def primary_reference
+      references.first
+    end
+
+    # Get the source URL of the primary reference
+    #
+    # @return [String, nil] the source URL
+    def source
+      primary_reference&.dig(:source)
+    end
+    alias src source
+    alias url source
+
+    # Get the mime type of the primary reference
+    #
+    # @return [String, nil] the mime type
+    def mime_type
+      primary_reference&.dig(:mime_type)
+    end
+
+    # Get the alternate text
+    #
+    # @return [String, nil] the alt text
+    def alt_text
+      primary_reference&.dig(:alternate_text)
+    end
+
+    # Get the width
+    #
+    # @return [Integer, nil] width in pixels
+    def width
+      primary_reference&.dig(:width)
+    end
+
+    # Get the height
+    #
+    # @return [Integer, nil] height in pixels
+    def height
+      primary_reference&.dig(:height)
+    end
+
+    # Get media metadata
+    #
+    # @return [Hash] additional metadata attributes
+    def metadata
+      @metadata ||= {
+        id: node.attributes["id"],
+        class: node.attributes["class"]
+      }.compact
+    end
+
+    private
+
+    def xpath_first(path)
+      REXML::XPath.first(node, path)
+    end
+
+    def xpath_match(path)
+      REXML::XPath.match(node, path)
+    end
+  end
+end