From af9f0f81d8b546f97d768bacc75d9ae0452a5171 Mon Sep 17 00:00:00 2001 From: Markus Triska Date: Tue, 24 Jan 2023 22:42:58 +0100 Subject: [PATCH] DOC: convert library(sgml) documentation to DocLog format --- src/lib/sgml.pl | 81 ++++++++++++++++++++++++++++--------------------- 1 file changed, 47 insertions(+), 34 deletions(-) diff --git a/src/lib/sgml.pl b/src/lib/sgml.pl index a0370e8c..bccba1f3 100644 --- a/src/lib/sgml.pl +++ b/src/lib/sgml.pl @@ -2,56 +2,69 @@ Predicates for parsing HTML and XML documents. Written 2020-2022 by Markus Triska (triska@metalevel.at) Part of Scryer Prolog. +- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */ - Currently, two predicates are provided: +/** Predicates for parsing HTML and XML documents. - - load_html(+Source, -Es, +Options) - - load_xml(+Source, -Es, +Options) +Currently, two predicates are provided: - These predicates parse HTML and XML documents, respectively. + - `load_html(+Source, -Es, +Options)` + - `load_xml(+Source, -Es, +Options)` - Source must be one of: +These predicates parse HTML and XML documents, respectively. - - a list of characters with the document contents - - stream(S), specifying a stream S from which to read the content - - file(Name), where Name is a list of characters specifying a file name. +Source must be one of: - Es is unified with the abstract syntax tree of the parsed document, - represented as a list of elements where each is of the form: + - a list of characters with the document contents + - `stream(S)`, specifying a stream S from which to read the content + - `file(Name)`, where Name is a list of characters specifying a file name. - * a list of characters, representing text - * element(Name, Attrs, Children) - - Name, an atom, is the name of the tag - - Attrs is a list of Key=Value pairs: - Key is an atom, and Value is a list of characters - - Children is a list of elements as specified here. +Es is unified with the abstract syntax tree of the parsed document, +represented as a list of elements where each is of the form: - Currently, Options are ignored. In the future, more options may be - provided to control parsing. + * a list of characters, representing text - Example: + * `element(Name, Attrs, Children)` - ?- load_html("Hello!", Es, []). + - `Name`, an atom, is the name of the tag - Yielding: + - `Attrs` is a list of `Key=Value` pairs: + `Key` is an atom, and `Value` is a list of characters - Es = [element(html,[], - [element(head,[], - [element(title,[], - ["Hello!"])]), - element(body,[],[])])]. + - `Children` is a list of elements as specified here. - library(xpath) provides convenient reasoning about parsed documents. - For example, to fetch the title of the document above, we can use: +Currently, Options are ignored. In the future, more options may be +provided to control parsing. - ?- load_html("Hello!", Es, []), - xpath(Es, //title(text), T). +Example: - Yielding T = "Hello!". +``` + ?- load_html("Hello!", Es, []). +``` - Use http_open/3 from library(http/http_open) to read answers from - web servers via streams. -- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */ +Yielding: + +``` + Es = [element(html,[], + [element(head,[], + [element(title,[], + ["Hello!"])]), + element(body,[],[])])]. +``` + +`library(xpath)` provides convenient reasoning about parsed documents. +For example, to fetch the title of the document above, we can use: + +``` + ?- load_html("Hello!", Es, []), + xpath(Es, //title(text), T). +``` + +Yielding `T = "Hello!"`. + +Use `http_open/3` from `library(http/http_open)` to read answers from +web servers via streams. +*/ :- module(sgml, [load_html/3, load_xml/3]). -- 2.54.0