Extracts values from HTML. More...

#include <Rule.h>

Public Member Functions
	Rule (HtmlTag tag=HtmlTag::ANY, bool optional=false, bool greedy=false) noexcept
	Constructs a Rule with a known HTML tag.

	Rule (std::string tag, bool optional=false, bool greedy=false) noexcept
	Constructs a Rule with the HTML tag given as a string.

	~Rule () noexcept=default

	Rule (Rule &&) noexcept=default

	Rule (const Rule &other)

Rule &	operator= (Rule &&) noexcept=default

Rule &	operator= (const Rule &other)

const Rule *	child () const noexcept
	Returns the child or nullptr if childless.

const Rule *	next () const noexcept
	Returns the next rule or nullptr if no following rule.

const std::vector< Rule > &	nested () const noexcept
	Returns the nested rules.

Rule *	child () noexcept
	Returns the child or nullptr if childless.

Rule *	next () noexcept
	Returns the next rule or nullptr if no following rule.

std::vector< Rule > &	nested () noexcept
	Returns the nested rules.

Rule &	append_child (Rule new_child)
	Appends a child.

Rule &	append_next (Rule sibling)
	Appends a following Rule.

Rule &	append_nested (Rule nested)
	Appends a nested Rule.

Rule &	append_match (std::unique_ptr< Match > match)
	Appends a Match.

template<typename MatchType , typename... Args>
Rule &	append_match (Args &&... arg)
	Emplaces a Match.

Rule &	append_capture (std::unique_ptr< Capture > cap)
	Appends a Capture.

template<typename CaptureType , typename... Args>
Rule &	append_capture (Args &&... arg)
	Emplaces a Capture.

HtmlTag	get_tag () const noexcept
	Returns the HtmlTag this rule matches.

Rule &	set_tag (HtmlTag tag) noexcept
	Sets the HtmlTag this rule matches.

bool	is_optional () const noexcept
	Returns true if this rule is optional, i.e. if a match has to be found.

Rule &	set_optional (bool optional) noexcept
	Sets whether this rule is optional, i.e.

bool	is_greedy () const noexcept
	Returns true if this rule is to be matched repeatedly.

Rule &	set_greedy (bool greedy) noexcept
	Sets whether this rule is to be matched repeatedly.

std::optional< std::string >	get_tagname () const
	Get custom HTML tag name.

Rule &	set_tagname (const std::string &tagname)
	Set custom HTML tag name.

hext::Result	extract (const Html &html, std::uint64_t max_searches=0) const
	Recursively extracts values from an hext::HTML.

hext::Result	extract (const GumboNode *node, std::uint64_t max_searches=0) const
	Recursively extracts values from a GumboNode.

bool	matches (const GumboNode *node) const
	Returns true if this Rule matches node.

std::vector< ResultPair >	capture (const GumboNode *node) const
	Returns the result of applying every Capture to node.

Detailed Description

Extracts values from HTML.

A Rule defines how to match and capture HTML nodes. It can be applied to a GumboNode tree, where it recursively tries to find matches.

Example:: // create a rule that matches anchor elements, ..

Rule anchor(HtmlTag::A);

// .. which must have an attribute called "href"

anchor.append_match<AttributeMatch>("href")

// capture attribute href and save it as "link"

.append_capture<AttributeCapture>("href", "link");

{

// create a rule that matches image elements

Rule img(HtmlTag::IMG);

// capture attribute src and save it as "img"

img.append_capture<AttributeCapture>("src", "img");

// append the image-rule to the anchor-rule

anchor.append_child(std::move(img));

}

// anchor is now equivalent to the following hext:

// <a href:link><img src:img/></a>

Html html(

"<div><a href='/bob'> <img src='bob.jpg'/> </a></div>"

"<div><a href='/alice'><img src='alice.jpg'/></a></div>"

"<div><a href='/carol'><img src='carol.jpg'/></a></div>");

hext::Result result = anchor.extract(html);

// result will be equivalent to this:

// vector{

// map{

// {"link", "/bob"}

// {"img", "bob.jpg"}

// },

// map{

// {"link", "/alice"}

// {"img", "alice.jpg"}

// },

// map{

// {"link", "/carol"}

// {"img", "carol.jpg"}

// },

// }

hext::AttributeCapture
Captures an HTML Element's attribute.
Definition AttributeCapture.h:64

hext::AttributeMatch
Matches HTML elements having an HTML attribute with a certain name and, optionally,...
Definition AttributeMatch.h:60

hext::Html
A RAII wrapper for Gumbo.
Definition Html.h:47

hext::Rule
Extracts values from HTML.
Definition Rule.h:90

hext::Rule::extract
hext::Result extract(const Html &html, std::uint64_t max_searches=0) const
Recursively extracts values from an hext::HTML.

hext::Rule::append_capture
Rule & append_capture(std::unique_ptr< Capture > cap)
Appends a Capture.

hext::Rule::append_child
Rule & append_child(Rule new_child)
Appends a child.

hext::HtmlTag::A
@ A
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a

hext::HtmlTag::IMG
@ IMG
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img

hext::Result
std::vector< ResultMap > Result
A vector containing ResultMap.
Definition Result.h:45

Definition at line 89 of file Rule.h.

Constructor & Destructor Documentation

◆ Rule() [1/4]

hext::Rule::Rule	(	HtmlTag	tag = `HtmlTag::ANY`,
		bool	optional = `false`,
		bool	greedy = `false`
	)

explicitnoexcept

Constructs a Rule with a known HTML tag.

Parameters

tag	The HtmlTag that this rule matches. Default: Match any tag.
optional	A subtree matches only if all mandatory rules were matched. Optional rules on the other hand are ignored if not found. Default: Rule is mandatory.
greedy	Whether this rule should be repeated once a match is found. Default: Rule is matched once.

◆ Rule() [2/4]

hext::Rule::Rule	(	std::string	tag,
		bool	optional = `false`,
		bool	greedy = `false`
	)

explicitnoexcept

Constructs a Rule with the HTML tag given as a string.

Parameters

tag	The HTML tagname that this rule matches. Custom/unknown HTML tags are allowed. If the tagname is a standard-HTML tag, it is converted to an HtmlTag.
optional	A subtree matches only if all mandatory rules were matched. Optional rules on the other hand are ignored if not found. Default: Rule is mandatory.
greedy	Whether this rule should be repeated once a match is found. Default: Rule is matched once.

◆ ~Rule()

hext::Rule::~Rule ( )

defaultnoexcept

◆ Rule() [3/4]

hext::Rule::Rule ( Rule && )

defaultnoexcept

◆ Rule() [4/4]

hext::Rule::Rule ( const Rule & other )

Member Function Documentation

◆ append_capture() [1/2]

template<typename CaptureType , typename... Args>

Rule & hext::Rule::append_capture ( Args &&... arg )

inline

Emplaces a Capture.

Forwards arguments to std::make_unique.

Returns: A reference for this Rule to enable method chaining.

Definition at line 194 of file Rule.h.

◆ append_capture() [2/2]

Rule & hext::Rule::append_capture ( std::unique_ptr< Capture > cap )

Appends a Capture.

Parameters

cap	The Capture to append.

Returns: A reference for this Rule to enable method chaining.

◆ append_child()

Rule & hext::Rule::append_child ( Rule new_child )

Appends a child.

Parameters

new_child The Rule to append.

Returns: A reference for this Rule to enable method chaining.

◆ append_match() [1/2]

template<typename MatchType , typename... Args>

Rule & hext::Rule::append_match ( Args &&... arg )

inline

Emplaces a Match.

Forwards arguments to std::make_unique.

Returns: A reference for this Rule to enable method chaining.

Definition at line 177 of file Rule.h.

◆ append_match() [2/2]

Rule & hext::Rule::append_match ( std::unique_ptr< Match > match )

Appends a Match.

Parameters

match The Match to append.

Returns: A reference for this Rule to enable method chaining.

◆ append_nested()

Rule & hext::Rule::append_nested ( Rule nested )

Appends a nested Rule.

Parameters

nested The Rule to append.

Returns: A reference for this Rule to enable method chaining.

◆ append_next()

Rule & hext::Rule::append_next ( Rule sibling )

Appends a following Rule.

Parameters

sibling The Rule to append.

Returns: A reference for this Rule to enable method chaining.

◆ capture()

std::vector< ResultPair > hext::Rule::capture ( const GumboNode * node ) const

Returns the result of applying every Capture to node.

Parameters

node	A GumboNode that is to be captured.

◆ child() [1/2]

const Rule * hext::Rule::child ( ) const

noexcept

Returns the child or nullptr if childless.

◆ child() [2/2]

Rule * hext::Rule::child ( )

noexcept

Returns the child or nullptr if childless.

◆ extract() [1/2]

hext::Result hext::Rule::extract	(	const GumboNode *	node,
		std::uint64_t	max_searches = `0`
	)		const

Recursively extracts values from a GumboNode.

Parameters

max_searches Abort extraction by throwing a MaxSearchError after doing this amount of searches in the given GumboNode.

Returns: A vector containing maps filled with the captured name value pairs.

◆ extract() [2/2]

hext::Result hext::Rule::extract	(	const Html &	html,
		std::uint64_t	max_searches = `0`
	)		const

Recursively extracts values from an hext::HTML.

Parameters

max_searches Abort extraction by throwing a MaxSearchError after doing this amount of searches in the given Html.

Returns: A vector containing maps filled with the captured name value pairs.

◆ get_tag()

HtmlTag hext::Rule::get_tag ( ) const

noexcept

Returns the HtmlTag this rule matches.

◆ get_tagname()

std::optional< std::string > hext::Rule::get_tagname ( ) const

Get custom HTML tag name.

Returns: Empty optional if no custom HTML tag name.

◆ is_greedy()

bool hext::Rule::is_greedy ( ) const

noexcept

Returns true if this rule is to be matched repeatedly.

◆ is_optional()

bool hext::Rule::is_optional ( ) const

noexcept

Returns true if this rule is optional, i.e. if a match has to be found.

◆ matches()

bool hext::Rule::matches ( const GumboNode * node ) const

Returns true if this Rule matches node.

Parameters

node	A GumboNode that is to be matched.

◆ nested() [1/2]

const std::vector< Rule > & hext::Rule::nested ( ) const

noexcept

Returns the nested rules.

◆ nested() [2/2]

std::vector< Rule > & hext::Rule::nested ( )

noexcept

Returns the nested rules.

◆ next() [1/2]

const Rule * hext::Rule::next ( ) const

noexcept

Returns the next rule or nullptr if no following rule.

◆ next() [2/2]

Rule * hext::Rule::next ( )

noexcept

Returns the next rule or nullptr if no following rule.

◆ operator=() [1/2]

Rule & hext::Rule::operator= ( const Rule & other )

◆ operator=() [2/2]

Rule & hext::Rule::operator= ( Rule && )

defaultnoexcept

◆ set_greedy()

Rule & hext::Rule::set_greedy ( bool greedy )

noexcept

Sets whether this rule is to be matched repeatedly.

Returns: A reference for this Rule to enable method chaining.

◆ set_optional()

Rule & hext::Rule::set_optional ( bool optional )

noexcept

Sets whether this rule is optional, i.e.

if a match has to be found.

Returns: A reference for this Rule to enable method chaining.

◆ set_tag()

Rule & hext::Rule::set_tag ( HtmlTag tag )

noexcept

Sets the HtmlTag this rule matches.

Returns: A reference for this Rule to enable method chaining.

◆ set_tagname()

Rule & hext::Rule::set_tagname ( const std::string & tagname )

Set custom HTML tag name.

Note: The HTML tag name is only matched if this Rule's HtmlTag equals HtmlTag::UNKNOWN.

Returns: A reference for this Rule to enable method chaining.

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

hext/Rule.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Rule() [1/4]

◆ Rule() [2/4]

◆ ~Rule()

◆ Rule() [3/4]

◆ Rule() [4/4]

Member Function Documentation

◆ append_capture() [1/2]

◆ append_capture() [2/2]

◆ append_child()

◆ append_match() [1/2]

◆ append_match() [2/2]

◆ append_nested()

◆ append_next()

◆ capture()

◆ child() [1/2]

◆ child() [2/2]

◆ extract() [1/2]

◆ extract() [2/2]

◆ get_tag()

◆ get_tagname()

◆ is_greedy()

◆ is_optional()

◆ matches()

◆ nested() [1/2]

◆ nested() [2/2]

◆ next() [1/2]

◆ next() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ set_greedy()

◆ set_optional()

◆ set_tag()

◆ set_tagname()