dotstrings 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9c320ba9bef4d63af10c9c9fd3d91ad41da99b3663538f0b89ebdc6fc780d31
-  data.tar.gz: 24e762927cd739f3475a8a550a751f808dd81d73292e47f7449c657edeaa88db
+  metadata.gz: 334f5c70b24599274f9e48180edc217e272305dc0880ceceb12588314ee29173
+  data.tar.gz: de469892a932333e2995b0b9ee8919fed43861186805f343f6f0ba43e70d2297
 SHA512:
-  metadata.gz: f24ad0efde29b52a33f28cd0e434970bde12556d9236c632495eebdfd089ed550e54a41f67fb844c70677c53bbdaccdbb93f593cafd535062532f062297ab7b4
-  data.tar.gz: d61a17f762188162a431c6289b96e23d4374ca2a29a82e84b58e92bf097d79746a352418859e12c2d1dcf13c8844a53a9975360be6c0a98f65d046c16aba45cc
+  metadata.gz: 17b42c2392f3bb05695e64c0d8f61134f9b78edb598ccefbd90ace096705cf871b4861fac378646ace56ebc545e88987dd46c5342bebfa8d3575e957a45423d7
+  data.tar.gz: eeabf73dfe816634936ebf46eba3e09e729842c2af5497674e7ee3d474c46b7e58f7838904cb60c6c075e4c42a64b48a8e9b99d1624e2a39202e601492ef615a

data/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## [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.
@@ -24,6 +27,7 @@
 ### Added
 * Initial release.
 
+[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
@@ -188,6 +193,8 @@ module DotStrings
       end
     end
 
+    # rubocop:disable Metrics/CyclomaticComplexity
+
     def parse_escaped_character(ch)
       @escaping = false
 
@@ -206,11 +213,15 @@ 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
 
@@ -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.5.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.5.0
 platform: ruby
 authors:
 - Ramon Torres
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-09-18 00:00:00.000000000 Z
+date: 2022-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -145,8 +145,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project:
-rubygems_version: 2.7.6
+rubygems_version: 3.1.2
 signing_key:
 specification_version: 4
 summary: Parse and create .strings files used in localization of iOS and macOS apps.