RFC: Config file format

[mmatyas]

Ok, here is the current concept for Pegasus' own config and metadata files. This is something I wouldn't want to change once it's implemented so feel free to share your opinions. There's also a GitHub issue [here].

How it works

Pegasus will store a list of directories that will be checked for games/roms. In every of such directory, there should be a file that describes (one or more) collections, and another that describes metadata for each game. The proposed name for them is collections.pegasus.txt and metadata.pegasus.txt.

File format

As a user (of my own program in this case), I want a simple text file in simple, readable format, that I can edit on any platform with any (minimally competent) text editor. I don't want to care about implementation details: I'm not going to hunt missing XML-tags, curly braces, semicolons or tabs/spaces. However, it must support Unicode text, multiline values and simple lists. It should be easy to edit and extend, yet something that doesn't take forever to read by the program.

Here's a more technical definition of the format, with examples for both the collections and metadata file further below. It was mainly inspired by the INI, Debian-control and nodejs-ini/npmrc formats, so some things might be familiar:

• the files are in Unicode (UTF-8 encoded without BOM)
• both the Unix and Windows-style line endings are supported, with Unix being preferred
• the file is processed line by line
• lines starting with # or ; are comments, and empty lines are ignored
• a file contains one or more sections, and sections are defined as [sectionname]
• sections contain settings, which are in option = value form
• lines starting with spaces or tabs are concatenated to the previous option's value
• if an option name ends with [] (ie. option[] = value), then option will be treated as a list, and value will be added to it as an element

Ok, let's see how that applies to the two files:

Collections file

The collection file defines one or more collections. You can select which files belong to a collection either by filtering for file extension (extensions), listing the file names (files[]), or using regular expressions (regex). Removing files from the collection can be done similarly, but with the ignore- prefix. If a collection is defined in multiple directories (with the same section name), the separate collections are merged into one (eg. a collection for all Zelda games but on different platforms).

explanation	line #	file contents
define a new collection called nes	1	[nes]
collections can have a proper name	2	name = Nintendo Entertainment System
I want it to include all .nes files	3	extensions = nes
except the following games	4	ignored-files[] = mybuggygame.nes
and	5	ignored-files[] = myduplicategame.nes
the launch command	6	launch = myemulator ${FILEPATH}
empty line to look fancy	7
define a new collection called mario	8	[mario]
with a name	9	name = Mario games
I want it to contain these files	10	files[] = Super Mario Bros.nes
and	10	files[] = Super Mario Bros 2.nes
and also	10	files[] = Super Mario Bros 3.nes
if the launch command was already defined for a file by a previous collection, I don't need to repeat it, so I'm commenting this line out	11	# launch = myemulator ${FILEPATH}
optional empty line	12
let's say I'm interested in having a collection of multi-game pirate cartridges	13	[pirate-multigame]
in case you forgot or don't want to name the collection, the section name will be used	14	name = Multi-game Pirate Carts
I want to include all files whose name contain "-in-1"; regular expressions can be used if you're familiar with them (you can find tutorials on the net)	15	regex = \d+.in.1

So that was the collections file; let's see the metadata now.

Metadata file

Every file can have its own section where the metadata is defined.

explanation	line #	file contents
section names are the file names	1	[Super Mario Bros.nes]
some metadata	2	title = Super Mario Bros.
	3	developer = Nintendo
	4	publisher = Nintendo
	5	genres[] = platformer
	6	players = 1-2
a multiline text example	7	description = This is a really really long,
lines starting with spacing will get appended to description	8	multiline description, in fact it's so long
	9	it spans three lines!
a short summary of (one paragraph or about 3-4 sentences)	10	summary = Hello, I'm a short summary,
	11	I'll just stop at being two lines long.
	12	# cloneof = filename.nes
year(-month(-date)) (lexical order)	13	release = 1985-09-13
	14	rating = 86%
custom launch command to override the one set by a collection	15	# launch = myemulator -someflag ${FILEPATH}
the format can be extended with additional fields, prefixed with x-; they may not be used by Pegasus, but other tools can add additional informations with it	16	x-scraper-source = somescraper.com
	17	x-retroarchievements-id = 123456

Aand that's the metadata file.

So this is roughly the format I'm planning. What do you think?

[mmatyas]

Some changes:

• ':' can also be used as a key-value separator
• arrays no longer need keys ending with [] - repeated keys will automatically turn into array

[mmatyas]

Implemented in #155.