Jump to content

  • Log In with Google      Sign In   
  • Create Account

#ActualScarabus2

Posted 01 April 2013 - 09:27 AM

Between having some issues with XML at our small independent game company and just wanting to scratch an itch I decided to create my own text-based data format. Its primarily an in-house format for our artists/designers to use, but part of the idea was also to make something that would be useful to inexperienced game programmers and the indie community as a whole. So right now I've made the code available on Sourceforge.
 
Source code: https://sourceforge.net/projects/leon-serialize/
Specification: https://docs.google.com/document/d/1Jx4OLn_c22RwZ3GIpucylFZGSU-JyT-steDfjpjubH0/edit
 
What is it, and why?
In short, it's an API that takes a LEON-formatted text file and gives you a data structure for accessing the values in a straight-forward way.
// LEON
value : 100
 
// C++
int iValue = leon["value"].AsInteger();
 
I like it when complexity comes from syntax and not the other way around, so I limited myself to a handful of structural characters and they only become necessary as complexity grows. Rather than
expecting strict rules to be followed the LEON parser will generally deal with what it's given.
You can have complex tree-based structures but they're not required. Similarly you don't have to put names on things if you don't need to. If you just want to throw some arbitraty text and numbers into a file that is fine too.
 
The most important point to me was that I wanted to give a LEON-file to someone who hasn't seen it (like one of our artists) and they should intrinsically understand the syntax and discern how to make changes, without me telling them how. That's why I opted out of using JSON, for instance.
 
Whether or not I've actually managed to do that is up for debate, but I still think it's a neat little API and so far it's worked out okay. At the end of the day this is just something I did for fun.
 
Why you should care
I often recommend TinyXML to anyone who dabbles with text files, rather than writing their own crude text readers. LEON is for those of you who use text files but doesn't want the syntactical or implementational burden that comes with XML, nor wishes to write their own parser. It sits somewhere in between those two cases.
 
Features
  • Supports common data types: strings, numbers, colors, lists, tables, etc. as well as custom types.
  • Straight-forward syntax and code.
  • Parser intelligently trims off irrelevant whitespace.
  • URI-naming convention for look-ups of values.
  • Syntax error reporting with line, column.
  • Ability to enable stricter parser rules to avoid unexpected results.
  • Currently used in production code.
Caveats
  • Types are evaluated by the user. A list could be a list, a table, or a sequence of unrelated values.
  • The API offers many function in a const and a non-const flavor. The const methods will always return a value, even if it's a null-value or zero. The non-const methods will throw an exception if a result can't be given. For convenience there are accompanying reader and writer-classes.
  • So far there is no API documentation other than the specification, which includes example data and code.
  • The code has not been optimized beyond regular memory-aware programming.
  • Uses STL internally.
  • This might look and behave exactly like another format that I am not aware of. In that case, now there is one more solutions to that problem.
Sample LEON data & C++ code:
leDataDocument leon("sample.txt");
Given the document loaded into a variable "leon"...
 
// Some prime numbers
2, 3, 5, 7, 11, 13, 17, 19, 23, 29
leDataStringList primes = leon.GetAttribute("#1").AsList();
 
// Some names
JJ. Abrams
Jon Favreau
Francis F. Coppola
Joss Whedon
Michael Bay
leDataStringList names = leon.GetRoot().AsList();
 
Enemy (
    name: Goomba
    health: 50
    strength: 10
    sprite: sprites/goomba.png
)

Enemy (
    name: Turtle
    health: 80
    strength: 20
    sprite: sprites/turtle.png
)
std::string enemyName = leon["Enemy#2.name"];
 
Element #gold
(
    name: "Au (Gold)"
    "atomic number": 79
    description: "Gold is a dense, soft, shiny,
                  malleable and ductile metal."
)
int goldNumber = leon["gold.atomic number"].AsInteger();

#1Scarabus2

Posted 01 April 2013 - 09:25 AM

Between having some issues with XML at our small independent game company and just wanting to scratch an itch I decided to create my own text-based data format. Its primarily an in-house format for our artists/designers to use, but part of the idea was also to make something that would be useful to inexperienced game programmers and the indie community as a whole. So right now I've made the code available on Sourceforge.
 
Source code: https://sourceforge.net/projects/leon-serialize/
Specification: https://docs.google.com/document/d/1Jx4OLn_c22RwZ3GIpucylFZGSU-JyT-steDfjpjubH0/edit
 
What is it, and why?
In short, it's an API that takes a LEON-formatted text file and gives you a data structure for accessing the values in a straight-forward way.

// LEON
value : 100
 
// C++
int iValue = leon["value"].AsInteger();

 

I like it when complexity comes from syntax and not the other way around, so I limited myself to a handful of structural characters and they only become necessary as complexity grows. Rather than
expecting strict rules to be followed the LEON parser will generally deal with what it's given.
You can have complex tree-based structures but they're not required. Similarly you don't have to put names on things if you don't need to. If you just want to throw some arbitraty text and numbers into a file that is fine too.
 
The most important point to me was that I wanted to give a LEON-file to someone who hasn't seen it (like one of our artists) and they should intrinsically understand the syntax and discern how to make changes, without me telling them how. That's why I opted out of using JSON, for instance.
 
Whether or not I've actually managed to do that is up for debate, but I still think it's a neat little API and so far it's worked out okay. At the end of the day this is just something I did for fun.
 
Why you should care
I often recommend TinyXML to anyone who dabbles with text files, rather than writing their own crude text readers. LEON is for those of you who use text files but doesn't want the syntactical or implementational burden that comes with XML, nor wishes to write their own parser. It sits somewhere in between those two cases.
 
Features

  • Supports common data types: strings, numbers, colors, lists, tables, etc. as well as custom types.
  • Straight-forward syntax and code.
  • Parser intelligently trims off irrelevant whitespace.
  • URI-naming convention for look-ups of values.
  • Syntax error reporting with line, column.
  • Ability to enable stricter parser rules to avoid unexpected results.
  • Currently used in production code.

Caveats

  • Types are evaluated by the user. A list could be a list, a table, or a sequence of unrelated values.
  • The API offers many function in a const and a non-const flavor. The const methods will always return a value, even if it's a null-value or zero. The non-const methods will throw an exception if a result can't be given. For convenience there are accompanying reader and writer-classes.
  • So far there is no API documentation other than the specification, which includes example data and code.
  • The code has not been optimized beyond regular memory-aware programming.
  • Uses STL internally.
  • This might look and behave exactly like another format that I am not aware of. In that case, now there is one more solutions to that problem.

Sample LEON data & C++ code:

leDataDocument leon("sample.txt");

Given the document loaded into a variable "leon"...

 

// Some prime numbers
2, 3, 5, 7, 11, 13, 17, 19, 23, 29
leDataStringList primes = leon.GetAttribute("#1").AsList();

 

// Some names
JJ. Abrams
Jon Favreau
Francis F. Coppola
Joss Whedon
Michael Bay
leDataStringList names = leon.GetRoot().AsList();

 

Enemy (
    name: Goomba
    health: 50
    strength: 10
    sprite: sprites/goomba.png
)

Enemy (
    name: Turtle
    health: 80
    strength: 20
    sprite: sprites/turtle.png
)
std::string enemyName = leon["Enemy#2.name"];

 

Element #gold
(
    name: "Au (Gold)"
    "atomic number": 79
    description: "Gold is a dense, soft, shiny,
                  malleable and ductile metal."
)
int goldNumber = leon["gold.atomic number"].AsInteger();

 


PARTNERS