rylev / apfel

A lightweight .strings file parser written in Ruby

Apfel

Introduction

Apfel is simple parser for .strings (DotStrings) files written in Ruby. DotStrings files are used by Apple platforms for localization. Apfel reads DotStrings files, parses them for key-value pairs and comments.

Once in the form of a hash, the content of the DotStrings file can easily be rebuilt as JSON, XML and RESX (with the help of Builder https://github.com/jimweirich/builder) and more!

Use

To start using Apfel first require the gem

require 'apfel'

Next, pass Apfel the .strings file you want to parse:

parsed_file = Apfel.parse('path/to/file')

Once the file has been parsed, you can do many things with it:

# Turn it into a ruby hash (includes comments)
parsed_file.to_hash

# Turn it into json (includes comments)
parsed_file.to_json

# With either #to_hash or #to_json you can specify
# whether you want the comments included
parsed_file.to_hash(with_comments: false)

# Get all the keys as an array
parsed_file.keys

# Get all the values as an array
parsed_file.values

# Return an array of key-value hashes
parsed_file.key_values

# Return an array of key-comment hashes
parsed_file.comments

# Return an array of all the comments without their keys
parsed_file.comments(with_keys: false)

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Commit tests (they should pass when rake is run)
5. Push to the branch (git push origin my-new-feature)
6. Create new Pull Request

apfel's Issues

Does not handle // comments at end of line, and error message does not say which line

RuntimeError because some of my lines didn't end with ";", while Xcode (or whichever Apple tool handles this) doesn't have any problem with it (not even a warning).

I believe that a "//" comment at the end of a line should be considered a comment belonging to the previous pair if on the same line, whereas when it is on a line of its own it should be attached to the following one instead. Personally I only use #to_hash(with_comments:false) but for those who do care about keeping comments, this rule would match how people use "//" in any source code that I know.

Also, error messages should say which line of the file it failed in, and ideally which file too, though for the latter it's easier to trace from one's own program, whereas for the line number I had to edit Apfel's dot_strings_parser.rb to add numbers, e.g.

linenum=0
@read_file.each do |content_line|
  linenum+=1
  current_line = begin Line.new(content_line)
    rescue Exception => e
    throw RuntimeError.new("at line #{linenum}: #{e.message}") end

Does not handle escaped strings

Like so:

"\".\" Shortcut" = "„.“ Kurzbefehl";

This fails the key value checker:

def key_value_pair?
  !!(/^\s*"([^"]+)"\s*=/.match(content))
end

and results to the key-value output being nil