This describes current and future output file formats.

Current: Everything is text.
- One sample per line in file.
- Each sample consists of:
  - An integer indicating sample weight, followed by an arbitrary number of stack frames,
    followed by the name of the most recently executed OP.
  - Weight, stack frames, and OP name are separated by a semicolon.
  - Each stack frame consists of:
    - The type of the stack frame (integer, meaning defined in the perl sources)
    - package
    - file/path
    - line
    - All parts of the stack frame are separated by a comma.

Future:
- Offsets in the file are generally measured in bytes from the start of the file.
- When referring to a string, unless otherwise stated, the string is represented
  as a flag byte followed by varint-encoded string length followed by a string of
  bytes without terminating NULL. The flag byte currently contains:
  least significant bit: UTF-8 string if set
- The file consists of a document header and a document body.
- The header starts with magic string "=statprofiler" followed by the version
  of the file format, encoded as a varint.
- The rest of the header consists of a number of meta data records, some mandatory,
  some optional. The header is ended by a special separator record, see the table
  below.
- A record has the structure:
  <tag byte> <varint-encoded length> <payload string of previously encoded length>
  The length is always present, even when the tag does not have a payload.
- The document body consists of a chain of records.
- All record types that are valid in the document BODY are followed by
  a varint indicating the total record size.
- The set of valid tags are:
  0: unused
  1: a sample-start record (payload: - sample weight as varint,
                                     - # of stack frames in sample as varint
                                     - name of topmost OP as string)
  2: a sample-end record (followed by just a 0-varint)
  3: a regular stack-frame record (payload: - package/sub name as string
                                            - file name as string
                                            - line number as varint)
  4: an eval stack-frame record (TODO!)
  198: section start marker (payload: section name string)
  199: section end marker (payload: section name string)
  200: custom meta data (header or body) (payload: meta data key string, meta data value string)
  201: header meta data: Perl version (payload: three varints for the three parts of the Perl version)
  202: header meta data: tick duration in ns (as varint)
  203: header meta data: sampling stack depth (as varint)
  204: header meta data: Devel::StatProfiler version (as major version varint, minor version varint)
  254: separation marker between header and body. Also document-end marker. (has no payload)
  255: Continuation marker (unused)

Notes:
- For the time being, meta data other than section start/end markers must be
  in the header.
- A Perl version, tick duration, sampling stack depth, and statprofiler version meta data
  must be present in the header.
- Any stack frame records must appear within a sample start and end records. They will
  be associated with the currently opened sample in order.
- Custom meta data is to be assembled in a dictionary.
- Section information must not appear within a sample.
