Release v0.2.2

README.md

@@ -1,30 +1,163 @@
-Used to load and save PO files.
+# pofile - gettext .po parsing for JavaScript
+
+> Parse and serialize Gettext PO files.
+
+[![Build Status](https://travis-ci.org/rubenv/pofile.png?branch=master)](https://travis-ci.org/rubenv/pofile)
+
+## Usage
+Add pofile to your project:
+
+### Installation (Node.JS, browser via Browserified)
+```
+npm install --save pofile
+```
+
+Reference it in your code:
 
 ```js
 var PO = require('pofile');
+```
 
+### Installation (via bower)
+```
+bower install --save pofile
+```
+
+Add it to your HTML file:
+
+```html
+<script src="bower_components/pofile/dist/pofile.js"></script>
+```
+
+Reference it in your code:
+
+```js
+var PO = require('pofile');
+```
+
+### Loading and parsing
+
+You can create a new empty PO file by using the class:
+
+```js
+var po = new PO();
+```
+
+Or by loading a file (Node.JS only):
+
+```js
 PO.load('text.po', function (err, po) {
     // Handle err if needed
-    console.log(po.headers);
-    console.log(po.items);
-  
-    po.save('copy.po', function (err) {
-        // Handle err if needed
-        console.log('We copied a PO file for no reason!');
-    });
+    // Do things with po
 });
 ```
 
+Or by parsing a string:
+
+```js
+var po = PO.parse(myString);
+```
+
+### The PO class
+
+The `PO` class exposes three members:
+
+* `comments`: An array of comments (found at the header of the file).
+* `headers`: A dictionary of the headers.
+* `items`: An array of `PO.Item` objects, each of which represents a string
+  from the gettext catalog.
+
+There are two methods available:
+
+* `save`: Accepts a filename and callback, writes the po file to disk.
+
+```js
+po.save('out.po', function (err) {
+    // Handle err if needed
+});
+```
+
+* `toString`: Serializes the po file to a string.
+
+### The PO.Item class
+
+The `PO` class exposes the following members:
+
+* `msgid`: The message id.
+* `msgid_plural`: The plural message id (null if absent).
+* `msgstr`: An array of translated strings. Items that have no plural msgid
+  only have one element in this array.
+* `references`: An array of reference strings.
+* `comments`: An array of string comments.
+* `flags`: A dictionary of the string flags. Each flag is mapped to a key with
+  value true. For instance, a string with the fuzzy flag set will have
+  `item.flags.fuzzy == true`.
+
+
+## Contributing
+
+In lieu of a formal styleguide, take care to maintain the existing coding
+style. Add unit tests for any new or changed functionality. Lint and test your
+code using [Grunt](http://gruntjs.com/).
+
 ## Credits
 
-  Originally based on node-po (written by Michael Holly). Rebranded because
-  node-po is unmaintained and because this library is no longer limited to
-  Node.JS: it works in the browser too.
+Originally based on node-po (written by Michael Holly). Rebranded because
+node-po is unmaintained and because this library is no longer limited to
+Node.JS: it works in the browser too.
 
-  Changes compared to node-po:
+### Changes compared to node-po
 
-  * Proper handling of async methods that won't crash your Node.JS process when
-    something goes wrong.
-  * Support for parsing string flags (e.g. fuzzy).
-  * A test suite.
-  * Browser support (through Browserified and bower).
+* Proper handling of async methods that won't crash your Node.JS process when
+  something goes wrong.
+* Support for parsing string flags (e.g. fuzzy).
+* A test suite.
+* Browser support (through Browserified and bower).
+
+### Migrating from node-po
+
+You'll need to update the module reference: `require('pofile')` instead of
+`require('node-po')`.
+
+At the initial release, node-po and pofile have identical APIs, with one small
+exception: the `save` and `load` methods now take a callback that has an `err`
+parameter: `(err)` for `save` and `(err, po)` for `load`. This is similar to
+Node.JS conventions.
+
+Change code such as:
+
+```js
+PO.load('text.po', function (po) {
+```
+
+To:
+
+```js
+PO.load('text.po', function (err, po) {
+    // Handle err if needed
+```
+
+## License 
+
+    (The MIT License)
+
+    Copyright (C) 2013 by Ruben Vermeersch <ruben@rocketeer.be>
+    Copyright (C) 2012 by Michael Holly
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in
+    all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+    THE SOFTWARE.

bower.json

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

package.json

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