MPC File Format

Working draft 1.1.

Preface

MPC file format is a format for bundling source code in different programming languages into one file. The syntax is optimized for reading and writing by humans.

Recomendations for the requirements and exports parts are added to simplify extracting dependency information and compiling multi-part components into modules in the target language.

Example MPC file

--- partA ---

partContent
partContent

--- partB ---------------

partContent
partContent

Structure

An MPC file is a UTF-8 text file without byte order marks.

The file is made from parts. Each part is made from its header and content.

A part header is made from:

1. an empty first line
2. second line consisting of:
   1. 3 minus characters
   2. a space character
   3. part name without spaces or special characters
   4. a space character
   5. 3 or more minus characters
3. an empty third line

The first empty line must be omitted at the beginning of a file.

Thus an MPC file must begin with a byte sequence 2d 2d 2d 20 followed by a letter.

Part content may be in any format as long as it does not contain part headers.

It is up to the human writer of an MPC file to ensure this requirement.

Recommendations

Requirements part

It is recommended that multi-part components expose their interdependencies in a part named requirements.

Example Requirements part

--- requirements ---

componentB
directoryC/componentD

../directoryE/componentF
/full/path/to/componentG
importNameForH: componentH

This part will consist of lines. Each line can be one of:

• an empty line (these will be ignored),
• a line containing a component URL (except finder URLs – see below),
• a line containing
  1. import name for the component,
  2. followed by a column character :,
  3. and followed by the component URL relative to the file that is being parsed.

Component URL

A component URL can be one of:

• an absolute filesystem path without an extension (e.g. /path/to/component),

• a relative filesystem path without an extension (e.g. ./sibling, ../uncle),

• a filesystem path in the includePath without an extension (e.g. path/to/component),

• a schemaless URL (e.g. `//example.org/path/to/component )

• a finder URL consisting of:

  1. a finder name (e.g. npm, github, bower)
  2. followed by a column character :,
  3. and followed by a string identifying the component which is passed to the relevant finder.

  (e.g. bower:jquery).

Exports part

It is recommended that multi-part components expose their API via a part named exports.

Example Exports part

--- exports ---

exportA
exportB: internalNameForExportB

exportC: createC( withParameter )

This part will consist of lines. Each line can be one of:

• an empty line (these will be ignored),
• a line containing export name if it is the same as the internal name for the exported value,
• a line containing export name followed by a column character :, followed by an internal name for the exported value
• a line containing export name followed by a column character :, followed by a one-line snippet of code that produces the exported value

Whitespace in Requirements and Exports

Whitespace characters will be ignored at:

• the beginning of line
• the end of line
• before the first column character
• after the first column character

For a possible parser implementation see this.

Further considerations

The current requirement for the allowed characters in part names is vague. This is intentionally so, until a format is found to describe both the purpose and the syntax of a part content. Whatever you use, you should definately avoid spaces, periods ., slashes / and backslashes \ in part names.

MPC file format is not intended to be used as a packaging/archiving format. Whatever problems may arise in trying to generate MPC files automaticly will be overriden by the goals of human readability and ease of writing in the further development of this format.

Recommendation for specifying requirements that should be fetched over the network will be added in the near future. If you have expertise to share, please send me your suggestions.

I am sorry for any errors or ambiguities in this document and warmly welcome your feedback.

Contributing

You can edit this document on GitHub.

Please send your feedback to Emilis Dambauskas emilis.d@gmail.com.