OPENRA - Learning Mini-Yaml questions

[Ronald]

Hello OpenRA Developement-team and Fellow OpenRA modders,
Since my OpenRA map-options settings crash (on the :Rules section of a map.yaml file) yesterday (27/08/2020)
-viewtopic.php?f=82&t=21257
-viewtopic.php?f=83&t=21256

I'm now "doing my homework" and I am busy scraping availiable OpenRA resources and the rest of the Internet looking for some good answers. Why?
I really try to understand the whole "mini-yaml" concept - from its very /ROOT - so I can finally start using it for my own OpenRA purposes.
In the process, I have compiled a series of questions about this "mini-yaml" to get started with this process:

QUESTION: Can you help me find some of the answers, which Iwas not able to find myself (yet) ?

[Ronald]

INTRODUCTION - MINI-YAML LANGUAGE BASICS / UNDERLYING PRINCIPLES:
To me "mini-yaml" comes down to using old-skool OOP-Pascal / C++ / Java software-defined-objects from the 198x's:

mini_yaml_1_object_oriented_principles.jpg (96.04 KiB) Viewed 625 times

Base-objects who define the biggest part of the work:
<tab>Child-objects who inherit characteristics from their base-objects
<tab>Child-objects have added specific child-details to itself

mini_yaml_2_si_vrs_mi.jpg (31.57 KiB) Viewed 625 times

Base-Child objects only can have single inheritance relationship.

Object characteristics are define by:
- parameter-value pairs
- parameter-value pairs


"MINI-YAML (TEXTUAL) SYNTAX DIAGRAM" (as far as I understand it now 28/08/2020)
Base Object(s):
parameter = value pair define an object's characteristic

<tab>Child Objects: (single inharitance from Base Objects)
<tab>parameter = value pair define an object characteristic
# - comment line

How am i doing? Am I on the right mini-yaml track here?

[Ronald]

FINDING MINI-YAML LANGUAGE (SYNTAX) RESOURCES:
So far I've only found these "mini-yaml-related" pages on the Internet:

INSIDE THE OPENRA COMMUNITY:
- https://www.openra.net/book/modding/miniyaml/index.html - Official OpenRA Book
- https://www.openra.net/book/modding/min ... yntax.html - Official OpenRA Book
- https://www.openra.net/book/modding/min ... ample.html - Official OpenRA Book
..
- https://github.com/OpenRA/OpenRAModSDK/ - Github - OpenRA SDK
..

mini_yaml_3_github_jimmie_bergmann.jpg (45 KiB) Viewed 625 times

OTHER GITHUB REPOSITORIES:
- https://github.com/jimmiebergmann/mini-yaml - "Single header YAML 1.0 C++11 serializer/deserializer" by Jimmie Bergmann
- https://github.com/jimmiebergmann/mini- ... l/Yaml.hpp - mini-yaml header file
- https://github.com/jimmiebergmann/mini- ... l/Yaml.cpp - mini-yaml cpp file

[Ronald]

ON MINI-YAML ITSELF:
Who has invented this "mini-yaml", Where did it originate from?
Her biggest langauge-look-a-like (YAML) seems to originating inside the JSON community:
- https://datacadamia.com/markup/yaml/yaml
- https://blog.codemagic.io/what-you-can-do-with-yaml/

But who has invented this "mini-yaml"? For what purpose? Why was it born?

-----------------------------------------------------------------------------------------------------------------------------
MINI-YAML: BEING USED INSIDE OPENRA:
Why was the decision made to create OpenRA;s own dialect over well-defined (open) industry standards?

MINI-YAML DOCUMENTATION - IN GENERAL:
Why is there almost no documentation on "mini-yaml" (inside /outside) the OpenRA community?

MINI-YAML DOCUMENTATION - OPENRA TOPICS RELATED:
Who has written the current avaliable OpenRA Mini-Yaml documentation inside the official OpenRA Book over here?
- https://www.openra.net/book/modding/miniyaml/index.html

[Ronald]

MINI-YAML FILE: EXACT CODING_STANDARDS (the $64.000 question):
Is the "mini-yaml" data format - inside the OpenRA community - based on <TAB's> or <SPACES>?
A - Github / OpenRa / Issues branch is full of confusion about this:
-https://github.com/OpenRA/OpenRA/issues/2310
-https://github.com/OpenRA/OpenRA/issues/14506
-https://github.com/OpenRA/OpenRA/issues/4856
..
B - The offfical YAML-language prefers <SPACES> for indentation:
- https://yaml.org/faq.html
- https://www.tutorialspoint.com/yaml/yaml_basics.htm
..

mini_yaml_4_openra_book_28082020.jpg (126.2 KiB) Viewed 625 times

C - The OpenRA book mentions BOTH: <TABS> and <SPACES> (on 28/08/2020)

- https://www.openra.net/book/modding/min ... yntax.html


So.. What is the official OpenRA mini-yaml indentation standard: <TAB's> or <SPACE's>?

[Ronald]

OPENRA - MINI-YAML FILE PARSING:
How does the OpenRA software checks / validates / parses its own mini-yaml files:
- Does OpenRA have it's own build-in native mini-yaml parsing engine?

I've already found some code_traces, but I'm not 100#% sure about it, since I do not know my way around in OpenRA source_code (yet):
- https://github.com/OpenRA/OpenRA/pull/6984/files
- https://github.com/OpenRA/OpenRA/pull/7 ... ad542276f5

-- If Yes:
--- Where can I learn more about the internal parser and how it truly functions?
--- Where is this parser-code located inside the OpenRA OpenSource project?package

Does OpenRa use a 3rd party mini-yaml-parsing-library to do this?
-- If Yes:
--- Which 3rd party lib is being used?
--- Where can I learn more about it?

-----------------------------------------------------------------------------------------------------------------------------

FINAL WORDS FOR THIS POSTING:
As you can see, I really try to wrap my head around this entire "mini-yaml" topic.
So any answers you can help me with, making me understand this mini-yaml, are really really appreciated.

Thank you all for your hint /tips /tricks / time and efforts.

[lawANDorder]

You really don't need to learn about the OpenRA mini yaml parsing logic for the things you seem to be interested in. OpenRA is a matured software project which means that such fundamental question have been solved in some way years ago and most likely are not related to any issues you experience while doing your first steps in yaml-modding. There certainly can be bugs, but these will more likely in such a case be caused by specific implementation details rather than core engine features, like the yaml parser is. Then the right thing to do would be to report the specific, reproducible issue on github, probably using the bug template and providing the in that template asked for information.

Generally, instead of getting lost in C# code or things google spits out, you should IMO start learning from the many available modded maps as a first step. You don't need to learn about yaml specification because OpenRA uses its own flavour. Simply following that standard (even if it may be controversial or weird) is the best you can do to make progress in modding. The trait docs, examples to learn from and getting in touch with people who you can ask specific questions for a specific problem that you can't solve on your own is all you need to get things done. Approaching a probably easy to solve problem from the "root" by reasoning about the evolution of a language specification is certainly the wrong way if you want to create a map mod.

Although it is not the complete answer: use tabs for intendation in yaml files. Some other questions you asked are interesting but not relevant for your goal and have already been debated and are either decided or are still unsolved because of reasons that are noted in these discussions and again not helpful for you with your current ambitions and knowledge.

Some of this might sound harsh but I think it is helpful for you to progress.

[Ronald]

@LawANDorder: Thank you for taking the time to share your insights with me.

[SirCake]

In addition to LawAndOrders's comment,
please don't open issues on GitHub until you have familiarized yourself sufficiently with how a working mod-code/script looks and how things come together in the end.

Most the time it's a really simple mistake which keeps you wondering for the longest time.

[Ronald]

@SirCake: Thank you for adding your suggestions.

[Matt]

https://github.com/jimmiebergmann/mini-yaml has nothing to do with OpenRA. YAML actually forbids tabs nowadays. MiniYAML is something very OpenRA specific. It also has very few to do with object-oriented programming. It is more something like .ini, .xml, .json or .toml which stores data. However, it supports nesting which makes it special.

[Ronald]

MiniYAML is something very OpenRA specific. It also has very few to do with object-oriented programming.
It is more something like .ini, .xml, .json or .toml which stores data. However, it supports nesting which makes it special.

".ini files" aha! Now you're talking my language. Thanks for the direction_pointers Matt.