add audioFormatExtended version

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Added
 - Added support for silent audioTrackUid references with ID 0. See `AudioTrackUid::isSilent` and `AudioTrackUid::getSilent`.
+- Added `audioFormatExtended` `version` attribute; this should be set for BS.2076-2 compliance: `document->set(Version("ITU-R_BS.2076-2"));`.
 
 ### Changed
 - Decimal times are now written without trailing zeros past 5 decimal places. To interoperate with ADM parsers which don't support more than 5 digits, users should round times in the ADM document before writing.

docs/reference_document.rst

@@ -4,3 +4,4 @@ ADM Document
 ############
 
 .. doxygenclass:: adm::Document
+.. doxygentypedef:: adm::Version

include/adm/document.hpp

@@ -2,20 +2,48 @@
 #pragma once
 
 #include <memory>
+#include <string>
 #include <vector>
 #include "adm/elements.hpp"
+#include "adm/detail/auto_base.hpp"
 #include "adm/detail/id_assigner.hpp"
+#include "adm/detail/named_type.hpp"
 #include "adm/export.h"
 
 namespace adm {
 
+  /// tag for version
+  struct VersionTag {};
+  /// NamedType for audioFormatExtended version attribute
+  using Version = detail::NamedType<std::string, VersionTag>;
+
+  namespace detail {
+    extern template class ADM_EXPORT_TEMPLATE_METHODS
+        OptionalParameter<Version>;
+
+    using DocumentBase = HasParameters<OptionalParameter<Version>>;
+  }  // namespace detail
+
   /**
-   * @ingroup main
    * @brief Class representation of a whole ADM document
-   * @headerfile document.hpp <adm/document.hpp>
    *
+   * \rst
+   * +---------------+-----------------+----------------------------+
+   * | ADM Parameter | Parameter Type  | Pattern Type               |
+   * +===============+=================+============================+
+   * | version       | :type:`Version` | :class:`OptionalParameter` |
+   * +---------------+-----------------+----------------------------+
+   * \endrst
+   *
+   * Note that:
+   * - version is defined in BS.2076-2 as being required, so should be set
+   *   manually to produce compliant documents. The version element does not
+   *   affect parsing of other elements, so for example new defaults for old
+   *   elements are not applied.
    */
-  class Document : public std::enable_shared_from_this<Document> {
+  class Document : public std::enable_shared_from_this<Document>,
+                   private detail::DocumentBase,
+                   public detail::AddWrapperMethods<Document> {
    public:
     /**
      * @brief Static helper function to create an Document
@@ -202,6 +230,12 @@ namespace adm {
         const AudioTrackUidId &trackUidId) const;
     ///@}
 
+    using detail::DocumentBase::set;
+    using detail::AddWrapperMethods<Document>::get;
+    using detail::AddWrapperMethods<Document>::has;
+    using detail::AddWrapperMethods<Document>::isDefault;
+    using detail::AddWrapperMethods<Document>::unset;
+
    private:
     ADM_EXPORT Document();
     ADM_EXPORT Document(const Document &) = default;
@@ -251,6 +285,13 @@ namespace adm {
     template <typename Element>
     bool checkParent(const std::shared_ptr<Element> &element, const char *type);
 
+    using detail::DocumentBase::get;
+    using detail::DocumentBase::has;
+    using detail::DocumentBase::isDefault;
+    using detail::DocumentBase::unset;
+
+    friend class detail::AddWrapperMethods<Document>;
+
     std::vector<std::shared_ptr<AudioProgramme>> audioProgrammes_;
     std::vector<std::shared_ptr<AudioContent>> audioContents_;
     std::vector<std::shared_ptr<AudioObject>> audioObjects_;

src/document.cpp

@@ -9,6 +9,10 @@
 #include <algorithm>
 
 namespace adm {
+  namespace detail {
+    template class OptionalParameter<Version>;
+  }  // namespace detail
+
   Document::Document() { idAssigner_.document(this); }
 
   std::shared_ptr<Document> Document::create() {

src/private/xml_parser.cpp

@@ -55,6 +55,8 @@ namespace adm {
         root = findAudioFormatExtendedNodeEbuCore(xmlDocument.first_node());
       }
       if (root) {
+        setOptionalAttribute<Version>(root, "version", document_);
+
         // add ADM elements to ADM document
         for (NodePtr node = root->first_node(); node;
              node = node->next_sibling()) {

src/private/xml_writer.cpp

@@ -38,6 +38,7 @@ namespace adm {
         root = xmlDocument.addEbuStructure();
       }
       // clang-format off
+      root.addOptionalAttribute<Version>(document, "version");
       root.addBaseElements<AudioProgramme, AudioProgrammeId>(document, "audioProgramme", &formatAudioProgramme);
       root.addBaseElements<AudioContent, AudioContentId>(document, "audioContent", &formatAudioContent);
       root.addBaseElements<AudioObject, AudioObjectId>(document, "audioObject", &formatAudioObject);

tests/CMakeLists.txt

@@ -68,6 +68,7 @@ add_adm_test("route_tracer_tests")
 add_adm_test("screen_edge_lock_tests")
 add_adm_test("speaker_position_tests")
 add_adm_test("type_descriptor_tests")
+add_adm_test("version_tests")
 add_adm_test("xml_audio_block_format_objects_tests")
 add_adm_test("xml_loudness_metadata_tests")
 add_adm_test("xml_parser_audio_block_format_direct_speakers_tests")

tests/test_data/version.accepted.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<ebuCoreMain xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns="urn:ebu:metadata-schema:ebuCore_2014" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" schema="EBU_CORE_20140201.xsd" xml:lang="en">
+	<coreMetadata>
+		<format>
+			<audioFormatExtended version="ITU-R_BS.2076-2"/>
+		</format>
+	</coreMetadata>
+</ebuCoreMain>
+

tests/test_data/xml_parser/version.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<ebuCoreMain>
+  <coreMetadata>
+    <format>
+      <audioFormatExtended version="ITU-R_BS.2076-2">
+      </audioFormatExtended>
+    </format>
+  </coreMetadata>
+</ebuCoreMain>

tests/version_tests.cpp

@@ -0,0 +1,28 @@
+#include <catch2/catch.hpp>
+#include "helper/parameter_checks.hpp"
+#include "adm/document.hpp"
+#include "adm/parse.hpp"
+#include "adm/write.hpp"
+#include "helper/file_comparator.hpp"
+
+using namespace adm;
+using namespace adm_test;
+
+TEST_CASE("version") {
+  auto document = Document::create();
+
+  check_optional_param<Version>(document,
+                                canBeSetTo(Version{"ITU-R_BS.2076-2"}));
+}
+
+TEST_CASE("xml/version") {
+  auto document = parseXml("xml_parser/version.xml");
+
+  REQUIRE(document->has<Version>());
+  REQUIRE(document->get<Version>().get() == "ITU-R_BS.2076-2");
+
+  std::stringstream xml;
+  writeXml(xml, document);
+
+  CHECK_THAT(xml.str(), EqualsXmlFile("version"));
+}