mdl_search.h File Reference

Pure search/discovery policy: query encoding, URL templating, and the honest zero-vs-broken result classifier. More...

#include <stddef.h>
#include <stdint.h>
#include "mdl_extract.h"

Include dependency graph for mdl_search.h:

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

Go to the source code of this file.

Enumerations
enum	mdl_search_outcome_t : uint8_t {   k_mdl_search_have_results = 0 ,   k_mdl_search_zero_results = 1 ,   k_mdl_search_markup_changed = 2 }
	The honest outcome of a parsed search/browse results page. More...

Functions
const char *	mdl_search_placeholder (void)
	The {q} placeholder a search-URL template must contain.
bool	mdl_query_encode (const char *term, char *out, size_t cap)
	Percent-encode a raw query term for safe inclusion in a URL.
bool	mdl_search_build_url (const char *tmpl, const char *encoded_term, char *out, size_t cap)
	Expand a query-URL template by substituting the encoded term for {q}.
mdl_search_outcome_t	mdl_search_classify (const mdl_hit_list_t *hits)
	Classify a parsed results page into an honest search outcome.
size_t	mdl_search_filter_series_hits (mdl_hit_list_t *hits, const char *chapter_marker)
	Remove chapter links and duplicate series URLs from discovery hits.

Detailed Description

Pure search/discovery policy: query encoding, URL templating, and the honest zero-vs-broken result classifier.

The network-free half of --search / --browse (#304). Three small, side-effect-free functions the discovery orchestrator (mdl_discover_run) composes with a governed page fetch and mdl_extract_hits:

• mdl_query_encode percent-encodes a raw search term so a request stays valid for spaces, &, #, + and non-ASCII UTF-8 bytes. The repo's pure-7-bit-ASCII rule constrains the source, not the runtime bytes: a term arriving from argv may hold UTF-8, and every non-unreserved byte is emitted as HH.
• mdl_search_build_url expands a site descriptor's query template by substituting the encoded term for the {q} placeholder.
• mdl_search_classify turns a parsed mdl_hit_list_t into one of three honest outcomes, so an empty result never masquerades as a successful search and a results page whose markup changed is reported as such.

Keeping these pure makes the whole discovery parse path unit-testable against a captured fixture with no network, which is exactly what #304 requires.

Copyright

Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Definition in file mdl_search.h.

Enumeration Type Documentation

mdl_search_outcome_t

enum mdl_search_outcome_t : uint8_t

The honest outcome of a parsed search/browse results page.

The distinction #304 demands: an empty list must never look like a successful search. mdl_search_classify maps the parsed hits plus the raw anchor tally onto exactly one of these, and the CLI prints a distinct message for each.

See also

mdl_search_classify()

Since

0.1.0

Enumerator
k_mdl_search_have_results	One or more hits matched; print them.
k_mdl_search_zero_results	Links present, none matched: a real no-hit.
k_mdl_search_markup_changed	No links at all: the page could not be read.

Definition at line 57 of file mdl_search.h.

Function Documentation

mdl_query_encode()

bool mdl_query_encode	(	const char *	term,
		char *	out,
		size_t	cap )

Percent-encode a raw query term for safe inclusion in a URL.

RFC 3986 encoding: the unreserved set (A-Z a-z 0-9 - . _ ~) is copied verbatim and every other byte – space, &, #, +, /, ?, and each byte of a multi-byte UTF-8 sequence – is written as HH with upper-case hex. Space becomes %20 (valid in both path and query), never +, so the result is unambiguous wherever the template places it.

Parameters

[in]	term	Raw term (may contain UTF-8 bytes), NUL-terminated.
[out]	out	Destination buffer for the NUL-terminated encoding.
[in]	cap	Capacity of out in bytes.

Returns

Whether the encoded term (plus its NUL) fit in out.

Return values

true	out holds the fully encoded term.
false	A NULL argument, cap == 0, or the encoding did not fit.

Precondition

term and out are non-NULL; out has room for cap bytes.

The caller treats false as "term too long", not "empty result".

Postcondition

On false with cap > 0, out[0] is '\0'.

On true, out contains only unreserved bytes and HH triplets.

Note

Thread-safe: writes only caller-provided storage.

See also

mdl_search_build_url

Since

0.1.0

Definition at line 75 of file mdl_search.c.

References internal_hex_digit(), internal_is_unreserved(), k_hi_nibble_shift, and k_triplet_len.

Referenced by internal_discover_url().

mdl_search_build_url()

bool mdl_search_build_url	(	const char *	tmpl,
		const char *	encoded_term,
		char *	out,
		size_t	cap )

Expand a query-URL template by substituting the encoded term for {q}.

Copies tmpl into out, replacing every {q} placeholder with encoded_term (already percent-encoded by mdl_query_encode). A template with no {q} is rejected – it could never carry the term, so silently fetching a fixed URL would be a lie about having searched.

Parameters

[in]	tmpl	Query-URL template holding at least one {q}.
[in]	encoded_term	The percent-encoded term to substitute.
[out]	out	Destination buffer for the NUL-terminated URL.
[in]	cap	Capacity of out in bytes.

Returns

Whether a URL containing the term was produced and fit.

Return values

true	out holds the expanded URL.
false	A NULL argument, cap == 0, no {q} in tmpl, or overflow.

Precondition

tmpl, encoded_term and out are non-NULL.

encoded_term came from mdl_query_encode (URL-safe bytes only).

Postcondition

On false with cap > 0, out[0] is '\0'.

On true, out contains encoded_term at each former {q}.

Note

Thread-safe: writes only caller-provided storage.

See also

mdl_query_encode

Since

0.1.0

Definition at line 108 of file mdl_search.c.

References memcpy(), s_placeholder, strlen(), and strncmp().

Referenced by internal_discover_url().

mdl_search_classify()

mdl_search_outcome_t mdl_search_classify

(

const mdl_hit_list_t *

hits

)

Classify a parsed results page into an honest search outcome.

The whole point of #304's honesty criterion in one pure decision. With at least one matched hit the outcome is k_mdl_search_have_results. With none, the raw anchor tally decides: a page that rendered links but matched none is a genuine k_mdl_search_zero_results, while a page carrying no resolvable links at all is k_mdl_search_markup_changed – the endpoint returned something we could not read as a results page (its markup drifted, or the request was blocked or answered with non-HTML). A NULL list is treated as unreadable.

Parameters

[in]

hits

Parsed hit list from mdl_extract_hits, or NULL.

Returns

The outcome class for hits.

Return values

k_mdl_search_have_results	hits->count > 0.
k_mdl_search_zero_results	count == 0 and anchors_seen > 0.
k_mdl_search_markup_changed	NULL, or count == 0 and no anchors seen.

Precondition

hits, when non-NULL, was filled by mdl_extract_hits.

The caller prints a distinct message per returned class.

Postcondition

No state is modified.

The returned class depends only on count and anchors_seen.

Note

Thread-safe: reads only its argument.

See also

mdl_extract_hits

Since

0.1.0

Definition at line 149 of file mdl_search.c.

References mdl_hit_list_t::anchors_seen, mdl_hit_list_t::count, k_mdl_search_have_results, k_mdl_search_markup_changed, and k_mdl_search_zero_results.

Referenced by mdl_discover_run().

mdl_search_filter_series_hits()

size_t mdl_search_filter_series_hits	(	mdl_hit_list_t *	hits,
		const char *	chapter_marker )

Remove chapter links and duplicate series URLs from discovery hits.

Site result pages commonly mix canonical series links with recent chapter links. A descriptor's chapter marker therefore acts as an exclusion as well as the series-page extraction selector. Exact duplicate URLs are collapsed while preserving first-seen order.

Parameters

[in,out]	hits	Parsed hit list to compact in place.
[in]	chapter_marker	Chapter URL substring to reject; an empty string disables only the chapter filter.

Returns

Number of entries removed.

Return values

0	No entry was removed, or an argument was NULL.

Precondition

hits and chapter_marker are non-NULL.

Every populated hit URL is NUL-terminated within its fixed buffer.

Postcondition

hits contains only canonical, unique series candidates.

The retained candidates preserve their original relative order.

Note

Thread-safe when callers use distinct hit lists.

Since

0.1.0

Definition at line 163 of file mdl_search.c.

References mdl_hit_list_t::count, mdl_hit_list_t::hits, strcmp(), strstr(), and mdl_hit_t::url.

Referenced by mdl_discover_run().

mdl_search_placeholder()

const char * mdl_search_placeholder

(

void

)

The {q} placeholder a search-URL template must contain.

Returns

Borrowed pointer to the static placeholder token ("{q}").

Return values

non-NULL

Always: the constant placeholder string.

Precondition

None.

Postcondition

No state is modified.

Note

Thread-safe: returns a constant.

Since

0.1.0

Definition at line 29 of file mdl_search.c.

References s_placeholder.

Referenced by internal_discover_url().