comicinfo 1.0.0

data/lib/comicinfo/issue.rb

@@ -0,0 +1,332 @@
+require 'nokogiri'
+require 'date'
+require 'json'
+require 'yaml'
+require_relative 'enums'
+require_relative 'errors'
+require_relative 'page'
+
+module ComicInfo
+  # Main class for parsing and accessing ComicInfo.xml data
+  # Follows the ComicInfo XSD schema v2.0 specification
+  class Issue
+    # String fields from ComicInfo schema
+    attr_reader :title, :series, :number, :alternate_series, :alternate_number,
+                :summary, :notes, :writer, :penciller, :inker, :colorist,
+                :letterer, :cover_artist, :editor, :translator, :publisher,
+                :imprint, :genre, :web, :language_iso, :format, :character,
+                :team, :location, :scan_information, :story_arc, :story_arc_number,
+                :series_group, :main_character_or_team, :review
+
+    # Integer fields from ComicInfo schema
+    attr_reader :count, :volume, :alternate_count, :year, :month, :day, :page_count
+
+    # Enum fields from ComicInfo schema
+    attr_reader :black_and_white, :manga, :age_rating
+
+    # Decimal fields from ComicInfo schema
+    attr_reader :community_rating
+
+    # Array fields from ComicInfo schema
+    attr_reader :pages
+
+    # Class method to load ComicInfo from file path or XML string
+    def self.load file_path_or_xml_string
+      raise Errors::ParseError, 'Input cannot be nil' if file_path_or_xml_string.nil?
+
+      input = file_path_or_xml_string.to_s
+      return new(input) if input.empty?
+
+      if looks_like_xml?(input)
+        new(input)
+      else
+        load_from_file(input)
+      end
+    end
+
+    private_class_method def self.looks_like_xml? input
+      input.strip.start_with?('<')
+    end
+
+    private_class_method def self.load_from_file input
+      validate_file_path(input)
+      raise Errors::FileError, "File does not exist: '#{input}'" unless File.exist?(input)
+
+      begin
+        xml_content = File.read(input)
+        new(xml_content)
+      rescue Errors::ParseError
+        # Re-raise parse errors from XML parsing
+        raise
+      rescue StandardError => e
+        raise Errors::FileError, "Failed to read file '#{input}': #{e.message}"
+      end
+    end
+
+    private_class_method def self.validate_file_path input
+      return unless input.match?(/^\d+$/) ||
+                    (!input.include?('.') && !input.include?('/') && !input.include?('\\'))
+
+      raise Errors::ParseError, "Input '#{input}' does not appear to be valid XML or a file path"
+    end
+
+    # Initialize from XML string
+    def initialize xml_string
+      raise Errors::ParseError, 'XML string cannot be nil or empty' if xml_string.nil? || xml_string.empty?
+
+      begin
+        @doc = Nokogiri::XML(xml_string) do |config|
+          config.strict.nonet
+        end
+
+        raise Errors::ParseError, "XML parsing failed: #{@doc.errors.first.message}" if @doc.errors.any?
+
+        @root = @doc.at_css('ComicInfo')
+        raise Errors::ParseError, 'No ComicInfo root element found' if @root.nil?
+      rescue Nokogiri::XML::SyntaxError => e
+        raise Errors::ParseError, "Invalid XML syntax: #{e.message}"
+      end
+
+      parse_fields
+    end
+
+    # Convenience methods for boolean checks
+    def manga?
+      Enums::Helpers.yes_value?(@manga)
+    end
+
+    def right_to_left?
+      Enums::Helpers.manga_right_to_left?(@manga)
+    end
+
+    def black_and_white?
+      Enums::Helpers.yes_value?(@black_and_white)
+    end
+
+    def pages?
+      @pages && !@pages.empty?
+    end
+
+    # Get only cover pages
+    def cover_pages
+      return [] unless pages?
+
+      @pages.select(&:cover?)
+    end
+
+    # Get only story pages
+    def story_pages
+      return [] unless pages?
+
+      @pages.select(&:story?)
+    end
+
+    # Get publication date as Date object if available
+    def publication_date
+      return nil if @year == Enums::DEFAULT_INTEGER
+
+      year = @year
+      month = @month == Enums::DEFAULT_INTEGER ? 1 : @month
+      day = @day == Enums::DEFAULT_INTEGER ? 1 : @day
+
+      begin
+        Date.new(year, month, day)
+      rescue ArgumentError
+        nil
+      end
+    end
+
+    # Plural methods that return arrays
+    def genres
+      split_comma_separated(@genre)
+    end
+
+    def characters
+      split_comma_separated(@character)
+    end
+
+    def teams
+      split_comma_separated(@team)
+    end
+
+    def locations
+      split_comma_separated(@location)
+    end
+
+    def story_arcs
+      split_comma_separated(@story_arc)
+    end
+
+    def story_arc_numbers
+      split_comma_separated(@story_arc_number)
+    end
+
+    def web_urls
+      return [] if @web.empty?
+
+      @web.split(/\s+/)
+    end
+
+    # Convert to JSON representation
+    def to_json(*)
+      to_h.to_json(*)
+    end
+
+    # Convert to YAML representation
+    def to_yaml(*)
+      to_h.to_yaml(*)
+    end
+
+    # Convert to hash representation for JSON serialization
+    def to_h
+      {
+        title:                  @title,
+        series:                 @series,
+        number:                 @number,
+        count:                  @count,
+        volume:                 @volume,
+        alternate_series:       @alternate_series,
+        alternate_number:       @alternate_number,
+        alternate_count:        @alternate_count,
+        summary:                @summary,
+        notes:                  @notes,
+        year:                   @year,
+        month:                  @month,
+        day:                    @day,
+        writer:                 @writer,
+        penciller:              @penciller,
+        inker:                  @inker,
+        colorist:               @colorist,
+        letterer:               @letterer,
+        cover_artist:           @cover_artist,
+        editor:                 @editor,
+        translator:             @translator,
+        publisher:              @publisher,
+        imprint:                @imprint,
+        genre:                  @genre,
+        genres:                 genres,
+        web:                    @web,
+        web_urls:               web_urls,
+        page_count:             @page_count,
+        language_iso:           @language_iso,
+        format:                 @format,
+        black_and_white:        @black_and_white,
+        manga:                  @manga,
+        character:              @character,
+        characters:             characters,
+        team:                   @team,
+        teams:                  teams,
+        location:               @location,
+        locations:              locations,
+        scan_information:       @scan_information,
+        story_arc:              @story_arc,
+        story_arcs:             story_arcs,
+        story_arc_number:       @story_arc_number,
+        story_arc_numbers:      story_arc_numbers,
+        series_group:           @series_group,
+        age_rating:             @age_rating,
+        main_character_or_team: @main_character_or_team,
+        community_rating:       @community_rating,
+        review:                 @review,
+        pages:                  @pages.map(&:to_h)
+      }.compact
+    end
+
+    private
+
+    def parse_fields
+      # String fields
+      @title = get_string_field('Title')
+      @series = get_string_field('Series')
+      @number = get_string_field('Number')
+      @alternate_series = get_string_field('AlternateSeries')
+      @alternate_number = get_string_field('AlternateNumber')
+      @summary = get_string_field('Summary')
+      @notes = get_string_field('Notes')
+
+      # Creator fields
+      @writer = get_string_field('Writer')
+      @penciller = get_string_field('Penciller')
+      @inker = get_string_field('Inker')
+      @colorist = get_string_field('Colorist')
+      @letterer = get_string_field('Letterer')
+      @cover_artist = get_string_field('CoverArtist')
+      @editor = get_string_field('Editor')
+      @translator = get_string_field('Translator')
+
+      # Publication fields
+      @publisher = get_string_field('Publisher')
+      @imprint = get_string_field('Imprint')
+      @genre = get_string_field('Genre')
+      @web = get_string_field('Web')
+      @language_iso = get_string_field('LanguageISO')
+      @format = get_string_field('Format')
+
+      # Multi-value string fields (singular names for string values)
+      @character = get_string_field('Characters')
+      @team = get_string_field('Teams')
+      @location = get_string_field('Locations')
+      @scan_information = get_string_field('ScanInformation')
+      @story_arc = get_string_field('StoryArc')
+      @story_arc_number = get_string_field('StoryArcNumber')
+      @series_group = get_string_field('SeriesGroup')
+      @main_character_or_team = get_string_field('MainCharacterOrTeam')
+      @review = get_string_field('Review')
+
+      # Integer fields
+      @count = get_integer_field('Count')
+      @volume = get_integer_field('Volume')
+      @alternate_count = get_integer_field('AlternateCount')
+      @year = Enums::Validators.validate_year(get_field_text('Year'))
+      @month = Enums::Validators.validate_month(get_field_text('Month'))
+      @day = Enums::Validators.validate_day(get_field_text('Day'))
+      @page_count = get_integer_field('PageCount', Enums::DEFAULT_PAGE_COUNT)
+
+      # Enum fields
+      @black_and_white = Enums::Validators.validate_yes_no(get_field_text('BlackAndWhite'))
+      @manga = Enums::Validators.validate_manga(get_field_text('Manga'))
+      @age_rating = Enums::Validators.validate_age_rating(get_field_text('AgeRating'))
+
+      # Decimal fields
+      @community_rating = Enums::Validators.validate_community_rating(get_field_text('CommunityRating'))
+
+      # Array fields
+      @pages = parse_pages
+    end
+
+    def get_string_field field_name
+      text = get_field_text(field_name)
+      text.nil? || text.empty? ? Enums::DEFAULT_STRING : text
+    end
+
+    def get_integer_field field_name, default = Enums::DEFAULT_INTEGER
+      text = get_field_text(field_name)
+      Enums::Validators.validate_integer(text, field_name, default)
+    end
+
+    def get_field_text field_name
+      element = @root.at_css(field_name)
+      element&.text
+    end
+
+    def parse_pages
+      pages_element = @root.at_css('Pages')
+      return [] unless pages_element
+
+      page_elements = pages_element.css('Page')
+      page_elements.map do |page_element|
+        attributes = {}
+        page_element.attributes.each do |name, attr|
+          attributes[name] = attr.value
+        end
+        Page.new(attributes)
+      end
+    end
+
+    def split_comma_separated text
+      return [] if text.nil? || text.empty?
+
+      text.split(/,\s*/).map(&:strip).reject(&:empty?)
+    end
+  end
+end

data/lib/comicinfo/page.rb

@@ -0,0 +1,182 @@
+require_relative 'enums'
+require_relative 'errors'
+
+module ComicInfo
+  # Represents a single page in a comic book with metadata
+  # Maps to ComicPageInfo type in the ComicInfo XSD schema
+  class Page
+    # Page attributes from XSD schema
+    attr_reader :image, :type, :double_page, :image_size, :key, :bookmark, :image_width, :image_height
+
+    def initialize attributes = {}
+      @image        = parse_image(attributes['Image'] || attributes[:image])
+      @type         = Enums::Validators.validate_comic_page_type(attributes['Type'] || attributes[:type])
+      @double_page  = parse_boolean(attributes['DoublePage'] || attributes[:double_page])
+      @image_size   = parse_image_size(attributes['ImageSize'] || attributes[:image_size])
+      @key          = (attributes['Key'] || attributes[:key] || Enums::DEFAULT_STRING).to_s
+      @bookmark     = (attributes['Bookmark'] || attributes[:bookmark] || Enums::DEFAULT_STRING).to_s
+      @image_width  = parse_image_dimension(attributes['ImageWidth'] || attributes[:image_width], 'ImageWidth')
+      @image_height = parse_image_dimension(attributes['ImageHeight'] || attributes[:image_height], 'ImageHeight')
+    end
+
+    # Check if this page is a cover page
+    def cover?
+      @type == 'FrontCover' || @type == 'BackCover' || @type == 'InnerCover'
+    end
+
+    # Check if this page is a story page
+    def story?
+      @type == 'Story'
+    end
+
+    # Check if this page should be deleted/hidden
+    def deleted?
+      @type == 'Deleted'
+    end
+
+    # Check if this is a double-page spread
+    def double_page?
+      @double_page
+    end
+
+    # Get page types as an array (handles space-separated values)
+    def types
+      @type.split(/\s+/)
+    end
+
+    # Check if page has a specific type
+    def include_type? type
+      types.include?(type)
+    end
+
+    # Get image dimensions as a hash
+    def dimensions
+      {
+        width:  @image_width == Enums::DEFAULT_INTEGER ? nil : @image_width,
+        height: @image_height == Enums::DEFAULT_INTEGER ? nil : @image_height
+      }
+    end
+
+    # Check if image dimensions are available
+    def dimensions_available?
+      @image_width != Enums::DEFAULT_INTEGER && @image_height != Enums::DEFAULT_INTEGER
+    end
+
+    # Get aspect ratio if dimensions are available
+    def aspect_ratio
+      return nil unless dimensions_available? && @image_height != 0
+
+      @image_width.to_f / @image_height
+    end
+
+    # Check if this page has a bookmark
+    def bookmarked?
+      !@bookmark.empty?
+    end
+
+    # Convert to hash representation
+    def to_h
+      {
+        image:        @image,
+        type:         @type,
+        double_page:  @double_page,
+        image_size:   @image_size,
+        key:          @key,
+        bookmark:     @bookmark,
+        image_width:  @image_width,
+        image_height: @image_height
+      }
+    end
+
+    # Convert to XML attributes hash (for XML generation)
+    def to_xml_attributes
+      attrs = { 'Image' => @image.to_s }
+      attrs['Type']        = @type unless @type == Enums::DEFAULT_PAGE_TYPE
+      attrs['DoublePage']  = @double_page.to_s unless @double_page == Enums::DEFAULT_DOUBLE_PAGE
+      attrs['ImageSize']   = @image_size.to_s unless @image_size == Enums::DEFAULT_IMAGE_SIZE
+      attrs['Key']         = @key unless @key.empty?
+      attrs['Bookmark']    = @bookmark unless @bookmark.empty?
+      attrs['ImageWidth']  = @image_width.to_s unless @image_width == Enums::DEFAULT_INTEGER
+      attrs['ImageHeight'] = @image_height.to_s unless @image_height == Enums::DEFAULT_INTEGER
+      attrs
+    end
+
+    # String representation
+    def to_s
+      parts = ["Page #{@image}"]
+      parts << "Type: #{@type}" unless @type == Enums::DEFAULT_PAGE_TYPE
+      parts << 'Double' if @double_page
+      parts << "Bookmark: #{@bookmark}" unless @bookmark.empty?
+      parts.join(', ')
+    end
+
+    # Detailed inspection
+    def inspect
+      "#<ComicInfo::Page #{self}>"
+    end
+
+    # Equality comparison
+    def == other
+      return false unless other.is_a?(Page)
+
+      @image == other.image &&
+        @type == other.type &&
+        @double_page == other.double_page &&
+        @image_size == other.image_size &&
+        @key == other.key &&
+        @bookmark == other.bookmark &&
+        @image_width == other.image_width &&
+        @image_height == other.image_height
+    end
+
+    alias eql? ==
+
+    def hash
+      [@image, @type, @double_page, @image_size, @key, @bookmark, @image_width, @image_height].hash
+    end
+
+    private
+
+    def parse_image value
+      raise Errors::SchemaError, 'Image attribute is required for Page' if value.nil? || value.to_s.empty?
+
+      begin
+        Integer(value)
+      rescue ArgumentError
+        raise Errors::TypeCoercionError.new('Image', value, 'Integer')
+      end
+    end
+
+    def parse_boolean value
+      case value.to_s.downcase
+      when 'true', '1', 'yes'
+        true
+      when 'false', '0', 'no', ''
+        false
+      else
+        raise Errors::TypeCoercionError.new('DoublePage', value, 'Boolean')
+      end
+    end
+
+    def parse_image_size value
+      return Enums::DEFAULT_IMAGE_SIZE if value.nil? || value.to_s.empty?
+
+      begin
+        size = Integer(value)
+        size.negative? ? Enums::DEFAULT_IMAGE_SIZE : size
+      rescue ArgumentError
+        raise Errors::TypeCoercionError.new('ImageSize', value, 'Integer')
+      end
+    end
+
+    def parse_image_dimension value, field_name
+      return Enums::DEFAULT_INTEGER if value.nil? || value.to_s.empty?
+
+      begin
+        Integer(value)
+      rescue ArgumentError
+        raise Errors::TypeCoercionError.new(field_name, value, 'Integer')
+      end
+    end
+  end
+end

data/lib/comicinfo/version.rb

@@ -0,0 +1,3 @@
+module ComicInfo
+  VERSION = '1.0.0'.freeze
+end

data/lib/comicinfo.rb

@@ -0,0 +1,15 @@
+require_relative 'comicinfo/version'
+
+module ComicInfo
+  class Error < StandardError; end
+
+  autoload :Issue, 'comicinfo/issue'
+  autoload :Page, 'comicinfo/page'
+  autoload :Enums, 'comicinfo/enums'
+  autoload :Errors, 'comicinfo/errors'
+
+  # Convenience method for loading ComicInfo files
+  def self.load file_path_or_xml_string
+    Issue.load(file_path_or_xml_string)
+  end
+end

data/schemas/1.0/ComicInfo.xsd

@@ -0,0 +1,77 @@
+<?xml version="1.0" encoding="utf-8"?>
+<xs:schema elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
+    <xs:element name="ComicInfo" nillable="true" type="ComicInfo"/>
+    <xs:complexType name="ComicInfo">
+        <xs:sequence>
+            <xs:element minOccurs="0" maxOccurs="1" default="" name="Title" type="xs:string"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="" name="Series" type="xs:string"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="" name="Number" type="xs:string"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="-1" name="Count" type="xs:int"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="-1" name="Volume" type="xs:int"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="" name="AlternateSeries" type="xs:string"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="" name="AlternateNumber" type="xs:string"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="-1" name="AlternateCount" type="xs:int"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="" name="Summary" type="xs:string"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="" name="Notes" type="xs:string"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="-1" name="Year" type="xs:int"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="-1" name="Month" type="xs:int"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="" name="Writer" type="xs:string"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="" name="Penciller" type="xs:string"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="" name="Inker" type="xs:string"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="" name="Colorist" type="xs:string"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="" name="Letterer" type="xs:string"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="" name="CoverArtist" type="xs:string"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="" name="Editor" type="xs:string"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="" name="Publisher" type="xs:string"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="" name="Imprint" type="xs:string"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="" name="Genre" type="xs:string"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="" name="Web" type="xs:string"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="0" name="PageCount" type="xs:int"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="" name="LanguageISO" type="xs:string"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="" name="Format" type="xs:string"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="Unknown" name="BlackAndWhite" type="YesNo"/>
+            <xs:element minOccurs="0" maxOccurs="1" default="Unknown" name="Manga" type="YesNo"/>
+            <xs:element minOccurs="0" maxOccurs="1" name="Pages" type="ArrayOfComicPageInfo"/>
+        </xs:sequence>
+    </xs:complexType>
+    <xs:simpleType name="YesNo">
+        <xs:restriction base="xs:string">
+            <xs:enumeration value="Unknown"/>
+            <xs:enumeration value="No"/>
+            <xs:enumeration value="Yes"/>
+        </xs:restriction>
+    </xs:simpleType>
+    <xs:complexType name="ArrayOfComicPageInfo">
+        <xs:sequence>
+            <xs:element minOccurs="0" maxOccurs="unbounded" name="Page" nillable="true" type="ComicPageInfo"/>
+        </xs:sequence>
+    </xs:complexType>
+    <xs:complexType name="ComicPageInfo">
+        <xs:attribute name="Image" type="xs:int" use="required"/>
+        <xs:attribute default="Story" name="Type" type="ComicPageType"/>
+        <xs:attribute default="false" name="DoublePage" type="xs:boolean"/>
+        <xs:attribute default="0" name="ImageSize" type="xs:long"/>
+        <xs:attribute default="" name="Key" type="xs:string"/>
+        <xs:attribute default="-1" name="ImageWidth" type="xs:int"/>
+        <xs:attribute default="-1" name="ImageHeight" type="xs:int"/>
+    </xs:complexType>
+    <xs:simpleType name="ComicPageType">
+        <xs:list>
+            <xs:simpleType>
+                <xs:restriction base="xs:string">
+                    <xs:enumeration value="FrontCover"/>
+                    <xs:enumeration value="InnerCover"/>
+                    <xs:enumeration value="Roundup"/>
+                    <xs:enumeration value="Story"/>
+                    <xs:enumeration value="Advertisement"/>
+                    <xs:enumeration value="Editorial"/>
+                    <xs:enumeration value="Letters"/>
+                    <xs:enumeration value="Preview"/>
+                    <xs:enumeration value="BackCover"/>
+                    <xs:enumeration value="Other"/>
+                    <xs:enumeration value="Deleted"/>
+                </xs:restriction>
+            </xs:simpleType>
+        </xs:list>
+    </xs:simpleType>
+</xs:schema>