Enable concatenation of mission files

[dmagree]

It would be useful to be able to chain mission files together. For example, a user may want to separate different configurations of entities into standalone files, that then can be referenced from a primary mission file.

I envision it working with a mission_file_child xml tag, that would trigger a file lookup when found in MissionParse::parse. The child file would then be parsed and its nodes inserted into the DOM tree in the location of the mission_file_child node. Child nodes could also contain children, but would be a depth limit to protect against circular references in the child files.

[jblee123]

• Minor, but I'd opt for something standard like import or include as the tag name. Adding mission_file is redundant because that could be said of anything in the mission file, and "child" could have semantics (e.g. "tree structure") that you may not actually want.
• Are you intending that included files be fully valid mission files in and of themselves? If not, that could cause confusion. "Why isn't this mission file working?" "Oh, it's only meant to be a partial that is included by others." "Then why is it called a mission file?!?" I do not see a reason why you shouldn't be able to include a fully runnable file with the understanding that the runnable node itself isn't brought over, but only its children, but [see next point].

• For explicitness, consider a msnlib file that's only meant for portions of a mission. Then, they would explicitly not be runnable on their own (because they're only portions), and you could do something like the following:

  <msnlib>
  <section name="foo"> ... </section>
  <section name="bar"> ... </section>
  <section name="baz"> ... </section>
  </msnlib>

  and, if it makes sense, have a single import file that you can import individual pieces from:

  <import file="my_config_options.msnlib"
      section="foo"
      section="baz" />
  
  <!-- which would be equivalent to -->
  
  <import file="my_config_options.msnlib" section="foo" />
  <import file="my_config_options.msnlib" section="baz" />

• I'm assuming the specified files would be searched for in the list of directories specified by SCRIMMAGE_MISSION_PATH. I'm not 100% sure how the search rules for that works (does it search only in the specified directories, or in those directories and their children?), but it could be handy to allow for relative-to-current-file paths.
• The "depth limit for cycles" rule seems icky. If I have a valid tree that happens to go one past the depth limit, I'd be irked because an artificial limit was being imposed on me, and if the limit is just set high enough that if it's reached, the only logical explanation is that there's a cycle, then I'd be irked the only info I'm being given is "tree too deep". We can unambiguously track the tree of included paths (or if the "sections" idea sounds handy, the tree of path/section pairs) and unambiguously tell the user what the cycle is.

[dmagree]

...I'd opt for something standard like import or include...

I like that better too.

Are you intending that included files be fully valid mission files in and of themselves?

I wasn't, for the reason that there is a lot of boilerplate on full mission files and it would be somewhat arbitrary what you carry over or not. Prob not the run node. What about origin location? Grid spacing? Certain plugin types like entity interaction or network? I'm not sure where to draw the line, I think it would be pretty arbitrary in the end. Thats why I was leaning towards a method that puts the responsibility on the author to make sure that whats include doesn't wreck the original intent. They are just xml files, and all of the contents will get rolled into the mission file.

For explicitness, consider a msnlib file...

This approach could make what I said above more explicit

I'm assuming the specified files would be searched for in the list of directories specified by SCRIMMAGE_MISSION_PATH.

That was my intent, although I don't know all the ins and outs of that search path either.

We can...unambiguously tell the user what the cycle is.

My graph theory is a little weak. if you can point me to an algorithm or library that would help with this, I'm all ears.

[waford]

I've been working on adding this feature. XML defines a standard for including other XML files in its DOM called XInclude, which can be enabled by including the XInclude namespace in the XML file, e.g. the runscript tag in a mission file might look like: <runscript xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xi="http://www.w3.org/2001/XInclude" name="Straight Mission With XInclude">

Other XML files can then be included with an xi:include tag. For example, to include the definition of an entity in the file "entity1.xml", all that is needed would be <xi:include href="entity1.xml" />

For explicitness, consider a msnlib file...

Subsections of other XML files can be included as well, utilizing XML's XPointers. For example, to include all entity_interaction nodes from a file straight.xml, all you would need is to have the xpointer attribute of the xi:include tag specify this node path: <xi:include href="straight.xml" xpointer="xpointer(/*/entity_interaction)"/>

I'm assuming the specified files would be searched for in the list of directories specified by SCRIMMAGE_MISSION_PATH.

This is a downside of using XInclude, is that the parser will not actively search for files in a specific directory, the resource specified by the href attribute defines the relative path to the included xml file.

My graph theory is a little weak. if you can point me to an algorithm or library that would help with this, I'm all ears.

Not a problem. XInclude already handles inclusion loops, and will fail if it begins to recursively process the same xi:include elements. The full details about inclusion loops are here, but the general rule is that the same xi:include tag can not be included more than once in the same inclusion chain.

This feature is currently implemented in the branch and I've put together a simple example here demonstrating some simple examples of XInclude.

Please feel free to try it out or let me know if Scrimmage needs something a little more specialized!

[dmagree]

Finally was able to try this out. This approach solves the main need, thanks!