Specification language

Harmony's input is a web service specification written in a custom format. Harmony can parse and interpret this format in order to get all the necessary information for generating the output. We show the grammar of the specification language below (note that the comments starting with -- are not in the source code, but added here for explaining the different components).

-- Inline comments
comment "//" ;
-- Block comments
comment "/*" "*/" ;

-- The main object, an specification contains:
--   * The service name
--   * The service version
--   * The list of modules used
--   * The list of enum definitions
--   * The list of struct definitions
--   * The resources of the service
Spec.       Specification ::= 
              Name Version Modules [EnumType] [StructType] [Resource]; 

Nm.         Name          ::= "service_name" ":" Ident;
Ver.        Version       ::= "service_version" ":" VerIdent;

-- The list of modules can be empty
EmptyMods.  Modules       ::= ;
Mods.       Modules       ::= "require" "modules" "[" [Ident] "]";

-- An enum definition (e.g. enum EnumName { ONE, TWO, THREE })
DefEnum.    EnumType      ::= "enum" Ident "{" [EnumVal] "}";

-- A struct definition (e.g. struct StructName { <list of fields> })
DefStr.     StructType    ::= "struct" Ident "{" [Field] "}";

-- A resource refers a defined struct and a route, it also contains
-- information regarding the reading mode
-- (e.g. resource StructName ("/struct") read_only).
Res.        Resource      ::= 
              "resource" Ident "(" "\"" RouteIdent "\"" ")" Mode; 

-- Optional read mode (specify read_only if the resource cannot 
-- be modified)
ReadOnly.   Mode          ::= "read_only";
Write.      Mode          ::= ; 

-- Field definition (e.g. @Unique name : String)
FDef.       Field         ::= [Annotation] Ident ":" FType;

FString.    FType         ::= "String";
FInt.       FType         ::= "Int";
FLong.      FType         ::= "Long";
FDouble.    FType         ::= "Double";
FDefined.   FType         ::= Ident;
FList.      FType         ::= "[" FType "]";
Ann.        Annotation    ::= "@" Ident;
EnVal.      EnumVal       ::= Ident;

-- Definition of lists separators (using the nonempty modifier 
-- whenever we need a list to contain at least one element)
separator EnumType "";
separator nonempty Field ",";
separator nonempty StructType "";
separator nonempty Resource "";
separator nonempty EnumVal ",";
separator Annotation "";
separator nonempty Ident "";

-- Custom token definitions
token VerIdent digit '.' digit '.' digit;
token RouteIdent '/' letter+;