Source: lib/util/xml_utils.js

  1. /**
  2.  * @license
  3.  * Copyright 2016 Google Inc.
  4.  *
  5.  * Licensed under the Apache License, Version 2.0 (the "License");
  6.  * you may not use this file except in compliance with the License.
  7.  * You may obtain a copy of the License at
  8.  *
  9.  *     http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  18. goog.provide('shaka.util.XmlUtils');
  20. goog.require('shaka.log');
  21. goog.require('shaka.util.StringUtils');
  24. /**
  25.  * @namespace shaka.util.XmlUtils
  26.  * @summary A set of XML utility functions.
  27.  */
  30. /**
  31.  * Finds a child XML element.
  32.  * @param {!Node} elem The parent XML element.
  33.  * @param {string} name The child XML element's tag name.
  34.  * @return {Element} The child XML element, or null if a child XML element does
  35.  *   not exist with the given tag name OR if there exists more than one
  36.  *   child XML element with the given tag name.
  37.  */
  38. shaka.util.XmlUtils.findChild = function(elem, name) {
  39.   let children = shaka.util.XmlUtils.findChildren(elem, name);
  40.   if (children.length != 1) {
  41.     return null;
  42.   }
  43.   return children[0];
  44. };
  47. /**
  48.  * Finds a namespace-qualified child XML element.
  49.  * @param {!Node} elem The parent XML element.
  50.  * @param {string} ns The child XML element's namespace URI.
  51.  * @param {string} name The child XML element's local name.
  52.  * @return {Element} The child XML element, or null if a child XML element does
  53.  *   not exist with the given tag name OR if there exists more than one
  54.  *   child XML element with the given tag name.
  55.  */
  56. shaka.util.XmlUtils.findChildNS = function(elem, ns, name) {
  57.   let children = shaka.util.XmlUtils.findChildrenNS(elem, ns, name);
  58.   if (children.length != 1) {
  59.     return null;
  60.   }
  61.   return children[0];
  62. };
  65. /**
  66.  * Finds child XML elements.
  67.  * @param {!Node} elem The parent XML element.
  68.  * @param {string} name The child XML element's tag name.
  69.  * @return {!Array.<!Element>} The child XML elements.
  70.  */
  71. shaka.util.XmlUtils.findChildren = function(elem, name) {
  72.   return Array.prototype.filter.call(elem.childNodes, function(child) {
  73.     return child instanceof Element && child.tagName == name;
  74.   });
  75. };
  78. /**
  79.  * Finds namespace-qualified child XML elements.
  80.  * @param {!Node} elem The parent XML element.
  81.  * @param {string} ns The child XML element's namespace URI.
  82.  * @param {string} name The child XML element's local name.
  83.  * @return {!Array.<!Element>} The child XML elements.
  84.  */
  85. shaka.util.XmlUtils.findChildrenNS = function(elem, ns, name) {
  86.   return Array.prototype.filter.call(elem.childNodes, function(child) {
  87.     return child instanceof Element && child.localName == name &&
  88.         child.namespaceURI == ns;
  89.   });
  90. };
  93. /**
  94.  * Gets a namespace-qualified attribute.
  95.  * @param {!Element} elem The element to get from.
  96.  * @param {string} ns The namespace URI.
  97.  * @param {string} name The local name of the attribute.
  98.  * @return {?string} The attribute's value, or null if not present.
  99.  */
  100. shaka.util.XmlUtils.getAttributeNS = function(elem, ns, name) {
  101.   // Some browsers return the empty string when the attribute is missing,
  102.   // so check if it exists first.  See: https://mzl.la/2L7F0UK
  103.   return elem.hasAttributeNS(ns, name) ? elem.getAttributeNS(ns, name) : null;
  104. };
  107. /**
  108.  * Gets the text contents of a node.
  109.  * @param {!Node} elem The XML element.
  110.  * @return {?string} The text contents, or null if there are none.
  111.  */
  112. shaka.util.XmlUtils.getContents = function(elem) {
  113.   let isText = (child) => {
  114.     return child.nodeType == Node.TEXT_NODE ||
  115.         child.nodeType == Node.CDATA_SECTION_NODE;
  116.   };
  117.   if (!Array.prototype.every.call(elem.childNodes, isText)) {
  118.     return null;
  119.   }
  121.   // Read merged text content from all text nodes.
  122.   return elem.textContent.trim();
  123. };
  126. /**
  127.  * Parses an attribute by its name.
  128.  * @param {!Element} elem The XML element.
  129.  * @param {string} name The attribute name.
  130.  * @param {function(string): (T|null)} parseFunction A function that parses
  131.  *   the attribute.
  132.  * @param {(T|null)=} defaultValue The attribute's default value, if not
  133.  *   specified, the attibute's default value is null.
  134.  * @return {(T|null)} The parsed attribute on success, or the attribute's
  135.  *   default value if the attribute does not exist or could not be parsed.
  136.  * @template T
  137.  */
  138. shaka.util.XmlUtils.parseAttr = function(
  139.     elem, name, parseFunction, defaultValue = null) {
  140.   let parsedValue = null;
  142.   let value = elem.getAttribute(name);
  143.   if (value != null) {
  144.     parsedValue = parseFunction(value);
  145.   }
  146.   return parsedValue == null ? defaultValue : parsedValue;
  147. };
  150. /**
  151.  * Parses an XML date string.
  152.  * @param {string} dateString
  153.  * @return {?number} The parsed date in seconds on success; otherwise, return
  154.  *   null.
  155.  */
  156. shaka.util.XmlUtils.parseDate = function(dateString) {
  157.   if (!dateString) {
  158.     return null;
  159.   }
  161.   // Times in the manifest should be in UTC.  If they don't specify a timezone,
  162.   // Date.parse() will use the local timezone instead of UTC.  So manually add
  163.   // the timezone if missing ('Z' indicates the UTC timezone).
  164.   // Format: YYYY-MM-DDThh:mm:ss.ssssss
  165.   if (/^\d+-\d+-\d+T\d+:\d+:\d+(\.\d+)?$/.test(dateString)) {
  166.     dateString += 'Z';
  167.   }
  169.   let result = Date.parse(dateString);
  170.   return (!isNaN(result) ? Math.floor(result / 1000.0) : null);
  171. };
  174. /**
  175.  * Parses an XML duration string.
  176.  * Negative values are not supported. Years and months are treated as exactly
  177.  * 365 and 30 days respectively.
  178.  * @param {string} durationString The duration string, e.g., "PT1H3M43.2S",
  179.  *   which means 1 hour, 3 minutes, and 43.2 seconds.
  180.  * @return {?number} The parsed duration in seconds on success; otherwise,
  181.  *   return null.
  182.  * @see {@link http://www.datypic.com/sc/xsd/t-xsd_duration.html}
  183.  */
  184. shaka.util.XmlUtils.parseDuration = function(durationString) {
  185.   if (!durationString) {
  186.     return null;
  187.   }
  189.   let re = '^P(?:([0-9]*)Y)?(?:([0-9]*)M)?(?:([0-9]*)D)?' +
  190.            '(?:T(?:([0-9]*)H)?(?:([0-9]*)M)?(?:([0-9.]*)S)?)?$';
  191.   let matches = new RegExp(re).exec(durationString);
  193.   if (!matches) {
  194.     shaka.log.warning('Invalid duration string:', durationString);
  195.     return null;
  196.   }
  198.   // Note: Number(null) == 0 but Number(undefined) == NaN.
  199.   let years = Number(matches[1] || null);
  200.   let months = Number(matches[2] || null);
  201.   let days = Number(matches[3] || null);
  202.   let hours = Number(matches[4] || null);
  203.   let minutes = Number(matches[5] || null);
  204.   let seconds = Number(matches[6] || null);
  206.   // Assume a year always has 365 days and a month always has 30 days.
  207.   let d = (60 * 60 * 24 * 365) * years +
  208.           (60 * 60 * 24 * 30) * months +
  209.           (60 * 60 * 24) * days +
  210.           (60 * 60) * hours +
  211.           60 * minutes +
  212.           seconds;
  213.   return isFinite(d) ? d : null;
  214. };
  217. /**
  218.  * Parses a range string.
  219.  * @param {string} rangeString The range string, e.g., "101-9213".
  220.  * @return {?{start: number, end: number}} The parsed range on success;
  221.  *   otherwise, return null.
  222.  */
  223. shaka.util.XmlUtils.parseRange = function(rangeString) {
  224.   let matches = /([0-9]+)-([0-9]+)/.exec(rangeString);
  226.   if (!matches) {
  227.     return null;
  228.   }
  230.   let start = Number(matches[1]);
  231.   if (!isFinite(start)) {
  232.     return null;
  233.   }
  235.   let end = Number(matches[2]);
  236.   if (!isFinite(end)) {
  237.     return null;
  238.   }
  240.   return {start: start, end: end};
  241. };
  244. /**
  245.  * Parses an integer.
  246.  * @param {string} intString The integer string.
  247.  * @return {?number} The parsed integer on success; otherwise, return null.
  248.  */
  249. shaka.util.XmlUtils.parseInt = function(intString) {
  250.   let n = Number(intString);
  251.   return (n % 1 === 0) ? n : null;
  252. };
  255. /**
  256.  * Parses a positive integer.
  257.  * @param {string} intString The integer string.
  258.  * @return {?number} The parsed positive integer on success; otherwise,
  259.  *   return null.
  260.  */
  261. shaka.util.XmlUtils.parsePositiveInt = function(intString) {
  262.   let n = Number(intString);
  263.   return (n % 1 === 0) && (n > 0) ? n : null;
  264. };
  267. /**
  268.  * Parses a non-negative integer.
  269.  * @param {string} intString The integer string.
  270.  * @return {?number} The parsed non-negative integer on success; otherwise,
  271.  *   return null.
  272.  */
  273. shaka.util.XmlUtils.parseNonNegativeInt = function(intString) {
  274.   let n = Number(intString);
  275.   return (n % 1 === 0) && (n >= 0) ? n : null;
  276. };
  279. /**
  280.  * Parses a floating point number.
  281.  * @param {string} floatString The floating point number string.
  282.  * @return {?number} The parsed floating point number on success; otherwise,
  283.  *   return null. May return -Infinity or Infinity.
  284.  */
  285. shaka.util.XmlUtils.parseFloat = function(floatString) {
  286.   let n = Number(floatString);
  287.   return !isNaN(n) ? n : null;
  288. };
  291. /**
  292.  * Evaluate a division expressed as a string.
  293.  * @param {string} exprString
  294.  *   The expression to evaluate, e.g. "200/2". Can also be a single number.
  295.  * @return {?number} The evaluated expression as floating point number on
  296.  *   success; otherwise return null.
  297.  */
  298. shaka.util.XmlUtils.evalDivision = function(exprString) {
  299.   let res;
  300.   let n;
  301.   if ((res = exprString.match(/^(\d+)\/(\d+)$/))) {
  302.     n = Number(res[1] / res[2]);
  303.   } else {
  304.     n = Number(exprString);
  305.   }
  306.   return !isNaN(n) ? n : null;
  307. };
  310. /**
  311.  * Parse a string and return the resulting root element if
  312.  * it was valid XML.
  313.  * @param {string} xmlString
  314.  * @param {string} expectedRootElemName
  315.  * @return {Element|undefined}
  316.  */
  317. shaka.util.XmlUtils.parseXmlString = function(xmlString, expectedRootElemName) {
  318.   const parser = new DOMParser();
  319.   let rootElem;
  320.   let xml;
  321.   try {
  322.     xml = parser.parseFromString(xmlString, 'text/xml');
  323.   } catch (exception) {}
  324.   if (xml) {
  325.     // The top-level element in the loaded xml should have the
  326.     // same type as the element linking.
  327.     if (xml.documentElement.tagName == expectedRootElemName) {
  328.       rootElem = xml.documentElement;
  329.     }
  330.   }
  331.   if (rootElem && rootElem.getElementsByTagName('parsererror').length > 0) {
  332.     return null;
  333.   }  // It had a parser error in it.
  335.   return rootElem;
  336. };
  339. /**
  340.  * Parse some UTF8 data and return the resulting root element if
  341.  * it was valid XML.
  342.  * @param {ArrayBuffer} data
  343.  * @param {string} expectedRootElemName
  344.  * @return {Element|undefined}
  345.  */
  346. shaka.util.XmlUtils.parseXml = function(data, expectedRootElemName) {
  347.   try {
  348.     const string = shaka.util.StringUtils.fromUTF8(data);
  349.     return shaka.util.XmlUtils.parseXmlString(string, expectedRootElemName);
  350.   } catch (exception) {}
  351. };