nitfr 1.0.0

data/lib/nitfr/paragraph.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module NITFr
+  # Represents a paragraph from an NITF document body
+  #
+  # Paragraphs can contain inline elements like emphasis,
+  # links, and other markup.
+  #
+  # Entity extraction (people, organizations, locations, emphasis) uses
+  # lazy batch extraction - a single DOM traversal populates all entity
+  # arrays on first access to any entity method.
+  class Paragraph
+    include TextExtractor
+
+    attr_reader :node
+
+    def initialize(node)
+      @node = node
+      @entities_extracted = false
+    end
+
+    # Get the plain text content of the paragraph
+    #
+    # @return [String] the paragraph text with inline elements stripped
+    def text
+      @text ||= extract_all_text(node).strip
+    end
+    alias to_s text
+
+    # Get the paragraph ID if present
+    #
+    # @return [String, nil] the paragraph ID
+    def id
+      node.attributes["id"]
+    end
+
+    # Get the paragraph's lede attribute (indicates lead paragraph)
+    #
+    # @return [String, nil] the lede value
+    def lede
+      node.attributes["lede"]
+    end
+
+    # Check if this is a lead paragraph
+    #
+    # @return [Boolean] true if marked as lead
+    def lead?
+      lede == "true" || lede == "yes"
+    end
+
+    # Get any emphasized text within the paragraph
+    #
+    # @return [Array<String>] array of emphasized text
+    def emphasis
+      extract_entities unless @entities_extracted
+      @emphasis
+    end
+
+    # Get any links within the paragraph
+    #
+    # @return [Array<Hash>] array of link info hashes
+    def links
+      extract_entities unless @entities_extracted
+      @links
+    end
+
+    # Get any person references in the paragraph
+    #
+    # @return [Array<String>] array of person names
+    def people
+      extract_entities unless @entities_extracted
+      @people
+    end
+
+    # Get any organization references in the paragraph
+    #
+    # @return [Array<String>] array of organization names
+    def organizations
+      extract_entities unless @entities_extracted
+      @organizations
+    end
+
+    # Get any location references in the paragraph
+    #
+    # @return [Array<String>] array of location names
+    def locations
+      extract_entities unless @entities_extracted
+      @locations
+    end
+
+    # Get the raw HTML/XML content of the paragraph
+    #
+    # @return [String] the inner XML
+    def inner_html
+      node.children.map(&:to_s).join
+    end
+
+    # Check if paragraph has content
+    #
+    # @return [Boolean] true if paragraph has text
+    def present?
+      !text.empty?
+    end
+
+    # Get word count for the paragraph
+    #
+    # @return [Integer] approximate word count
+    def word_count
+      return 0 if text.empty?
+
+      text.split(/\s+/).size
+    end
+
+    private
+
+    # Extract all entities in a single DOM traversal
+    #
+    # This is more efficient than running separate XPath queries
+    # for each entity type when multiple entity methods are called.
+    def extract_entities
+      @people = []
+      @organizations = []
+      @locations = []
+      @emphasis = []
+      @links = []
+
+      traverse_for_entities(node)
+
+      @entities_extracted = true
+    end
+
+    # Recursively traverse elements and extract entities
+    #
+    # @param element [REXML::Element] the element to traverse
+    def traverse_for_entities(element)
+      element.each_element do |child|
+        case child.name
+        when "person"
+          text = child.text&.strip
+          @people << text if text && !text.empty?
+        when "org"
+          text = child.text&.strip
+          @organizations << text if text && !text.empty?
+        when "location"
+          text = child.text&.strip
+          @locations << text if text && !text.empty?
+        when "em"
+          text = child.text&.strip
+          @emphasis << text if text && !text.empty?
+        when "a"
+          @links << {
+            text: child.text&.strip,
+            href: child.attributes["href"]
+          }
+        end
+
+        # Continue traversing for nested entities
+        traverse_for_entities(child)
+      end
+    end
+  end
+end

data/lib/nitfr/text_extractor.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module NITFr
+  # Shared module for extracting text from REXML elements
+  #
+  # REXML's built-in text method only returns direct text content,
+  # not text from nested elements. This module provides a method
+  # to recursively extract all text content.
+  module TextExtractor
+    # Extract all text content from an element and its descendants
+    #
+    # @param element [REXML::Element] the element to extract text from
+    # @return [String] the concatenated text content
+    def extract_all_text(element)
+      result = +""
+      element.each_child do |child|
+        if child.is_a?(REXML::Text)
+          result << child.value
+        elsif child.is_a?(REXML::Element)
+          result << extract_all_text(child)
+        end
+      end
+      result
+    end
+  end
+end

data/lib/nitfr/version.rb

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

data/lib/nitfr.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "rexml/document"
+require "rexml/xpath"
+
+# Configure REXML security settings at load time
+# This protects against XML entity expansion attacks (Billion Laughs)
+if defined?(REXML::Security)
+  REXML::Security.entity_expansion_limit = 100
+  REXML::Security.entity_expansion_text_limit = 10_000
+end
+
+require_relative "nitfr/version"
+require_relative "nitfr/errors"
+require_relative "nitfr/text_extractor"
+require_relative "nitfr/document"
+require_relative "nitfr/head"
+require_relative "nitfr/body"
+require_relative "nitfr/headline"
+require_relative "nitfr/byline"
+require_relative "nitfr/paragraph"
+require_relative "nitfr/media"
+require_relative "nitfr/docdata"
+
+module NITFr
+  class << self
+    # Parse an NITF XML string and return a Document
+    #
+    # @param xml [String] the NITF XML content
+    # @return [Document] the parsed document
+    # @raise [ParseError] if the XML is invalid or not NITF
+    def parse(xml)
+      Document.new(xml)
+    end
+
+    # Parse an NITF XML file and return a Document
+    #
+    # @param path [String] path to the NITF XML file
+    # @param encoding [String] the file encoding (default: UTF-8)
+    # @return [Document] the parsed document
+    # @raise [ParseError] if the file cannot be read or XML is invalid
+    # @raise [Errno::ENOENT] if the file does not exist
+    def parse_file(path, encoding: "UTF-8")
+      xml = File.read(path, encoding: encoding)
+      parse(xml)
+    end
+  end
+end

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: nitfr
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Mark Turner
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rexml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: test-unit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+description: NITFr makes it easy for Ruby applications to parse and extract content
+  from NITF XML files, the standard format used in the news industry.
+email:
+- mark@amerine.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- lib/nitfr.rb
+- lib/nitfr/body.rb
+- lib/nitfr/byline.rb
+- lib/nitfr/docdata.rb
+- lib/nitfr/document.rb
+- lib/nitfr/errors.rb
+- lib/nitfr/head.rb
+- lib/nitfr/headline.rb
+- lib/nitfr/media.rb
+- lib/nitfr/paragraph.rb
+- lib/nitfr/text_extractor.rb
+- lib/nitfr/version.rb
+homepage: https://github.com/amerine/nitfr
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/amerine/nitfr
+  source_code_uri: https://github.com/amerine/nitfr
+  changelog_uri: https://github.com/amerine/nitfr/blob/master/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: A Ruby gem for parsing NITF (News Industry Text Format) XML files
+test_files: []