xrefs._XrefPattern Class Reference

Inheritance diagram for xrefs._XrefPattern:

Public Member Functions
	__init__ (self, md, SymbolsIndex symbols_index, Dict[str, str] packages)
	handleMatch (self, m, data)

Public Attributes
	symbols_index
	packages
	md

Static Public Attributes
str	XREF_RE = r'\[`(?P<symbol>[^]]+)`\]?\[\]|\[(?P<text>[^]]*)\]\[`(?P<target>[^]]+)`\]'

Protected Member Functions
Optional[str]	_resolve_ref (self, str ref)
str	_make_github_uri (self, str file, Optional[int] lineno=None)

Detailed Description

Converts xrefs into GitHub links.

Recognizes [`symbol`][] and [text][`symbol`] link formats where symbol
is expected to be one of the following:

* Fully qualified reference to a C++ class, method or function;
* Package URI pointing to one of the packages included in the SDK
checkout.
* File reference to one of the file in the SDK.

Definition at line 38 of file xrefs.py.

Constructor & Destructor Documentation

__init__()

xrefs._XrefPattern.__init__	(		self,
			md,
		SymbolsIndex	symbols_index,
		Dict[str, str]	packages
	)

Definition at line 52 of file xrefs.py.

                 packages: Dict[str, str]):
        super().__init__(_XrefPattern.XREF_RE)
        self.symbols_index = symbols_index
        self.packages = packages
        self.md = md
 

Member Function Documentation

_make_github_uri()

str xrefs._XrefPattern._make_github_uri (   self, str  file, Optional[int]   lineno = None  )

protected

Generates source link pointing to GitHub

Definition at line 109 of file xrefs.py.

    def _make_github_uri(self, file: str, lineno: Optional[int] = None) -> str:
        """Generates source link pointing to GitHub"""
        fragment = f'#L{lineno}' if lineno is not None else ''
        return f'https://github.com/dart-lang/sdk/blob/{self.symbols_index.commit}/{file}{fragment}'
 
 

_resolve_ref()

Optional[str] xrefs._XrefPattern._resolve_ref (   self, str  ref  )

protected

Definition at line 86 of file xrefs.py.

    def _resolve_ref(self, ref: str) -> Optional[str]:
        if ref.startswith('package:'):
            # Resolve as package uri via .packages.
            uri = urlparse(ref)
            (package_name, *path_to_file) = uri.path.split('/', 1)
            package_path = self.packages[package_name]
            if len(path_to_file) == 0:
                return self._make_github_uri(package_path)
            else:
                return self._make_github_uri(
                    os.path.join(package_path, path_to_file[0]))
        elif os.path.exists(ref):
            # Resolve as a file link.
            return self._make_github_uri(ref)
        else:
            # Resolve as a symbol.
            loc = self.symbols_index.try_resolve(ref)
            if loc is not None:
                return self._make_github_uri(loc.filename, loc.lineno)
 
        logging.error('Failed to resolve xref %s', ref)
        return None
 

handleMatch()

xrefs._XrefPattern.handleMatch	(		self,
			m,
			data
	)

Definition at line 59 of file xrefs.py.

    def handleMatch(self, m, data):
        text = m.group('text')
        symbol = m.group('symbol')
        if symbol is None:
            symbol = m.group('target')
 
        uri = self._resolve_ref(symbol) or '#broken-link'
 
        # Remember this xref. build process can later use this information
        # to produce xref reference section at the end of the markdown file.
        self.md.xrefs[f"`{symbol}`"] = uri
 
        # Create <a href='uri'>text</a> element. If text is not defined
        # simply use a slightly sanitized symbol name.
        anchor = etree.Element('a')
        anchor.attrib['href'] = uri
        anchor.attrib['target'] = '_blank'
        if text is not None:
            anchor.text = text
        else:
            code = etree.Element('code')
            code.text = re.sub(r'^dart::', '', symbol)
            anchor.append(code)
 
        # Replace the whole pattern match with anchor element.
        return anchor, m.start(0), m.end(0)
 

Member Data Documentation

md

xrefs._XrefPattern.md

Definition at line 57 of file xrefs.py.

packages

xrefs._XrefPattern.packages

Definition at line 56 of file xrefs.py.

symbols_index

xrefs._XrefPattern.symbols_index

Definition at line 55 of file xrefs.py.

XREF_RE

str xrefs._XrefPattern.XREF_RE = r'\[`(?P<symbol>[^]]+)`\]?\[\]|\[(?P<text>[^]]*)\]\[`(?P<target>[^]]+)`\]'

static

Definition at line 50 of file xrefs.py.

---

The documentation for this class was generated from the following file:

• third_party/dart-lang/sdk/runtime/tools/wiki/build/xrefs.py