txt: ## dist_cpan-JNTHN-POFile.md
  ### NAME
  
  POFile - Perl 6 module for manipulating data in PO files.
  
  ### SYNOPSIS
  
  ```
  use POFile;
  my $po = POFile.load('foo.po');
  
  say $po.obsolete-messages; # list of obsolete messages
  say $result[0]; # POFile::Entry object at 0 index
  say $result{'Splash text'}; # POFile::Entry object with msgid `Splash text`
  for @$po -> $item {
      say $item.reference; # 'finddialog.cpp:38'
      say $item.msgstr; # msgstr value
      $item.msgstr = update($item.msgstr); # Do some update
  }
  $po.save('foo-updated.po');
  
  ```
  
  ### DESCRIPTION
  
  The `.po` file as a whole is represented by the `POFile` class, which
  holds a `POFile::Entry` object per entry in the PO file.
  
  ##### POFile::Entry
  
  `POFile::Entry` represents a single record in PO file, and has its
  fields as attributes: `msgid`, `msgid-plural`, `msgstr`, `msgctxt`,
  `reference` (reference comment), `extracted` (extracted comment),
  `comment` (translator comment), `format-style`, `fuzzy-msgid`,
  `fuzzy-msgctxt`. All these attributes are set read/write.
  
  You can create a single `POFile::Entry` object from a `Str` using the
  `POFile::Entry.parse($str)` method.
  
  The `msgid` and `msgstr` accessors always provided unquoted values;
  the methods `msgid-quoted` and `msgstr-quoted` are present to provide
  access to the quoted messages.
  
  The value of `msgstr` attribute might be either `Str` or `Array`, and
  is based on value of `msgid-plural` attribute:
  
  ```
  with $po.msgid-plural {
      say $po.msgid; # Singular form
      say $_; # Plural form
      for $po.msgstr -> $form {
          say $form; # Every plural form of end language
      }
  }
  
  ```
  
  You can serialize an entry with `Str` method or its `~` shortcut:
  
  ```
  my $po-entry = $po[1]; # Get second entry
  say ~$po-entry;    # Serialized 1
  say $po-entry.Str; # Serialized 2
  
  ```
  
  Note that *no line wrapping* is done by the module.
  
  ##### POFile
  
  `POFile` provides access to `POFile::Entry` objects using either index
  (position in original file) or key (msgid value). It must be noted
  that this module provides hash-like access by msgid, which might not
  be unique. Please consider that *only array access* is stable in this
  case. Use hash access you know *for sure* there are no items with the
  same `msgid`, yet different `msgctxt`.
  
  `POFile` also contains all obsolete messages, which can be accessed using
  `obsolete-messages` attribute.
  
  You can create from scratch a new `POFile` object and populate it with
  entries, as well as delete entries by id or by key:
  
  ```
  my $po = POFile.new;
  $result.push(POFile::Entry.parse(...));
  $result.push(POFile::Entry.parse(...));
  $po[0]:delete;
  $po{'my msgid'}:delete;
  
  ```
  
  As well as `POFile::Entry`, you can serialize a `POFile` object
  calling `Str` method on it.
  
  ##### Escaping
  
  Additionally, two routines are available to escape and unescape strings accordingly to
  rules described for PO format.
  
  ```
  use POFile :quoting;
  
  say po-unquote(｢\t\"\\\n｣); # ｢\t"\\n｣      <- unquoting
  say po-quote(｢\t"\\n\｣);    # ｢\t\"\\\n\\｣  <- quoting
  
  ```
  