parse-hyperlinks 0.26.3

A Nom parser library for hyperlinks with markup.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

# Parse hyperlinks

[Parse-hyperlinks](https://crates.io/crates/parse-hyperlinks),
a parser library written with [Nom](https://crates.io/crates/nom) to
recognize hyperlinks and link reference definitions in Markdown,
reStructuredText, Asciidoc and HTML formatted text input.

[![Cargo](https://img.shields.io/crates/v/parse-hyperlinks.svg)](
https://crates.io/crates/parse-hyperlinks)
[![Documentation](https://docs.rs/parse-hyperlinks/badge.svg)](
https://docs.rs/parse-hyperlinks)
[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](
https://gitlab.com/getreu/parse-hyperlinks)

The library implements the
[CommonMark Specification 0.30](https://spec.commonmark.org/0.30/),
[reStructuredText Markup Specification](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html)
(revision 8571, date 2020-10-28), the specifications in
[Asciidoctor User Manual, chapter 26](https://asciidoctor.org/docs/user-manual/#url) (date 2020-12-03)
and [HTML 5.2: section 4.5](https://www.w3.org/TR/html52/textlevel-semantics.html#the-a-element).

To illustrate the usage and the
[API of the library](https://docs.rs/parse-hyperlinks/0.19.6/parse_hyperlinks/index.html),
[Parse-hyperlinks](https://crates.io/crates/parse-hyperlinks) comes with a
simple command line application:
[Atext2html](https://crates.io/crates/atext2html)


## The Parse-Hyperlinks input contract

1. All input is UTF-8 encoded.

2. The input text is formatted according to one of the markup language
   specification above. As Parse-Hyperlinks ignores most of the markup, it
   relies solely on the hyperlink specification of the respective markup
   language.



## General HTML requirements

1. The characters `&<>"` in absolute URLs in HTML documents must be _HTML-
   escape-encoded_: these characters are replaced with their entity names, e.g.
   `&amp;`, `&lt;`, `&gt;` and `&quote`.

2. Relative URLs (local links) in UTF-8 encoded HTML document, do not need to
   be HTML-escape encoded. I recommend not to do so.

3. Relative URLs (local links) must not be preceded by a scheme, e.g. `html:`.

4. In addition to HTML-escape-encoding, URLs can be _percent encoded_, e.g.
   `%20` or `%26`. When both encoding appear in an HTML document, the HTML
   escape decoding is applied first, then the percent encoding. 
   For example, the encoded string `Ü ber%26amp;Über &amp` is decoded to 
   `Ü  ber&amp;Über &`. In general, URLs in UTF-8 HTML documents can be 
   expressed without percent encoding, which is recommended.


      
## Parse-Hyperlinks output guaranties

The following section explains how Parse-Hyperlinks meets the above _General
HTML requirements_. It refers to the items in the list above.

1. Only functions in the `renderer` module, _HTML-escape_ encode absolute URLs
   in HTML documents: The characters `&<>"` are replaced with their HTML escape
   entity names, e.g.: `&amp;`, `&lt;`, `&gt;` and `&quote`. All other parsers
   and iterators do not apply HTML-escape-encoding to absolute URLs.

2. No function, parser or iterator in Parse-Hyperlinks applies 
   escape-encoding to relative URLs.

3. This property is not enforced by Parse-Hyperlinks. Compliance depend on
   the parser's input.

4. Percent-encoding in Parse-Hyperlinks:
  
   * No _percent encoding_ at all is performed in Parse-Hyperlinks.
   
   * _Percent decoding_: In some cases, when the markup language specification
     requires the input URL to be percent encoded, the concerned consuming
     parser decodes the percent encoding automatically.
     Percent decoding is URL's is performed implicitly when consuming:
     * Markdown autolinks when parsed by: `md_text2dest()`,
     * Asciidoc URLs when parsed by: `adoc_label2dest()`, `adoc_text2dest`
     * WikiText URLs when parsed by: `wikitext_text2dest()`

   * Rendered autolink markup:
   
     1. The same Markdown input may result in different HTML according to
        the renderer. For example: `pulldown-cmark` renders 
        the Markdown autolink  `<http://getreu.net/Ü%20&>` into 
        `<a href="http://getreu.net/%C3%9C%20&amp;">http://getreu.net/Ü%20&amp;</a>`.
        * Observation 1: the rendition contains percent and HTML escape codes.
        * Obesrvation 2: the link destination 
          (`http://getreu.net/%C3%9C%20&amp;`) and the link text
          (`http://getreu.net/Ü%20&amp;`) are slightly different, which has
          to be taken into account when detecting autolinks based on the HTML
          rendition.
  
     2. The Parse-Hyperlinks Markdown renderer gives for the same 
        input `<http://getreu.net/Ü%20&>` a slightly different result: 
        `<a href="http://getreu.net/Ü%20&amp;">http://getreu.net/Ü &amp;</a>`.
        Explanation: first the parser `md_text2dest()` (percent) decodes the
        URL to `http://getreu.net/Ü &` and the renderer function in the module
        `renderer` (HTML-escape) encodes the result into 
        `http://getreu.net/Ü%20&amp;`