hal_sdk/lib.rs
1//! # hal-sdk
2//!
3//! An asynchronous Rust SDK for the **HAL** open-archive search API.
4//!
5//! ## What is HAL?
6//!
7//! HAL (*Hyper Articles en Ligne*) is a French open-access repository operated by
8//! the [CCSD](https://www.ccsd.cnrs.fr/). Researchers deposit scholarly documents
9//! there — articles, preprints, theses, conference papers, reports — so that they
10//! remain freely available to everyone. It hosts millions of records, many of them
11//! in French, though the archive is multilingual and international.
12//!
13//! HAL exposes a public HTTP search API (backed by Apache Solr) documented at
14//! <https://api.archives-ouvertes.fr/docs/search>. This crate wraps that API in
15//! idiomatic, strongly typed Rust.
16//!
17//! ## Design
18//!
19//! The client is `async` and works on **both native targets and `wasm32`**
20//! (in the browser it uses the `fetch` API through `reqwest`). The HAL API sends
21//! `Access-Control-Allow-Origin: *`, so it can be queried directly from a web page.
22//!
23//! ## Quick start
24//!
25//! ```no_run
26//! use hal_sdk::HalClient;
27//!
28//! # async fn run() -> Result<(), hal_sdk::HalError> {
29//! let client = HalClient::new();
30//! let results = client.basic_search("programmation").await?;
31//! println!("{} documents found", results.num_found());
32//! for doc in results.docs() {
33//! println!("{} — {:?}", doc.docid, doc.label_s);
34//! }
35//! # Ok(())
36//! # }
37//! ```
38//!
39//! ## Building richer queries
40//!
41//! [`SearchQuery`] is a builder covering every search mode described in the HAL
42//! documentation: search within a field, several terms in a field, proximity
43//! search, field selection (`fl`), pagination and facets.
44//!
45//! ```no_run
46//! use hal_sdk::{HalClient, SearchQuery};
47//!
48//! # async fn run() -> Result<(), hal_sdk::HalError> {
49//! let client = HalClient::new();
50//!
51//! let query = SearchQuery::field("title_t", "europe")
52//! .fields(["docid", "label_s", "title_s", "authFullName_s", "producedDate_s"])
53//! .facet("docType_s")
54//! .page(0, 20);
55//!
56//! let results = client.search(&query).await?;
57//! # Ok(())
58//! # }
59//! ```
60//!
61//! ## History
62//!
63//! This crate is the companion project of chapter 16 ("Projet final : coder et
64//! publier une caisse") of the book *Rust* by Benoît Prieur, brought up to date:
65//! the original chapter shipped a minimal, blocking, basic-search-only library
66//! (`apiarchivesouvertesrust` `0.1`). This version modernises it into a complete,
67//! asynchronous, WebAssembly-capable SDK.
68
69#![forbid(unsafe_code)]
70#![warn(missing_docs)]
71
72/// The crate version, as published on crates.io.
73pub const VERSION: &str = env!("CARGO_PKG_VERSION");
74
75mod client;
76mod doc;
77mod error;
78mod query;
79mod response;
80
81pub use client::HalClient;
82pub use doc::HalDoc;
83pub use error::HalError;
84pub use query::{Field, SearchQuery};
85pub use response::{FacetCounts, ResponseBody, SearchResponse};