dotstrings 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9c320ba9bef4d63af10c9c9fd3d91ad41da99b3663538f0b89ebdc6fc780d31
-  data.tar.gz: 24e762927cd739f3475a8a550a751f808dd81d73292e47f7449c657edeaa88db
+  metadata.gz: 3043892fd5f3068811c63cd3da980cfef6779522359be1974dea0b3be6d4f60c
+  data.tar.gz: eb04dbb9ff868273b783a1f8337d4cd11098cc0450a4676beb241a0b88e49dff
 SHA512:
-  metadata.gz: f24ad0efde29b52a33f28cd0e434970bde12556d9236c632495eebdfd089ed550e54a41f67fb844c70677c53bbdaccdbb93f593cafd535062532f062297ab7b4
-  data.tar.gz: d61a17f762188162a431c6289b96e23d4374ca2a29a82e84b58e92bf097d79746a352418859e12c2d1dcf13c8844a53a9975360be6c0a98f65d046c16aba45cc
+  metadata.gz: 53c29b660b3af9ab6795080176567edc8950c4df357a86d5845b6c4166aad593812a9529d6ec2b333c8cfa1996953c7df1ece183d6ac7011eaa1517c9461eeba
+  data.tar.gz: bb1a56e77beae28a1a3b1fc52c47096448731db40cd81905e7cfb9652aa9836d93a2a756cf674d7679dc7e45842c70dbde59f70cf214847e167c96015a92b949

data/CHANGELOG.md

@@ -1,29 +1,50 @@
 # Changelog
 
+## [v0.6.0] - 2024-02-27
+
+- Dropped support for Ruby 2.5.
+- Small performance improvements for unicode parsing.
+
+## [v0.5.0] - 2022-09-24
+
+- Added `strict` parameter to the parser to allow for more lenient parsing. This is useful in cases where we don't want the parser to raise an error when encountering multiple comments or escaped characters that don't need to be escaped.
+
 ## [v0.4.0] - 2022-09-18
+
 ### Added
-* Added `DotStrings::File#each`, `DotStrings::File#length`, `DotStrings::File#count`, and `DotStrings::File#empty?` methods.
-* Allow comparing `DotStrings::File` objects.
+
+- Added `DotStrings::File#each`, `DotStrings::File#length`, `DotStrings::File#count`, and `DotStrings::File#empty?` methods.
+- Allow comparing `DotStrings::File` objects.
 
 ## [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.
+
+- 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.
-* Added option to ignore comments when serializing.
+
+- Made some state transitions more strict.
+- Added option to ignore comments when serializing.
 
 ## [v0.1.1] - 2022-07-12
+
 ### Changed
-* Escaping single quotes is now optional.
+
+- Escaping single quotes is now optional.
 
 ## [v0.1.0] - 2022-07-06
+
 ### Added
-* Initial release.
 
+- Initial release.
+
+[v0.6.0]: https://github.com/raymondjavaxx/dotstrings/releases/tag/v0.6.0
+[v0.5.0]: https://github.com/raymondjavaxx/dotstrings/releases/tag/v0.5.0
 [v0.4.0]: https://github.com/raymondjavaxx/dotstrings/releases/tag/v0.4.0
 [v0.3.0]: https://github.com/raymondjavaxx/dotstrings/releases/tag/v0.3.0
 [v0.2.0]: https://github.com/raymondjavaxx/dotstrings/releases/tag/v0.2.0

data/README.md

@@ -36,15 +36,32 @@ file.items.each do |item|
 end
 ```
 
-## Examples
+## Strict Mode
+
+By default, the parser runs in *strict mode*. This means that it will raise a `DotStrings::ParsingError` if it encounters comments that are not tied to a key-value pair. For example, the following file will raise an error because the first comment is not followed by a key-value pair:
 
-### Listing keys
+```
+/* Spanish localizations */
+
+/* Title for a button for accepting something */
+"Accept" = "Aceptar";
+```
+
+In *strict mode*, the parser will also raise an error if it encounters escaped characters that don't need to be escaped. For example, the following file will raise an error because the `?` character doesn't need to be escaped:
+
+```
+/* Confirmation message */
+"Are you sure\?" = "¿Estás seguro\?";
+```
+
+If you want to disable *strict mode*, you can pass `strict: false` to the `DotStrings.parse_file()` method. This will match the behavior of Apple's own parser, which is more lenient.
 
 ```ruby
-puts file.keys
-# => ["key 1", "key 2", ...]
+file = DotStrings.parse_file('es-ES/Localizable.strings', strict: false)
 ```
 
+## Examples
+
 ### Accessing items by key
 
 ```ruby
@@ -73,3 +90,5 @@ file << DotStrings::Item(
 ```ruby
 File.write('en-US/Localizable.strings', file.to_s)
 ```
+
+For more examples, consult the [documentation](https://www.rubydoc.info/gems/dotstrings/DotStrings) or the [test suite](test).

data/lib/dotstrings/file.rb

@@ -45,12 +45,13 @@ module DotStrings
     #   file = DotStrings::File.parse(io)
     #
     # @param io [IO] The IO object to parse.
+    # @param strict [Boolean] Whether to parse in strict mode.
     # @return [DotStrings::File] The parsed file.
     # @raise [DotStrings::ParsingError] if the file could not be parsed.
-    def self.parse(io)
+    def self.parse(io, strict: true)
       items = []
 
-      parser = Parser.new
+      parser = Parser.new(strict: strict)
       parser.on_item { |item| items << item }
       parser << normalize_encoding(io.read)
 
@@ -64,11 +65,12 @@ module DotStrings
     #   file = DotStrings::File.parse_file('path/to/en.lproj/Localizable.strings')
     #
     # @param path [String] The path to the file to parse.
+    # @param strict [Boolean] Whether to parse in strict mode.
     # @return [DotStrings::File] The parsed file.
     # @raise [DotStrings::ParsingError] if the file could not be parsed.
-    def self.parse_file(path)
+    def self.parse_file(path, strict: true)
       ::File.open(path, 'r') do |file|
-        parse(file)
+        parse(file, strict: strict)
       end
     end
 

data/lib/dotstrings/parser.rb

@@ -7,6 +7,9 @@ module DotStrings
 
   ##
   # Parser for .strings files.
+  #
+  # You can use this class directly, but it is recommended to use
+  # {File.parse} and {File.parse_file} wrappers instead.
   class Parser
     # Special tokens
     TOK_SLASH        = '/'
@@ -39,7 +42,13 @@ module DotStrings
     STATE_UNICODE_SURROGATE   = 11
     STATE_UNICODE_SURROGATE_U = 12
 
-    def initialize
+    ##
+    # Returns a new Parser instance.
+    #
+    # @param strict [Boolean] Whether to parse in strict mode.
+    def initialize(strict: true)
+      @strict = strict
+
       @state = STATE_START
       @temp_state = nil
 
@@ -101,11 +110,7 @@ module DotStrings
             @buffer << ch
           end
         when STATE_COMMENT_END
-          if ch == TOK_QUOTE
-            @state = STATE_KEY
-          else
-            raise_error("Unexpected character '#{ch}'") unless whitespace?(ch)
-          end
+          comment_end(ch)
         when STATE_KEY
           parse_string(ch) do |key|
             @current_key = key
@@ -174,7 +179,7 @@ module DotStrings
 
     def parse_string(ch, &block)
       if @escaping
-        parse_escaped_character(ch, &block)
+        parse_escaped_character(ch)
       else
         case ch
         when TOK_BACKSLASH
@@ -188,6 +193,8 @@ module DotStrings
       end
     end
 
+    # rubocop:disable Metrics/CyclomaticComplexity
+
     def parse_escaped_character(ch)
       @escaping = false
 
@@ -206,13 +213,17 @@ module DotStrings
       when TOK_ZERO
         @buffer << "\0"
       else
-        raise_error("Unexpected character '#{ch}'")
+        raise_error("Unexpected character '#{ch}'") if @strict
+        @buffer << ch
       end
     end
 
+    # rubocop:enable Metrics/CyclomaticComplexity
+
     # 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
+      raise_error("Unexpected character '#{ch}', expecting a hex digit") unless TOK_HEX_DIGIT.match?(ch)
 
       @unicode_buffer << ch
 
@@ -267,19 +278,33 @@ module DotStrings
       end
     end
 
-    def start_value(ch)
+    def start_value(ch, resets: true)
       case ch
       when TOK_SLASH
         @state = STATE_COMMENT_START
-        reset_state
+        reset_state if resets
       when TOK_QUOTE
         @state = STATE_KEY
-        reset_state
+        reset_state if resets
       else
         raise_error("Unexpected character '#{ch}'") unless whitespace?(ch)
       end
     end
 
+    def comment_end(ch)
+      if @strict
+        # In strict mode, we expect a key to follow the comment.
+        if ch == TOK_QUOTE
+          @state = STATE_KEY
+        else
+          raise_error("Unexpected character '#{ch}'") unless whitespace?(ch)
+        end
+      else
+        # In lenient mode, we allow comments to be followed by anything.
+        start_value(ch, resets: false)
+      end
+    end
+
     def reset_state
       @current_comment = nil
       @current_key = nil

data/lib/dotstrings/version.rb

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

data/lib/dotstrings.rb

@@ -12,9 +12,10 @@ module DotStrings
   # This is a convenience method for {DotStrings::File.parse}.
   #
   # @param io [IO] The IO object to parse.
+  # @param strict [Boolean] Whether to parse in strict mode.
   # @return [DotStrings::File] The parsed file.
-  def self.parse(io)
-    File.parse(io)
+  def self.parse(io, strict: true)
+    File.parse(io, strict: strict)
   end
 
   ##
@@ -23,8 +24,9 @@ module DotStrings
   # This is a convenience method for {DotStrings::File.parse_file}.
   #
   # @param path [String] The path to the .strings file to parse.
+  # @param strict [Boolean] Whether to parse in strict mode.
   # @return [DotStrings::File] The parsed file.
-  def self.parse_file(path)
-    File.parse_file(path)
+  def self.parse_file(path, strict: true)
+    File.parse_file(path, strict: strict)
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dotstrings
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Ramon Torres
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-09-18 00:00:00.000000000 Z
+date: 2024-02-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -56,30 +56,30 @@ dependencies:
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.50.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.50.2
 - !ruby/object:Gem::Dependency
   name: rubocop-minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.30.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.30.0
 - !ruby/object:Gem::Dependency
   name: rubocop-rake
   requirement: !ruby/object:Gem::Requirement
@@ -138,15 +138,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.5.0
+      version: 2.6.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project:
-rubygems_version: 2.7.6
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: Parse and create .strings files used in localization of iOS and macOS apps.