code: def token_matches(
      doclike: types.DocLike,
      patterns: str
      | list[str]
      | list[dict[str, str]]
      | list[list[dict[str, str]]],
      *,
      on_match: Optional[Callable] = None,
  ) -> Iterable[Span]:
      """
      Extract ``Span`` s from a document or sentence matching one or more patterns
      of per-token attr:value pairs, with optional quantity qualifiers.
  
      Args:
          doclike
          patterns:
              One or multiple patterns to match against ``doclike``
              using a :class:`spacy.matcher.Matcher`.
  
              If list[dict] or list[list[dict]], each pattern is specified
              as attr: value pairs per token, with optional quantity qualifiers:
  
              - ``[{"POS": "NOUN"}]`` matches singular or plural nouns,
                like "friend" or "enemies"
              - ``[{"POS": "PREP"}, {"POS": "DET", "OP": "?"}, {"POS": "ADJ", "OP": "?"}, {"POS": "NOUN", "OP": "+"}]``
                matches prepositional phrases, like "in the future" or "from the distant past"
              - ``[{"IS_DIGIT": True}, {"TAG": "NNS"}]`` matches numbered plural nouns,
                like "60 seconds" or "2 beers"
              - ``[{"POS": "PROPN", "OP": "+"}, {}]`` matches proper nouns and
                whatever word follows them, like "Burton DeWilde yaaasss"
  
              If str or list[str], each pattern is specified as one or more
              per-token patterns separated by whitespace where attribute, value,
              and optional quantity qualifiers are delimited by colons. Note that
              boolean and integer values have special syntax --- "bool(val)" and
              "int(val)", respectively --- and that wildcard tokens still need
              a colon between the (empty) attribute and value strings.
  
              - ``"POS:NOUN"`` matches singular or plural nouns
              - ``"POS:PREP POS:DET:? POS:ADJ:? POS:NOUN:+"`` matches prepositional phrases
              - ``"IS_DIGIT:bool(True) TAG:NNS"`` matches numbered plural nouns
              - ``"POS:PROPN:+ :"`` matches proper nouns and whatever word follows them
  
              Also note that these pattern strings don't support spaCy v2.1's
              "extended" pattern syntax; if you need such complex patterns, it's
              probably better to use a list[dict] or list[list[dict]], anyway.
  
          on_match: Callback function to act on matches.
              Takes the arguments ``matcher``, ``doclike``, ``i`` and ``matches``.
  
      Yields:
          Next matching ``Span`` in ``doclike``, in order of appearance
  
      Raises:
          TypeError
          ValueError
  
      See Also:
          - https://spacy.io/usage/rule-based-matching
          - https://spacy.io/api/matcher
      """  # noqa: E501
      if isinstance(patterns, str):
          patterns = [_make_pattern_from_string(patterns)]
      elif isinstance(patterns, (list, tuple)):
          if all(isinstance(item, str) for item in patterns):
              patterns = [_make_pattern_from_string(pattern) for pattern in patterns]  # type: ignore
          elif all(isinstance(item, dict) for item in patterns):
              patterns = [patterns]  # type: ignore
          elif all(
              isinstance(item, (list, tuple)) for item in patterns
          ):
              pass  # already in the right format!
          else:
              raise TypeError(
                  errors.type_invalid_msg(
                      "patterns",
                      type(patterns),
                      Union[
                          str,
                          list[str],
                          list[dict[str, str]],
                          list[list[dict[str, str]]],
                      ],
                  )
              )
      else:
          raise TypeError(
              errors.type_invalid_msg(
                  "patterns",
                  type(patterns),
                  Union[
                      str,
                      list[str],
                      list[dict[str, str]],
                      list[list[dict[str, str]]],
                  ],
              )
          )
      matcher = Matcher(doclike.vocab)
      matcher.add("match", patterns, on_match=on_match)
      for match in matcher(doclike, as_spans=True):
          yield match
  
file_path: textacy/src/textacy/extract/matches.py
imports: from __future__ import annotations
  import re
  from typing import Callable, Iterable, Literal, Optional, Pattern, Union
  from spacy.matcher import Matcher
  from spacy.tokens import Span
  from ..None import constants, errors, types
label_desc: Use image node_id 1 for calling a global function with example usage: token_matches(doclike, patterns) without return types