UrlDetection.h File Reference

Finds the web links in a piece of plain text (GH #2396). More...

#include <wx/string.h>
#include <functional>
#include <vector>

Include dependency graph for UrlDetection.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	wxm::UrlSpan
	Where a link sits in a string: the index of its first character and its length. More...

Functions
std::vector< UrlSpan >	wxm::FindUrls (const wxString &text)
	Finds every http://, https:// and mailto: link in a piece of text.
bool	wxm::IsLaunchableUrl (const wxString &url)
	Is this a link wxMaxima may hand to the web browser?
wxString	wxm::ProtectUrls (const wxString &text, std::vector< wxString > &urls)
	Replaces every link in a text by a placeholder an exporter won't touch.
wxString	wxm::RestoreUrls (const wxString &text, const std::vector< wxString > &urls, const std::function< wxString(const wxString &)> &format)
	Undoes ProtectUrls(), writing each link as format(url) returns it.

Detailed Description

Finds the web links in a piece of plain text (GH #2396).

Text cells show a bare "https://..." as a clickable link, and the HTML and LaTeX exports turn it into a real link. All three need to agree on where a link starts and ends, so the rule lives here, in one GUI-free place a unit test can pin directly.

Links are derived from the text every time rather than stored anywhere: the file formats don't change, and a worksheet written by this version reads exactly the same in an older one.

Function Documentation

FindUrls()

std::vector< UrlSpan > wxm::FindUrls

(

const wxString &

text

)

Finds every http://, https:// and mailto: link in a piece of text.

A link has to begin a word (so "xhttp://" is not one) and runs until the first character a URL may not contain unescaped: whitespace, or one of <>"{}|\^`. Punctuation that ends a sentence rather than the link (".,;:!?'") is left out, and so is a closing parenthesis or bracket that has no opening partner inside the link &ndash; "(see https://example.org)" links to "https://example.org", while a Wikipedia address ending in "_(physics)" keeps its parenthesis.

Since whitespace ends a link, a link never spans two lines: soft line breaks, which the text cells only ever put at spaces, can't split one.

Cheap enough to run on every restyle: a text without a ':' is rejected before anything else is looked at, and otherwise it is one linear pass.

IsLaunchableUrl()

bool wxm::IsLaunchableUrl

(

const wxString &

url

)

Is this a link wxMaxima may hand to the web browser?

Only http, https and mailto are allowed. A worksheet is a document from somewhere else, and letting a click in it launch a "file:" link, or one of the scheme handlers an operating system registers for its own programs, would let that document start things on the user's machine.

ProtectUrls()

wxString wxm::ProtectUrls	(	const wxString &	text,
		std::vector< wxString > &	urls
	)

Replaces every link in a text by a placeholder an exporter won't touch.

The exporters escape a text cell's characters one kind at a time (LaTeX turns "_" into "\_", "%" into "\%", HTML "&" into "&amp;", ...) and then run the result through the Markdown converter. A link must come out of that unchanged, so it is parked in urls and represented by a run of private-use characters and digits, which none of those steps change. RestoreUrls() puts it back, formatted as the exporter wants it.