1. Index
--------------------------------------------------------------------------------

    1. Index
    2. Adding a new emulator
    3. Generic configuration
    4. Data sources
    5. Variables
    Appendix A. Configuration file values.  
    Appendix B. Gamelist DTD.

2. Adding a new emulator
--------------------------------------------------------------------------------
The addition of a new emulator to loemu consists in the creation of the new 
emulator's configuration file. This file must be placed in share/loemu/config 
with extension .conf so loemu parser can identify it as emulator configuration 
file.

This file is divided in sections and entries with structure of INI files. Each 
entry value is calculated at runtime as follows:

   1. The substrings @('Variables','var') of the entry value are replaced with 
      the user value of the variable 'var' (the definition of this variables 
      are explained below). 
   2. If it's possible the entry value is evaluated as a python instruction.
   3. Finally the resulting string value is assigned to entry. 

The appendix A shows an example of final file values. Note that there are 
strings that are interpreted as python lists or dicts (like images value or 
state value).

3. Generic configuration
--------------------------------------------------------------------------------
The General section is the main section of the emulator configuration file. It 
describes the general parameters of the emulator used by the application. This 
section has the following entries:

label
    Identifies the emulator in the user interface.
binary      
    The executable file of the emulator.
start
    The command to launch the emulation. The string @(attribute) is replaced 
    by the value of the attribute of the game selected in the front end.
images
    The list of sets of images. Each set can be a directory or a zip file.
image_file
    The image file format. The string @(attribute) is replaced by the value of 
    attribute of the current game in the front end.
state
    Convert state values of emulator (like incorrrect or correct) by another 
    values (like bad or good)
identity
    Identifies the common attribute to all emulator data sources. It's the 
    identifier attribute that allows the linkage of the data sources. It must 
    be unique for every game.
titles
    Titles of the game attributes shown in the Loemu interface.
sources
    The list of sections that describes the sources of emulator data. The 
    format of these sections is explained below.
variables
    The list of variables of the emulator and also the list of the sections 
    that defines this variables. The format of these sections is explained 
    below.

4. Data sources
--------------------------------------------------------------------------------
The sources entry of General section is the list of data source sections of 
the emulator. These sources define the game attributes capture and allow loemu 
parser to build the part of the gamelist for this emulator.

Each section has a group of entries that describe how to capture some game 
attributes. The current attributes supported by graphical interface are 
description, category, year, manufacturer, romset, players, version and state. 
The entries of source sections are described as follows. 

type
    The type of source. Its value must be:
        archive
            The source is a file. This type requires the archive entry.
        command
            The source is the standard output of a command. This type requires 
            the command entry.
archive
    The path of the data file that have to be parsed. This entry is required 
    if type value is archive.
command
    The command that outputs the data to be parsed. This entry is required if 
    type value is command.
format
    The structure of the data to parse. Allowed values are:
        xml
            The source data has xml structure. This format requires the xsl 
            entry.
        ini-sections
            The source data has INI structure with sections and entries, the 
            sections are the attribute labels of the games and the entries of 
            this attribute sections are the identifier attribute of every game. 
            This format requires the sections entry.
        ini-options
            The data has INI structure with sections and entries, the sections 
            are the identifier attributes of every game and the entries of this 
            game identifiers are the attributes of the game. This format 
            requires the options entry.
        plain
            The data is a plain text where each line belongs to one game. This 
            format requires the pattern entry.
xsl
    A xslt file. It tells how to convert the xml source data to the gamelist 
    format (explained in Appendix B). This entry is required if format value is 
    xml.
sections
    Conversion between the section label and the attribute label of the games. 
    Only the section labels defined in this conversion are parsed. This entry 
    is required if format value is ini-sections.
options
    Conversion between the entry label and the attribute label of the games. 
    Only the entry labels defined in this conversion are parsed. This entry is 
    required if format value is ini-options.
pattern
    A regular expression. It must define named groups with the names of the 
    attributes to be parsed. An extensive explanation of the regular expression 
    syntax can be found here. This entry is required if format value is plain.

5. Variables
--------------------------------------------------------------------------------
The variables entry of General section is the list of variables that allow user 
to customize the emulator parameters.

The variables can be set by the user in the Emulators tab of the Preferences 
dialog and they can be referenced in the emulator file with the substring 
@('Variables','var') to capture the customized user value.

The sections of the variables can be defined to improve the appearance of the 
variables entries in the Preferences dialog. Each variable section name must be 
the variable name and it can contain the following entries. 

type
    The data type of this variable. It defines how user enter the data in the 
    Preferences dialog. Current supported values are: select_file, 
    select_directory, images and text (this is the default).
text
    The description of the variable. It is shown next to the parameter value 
    and it is recognized as a localization string.
default
    The default value of the variable.

Appendix A. Configuration file values.
--------------------------------------------------------------------------------

**** original xmame.conf ****

[General]
label:              XMAME
binary:             @('Variables','binary')
start:              @('Variables','binary') + ' -rp ' + @('Variables','rompath') + ' ' + @('Variables','extra_param') + ' @(romset)'
images:             @('Variables','images')
image_file:         @(romset).png
state:              {'':'bad','incorrect':'bad','not found':'bad','best available':'best available','correct':'good'}
identity:           romset
titles:             {'romset':'Romset','category':'Category','description':'Description','nplayers':'Players','state':'State','version':'Version','emulator':'Emulator','year':'Year','manufacturer':'Manufacturer'}
sources:            ['xml-src','catver-src','verify-src','players-src']
variables:          ['binary','rompath','catver','players','images','extra_param']

; VARIABLES
[binary]
type:               select_file
text:               Select executable file
default:            xmame
[rompath]
type:               select_directory
text:               Select ROMs location
default:            sys.prefix + '/share/loemu/roms'
[catver]
type:               select_file
text:               Select catver.ini file. It defines category and version of games.
[players] 
type:               select_file
text:               Select nplayers.ini file. It defines the number of players supported by game.
[images]
type:               images
text:               Define image sets that will be shown for every game.
default:            [sys.prefix + '/share/loemu/snaps', sys.prefix + '/share/loemu/flyers']
[extra_param]
type:               text
text:               Define extra parameters
default:           -s 2 -fullscreen -jdev /dev/input/js0 -jt 1

; SOURCES
[xml-src]
command:            @('Variables','binary') + ' -lx'
type:               command
format:             xml
xsl:                mame.xsl
[players-src]
archive:            @('Variables','players')
type:               archive
format:             ini-sections
sections:           {'NPlayers': 'players'}
[catver-src]
archive:            @('Variables','catver')
type:               archive
format:             ini-sections
sections:           {'Category': 'category', 'VerAdded': 'version'}
[verify-src]
command:            @('Variables','binary') + ' -vr -rp ' + @('Variables','rompath')
type:               command
format:             plain
pattern:            '^romset\s*(?P<romset>\w+)\s*(?P<state>.+)$'

**** xmame.conf replaced values ****

[General]
label:              XMAME
binary:             xmame
start:              xmame -rp /usr/share/loemu/roms -s 2 -fullscreen -jdev /dev/input/js0 -jt 1 @(romset)
images:             ['/usr/share/loemu/snaps', 'usr/share/loemu/flyers']
image_file:         @(romset).png
state:              {'':'bad','incorrect':'bad','not found':'bad','best available':'best available','correct':'good'}
identity:           romset
titles:             {'romset':'Romset','category':'Category','description':'Description','nplayers':'Players','state':'State','version':'Version','emulator':'Emulator','year':'Year','manufacturer':'Manufacturer'}
sources:            ['xml-src','catver-src','verify-src','players-src']
variables:          ['binary','rompath','catver','players','images','extra_param']

; VARIABLES
[binary]
type:               select_file
text:               Select executable file
default:            xmame
[rompath]
type:               select_directory
text:               Select ROMs location
default:            /usr/share/loemu/roms
[catver]
type:               select_file
text:               Select catver.ini file. It defines category and version of games.
[players] 
type:               select_file
text:               Select nplayers.ini file. It defines the number of players supported by game.
[images]
type:               images
text:               Define image sets that will be shown for every game.
default:            ['/usr/share/loemu/snaps', 'usr/share/loemu/flyers']
[extra_param]
type:               text
text:               Define extra parameters
default:            -s 2 -fullscreen -jdev /dev/input/js0 -jt 1

; SOURCES
[xml-src]
command:            xmame -lx
type:               command
format:             xml
xsl:                mame.xsl
[players-src]
archive:            
type:               archive
format:             ini-sections
sections:           {'NPlayers': 'players'}
[catver-src]
archive:            
type:               archive
format:             ini-sections
sections:           {'Category': 'category', 'VerAdded': 'version'}
[verify-src]
command:            xmame -vr -rp /usr/share/loemu/roms
type:               command
format:             plain
pattern:            '^romset\s*(?P<romset>\w+)\s*(?P<state>.+)$'

Appendix B. Gamelist DTD.
--------------------------------------------------------------------------------

<?xml version="1.0" ?>
<!DOCTYPE gamelist [
  <!ELEMENT gamelist (game*)>
  <!ELEMENT game EMPTY>
  <!ATTLIST game description CDATA #IMPLIED>
  <!ATTLIST game category CDATA #IMPLIED>
  <!ATTLIST game year CDATA #IMPLIED>
  <!ATTLIST game manufacturer CDATA #IMPLIED>
  <!ATTLIST game romset CDATA #IMPLIED>
  <!ATTLIST game nplayers CDATA #IMPLIED>
  <!ATTLIST game version CDATA #IMPLIED>
  <!ATTLIST game state CDATA #IMPLIED>
  <!ATTLIST game emulator CDATA #IMPLIED>
  <!ATTLIST game clone CDATA #IMPLIED>
  <!ATTLIST game archive CDATA #IMPLIED>
  <!ATTLIST game any_other_attribute CDATA #IMPLIED>
]>




