Source: parser/parsedHedTag.js

  1. import { IssueError } from '../issues/issues'
  2. import ParsedHedSubstring from './parsedHedSubstring'
  3. import { SchemaValueTag } from '../schema/entries'
  4. import TagConverter from './tagConverter'
  5. import { ReservedChecker } from './reservedChecker'
  7. const TWO_LEVEL_TAGS = new Set(['Definition', 'Def', 'Def-expand'])
  8. const allowedRegEx = /^[^{},]*$/
  10. /**
  11.  * A parsed HED tag.
  12.  */
  13. export default class ParsedHedTag extends ParsedHedSubstring {
  14.   /**
  15.    * The formatted canonical version of the HED tag.
  16.    * @type {string}
  17.    */
  18.   formattedTag
  20.   /**
  21.    * The canonical form of the HED tag.
  22.    * @type {string}
  23.    */
  24.   canonicalTag
  26.   /**
  27.    * The HED schema this tag belongs to.
  28.    * @type {Schema}
  29.    */
  31.   schema
  32.   /**
  33.    * The schema's representation of this tag.
  34.    *
  35.    * @type {SchemaTag}
  36.    * @private
  37.    */
  39.   _schemaTag
  41.   /**
  42.    * The remaining part of the tag after the portion actually in the schema.
  43.    * @type {string}
  44.    * @private
  45.    */
  46.   _remainder
  48.   /**
  49.    * The value of the tag, if any.
  50.    * @type {string}
  51.    * @private
  52.    */
  53.   _value
  55.   /**
  56.    * If definition, this is the second value, otherwise empty string.
  57.    * @type {string}
  58.    * @private
  59.    */
  60.   _splitValue
  62.   /**
  63.    * The units if any.
  64.    * @type {string}
  65.    * @private
  66.    */
  67.   _units
  69.   /**
  70.    * Constructor.
  71.    *
  72.    * @param {TagSpec} tagSpec The token for this tag.
  73.    * @param {Schemas} hedSchemas The collection of HED schemas.
  74.    * @param {string} hedString The original HED string.
  75.    * @throws {IssueError} If tag conversion or parsing fails.
  76.    */
  77.   constructor(tagSpec, hedSchemas, hedString) {
  78.     super(tagSpec.tag, tagSpec.bounds) // Sets originalTag and originalBounds
  79.     this._convertTag(hedSchemas, hedString, tagSpec)
  80.     this._normalized = this.format(false) // Sets various forms of the tag.
  81.   }
  83.   /**
  84.    * Convert this tag to its various forms
  85.    *
  86.    * @param {Schemas} hedSchemas The collection of HED schemas.
  87.    * @param {string} hedString The original HED string.
  88.    * @param {TagSpec} tagSpec The token for this tag.
  89.    * @throws {IssueError} If tag conversion or parsing fails.
  90.    */
  91.   _convertTag(hedSchemas, hedString, tagSpec) {
  92.     const schemaName = tagSpec.library
  93.     this.schema = hedSchemas.getSchema(schemaName)
  94.     if (this.schema === undefined) {
  95.       if (schemaName !== '') {
  96.         IssueError.generateAndThrow('unmatchedLibrarySchema', {
  97.           tag: this.originalTag,
  98.           library: schemaName,
  99.         })
  100.       } else {
  101.         IssueError.generateAndThrow('unmatchedBaseSchema', {
  102.           tag: this.originalTag,
  103.         })
  104.       }
  105.     }
  107.     const [schemaTag, remainder] = new TagConverter(tagSpec, hedSchemas).convert()
  108.     this._schemaTag = schemaTag
  109.     this._remainder = remainder
  110.     this.canonicalTag = this._schemaTag.longExtend(remainder)
  111.     this.formattedTag = this.canonicalTag.toLowerCase()
  112.     this._handleRemainder(schemaTag, remainder)
  113.   }
  115.   /**
  116.    * Handle the remainder portion for value tag (converter handles others).
  117.    *
  118.    * @param {SchemaTag} schemaTag - The part of the tag that is in the schema.
  119.    * @param {string} remainder - the leftover part.
  120.    * @throws {IssueError} If parsing the remainder section fails.
  121.    * @private
  122.    */
  123.   _handleRemainder(schemaTag, remainder) {
  124.     if (!(schemaTag instanceof SchemaValueTag)) {
  125.       return
  126.     }
  127.     // Check that there is a value if required
  128.     const reserved = ReservedChecker.getInstance()
  129.     if ((schemaTag.hasAttribute('requireChild') || reserved.requireValueTags.has(schemaTag.name)) && remainder === '') {
  130.       IssueError.generateAndThrow('valueRequired', { tag: this.originalTag })
  131.     }
  132.     // Check if this could have a two-level value
  133.     const [value, rest] = this._getSplitValue(remainder)
  134.     this._splitValue = rest
  136.     // Resolve the units and check
  137.     const [actualUnit, actualUnitString, actualValueString] = this._separateUnits(schemaTag, value)
  138.     this._units = actualUnitString
  139.     this._value = actualValueString
  141.     if (actualUnit === null && actualUnitString !== null) {
  142.       IssueError.generateAndThrow('unitClassInvalidUnit', { tag: this.originalTag })
  143.     }
  144.     if (!this.checkValue(actualValueString)) {
  145.       IssueError.generateAndThrow('invalidValue', { tag: this.originalTag })
  146.     }
  147.   }
  149.   /**
  150.    * Separate the remainder of the tag into three parts.
  151.    *
  152.    * @param {SchemaTag} schemaTag - The part of the tag that is in the schema.
  153.    * @param {string} remainder - The leftover part.
  154.    * @returns {Array} - [SchemaUnit, string, string] representing the actual Unit, the unit string and the value string.
  155.    * @throws {IssueError} - If parsing the remainder section fails.
  156.    */
  157.   _separateUnits(schemaTag, remainder) {
  158.     const unitClasses = schemaTag.unitClasses
  159.     let actualUnit = null
  160.     let actualUnitString = null
  161.     let actualValueString = remainder // If no unit class, the remainder is the value
  162.     for (let i = 0; i < unitClasses.length; i++) {
  163.       ;[actualUnit, actualUnitString, actualValueString] = unitClasses[i].extractUnit(remainder)
  164.       if (actualUnit !== null) {
  165.         break // found the unit
  166.       }
  167.     }
  168.     return [actualUnit, actualUnitString, actualValueString]
  169.   }
  171.   /**
  172.    * Handle reserved three-level tags.
  173.    * @param {string} remainder - The remainder of the tag string after schema tag.
  174.    */
  175.   _getSplitValue(remainder) {
  176.     if (!TWO_LEVEL_TAGS.has(this.schemaTag.name)) {
  177.       return [remainder, null]
  178.     }
  179.     const [first, ...rest] = remainder.split('/')
  180.     return [first, rest.join('/')]
  181.   }
  183.   /**
  184.    * Nicely format this tag.
  185.    *
  186.    * @param {boolean} long - Whether the tags should be in long form.
  187.    * @returns {string} - The nicely formatted version of this tag.
  188.    */
  189.   format(long = true) {
  190.     let tagName
  191.     if (long) {
  192.       tagName = this._schemaTag?.longExtend(this._remainder)
  193.     } else {
  194.       tagName = this._schemaTag?.extend(this._remainder)
  195.     }
  196.     if (tagName === undefined) {
  197.       tagName = this.originalTag
  198.     }
  199.     if (this.schema?.prefix) {
  200.       return this.schema.prefix + ':' + tagName
  201.     } else {
  202.       return tagName
  203.     }
  204.   }
  206.   /**
  207.    * Return the normalized version of this tag.
  208.    * @returns {string} - The normalized version of this tag.
  209.    */
  210.   get normalized() {
  211.     return this._normalized
  212.   }
  214.   /**
  215.    * Override of {@link Object.prototype.toString}.
  216.    *
  217.    * @returns {string} The original form of this HED tag.
  218.    */
  219.   toString() {
  220.     if (this.schema?.prefix) {
  221.       return this.schema.prefix + ':' + this.originalTag
  222.     } else {
  223.       return this.originalTag
  224.     }
  225.   }
  227.   /**
  228.    * Determine whether this tag has a given attribute.
  229.    *
  230.    * @param {string} attribute An attribute name.
  231.    * @returns {boolean} Whether this tag has the named attribute.
  232.    */
  233.   hasAttribute(attribute) {
  234.     return this.schemaTag.hasAttribute(attribute)
  235.   }
  237.   /**
  238.    * Determine if this HED tag is equivalent to another HED tag.
  239.    *
  240.    * Note: HED tags are deemed equivalent if they have the same schema and normalized tag string.
  241.    *
  242.    * @param {ParsedHedTag} other - A HED tag to compare with this one.
  243.    * @returns {boolean} Whether {@link other} True, if other is equivalent to this HED tag.
  244.    */
  245.   equivalent(other) {
  246.     return other instanceof ParsedHedTag && this.formattedTag === other.formattedTag && this.schema === other.schema
  247.   }
  249.   /**
  250.    * Get the schema tag object for this tag.
  251.    *
  252.    * @returns {SchemaTag} The schema tag object for this tag.
  253.    */
  254.   get schemaTag() {
  255.     if (this._schemaTag instanceof SchemaValueTag) {
  256.       return this._schemaTag.parent
  257.     } else {
  258.       return this._schemaTag
  259.     }
  260.   }
  262.   /**
  263.    * Indicates whether the tag is deprecated
  264.    * @returns {boolean}
  265.    */
  266.   get isDeprecated() {
  267.     return this.schemaTag.hasAttribute('deprecatedFrom')
  268.   }
  270.   /**
  271.    * Indicates whether the tag is deprecated
  272.    * @returns {boolean}
  273.    */
  274.   get isExtended() {
  275.     return !this.takesValueTag && this._remainder !== ''
  276.   }
  278.   /**
  279.    * Get the schema tag object for this tag's value-taking form.
  280.    *
  281.    * @returns {SchemaValueTag} The schema tag object for this tag's value-taking form.
  282.    */
  283.   get takesValueTag() {
  284.     if (this._schemaTag instanceof SchemaValueTag) {
  285.       return this._schemaTag
  286.     }
  287.     return undefined
  288.   }
  290.   /**
  291.    * Checks if this HED tag has the {@code takesValue} attribute.
  292.    *
  293.    * @returns {boolean} Whether this HED tag has the {@code takesValue} attribute.
  294.    */
  295.   get takesValue() {
  296.     return this.takesValueTag !== undefined
  297.   }
  299.   /**
  300.    * Checks if this HED tag has the {@code unitClass} attribute.
  301.    *
  302.    * @returns {boolean} Whether this HED tag has the {@code unitClass} attribute.
  303.    */
  304.   get hasUnitClass() {
  305.     if (!this.takesValueTag) {
  306.       return false
  307.     }
  308.     return this.takesValueTag.hasUnitClasses
  309.   }
  311.   /**
  312.    * Get the unit classes for this HED tag.
  313.    *
  314.    * @returns {SchemaUnitClass[]} The unit classes for this HED tag.
  315.    */
  316.   get unitClasses() {
  317.     if (this.hasUnitClass) {
  318.       return this.takesValueTag.unitClasses
  319.     }
  320.     return []
  321.   }
  323.   /**
  324.    * Check if value is a valid value for this tag.
  325.    *
  326.    * @param {string} value - The value to be checked.
  327.    * @returns {boolean} The result of check -- false if not a valid value.
  328.    */
  329.   checkValue(value) {
  330.     if (!this.takesValue) {
  331.       return false
  332.     }
  333.     if (value === '#') {
  334.       // Placeholders work
  335.       return true
  336.     }
  337.     const valueAttributeNames = this._schemaTag.valueAttributeNames
  338.     const valueClassNames = valueAttributeNames?.get('valueClass')
  339.     if (!valueClassNames) {
  340.       // No specified value classes
  341.       return allowedRegEx.test(value)
  342.     }
  343.     const entryManager = this.schema.entries.valueClasses
  344.     for (let i = 0; i < valueClassNames.length; i++) {
  345.       if (entryManager.getEntry(valueClassNames[i]).validateValue(value)) return true
  346.     }
  347.     return false
  348.   }
  349. }