comicinfo 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f66dfb29761ad9d67b58cb229eeb3806205ecc417162830fa7688075b7886fba
-  data.tar.gz: bec2db8b6b877f0f6b35a7e3123653a7216dc653d847bcd16fa1112b5fe896a2
+  metadata.gz: ed9c12d2685a70526b85e3be44e9524720b7f90bba6548a09541290df18bdbf7
+  data.tar.gz: 9856df6a2adbc6a7e81381992b7ae7c1fae68f184b47400f68a95fbe9ab7ac63
 SHA512:
-  metadata.gz: f3094240a2e409a5dd41834ba35c2a4cc3ce73ad0e834b14db06d93dd344629dc318dba0760d1a1f8e56a7e6876832d9422b9d34264caca489ea2561f05eda37
-  data.tar.gz: 9de5a0f9c1f14a79139fa6837051a290deb5a1fb43eaa0dc2631153466daf2659d9914befae597669a5fd7c7198496ef5245f28a9554b957aada6ace71d4589e
+  metadata.gz: 6ca41d4b00d7413aec6d2d78297a17c828fcd2ae79f9309b89fe7aebbf575ed2ed4970f09c620d558d89befde9991092a4d629b168675a5724f6602a6dcff49a
+  data.tar.gz: 329402c1d139d5668651834900a2ba08c463cda8d258b3161fc2a1b73e4b34dcb76d3ea5c6449a1310b8449326c098e0206da750570a4797dc86e0502945fc4b

data/CHANGELOG.md

@@ -5,6 +5,40 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.0] - 2025-11-10
+
+### Added
+- **XML Generation**: Complete ComicInfo XML writing functionality
+  - `ComicInfo::Issue#to_xml` method for generating XML strings
+  - `ComicInfo::Issue#save(file_path_or_io)` method for writing to files or IO objects
+  - Valid ComicInfo v2.0 compliant XML output with UTF-8 encoding and schema namespaces
+  - Only includes non-default/non-empty values for clean XML output
+  - Proper XML entity escaping for special characters
+  - Full Pages section generation with all page attributes
+  - Round-trip consistency (load -> save -> load maintains data integrity)
+
+### Changed - BREAKING
+- **Multi-value field method naming**: Changed from singular/plural pattern to plural/raw_data pattern
+  - Plural methods (e.g., `genres`, `characters`) now return arrays
+  - Raw data methods (e.g., `genres_raw_data`, `characters_raw_data`) return original comma-separated strings
+  - Singular schema elements now alias to plural methods (e.g., `genre` aliases to `genres`)
+  - Export hashes include both raw data keys and _raw_data keys with duplicate values for backward compatibility
+  - This affects: `genre`/`genres`, `character`/`characters`, `team`/`teams`, `location`/`locations`, `story_arc`/`story_arcs`, `story_arc_number`/`story_arc_numbers`
+
+### Migration Guide
+- Replace `.genre` calls with `.genres` (now returns array) or `.genres_raw_data` (for string)
+- Replace `.character` calls with `.characters_raw_data` (for string) - `.characters` was already array
+- Replace `.team` calls with `.teams_raw_data` (for string) - `.teams` was already array
+- Replace `.location` calls with `.locations_raw_data` (for string) - `.locations` was already array
+- Replace `.story_arc` calls with `.story_arcs` (now returns array) or `.story_arcs_raw_data` (for string)
+- Replace `.story_arc_number` calls with `.story_arc_numbers` (now returns array) or `.story_arc_numbers_raw_data` (for string)
+
+### Export Hash Changes
+- Hash exports now include both `:genre` and `:genres_raw_data` keys with identical raw string values
+- Hash exports now include both `:story_arc` and `:story_arcs_raw_data` keys with identical raw string values
+- Hash exports now include both `:story_arc_number` and `:story_arc_numbers_raw_data` keys with identical raw string values
+- This maintains backward compatibility while supporting the new API design
+
 ## [1.0.0] - 2025-10-05
 
 ### Added
@@ -33,7 +67,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Pages**: Complete page object model with type predicates and attributes
 - **Multi-value**: Smart handling of comma/space-separated field values
 
-## [0.1.0] - 2025-01-XX
+## [0.1.0] - 2025-10-05
 
 ### Added
 - Initial project structure

data/README.md

@@ -17,7 +17,8 @@ following the official ComicInfo schema specifications from the
 - 📖 **Manga Support**: Right-to-left reading direction and manga-specific fields
 - ✅ **Comprehensive Validation**: Schema-compliant enum validation and type coercion
 - 🚨 **Detailed Error Handling**: Custom exception classes with helpful error messages
-- 📊 **Export Support**: JSON and YAML serialization with hash representation (in progress)
+- 📊 **Export Support**: JSON, YAML, and XML serialization with hash representation
+- ✍️ **XML Generation**: Complete ComicInfo.xml writing with round-trip consistency
 
 ## Installation
 
@@ -108,6 +109,16 @@ teams      = comic.teams      #=> ["Avengers"]
 locations  = comic.locations  #=> ["New York City", "Manhattan", ...]
 genres     = comic.genres     #=> ["Superhero", "Action", "Adventure"]
 web_urls   = comic.web_urls   #=> ["https://marvel.com/...", "https://comicvine.com/..."]
+
+# Raw data methods for original comma-separated strings
+genres_raw     = comic.genres_raw_data     #=> "Superhero, Action, Adventure"
+characters_raw = comic.characters_raw_data #=> "Spider-Man, Peter Parker, J. Jonah Jameson, Aunt May"
+story_arcs_raw = comic.story_arcs_raw_data #=> "Brand New Day, Spider-Island"
+
+# Singular schema elements alias to plural arrays
+genre          = comic.genre          #=> ["Superhero", "Action", "Adventure"] (same as genres)
+story_arc      = comic.story_arc      #=> ["Brand New Day", "Spider-Island"] (same as story_arcs)
+story_arc_num  = comic.story_arc_number #=> ["1", "5"] (same as story_arc_numbers)
 ```
 
 ### Working with Pages
@@ -131,7 +142,7 @@ puts page.deleted? #=> true for Deleted pages
 
 ```ruby
 # Load a manga ComicInfo file
-manga = ComicInfo.load 'path/to/manga/ComicInfo.xml')
+manga = ComicInfo.load 'path/to/manga/ComicInfo.xml'
 
 puts manga.title            #=> "進撃の巨人"
 puts manga.series           #=> "Attack on Titan"
@@ -167,9 +178,17 @@ This gem fully supports the ComicInfo v2.0 XSD schema with all field types:
 ### String Fields
 - Title, Series, Number, Summary, Notes
 - Creator fields (Writer, Penciller, Inker, Colorist, Letterer, CoverArtist, Editor, Translator)
-- Publication fields (Publisher, Imprint, Genre, Web, LanguageISO, Format)
-- Character/Location fields (Characters, Teams, Locations, MainCharacterOrTeam)
-- Story fields (StoryArc, StoryArcNumber, SeriesGroup, ScanInformation, Review)
+- Publication fields (Publisher, Imprint, Web, LanguageISO, Format)
+- Character/Location fields (MainCharacterOrTeam)
+- Story fields (SeriesGroup, ScanInformation, Review)
+
+### Multi-value Fields (String + Array Access)
+- Genre/Genres: Raw comma-separated string + parsed array
+- Characters: Raw comma-separated string + parsed array
+- Teams: Raw comma-separated string + parsed array
+- Locations: Raw comma-separated string + parsed array
+- StoryArc/StoryArcs: Raw comma-separated string + parsed array
+- StoryArcNumber/StoryArcNumbers: Raw comma-separated string + parsed array
 
 ### Integer Fields
 - Count, Volume, AlternateCount, PageCount
@@ -190,9 +209,10 @@ This gem fully supports the ComicInfo v2.0 XSD schema with all field types:
 ### Export Formats
 - **JSON**: Complete serialization with all fields
 - **YAML**: Human-readable format with array structures
+- **XML**: Valid ComicInfo v2.0 compliant XML generation
 - **Hash**: Ruby hash representation with symbol keys
 
-### Data Export
+### Data Export & XML Generation
 
 ```ruby
 comic = ComicInfo.load 'path/to/ComicInfo.xml'
@@ -205,11 +225,27 @@ puts JSON.pretty_generate(JSON.parse(json_string))
 yaml_string = comic.to_yaml
 puts yaml_string
 
+# Generate XML
+xml_string = comic.to_xml
+puts xml_string
+
+# Save to file
+comic.save 'path/to/new/ComicInfo.xml'
+
+# Save to IO object
+File.open('path/to/new/ComicInfo.xml', 'w') do |file|
+  comic.save file
+end
+
 # Export as Hash
 hash = comic.to_h
-puts hash[:title]        #=> "The Amazing Spider-Man"
-puts hash[:characters]   #=> ["Spider-Man", "Peter Parker", ...]
-puts hash[:pages].length #=> 12
+puts hash[:title]                   #=> "The Amazing Spider-Man"
+puts hash[:genre]                   #=> "Superhero, Action, Adventure" (raw data)
+puts hash[:genres]                  #=> ["Superhero", "Action", "Adventure"] (parsed array)
+puts hash[:genres_raw_data]         #=> "Superhero, Action, Adventure" (same as :genre)
+puts hash[:characters]              #=> ["Spider-Man", "Peter Parker", ...]
+puts hash[:characters_raw_data]     #=> "Spider-Man, Peter Parker, J. Jonah Jameson, Aunt May"
+puts hash[:pages].length            #=> 12
 ```
 
 ## Development
@@ -252,18 +288,18 @@ bundle exec rubocop --autocorrect
 
 ### Current Features ✅
 - **Core Reading**: Complete ComicInfo.xml parsing
+- **XML Writing**: Full ComicInfo.xml generation with round-trip consistency
 - **Schema Compliance**: Full ComicInfo v2.0 support
 - **Field Types**: String, Integer, Decimal, Enum, Boolean, Arrays
 - **Multi-value Fields**: Both string and array access methods
 - **Issue &Page Support**: Complete Issue and nested Page objects
 - **Error Handling**: Custom exceptions with detailed messages
-- **Data Export**: JSON and YAML serialization
+- **Data Export**: JSON, YAML, and XML serialization
 - **Validation**: Enum values, ranges, type coercion
 - **Unicode Support**: International characters and special symbols
-- **Test Coverage**: 156 comprehensive test cases
+- **Test Coverage**: 178 comprehensive test cases
 
 ### Planned Features 🚧
-- **XML Generation**: Writing ComicInfo.xml files
 - **CLI Tool**: Command-line interface for file manipulation
 - **Schema Migration**: Support for multiple ComicInfo versions
 

data/lib/comicinfo/enums.rb

@@ -48,6 +48,7 @@ module ComicInfo
     DEFAULT_PAGE_TYPE = 'Story'.freeze
     DEFAULT_DOUBLE_PAGE = false
     DEFAULT_IMAGE_SIZE = 0
+    DEFAULT_COMMUNITY_RATING = -1.0
 
     # Validation methods
     module Validators

data/lib/comicinfo/issue.rb

@@ -2,6 +2,7 @@ require 'nokogiri'
 require 'date'
 require 'json'
 require 'yaml'
+require 'fileutils'
 require_relative 'enums'
 require_relative 'errors'
 require_relative 'page'
@@ -11,12 +12,10 @@ module ComicInfo
   # 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
+    attr_reader :alternate_number, :alternate_series, :colorist, :cover_artist, :editor,
+                :format, :imprint, :inker, :language_iso, :letterer, :main_character_or_team,
+                :notes, :number, :penciller, :publisher, :review, :scan_information, :series,
+                :series_group, :summary, :title, :translator, :web, :writer
 
     # Integer fields from ComicInfo schema
     attr_reader :count, :volume, :alternate_count, :year, :month, :day, :page_count
@@ -137,34 +136,115 @@ module ComicInfo
     end
 
     # Plural methods that return arrays
-    def genres
-      split_comma_separated(@genre)
-    end
-
-    def characters
-      split_comma_separated(@character)
-    end
+    def genres            = split_comma_separated @genre
+    def characters        = split_comma_separated @character
+    def teams             = split_comma_separated @team
+    def locations         = split_comma_separated @location
+    def story_arcs        = split_comma_separated @story_arc
+    def story_arc_numbers = split_comma_separated @story_arc_number
 
-    def teams
-      split_comma_separated(@team)
-    end
+    def web_urls
+      return [] if @web.empty?
 
-    def locations
-      split_comma_separated(@location)
+      @web.split(/\s+/)
     end
 
-    def story_arcs
-      split_comma_separated(@story_arc)
-    end
+    # Raw data methods that return the original string values
+    def genres_raw_data            = @genre
+    def characters_raw_data        = @character
+    def teams_raw_data             = @team
+    def locations_raw_data         = @location
+    def story_arcs_raw_data        = @story_arc
+    def story_arc_numbers_raw_data = @story_arc_number
+
+    # Singular aliases for schema elements that are singular
+    alias genre genres
+    alias story_arc story_arcs
+    alias story_arc_number story_arc_numbers
+
+    # Convert to XML representation
+    def to_xml
+      doc = Nokogiri::XML::Builder.new(encoding: 'UTF-8') do |xml|
+        xml.ComicInfo('xmlns:xsi' => 'http://www.w3.org/2001/XMLSchema-instance',
+                      'xmlns:xsd' => 'http://www.w3.org/2001/XMLSchema') do
+          # String fields in schema order
+          xml.Title(@title) unless @title == Enums::DEFAULT_STRING
+          xml.Series(@series) unless @series == Enums::DEFAULT_STRING
+          xml.Number(@number) unless @number == Enums::DEFAULT_STRING
+          xml.Count(@count) unless @count == Enums::DEFAULT_INTEGER
+          xml.Volume(@volume) unless @volume == Enums::DEFAULT_INTEGER
+          xml.AlternateSeries(@alternate_series) unless @alternate_series == Enums::DEFAULT_STRING
+          xml.AlternateNumber(@alternate_number) unless @alternate_number == Enums::DEFAULT_STRING
+          xml.AlternateCount(@alternate_count) unless @alternate_count == Enums::DEFAULT_INTEGER
+          xml.Summary(@summary) unless @summary == Enums::DEFAULT_STRING
+          xml.Notes(@notes) unless @notes == Enums::DEFAULT_STRING
+          xml.Year(@year) unless @year == Enums::DEFAULT_INTEGER
+          xml.Month(@month) unless @month == Enums::DEFAULT_INTEGER
+          xml.Day(@day) unless @day == Enums::DEFAULT_INTEGER
+          xml.Writer(@writer) unless @writer == Enums::DEFAULT_STRING
+          xml.Penciller(@penciller) unless @penciller == Enums::DEFAULT_STRING
+          xml.Inker(@inker) unless @inker == Enums::DEFAULT_STRING
+          xml.Colorist(@colorist) unless @colorist == Enums::DEFAULT_STRING
+          xml.Letterer(@letterer) unless @letterer == Enums::DEFAULT_STRING
+          xml.CoverArtist(@cover_artist) unless @cover_artist == Enums::DEFAULT_STRING
+          xml.Editor(@editor) unless @editor == Enums::DEFAULT_STRING
+          xml.Translator(@translator) unless @translator == Enums::DEFAULT_STRING
+          xml.Publisher(@publisher) unless @publisher == Enums::DEFAULT_STRING
+          xml.Imprint(@imprint) unless @imprint == Enums::DEFAULT_STRING
+          xml.Genre(@genre) unless @genre == Enums::DEFAULT_STRING
+          xml.Web(@web) unless @web == Enums::DEFAULT_STRING
+          xml.PageCount(@page_count) unless @page_count == Enums::DEFAULT_PAGE_COUNT
+          xml.LanguageISO(@language_iso) unless @language_iso == Enums::DEFAULT_STRING
+          xml.Format(@format) unless @format == Enums::DEFAULT_STRING
+          xml.BlackAndWhite(@black_and_white) unless @black_and_white == Enums::DEFAULT_ENUM_UNKNOWN
+          xml.Manga(@manga) unless @manga == Enums::DEFAULT_ENUM_UNKNOWN
+          xml.Characters(@character) unless @character == Enums::DEFAULT_STRING
+          xml.Teams(@team) unless @team == Enums::DEFAULT_STRING
+          xml.Locations(@location) unless @location == Enums::DEFAULT_STRING
+          xml.ScanInformation(@scan_information) unless @scan_information == Enums::DEFAULT_STRING
+          xml.StoryArc(@story_arc) unless @story_arc == Enums::DEFAULT_STRING
+          xml.StoryArcNumber(@story_arc_number) unless @story_arc_number == Enums::DEFAULT_STRING
+          xml.SeriesGroup(@series_group) unless @series_group == Enums::DEFAULT_STRING
+          xml.AgeRating(@age_rating) unless @age_rating == Enums::DEFAULT_ENUM_UNKNOWN
+          xml.MainCharacterOrTeam(@main_character_or_team) unless @main_character_or_team == Enums::DEFAULT_STRING
+          xml.CommunityRating(@community_rating) unless @community_rating.nil?
+          xml.Review(@review) unless @review == Enums::DEFAULT_STRING
+
+          # Pages section
+          if @pages && !@pages.empty?
+            xml.Pages do
+              @pages.each do |page|
+                xml.Page(page.to_xml_attributes)
+              end
+            end
+          end
+        end
+      end
 
-    def story_arc_numbers
-      split_comma_separated(@story_arc_number)
+      doc.to_xml
     end
 
-    def web_urls
-      return [] if @web.empty?
-
-      @web.split(/\s+/)
+    # Save to file or IO object
+    def save file_path_or_io
+      xml_content = to_xml
+
+      case file_path_or_io
+      when String
+        begin
+          FileUtils.mkdir_p(File.dirname(file_path_or_io))
+          File.write(file_path_or_io, xml_content)
+        rescue StandardError => e
+          raise Errors::FileError, "Failed to write file '#{file_path_or_io}': #{e.message}"
+        end
+      when IO
+        begin
+          file_path_or_io.write(xml_content)
+        rescue StandardError => e
+          raise Errors::FileError, "Failed to write to IO object: #{e.message}"
+        end
+      else
+        raise Errors::FileError, 'Invalid file path or IO object'
+      end
     end
 
     # Convert to JSON representation
@@ -180,55 +260,58 @@ module ComicInfo
     # 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)
+        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_raw_data:            genres_raw_data,
+        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,
+        characters_raw_data:        characters_raw_data,
+        characters:                 characters,
+        teams_raw_data:             teams_raw_data,
+        teams:                      teams,
+        locations_raw_data:         locations_raw_data,
+        locations:                  locations,
+        scan_information:           @scan_information,
+        story_arc:                  @story_arc,
+        story_arcs_raw_data:        story_arcs_raw_data,
+        story_arcs:                 story_arcs,
+        story_arc_number:           @story_arc_number,
+        story_arc_numbers_raw_data: story_arc_numbers_raw_data,
+        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
 

data/lib/comicinfo/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: comicinfo
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Shane Becker
@@ -73,7 +73,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Ruby interface for working with ComicInfo.xml files
 test_files: []