[ABANDONED] ZML

[Sarah]

---

ZMLv0.1
ZScript eXtensible Markup Language

• The name is a bit of a misnomer, ZML is an XML parser, written in ZScript.
  It is also a developer tool and will do nothing by itself! You do not need to download ZML unless told to as part of installation of another mod!

• *Please note that this post as well as the project are WIP.
  The parser is in a workable state that I am reading XML files with it, I just need to document and do the API.
  Your patience is appreciated! I do this for a hobby

What Does It Do?

• ZML allows modders to define information in an organized document file structure for storage outside of the standard (G)ZDoom project data.
  For example, if you had a music randomizer written in ZScript, you might want to hard code the track list into it. With ZML you can define the track list information in a single file and store it in an easily accessible format.

What ZML Does Not Do:

• Anything relating to HTML. ZML is an XML-like language. It follows the syntax rules you can find on the W3 Schools website. Any deviation is either intentional - because ZScript/game engine - or an oversight of mine and should be reported.

XML in ZScript!
The following is an actual ZML definition file from my own projects.

• Code: Select all

  <zml>
      <playableGhost levelName="testh">
          <ghostTrack trackName="music/13 Ghosts II.mp3">
              <trackMin>3</trackMin>
              <trackSec>13</trackSec>
              <fadeIn>1</fadeIn>
              <fadeInTicks>105</fadeInTicks>
          </ghostTrack>
  		<ghostTrack>
  			<trackMin>45</trackMin>
  		</ghostTrack>
      </playableGhost>
  </zml>

How Does It Work?

• Like all of my mods, it's something you need to put in your load order, or incorporate into your own mod, and then make use of.
• ZML defines 2 parsers - the XML parser, and the ZMLDEFS parser.
• The XML parser is self-explanatory, but ask, how does ZML know what is and isn't a valid XML tag? ZMLDEFS.
• ZMLDEFS is a simple syntax language used to define your tags. It has a C-like structure.
• Finally, ZMLDEFS and a ZML translation unit (just like your ZScript includes) is placed in the root of a project.
• The ZML translation unit is itself XML and defines where in your project the actual XML definitions are located. Read XML to read more XML
• The XML tree is stored in an actor in the game level to make it the most accessible. Usage is still geared toward ZScript.

Example ZMLDEFS file:

Code: Select all

tag "crewsocks", "t_none"
{
    attributes
    {
         "stripecolor", "t_string";
    }
}

tag "sockbrand", "t_string";

Working Features: - since I've already found problems and gotten requests! TY

• XML and Tag parsers
• Error checking for all the regular stuff - did you close your tags and spell things right? Stop using Notepad and get a proper syntax highlighter! ZMLDEFS error checks too, the syntax is obtuse in of itself. No one's ever satisfied with any language. Ever.
• Both XML and ZMLDEFS files can have comments. XML only defines the comment tag. ZMLDEFS handles C-style line and block comments.
• ZML supports self-closing tags and attributes.

In Progress Features: - please keep in mind that just because you ask for it, even write code for it, that I'll accept it. I reserve the right to say NO. TY

• Documentation - because it's something everyone has to do to they're project they expect other people to use.
• API - this will be some basic access functions and wrappers for common tasks. You probably do need to write ZScript yourself to use ZML. Note the italicized "probably".

Future Feature: - I have agreed to do this at some point but I have not given any time frame whatsoever. And I will not. TY

• Schema validation - I'll use the fancy term for I'll figure out a way to enforce a defined structure. I have 2 ideas, the second of which I'm not fond of

Where Do You Get It

• Currently from Github. The big ZML at the top of this post is the link.

Can You Help?

• Sure, make pull requests and open up issues if you find bugs - mostly likely thing will be I missed some obtuse-but-valid syntax style that the parser isn't loose enough to handle and garbage ensues.

License:

• Whatever governs the engine. Please credit me in your project if you use ZML. Thank you!

Other Notes:
The FileStream

• The file stream is a piece of code I wrote for the sole purpose of making reading lumps a lot easier. I point this out because I also wrote that code to hopefully also save someone else the headache of writing their own way of making some semblance of sense of a single string's worth of file contents. It's documented fairly well, in the code, and ZML itself is an example of its use potential. I'm around to answer questions if anyone decides it would be useful to their needs.

Updates - DD/MM/YYYY

• 22/06/2022 - I took a break because of real life. It literally took me completely away from my computer all this time, and that was a good thing, I needed to refocus. I am looking at schema validation. This will be a big rewrite of most of ZML, so branches have been merged and ZML is functional in its current state. I'm using it in my own project. There will be no further updates to the code until I have something functional to push to Github.
  
  What does this mean for any current use of ZML besides myself? Go ahead and use it! Changes to any projects using ZML should be small.
  • In the future you will lose the ZMLDEFS file.
  • You will gain a "schema" attribute in the root "zml" tag; this will have rules governing usage. This is sort of a hybrid of XSD and DTD
  • You will also gain a ".zsd" file that will be an XSD-based schematic file.
    Too many acronyms? The tldr is you lose the tag definition lump but gain structure enforcement lumps. Note the change to plural there.

ZML is no longer available on the ZDoom Forums. Thank you.

My mods are available on my GitHub.

[Nash]

Ah, cool, an XML-like reader for custom lumps!

[Graf Zahl]

XML? Yuck!

Why not something sane and less bloated like Json or a limited subset of YML?

[Sarah]

"XML-like" - yeah that's accurate. This follows the XML syntax, it doesn't do anything relating to HTML. I consider how I produce the tree pure witchcraft.

Graf, whatever gave you the idea that I'm a sane person? Lol. And to answer your question, didn't someone already do a Json parser? What's YML?
I think what you intend to do with the data really determines how you store it, so in this case I thought XML was really the best option.
I was also thinking about re-usability - why should I write one specific parser for my needs when I can cover a lot of needs by writing a generic one? XML is pretty straightforward to start using when you don't know more complex languages.
And yes, yuck, that was not fun, I've done it twice now, once with actual XML libraries!

[mjr4077au]

Curious as to whether this supports schema files to govern the validity of the data, and if not, is it planned? If there's no validation of the incoming data, I'd probably have a preference towards JSON too. Validating the data in the schema means modders need to less validation in the zscript files, saving processing time and increasing performance.

[Sarah]

I was going to ask you for English, please, but a quick Google showed me that you're asking the same question I have: "what is enforcing the structure? Is there a way to make sure user data is organized correctly?"

The answer is: right now, absolutely nothing. Make sure you're structure is what you want. BUT, ZMLDEFS is sort-of what we're both looking for. Already I force type expression, and the XML parser will not accept an attribute that is not defined in the given tag. Each file results in its own DOM at the top of the tree; if you go through the root siblings they're all the root of each file. SO, expansion of ZMLDEFS would, at least I think from cursory overview of what we both want, would be the best route. The only real downside is increased complexity of that lump, but should you be reading data from files other than your own, odds are ZML has not read a ZMLDEFS from that other file, it read your tags and now needs to read the other file with your tags, thus I should verify the structure. Consider it planned. When? I do not currently know, I'd like to get accessing the tree going as my own project needs ZML too. One weekend at a time!

Edit: one thing to keep in mind, I'm not expert at XML, I just hack and bash my way to what I want

Edit Edit: After having more of a look at schema validation - yes totally doable. I think, at least initial ideas, that ZMLDEFS needs expanded to be the schema definition, the XML parser needs to then enforce a schema declaration, and honestly do the validation post-parse. If the DOM doesn't match the schema, eject it, that's been the default for any error, file or tree.