Release v1.0.0

add tests to better document reference comments

bower.json

@@ -1,6 +1,6 @@
 {
   "name": "pofile",
-  "version": "0.2.9",
+  "version": "1.0.0",
   "authors": [
     "Ruben Vermeersch <ruben@rocketeer.be>"
   ],

dist/pofile.js

@@ -1,4 +1,6 @@
-require=(function e(t,n,r){function s(o,u){if(!n[o]){if(!t[o]){var a=typeof require=="function"&&require;if(!u&&a)return a(o,!0);if(i)return i(o,!0);throw new Error("Cannot find module '"+o+"'")}var f=n[o]={exports:{}};t[o][0].call(f.exports,function(e){var n=t[o][1][e];return s(n?n:e)},f,f.exports,e,t,n,r)}return n[o].exports}var i=typeof require=="function"&&require;for(var o=0;o<r.length;o++)s(r[o]);return s})({"W8CkM0":[function(require,module,exports){
+require=(function e(t,n,r){function s(o,u){if(!n[o]){if(!t[o]){var a=typeof require=="function"&&require;if(!u&&a)return a(o,!0);if(i)return i(o,!0);throw new Error("Cannot find module '"+o+"'")}var f=n[o]={exports:{}};t[o][0].call(f.exports,function(e){var n=t[o][1][e];return s(n?n:e)},f,f.exports,e,t,n,r)}return n[o].exports}var i=typeof require=="function"&&require;for(var o=0;o<r.length;o++)s(r[o]);return s})({"pofile":[function(require,module,exports){
+module.exports=require('W8CkM0');
+},{}],"W8CkM0":[function(require,module,exports){
 var fs = require('fs');
 var isArray = require('lodash.isarray');
 
@@ -8,6 +10,7 @@ function trim(string) {
 
 var PO = function () {
     this.comments = [];
+    this.extractedComments = [];
     this.headers = {};
     this.items = [];
 };
@@ -24,6 +27,11 @@ PO.prototype.toString = function () {
             lines.push('# ' + comment);
         });
     }
+    if (this.extractedComments) {
+        this.extractedComments.forEach(function (comment) {
+            lines.push('#. ' + comment);
+        });
+    }
 
     lines.push('msgid ""');
     lines.push('msgstr ""');
@@ -87,10 +95,11 @@ PO.parse = function (data) {
         acc.push(line);
         return acc;
     }, []).forEach(function (header) {
-        if (header.match(/^#/)) {
+        if (header.match(/^#\./)) {
+            po.extractedComments.push(header.replace(/^#\.\s*/, ''));
+        } else if (header.match(/^#/)) {
             po.comments.push(header.replace(/^#\s*/, ''));
-        }
+        } else if (header.match(/^"/)) {
-        if (header.match(/^"/)) {
             header = header.trim().replace(/^"/, '').replace(/\\n"$/, '');
             var p = header.split(/:/);
             var name = p.shift().trim();
@@ -120,8 +129,32 @@ PO.parse = function (data) {
     function extract(string) {
         string = trim(string);
         string = string.replace(/^[^"]*"|"$/g, '');
-        string = string.replace(/\\"/g, '"');
+        string = string.replace(/\\([abtnvfr'"\\?]|([0-7]{3})|x([0-9a-fA-F]{2}))/g, function (match, esc, oct, hex) {
-        string = string.replace(/\\\\/g, '\\');
+            if (oct) {
+                return String.fromCharCode(parseInt(oct, 8));
+            }
+            if (hex) {
+                return String.fromCharCode(parseInt(hex, 16));
+            }
+            switch (esc) {
+                case 'a':
+                    return '\x07';
+                case 'b':
+                    return '\b';
+                case 't':
+                    return '\t';
+                case 'n':
+                    return '\n';
+                case 'v':
+                    return '\v';
+                case 'f':
+                    return '\f';
+                case 'r':
+                    return '\r';
+                default:
+                    return esc;
+            }
+        });
         return string;
     }
 
@@ -147,9 +180,9 @@ PO.parse = function (data) {
             for (var i = 0; i < flags.length; i++) {
                 item.flags[flags[i]] = true;
             }
-        } else if (line.match(/^#\s+/)) { // Translator comment
+        } else if (line.match(/^#($|\s+)/)) { // Translator comment
             finish();
-            item.comments.push(trim(line.replace(/^#\s+/, '')));
+            item.comments.push(trim(line.replace(/^#($|\s+)/, '')));
         } else if (line.match(/^#\./)) { // Extracted comment
             finish();
             item.extractedComments.push(trim(line.replace(/^#\./, '')));
@@ -213,8 +246,27 @@ PO.Item.prototype.toString = function () {
 
     // reverse what extract(string) method during PO.parse does
     var _escape = function (string) {
-        string = string.replace(/\\/g, '\\\\');
+        // don't unescape \n, since string can never contain it
-        return string.replace(/"/g, '\\"');
+        // since split('\n') is called on it
+        string = string.replace(/[\x07\b\t\v\f\r"\\]/g, function (match) {
+            switch (match) {
+                case '\x07':
+                    return '\\a';
+                case '\b':
+                    return '\\b';
+                case '\t':
+                    return '\\t';
+                case '\v':
+                    return '\\v';
+                case '\f':
+                    return '\\f';
+                case '\r':
+                    return '\\r';
+                default:
+                    return '\\' + match;
+            }
+        });
+        return string;
     };
 
     var _process = function (keyword, text, i) {
@@ -247,7 +299,9 @@ PO.Item.prototype.toString = function () {
         lines.push('#: ' + ref);
     });
 
-    var flags = Object.keys(this.flags);
+    var flags = Object.keys(this.flags).filter(function (flag) {
+        return !!this.flags[flag];
+    }, this);
     if (flags.length > 0) {
         lines.push('#, ' + flags.join(','));
     }
@@ -262,7 +316,12 @@ PO.Item.prototype.toString = function () {
                 });
             } else {
                 text = isArray(text) ? text.join() : text;
-                lines = lines.concat(mkObsolete + _process(keyword, text));
+                var processed = _process(keyword, text);
+                //handle \n in single-line texts (can not be handled in _escape)
+                for (var i = 1; i < processed.length - 1; i++) {
+                    processed[i] = processed[i].slice(0, -1) + '\\n"';
+                }
+                lines = lines.concat(mkObsolete + processed.join('\n' + mkObsolete));
             }
         }
     });
@@ -272,9 +331,7 @@ PO.Item.prototype.toString = function () {
 
 module.exports = PO;
 
-},{"fs":3,"lodash.isarray":4}],"pofile":[function(require,module,exports){
+},{"fs":3,"lodash.isarray":4}],3:[function(require,module,exports){
-module.exports=require('W8CkM0');
-},{}],3:[function(require,module,exports){
 
 },{}],4:[function(require,module,exports){
 /**

lib/po.js

@@ -7,6 +7,7 @@ function trim(string) {
 
 var PO = function () {
     this.comments = [];
+    this.extractedComments = [];
     this.headers = {};
     this.items = [];
 };
@@ -23,6 +24,11 @@ PO.prototype.toString = function () {
             lines.push('# ' + comment);
         });
     }
+    if (this.extractedComments) {
+        this.extractedComments.forEach(function (comment) {
+            lines.push('#. ' + comment);
+        });
+    }
 
     lines.push('msgid ""');
     lines.push('msgstr ""');
@@ -86,10 +92,11 @@ PO.parse = function (data) {
         acc.push(line);
         return acc;
     }, []).forEach(function (header) {
-        if (header.match(/^#/)) {
+        if (header.match(/^#\./)) {
+            po.extractedComments.push(header.replace(/^#\.\s*/, ''));
+        } else if (header.match(/^#/)) {
             po.comments.push(header.replace(/^#\s*/, ''));
-        }
+        } else if (header.match(/^"/)) {
-        if (header.match(/^"/)) {
             header = header.trim().replace(/^"/, '').replace(/\\n"$/, '');
             var p = header.split(/:/);
             var name = p.shift().trim();
@@ -119,8 +126,32 @@ PO.parse = function (data) {
     function extract(string) {
         string = trim(string);
         string = string.replace(/^[^"]*"|"$/g, '');
-        string = string.replace(/\\"/g, '"');
+        string = string.replace(/\\([abtnvfr'"\\?]|([0-7]{3})|x([0-9a-fA-F]{2}))/g, function (match, esc, oct, hex) {
-        string = string.replace(/\\\\/g, '\\');
+            if (oct) {
+                return String.fromCharCode(parseInt(oct, 8));
+            }
+            if (hex) {
+                return String.fromCharCode(parseInt(hex, 16));
+            }
+            switch (esc) {
+                case 'a':
+                    return '\x07';
+                case 'b':
+                    return '\b';
+                case 't':
+                    return '\t';
+                case 'n':
+                    return '\n';
+                case 'v':
+                    return '\v';
+                case 'f':
+                    return '\f';
+                case 'r':
+                    return '\r';
+                default:
+                    return esc;
+            }
+        });
         return string;
     }
 
@@ -146,9 +177,9 @@ PO.parse = function (data) {
             for (var i = 0; i < flags.length; i++) {
                 item.flags[flags[i]] = true;
             }
-        } else if (line.match(/^#\s+/)) { // Translator comment
+        } else if (line.match(/^#($|\s+)/)) { // Translator comment
             finish();
-            item.comments.push(trim(line.replace(/^#\s+/, '')));
+            item.comments.push(trim(line.replace(/^#($|\s+)/, '')));
         } else if (line.match(/^#\./)) { // Extracted comment
             finish();
             item.extractedComments.push(trim(line.replace(/^#\./, '')));
@@ -212,8 +243,27 @@ PO.Item.prototype.toString = function () {
 
     // reverse what extract(string) method during PO.parse does
     var _escape = function (string) {
-        string = string.replace(/\\/g, '\\\\');
+        // don't unescape \n, since string can never contain it
-        return string.replace(/"/g, '\\"');
+        // since split('\n') is called on it
+        string = string.replace(/[\x07\b\t\v\f\r"\\]/g, function (match) {
+            switch (match) {
+                case '\x07':
+                    return '\\a';
+                case '\b':
+                    return '\\b';
+                case '\t':
+                    return '\\t';
+                case '\v':
+                    return '\\v';
+                case '\f':
+                    return '\\f';
+                case '\r':
+                    return '\\r';
+                default:
+                    return '\\' + match;
+            }
+        });
+        return string;
     };
 
     var _process = function (keyword, text, i) {
@@ -246,7 +296,9 @@ PO.Item.prototype.toString = function () {
         lines.push('#: ' + ref);
     });
 
-    var flags = Object.keys(this.flags);
+    var flags = Object.keys(this.flags).filter(function (flag) {
+        return !!this.flags[flag];
+    }, this);
     if (flags.length > 0) {
         lines.push('#, ' + flags.join(','));
     }
@@ -261,7 +313,12 @@ PO.Item.prototype.toString = function () {
                 });
             } else {
                 text = isArray(text) ? text.join() : text;
-                lines = lines.concat(mkObsolete + _process(keyword, text));
+                var processed = _process(keyword, text);
+                //handle \n in single-line texts (can not be handled in _escape)
+                for (var i = 1; i < processed.length - 1; i++) {
+                    processed[i] = processed[i].slice(0, -1) + '\\n"';
+                }
+                lines = lines.concat(mkObsolete + processed.join('\n' + mkObsolete));
             }
         }
     });

package.json

@@ -1,7 +1,7 @@
 {
   "name": "pofile",
   "description": "Parse and serialize Gettext PO files.",
-  "version": "0.2.9",
+  "version": "1.0.0",
   "author": {
     "name": "Ruben Vermeersch",
     "email": "ruben@savanne.be",

test/fixtures/c-strings.po

@@ -17,3 +17,43 @@ msgstr ""
 
 msgid "The name field must not contain characters like \" or \\"
 msgstr ""
+
+# possibility to reorder items depending on locale
+#. Format of addresses
+#. %1$s is the street
+#. %2$s is the postal code
+#. %3$s is the city
+#. %4$s is the state
+#. %5$s is the country
+msgid ""
+"%1$s\n"
+"%2$s %3$s\n"
+"%4$s\n"
+"%5$s"
+msgstr ""
+
+# "i18"ned code
+#. used in <pre> environment, so don't remove any control sequences
+msgid ""
+"define('some/test/module', function () {\n"
+"\t'use strict';\n"
+"\treturn {};\n"
+"});\n"
+""
+msgstr ""
+"define('random/test/file', function () {\n"
+"\t'use strict';\n"
+"\treturn {};\n"
+"});\n"
+""
+
+# all one-letter escape characters
+# be aware, that \a, \b, \v, \f and \r should not be used
+# in i18ned messages (according to gettext tools)
+# however, they should be properly parsed, anyway
+msgid ""
+"\a\b\t\n"
+"\v\f\r"
+msgstr ""
+"\a\b\t\n"
+"\v\f\r"

test/fixtures/comment.po

@@ -1,6 +1,7 @@
 # French translation of Link (6.x-2.9)
 # Copyright (c) 2011 by the French translation team
 #
+#. extracted from test
 msgid ""
 msgstr ""
 "Project-Id-Version: Link (6.x-2.9)\n"
@@ -19,3 +20,11 @@ msgstr ""
 #. Extracted comment
 msgid "Title, as plain text"
 msgstr "Attribut title, en tant que texte brut"
+
+#
+#.
+#:
+#, fuzzy
+msgid "Empty comment"
+msgstr "Empty"
+

test/fixtures/reference.po

@@ -24,3 +24,7 @@ msgstr "Attribut title, en tant que texte brut"
 #: b
 msgid "X"
 msgstr "Y"
+
+#: standard input:12 standard input:17
+msgid "Z"
+msgstr "ZZ"

test/parse.js

@@ -31,10 +31,24 @@ describe('Parse', function () {
         assert.equal(po.headers['Plural-Forms'], 'nplurals=3; plural=n==1 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;');
     });
 
+    it('Handle empty comments', function (done) {
+        PO.load(__dirname + '/fixtures/comment.po', function (err, po) {
+            assert.equal(err, null);
+
+            var item = po.items[1];
+            assert.equal(item.msgid, 'Empty comment');
+            assert.equal(item.msgstr, 'Empty');
+            assert.deepEqual(item.comments, ['']);
+            assert.deepEqual(item.extractedComments, ['']);
+            assert.deepEqual(item.references, ['']);
+            done();
+        });
+    });
+
     it('Handles translator comments', function () {
         var po = PO.parse(fs.readFileSync(__dirname + '/fixtures/comment.po', 'utf8'));
         assert.notEqual(po, null);
-        assert.equal(po.items.length, 1);
+        assert.equal(po.items.length, 2);
 
         var item = po.items[0];
         assert.equal(item.msgid, 'Title, as plain text');
@@ -45,7 +59,10 @@ describe('Parse', function () {
     it('Handles extracted comments', function () {
         var po = PO.parse(fs.readFileSync(__dirname + '/fixtures/comment.po', 'utf8'));
         assert.notEqual(po, null);
-        assert.equal(po.items.length, 1);
+        assert.equal(po.items.length, 2);
+
+        assert.equal(po.extractedComments.length, 1);
+        assert.equal(po.extractedComments[0], 'extracted from test');
 
         var item = po.items[0];
         assert.equal(item.msgid, 'Title, as plain text');
@@ -53,23 +70,34 @@ describe('Parse', function () {
         assert.deepEqual(item.extractedComments, ['Extracted comment']);
     });
 
-    it('Handles string references', function () {
+    describe('Handles string references', function () {
         var po = PO.parse(fs.readFileSync(__dirname + '/fixtures/reference.po', 'utf8'));
         assert.notEqual(po, null);
-        assert.equal(po.items.length, 2);
+        assert.equal(po.items.length, 3);
 
+        it('in simple cases', function () {
             var item = po.items[0];
             assert.equal(item.msgid, 'Title, as plain text');
             assert.equal(item.msgstr, 'Attribut title, en tant que texte brut');
             assert.deepEqual(item.comments, ['Comment']);
             assert.deepEqual(item.references, ['.tmp/crm/controllers/map.js']);
+        });
 
-        item = po.items[1];
+        it('with two different references', function () {
+            var item = po.items[1];
             assert.equal(item.msgid, 'X');
             assert.equal(item.msgstr, 'Y');
             assert.deepEqual(item.references, ['a', 'b']);
         });
 
+        it('and does not process reference items', function () {
+            var item = po.items[2];
+            assert.equal(item.msgid, 'Z');
+            assert.equal(item.msgstr, 'ZZ');
+            assert.deepEqual(item.references, ['standard input:12 standard input:17']);
+        });
+    });
+
     it('Parses flags', function () {
         var po = PO.parse(fs.readFileSync(__dirname + '/fixtures/fuzzy.po', 'utf8'));
         assert.notEqual(po, null);
@@ -119,19 +147,29 @@ describe('Parse', function () {
     });
 
     describe('C-Strings', function () {
-        it('should parse the c-strings.po file', function () {
         var po = PO.parse(fs.readFileSync(__dirname + '/fixtures/c-strings.po', 'utf8'));
-
+        it('should parse the c-strings.po file', function () {
             assert.notEqual(po, null);
         });
 
         it('should extract strings containing " and \\ characters', function () {
-            var po = PO.parse(fs.readFileSync(__dirname + '/fixtures/c-strings.po', 'utf8'));
-
             var items = po.items.filter(function (item) {
                 return (/^The name field must not contain/).test(item.msgid);
             });
             assert.equal(items[0].msgid, 'The name field must not contain characters like " or \\');
         });
+
+        it('should handle \\n characters', function () {
+            var item = po.items[1];
+            assert.equal(item.msgid, '%1$s\n%2$s %3$s\n%4$s\n%5$s');
+        });
+
+        it('should handle \\t characters', function () {
+            var item = po.items[2];
+            assert.equal(item.msgid, 'define(\'some/test/module\', function () {\n' +
+                '\t\'use strict\';\n' +
+                '\treturn {};\n' +
+                '});\n');
+        });
     });
 });

test/write.js

@@ -16,6 +16,20 @@ function assertHasLine(str, line) {
     assert(found, 'Could not find line: ' + line);
 }
 
+function assertDoesntHaveLine(str, line) {
+    var lines = str.split('\n');
+    var found = false;
+
+    for (var i = 0; i < lines.length; i++) {
+        if (lines[i].trim() === line) {
+            found = true;
+            break;
+        }
+    }
+
+    assert(!found, 'Shouldn\'t have line: ' + line);
+}
+
 describe('Write', function () {
     it('write flags', function () {
         var input = fs.readFileSync(__dirname + '/fixtures/fuzzy.po', 'utf8');
@@ -24,6 +38,17 @@ describe('Write', function () {
         assertHasLine(str, '#, fuzzy');
     });
 
+    it('write flags only when true', function () {
+        var input = fs.readFileSync(__dirname + '/fixtures/fuzzy.po', 'utf8');
+        var po = PO.parse(input);
+
+        // Flip flag
+        po.items[0].flags.fuzzy = false;
+
+        var str = po.toString();
+        assertDoesntHaveLine(str, '#, fuzzy');
+    });
+
     it('write msgid', function () {
         var input = fs.readFileSync(__dirname + '/fixtures/fuzzy.po', 'utf8');
         var po = PO.parse(input);
@@ -49,6 +74,7 @@ describe('Write', function () {
         var input = fs.readFileSync(__dirname + '/fixtures/comment.po', 'utf8');
         var po = PO.parse(input);
         var str = po.toString();
+        assertHasLine(str, '#. extracted from test');
         assertHasLine(str, '#. Extracted comment');
     });
 
@@ -92,6 +118,15 @@ describe('Write', function () {
             assertHasLine(item.toString(), 'msgid "\\\\ should be written escaped"');
         });
 
+        it('should escape \\n', function () {
+            var item = new PO.Item();
+
+            item.msgid = '\n should be written escaped';
+            assertHasLine(item.toString(), 'msgid ""');
+            assertHasLine(item.toString(), '"\\n"');
+            assertHasLine(item.toString(), '" should be written escaped"');
+        });
+
         it('should write identical file after parsing a file', function () {
             var input = fs.readFileSync(__dirname + '/fixtures/c-strings.po', 'utf8');
             var po = PO.parse(input);