dotstrings 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 605ff8ed35fcfcbd91f2fc33a4b53e69b614aab962de1c32c1d616f957ee1916
-  data.tar.gz: dddf00d461a893a4ff4e97c04fcc87617241e42189d0284b22e4ab98313ed25a
+  metadata.gz: a7f215ea68d4b6ce65de6f15811800b976eb722b89a4618bce4503338508df51
+  data.tar.gz: 51a72c22c7233b00df29f97d876abb3e59517de4bf0b78797ab8897d122250fe
 SHA512:
-  metadata.gz: a47fbb334a228e6642d7d6b3250b81ab7c7e239be8fb6ca92ba7877dfe9eb6ac0d3ba2bebe4176477afa9b825e4ce61af4a8d555b83e2a29ed6c176a6d392c90
-  data.tar.gz: fa824b2c3c59bee05bb64d59508a6bff112a551d37d6bbc198913433fc8b332a75a17af84a5524a944126fd6e38df8bef008615df303565e729556169eb21bc8
+  metadata.gz: 0d9247c103eb79e3e908a55af5661de97cae316cc36660c7c872a869f077a9875060eab7bab7caa0a9aa8c2ef82d6ce7c5b9acede49fa1227790b4aad53b205d
+  data.tar.gz: af144c8d6b3f9f552fc71db2df31db95f1189575fa8eb9e2c5f97ab0a15234024bcd97692218be4bbd04f7352f6a3d63966b4ff4948df84379158733583920ad

data/.gitignore

@@ -1,2 +1,5 @@
 pkg
 .vscode
+coverage
+doc
+.yardoc

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [v0.3.0] - 2022-08-07
+### Changed
+* Improved unicode code point parsing and validation.
+* Added `DotStrings::File#sort`, `DotStrings::File#sort!`, and `DotStrings::File#delete_if` methods.
+* Improved documentation.
+
 ## [v0.2.0] - 2022-07-17
 ### Changed
 * Made some state transitions more strict.

data/Gemfile.lock

@@ -1,12 +1,13 @@
 PATH
   remote: .
   specs:
-    dotstrings (0.2.0)
+    dotstrings (0.3.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
+    docile (1.4.0)
     minitest (5.15.0)
     parallel (1.22.1)
     parser (3.1.2.0)
@@ -31,6 +32,12 @@ GEM
     rubocop-rake (0.6.0)
       rubocop (~> 1.0)
     ruby-progressbar (1.11.0)
+    simplecov (0.21.2)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.4)
     unicode-display_width (2.2.0)
 
 PLATFORMS
@@ -44,6 +51,7 @@ DEPENDENCIES
   rubocop
   rubocop-minitest
   rubocop-rake
+  simplecov
 
 BUNDLED WITH
    2.2.18

data/README.md

@@ -7,6 +7,7 @@ A parser for Apple *strings* files (`.strings`) written in Ruby. Some of the fea
 * An API for creating strings files programmatically.
 * Handles Unicode and escaped characters.
 * Helpful error messages: know which line and column fail to parse and why.
+* Well [tested](test) and [documented](https://www.rubydoc.info/gems/dotstrings/DotStrings).
 
 ## Installing
 
@@ -19,12 +20,12 @@ $ gem install dotstrings
 Or by adding the following entry to your [Gemfile](https://guides.cocoapods.org/using/a-gemfile.html), then running `$ bundle install`.
 
 ```ruby
-gem "dotstrings"
+gem 'dotstrings'
 ```
 
 ## Usage
 
-You can load `.strings` files using the `DotString.parse()` utility method. This method returns a `DotStrings::File` object or raises an exception if the file is invalid.
+You can load `.strings` files using the `DotString.parse()` utility method. This method returns a `DotStrings::File` object or raises an exception if the file cannot be parsed.
 
 ```ruby
 file = DotStrings.parse_file('en-US/Localizable.strings')

data/dotstrings.gemspec

@@ -22,6 +22,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'rubocop'
   s.add_development_dependency 'rubocop-minitest'
   s.add_development_dependency 'rubocop-rake'
+  s.add_development_dependency 'simplecov'
 
   s.required_ruby_version = '>= 2.5.0'
   s.metadata['rubygems_mfa_required'] = 'true'

data/lib/dotstrings/errors.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module DotStrings
+  ##
+  # Class for errors raised by the parser.
   class ParsingError < RuntimeError
   end
 end

data/lib/dotstrings/file.rb

@@ -5,13 +5,48 @@ require 'dotstrings/errors'
 require 'dotstrings/item'
 
 module DotStrings
+  ##
+  # Represents a .strings file.
+  #
+  # It provides methods to parse .strings, as well as methods for accessing and
+  # manipulating localized string items.
   class File
+    ##
+    # All items in the file.
     attr_reader :items
 
     def initialize(items = [])
       @items = items
     end
 
+    ##
+    # Returns a new File with the items sorted using the given comparator block.
+    #
+    # If no block is given, the items will be sorted by key.
+    def sort(&block)
+      new_file = dup
+      new_file.sort!(&block)
+    end
+
+    ##
+    # Sort the items using the given block.
+    #
+    # If no block is given, the items will be sorted by key.
+    def sort!(&block)
+      @items.sort!(&block || ->(a, b) { a.key <=> b.key })
+      self
+    end
+
+    ##
+    # Parses a file from the given IO object.
+    #
+    # @example
+    #   io = Zlib::GzipReader.open('path/to/en.lproj/Localizable.strings.gz')
+    #   file = DotStrings::File.parse(io)
+    #
+    # @param io [IO] The IO object to parse.
+    # @return [DotStrings::File] The parsed file.
+    # @raise [DotStrings::ParsingError] if the file could not be parsed.
     def self.parse(io)
       items = []
 
@@ -22,32 +57,85 @@ module DotStrings
       File.new(items)
     end
 
+    ##
+    # Parses the file at the given path.
+    #
+    # @example
+    #   file = DotStrings::File.parse_file('path/to/en.lproj/Localizable.strings')
+    #
+    # @param path [String] The path to the file to parse.
+    # @return [DotStrings::File] The parsed file.
+    # @raise [DotStrings::ParsingError] if the file could not be parsed.
     def self.parse_file(path)
       ::File.open(path, 'r') do |file|
         parse(file)
       end
     end
 
+    ##
+    # Returns all keys in the file.
     def keys
       @items.map(&:key)
     end
 
+    ##
+    # Returns an item by key, if it exists, otherwise nil.
+    #
+    # @example
+    #   item = file['button.title']
+    #   unless item.nil?
+    #     puts item.value # => 'Submit'
+    #   end
+    #
+    # @param key [String] The key of the item to return.
+    # @return [DotStrings::Item] The item, if it exists.
     def [](key)
       @items.find { |item| item.key == key }
     end
 
+    ##
+    # Appends an item to the file.
+    #
+    # @example
+    #   file << DotStrings::Item.new(key: 'button.title', value: 'Submit')
+    #
+    # @param item [DotStrings::Item] The item to append.
+    # @return [DotStrings::Item] The item that was appended.
     def <<(item)
       @items << item
+      self
     end
 
+    ##
+    # Appends an item to the file.
+    #
+    # @example
+    #   file.append(DotStrings::Item.new(key: 'button.title', value: 'Submit'))
     def append(item)
       self << item
     end
 
+    ##
+    # Deletes an item by key.
     def delete(key)
       @items.delete_if { |item| item.key == key }
     end
 
+    ##
+    # Deletes all items for which the block returns true.
+    #
+    # @example
+    #   file.delete_if { |item| item.key.start_with?('button.') }
+    def delete_if(&block)
+      @items.delete_if(&block)
+      self
+    end
+
+    ##
+    # Serializes the file to a string.
+    #
+    # @param escape_single_quotes [Boolean] whether to escape single quotes.
+    # @param comments [Boolean] whether to include comments.
     def to_s(escape_single_quotes: false, comments: true)
       result = []
 

data/lib/dotstrings/item.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module DotStrings
+  ##
+  # Represents a localized string item.
   class Item
     attr_reader :comment, :key, :value
 
@@ -10,6 +12,11 @@ module DotStrings
       @value = value
     end
 
+    ##
+    # Serializes the item to string.
+    #
+    # @param escape_single_quotes [Boolean] Whether to escape single quotes.
+    # @param include_comment [Boolean] Whether to include the comment.
     def to_s(escape_single_quotes: false, include_comment: true)
       result = []
 

data/lib/dotstrings/parser.rb

@@ -4,6 +4,9 @@ require 'dotstrings/errors'
 
 module DotStrings
   # rubocop:disable Metrics/ClassLength
+
+  ##
+  # Parser for .strings files.
   class Parser
     # Special tokens
     TOK_SLASH        = '/'
@@ -36,8 +39,6 @@ module DotStrings
     STATE_UNICODE_SURROGATE   = 11
     STATE_UNICODE_SURROGATE_U = 12
 
-    attr_reader :items
-
     def initialize
       @state = STATE_START
       @temp_state = nil
@@ -59,11 +60,16 @@ module DotStrings
       @column = 1
     end
 
+    ##
+    # Specifies a block to be called when a new item is parsed.
     def on_item(&block)
       @item_block = block
     end
 
     # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/BlockLength
+
+    ##
+    # Feeds data to the parser.
     def <<(data)
       data.each_char do |ch|
         case @state
@@ -157,6 +163,7 @@ module DotStrings
         update_position(ch)
       end
     end
+
     # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/BlockLength
 
     private
@@ -203,30 +210,51 @@ module DotStrings
       end
     end
 
-    # rubocop:disable Style/GuardClause
+    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
     def parse_unicode(ch, &block)
       raise_error("Unexpected character '#{ch}', expecting a hex digit") unless ch =~ TOK_HEX_DIGIT
 
       @unicode_buffer << ch
 
-      if @unicode_buffer.length == 4
-        codepoint = @unicode_buffer.join.hex
+      # Check if we have enough digits to form a codepoint.
+      return if @unicode_buffer.length < 4
 
-        if codepoint >= 0xD800 && codepoint <= 0xDBFF
-          @high_surrogate = codepoint
-          @state = STATE_UNICODE_SURROGATE
-        elsif codepoint >= 0xDC00 && codepoint <= 0xDFFF
-          character = ((@high_surrogate - 0xD800) * 0x400) + (codepoint - 0xDC00) + 0x10000
-          block.call(character.chr('UTF-8'))
-        else
-          block.call(codepoint.chr('UTF-8'))
+      codepoint = @unicode_buffer.join.hex
+
+      if codepoint >= 0xD800 && codepoint <= 0xDBFF
+        unless @high_surrogate.nil?
+          raise_error(
+            'Found a high surrogate code point after another high surrogate'
+          )
         end
 
-        # Clear buffer after codepoint is parsed
-        @unicode_buffer.clear
+        @high_surrogate = codepoint
+        @state = STATE_UNICODE_SURROGATE
+      elsif codepoint >= 0xDC00 && codepoint <= 0xDFFF
+        if @high_surrogate.nil?
+          raise_error(
+            'Found a low surrogate code point before a high surrogate'
+          )
+        end
+
+        character = ((@high_surrogate - 0xD800) * 0x400) + (codepoint - 0xDC00) + 0x10000
+        @high_surrogate = nil
+
+        block.call(character.chr('UTF-8'))
+      else
+        unless @high_surrogate.nil?
+          raise_error(
+            "Invalid unicode codepoint '\\U#{codepoint.to_s(16).upcase}' after a high surrogate code point"
+          )
+        end
+
+        block.call(codepoint.chr('UTF-8'))
       end
+
+      # Clear buffer after codepoint is parsed
+      @unicode_buffer.clear
     end
-    # rubocop:enable Style/GuardClause
+    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
     def update_position(ch)
       @offset += 1

data/lib/dotstrings/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DotStrings
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/lib/dotstrings.rb

@@ -6,10 +6,24 @@ require 'dotstrings/item'
 require 'dotstrings/errors'
 
 module DotStrings
+  ##
+  # Parses a file from the given IO object.
+  #
+  # This is a convenience method for {DotStrings::File.parse}.
+  #
+  # @param io [IO] The IO object to parse.
+  # @return [DotStrings::File] The parsed file.
   def self.parse(io)
     File.parse(io)
   end
 
+  ##
+  # Parses a .strings file at the given path.
+  #
+  # This is a convenience method for {DotStrings::File.parse_file}.
+  #
+  # @param path [String] The path to the .strings file to parse.
+  # @return [DotStrings::File] The parsed file.
   def self.parse_file(path)
     File.parse_file(path)
   end

data/test/fixtures/escaped_unicode~bad_surrogate_order.strings

@@ -0,0 +1 @@
+"key" = "\UDC7B\UD83D";

data/test/fixtures/escaped_unicode~duplicated_high_surrogate.strings

@@ -0,0 +1 @@
+"key" = "\UD83D\UD83D";

data/test/fixtures/escaped_unicode~incomplete_surrogate_pair.strings

@@ -0,0 +1 @@
+"key" = "\UD83D";

data/test/fixtures/escaped_unicode~non_surrogate_after_high_surrogate.strings

@@ -0,0 +1 @@
+"key" = "\UD83D\U26A1";

data/test/test_dotstrings.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative 'helper'
+require_relative 'test_helper'
 
 class TestDotStrings < MiniTest::Test
   def test_parse_can_parse_valid_files
@@ -81,6 +81,25 @@ class TestDotStrings < MiniTest::Test
     assert_equal '⚡👻', file.items[0].value
   end
 
+  def test_raises_error_when_bad_surrogate_pair_is_found
+    # rubocop:disable Layout/LineLength
+    test_cases = {
+      'escaped_unicode~bad_surrogate_order.strings' => 'Found a low surrogate code point before a high surrogate at line 1, column 15 (offset: 14)',
+      'escaped_unicode~duplicated_high_surrogate.strings' => 'Found a high surrogate code point after another high surrogate at line 1, column 21 (offset: 20)',
+      'escaped_unicode~incomplete_surrogate_pair.strings' => 'Unexpected character \'"\', expecting another unicode codepoint at line 1, column 16 (offset: 15)',
+      'escaped_unicode~non_surrogate_after_high_surrogate.strings' => 'Invalid unicode codepoint \'\U26A1\' after a high surrogate code point at line 1, column 21 (offset: 20)'
+    }
+    # rubocop:enable Layout/LineLength
+
+    test_cases.each do |filename, error_message|
+      error = assert_raises DotStrings::ParsingError do
+        DotStrings.parse_file("test/fixtures/#{filename}")
+      end
+
+      assert_equal error_message, error.message
+    end
+  end
+
   def test_can_parse_utf16le_files_with_bom
     file = DotStrings.parse_file('test/fixtures/utf16le_bom.strings')
 

data/test/test_file.rb

@@ -1,8 +1,19 @@
 # frozen_string_literal: true
 
-require_relative 'helper'
+require_relative 'test_helper'
 
 class TestFile < MiniTest::Test
+  def test_sort
+    file = DotStrings::File.new([
+      DotStrings::Item.new(key: 'key 3', value: 'value 3'),
+      DotStrings::Item.new(key: 'key 2', value: 'value 2'),
+      DotStrings::Item.new(key: 'key 1', value: 'value 1')
+    ])
+
+    sorted = file.sort
+    assert_equal ['key 1', 'key 2', 'key 3'], sorted.keys
+  end
+
   def test_delete
     items = [
       DotStrings::Item.new(key: 'key 1', value: 'value 1'),
@@ -17,6 +28,17 @@ class TestFile < MiniTest::Test
     assert_equal ['key 1', 'key 3'], file.keys
   end
 
+  def test_delete_if
+    file = DotStrings::File.new([
+      DotStrings::Item.new(key: 'key 1', value: 'value 1'),
+      DotStrings::Item.new(key: 'key 2', value: 'value 2'),
+      DotStrings::Item.new(key: 'key 3', value: 'value 3')
+    ])
+
+    file.delete_if { |item| item.key == 'key 2' }
+    assert_equal ['key 1', 'key 3'], file.keys
+  end
+
   def test_access_by_key
     items = [
       DotStrings::Item.new(key: 'key 1', value: 'value 1'),

data/test/{helper.rb → test_helper.rb}

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
-gem 'minitest'
+require 'simplecov'
+SimpleCov.start
 
+require 'minitest'
 require 'minitest/pride'
 require 'minitest/autorun'
 

data/test/test_item.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative 'helper'
+require_relative 'test_helper'
 
 class TestFile < MiniTest::Test
   def test_to_s

data/test/test_parser.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative 'test_helper'
+
+class TestParser < MiniTest::Test
+  def test_handles_extraneous_characters_at_start_of_file
+    error = assert_raises DotStrings::ParsingError do
+      parser = DotStrings::Parser.new
+      parser << '$'
+    end
+
+    assert_equal "Unexpected character '$' at line 1, column 1 (offset: 0)", error.message
+  end
+
+  def test_handles_malformed_comments
+    error = assert_raises DotStrings::ParsingError do
+      parser = DotStrings::Parser.new
+      parser << '/@ test'
+    end
+
+    assert_equal "Unexpected character '@' at line 1, column 2 (offset: 1)", error.message
+  end
+
+  def test_raises_error_when_escaping_invalid_character
+    error = assert_raises DotStrings::ParsingError do
+      parser = DotStrings::Parser.new
+      parser << '"\\z" = "value";'
+    end
+
+    assert_equal "Unexpected character 'z' at line 1, column 3 (offset: 2)", error.message
+  end
+
+  def test_raises_error_when_items_are_not_separated_by_semicolon
+    error = assert_raises DotStrings::ParsingError do
+      parser = DotStrings::Parser.new
+      parser << '"key_1" = "value_1" "key_2" = "value_2"'
+    end
+
+    assert_equal "Unexpected character '\"', expecting ';' at line 1, column 21 (offset: 20)", error.message
+  end
+
+  def test_raises_error_if_low_surrogate_is_not_formatted_correctly
+    error = assert_raises DotStrings::ParsingError do
+      parser = DotStrings::Parser.new
+      parser << '"key" = "\UD83D\$DC7B";'
+    end
+
+    assert_equal "Unexpected character '$', expecting 'U' at line 1, column 17 (offset: 16)", error.message
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dotstrings
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Ramon Torres
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-07-17 00:00:00.000000000 Z
+date: 2022-08-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -94,6 +94,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Parse and create .strings files used in localization of iOS and macOS
   apps.
 email:
@@ -127,14 +141,19 @@ files:
 - test/fixtures/escaped_single_quotes.strings
 - test/fixtures/escaped_tabs.strings
 - test/fixtures/escaped_unicode.strings
+- test/fixtures/escaped_unicode~bad_surrogate_order.strings
+- test/fixtures/escaped_unicode~duplicated_high_surrogate.strings
+- test/fixtures/escaped_unicode~incomplete_surrogate_pair.strings
+- test/fixtures/escaped_unicode~non_surrogate_after_high_surrogate.strings
 - test/fixtures/utf16be_bom.strings
 - test/fixtures/utf16le_bom.strings
 - test/fixtures/utf8_bom.strings
 - test/fixtures/valid.strings
-- test/helper.rb
 - test/test_dotstrings.rb
 - test/test_file.rb
+- test/test_helper.rb
 - test/test_item.rb
+- test/test_parser.rb
 homepage: https://github.com/raymondjavaxx/dotstrings
 licenses:
 - MIT
@@ -168,11 +187,16 @@ test_files:
 - test/fixtures/escaped_single_quotes.strings
 - test/fixtures/escaped_tabs.strings
 - test/fixtures/escaped_unicode.strings
+- test/fixtures/escaped_unicode~bad_surrogate_order.strings
+- test/fixtures/escaped_unicode~duplicated_high_surrogate.strings
+- test/fixtures/escaped_unicode~incomplete_surrogate_pair.strings
+- test/fixtures/escaped_unicode~non_surrogate_after_high_surrogate.strings
 - test/fixtures/utf16be_bom.strings
 - test/fixtures/utf16le_bom.strings
 - test/fixtures/utf8_bom.strings
 - test/fixtures/valid.strings
-- test/helper.rb
 - test/test_dotstrings.rb
 - test/test_file.rb
+- test/test_helper.rb
 - test/test_item.rb
+- test/test_parser.rb