Store include info in Element

[azeey]

🎉 New feature

Closes #401

Summary

This stores the contents of <include> inside the Element loaded from the included file.
For example, given the following SDFormat:

<sdf version = '1.8'>
  <world name='default'>
    <include>
      <uri>model_uri</uri>
      <pose>1 2 3 0 0 0</pose>
    </include>
  </world>
</sdf>

The ElementPtr associated with the model loaded from 'model_uri' will
have its includeElement set to

    <include>
      <uri>model_uri</uri>
      <pose>1 2 3 0 0 0</pose>
    </include>

This can be used to retrieve additional information available under the tag after the entity has been loaded (eg. <name>, <pose>, <plugin>, etc.). An example use case for this is when saving a loaded world back to SDFormat in such a way that the <include> tags are left intact.

This also deprecates the functions Element::SetInclude and Element::GetInclude since they were never used. Based on the code in Element::ToString: https://github.com/osrf/sdformat/blob/54d9018599ce6605cee13d372c7dc51f0c0fcd2d/src/Element.cc#L528-L537
I think these functions were added a long time ago when the syntax for including files was <include filename="path">, which is not valid SDFormat anymore.

Checklist

• Signed all commits for DCO
• Added tests
• Added example and/or tutorial
• Updated documentation (as needed)
• Updated migration guide (as needed)
• Code check passed (In source directory, run sh tools/code_check.sh)
• All tests passed (See test coverage)
• While waiting for a review on your PR, please help review another open pull request to support the maintainers

Note to maintainers: Remember to use Squash-Merge

[EricCousineau-TRI]

Sweet! Minor nits, and a testing update.

[EricCousineau-TRI]

nit Consider using non-global version? ;)

[azeey]

Using non-global version in 2631da1

[EricCousineau-TRI]

I'm not fully 1000% convinced that this preserves the information across load str -> element -> dump str.

Can you add a quick idempotent check that the include markup is preserved as-is?

[EricCousineau-TRI]

Per f2f, this implies that the //include tags would be preserved, which should not be the default libsdformat behavior.

Perhaps there should be an option (API + cmdline) to preserve includes?

[azeey]

I created an issue to capture this: #522. How about we tackle that in a follow up PR?

[EricCousineau-TRI]

Sounds great!

[jennuine]

Looks good! Did a first pass and left some minor comments. I'm curious, is includeFilename needed anymore?

If so, should Element::ToString() be updated since <include filename="path"> is no longer valid? (or removed)
https://github.com/osrf/sdformat/blob/69dc1542641df2586d2e8dcfb02e307a8a865fdb/src/Element.cc#L535-L536

[aaronchongth]

This is awesome!

On the topic of the ToString function, would a good way of re-implementing it be to use the output of PrintValuesImpl, but modify the fields depending on what is stored in includeElement, the pose, static flags, etc?

[azeey]

On the topic of the ToString function, would a good way of re-implementing it be to use the output of PrintValuesImpl, but modify the fields depending on what is stored in includeElement, the pose, static flags, etc?

I think this is actually how it works currently. The parser overrides all those parameters of the included model based on the contents of the <include> element when it first loads the include model: https://github.com/osrf/sdformat/blob/2631da14dff94ea7c66e2480be626ffd3e33e72e/src/parser.cc#L1225-L1291

[jennuine]

LGTM! Minor nit: I think one of your comments is missing "is" in the statement but feel free to disregard