add "match" function

[gajus]

Used to extract 1 match from the result.

This function function could be invoked either from the select, e.g.

::attribute(href)::match("/salles/(.+)")

or from the declarative API manifest, e.g.

nid: {
  selector: '::attribute(href)',
  match: '\/salles\/(.+)'
}

An implementation:

const match = (inputRule: RegExp, subject: string): string => {
  if (inputRule.ignoreCase) {
    throw new Error('"rule" parameter value must be an instance of a case sensitive RegExp.');
  }

  const rule = new RegExp(inputRule.source, 'gm');
  const matches = [];

  let match;

    // eslint-disable-next-line
    while (match = rule.exec(subject)) {
      matches.push(match[1]);
    }

  if (!matches.length) {
    throw new Error('Did not match.');
  }

  if (matches.length !== 1) {
    throw new Error('Matched more than one group.');
  }

  return matches[0];
};

[rla]

I could see ::matchAll(regex) be useful too in the case when multiple matching parts from the element/attribute/property text needs to be extracted. Maybe this goes into a separate issue?

[gajus]

Maybe this goes into a separate issue?

Here is fine. :-)

I could see ::matchAll(regex) be useful too in the case when multiple matching parts from the element/attribute/property text needs to be extracted.

Do you have any example of when such would be the case?

In all cases that I have observed in practise, when multiple matches need to be made, then there is an additional selector that can be used, e.g. span. Though, you have explicitly said attribute values. Therefore, I'd be curious to know of a practical example.

My problem with matchAll is that it isn't strict, i.e. it can match 0, 1, or 100 results. As such, it would make sense to simply extract the text value and process it imperatively.

I could be overlooking a use case, though.

[rla]

@gajus

Do you have any example of when such would be the case?

I propose to label feature proposals lacking an use case with the label needs-use-case. This helps to focus. I admit I tend to shoot sometime not-well-thought-out ideas.

[gajus]

Raised an issue to track the proposal.

#7