add parse method to Parseable trait for easy parsing

check.sh

@@ -5,16 +5,18 @@ source /lib/gentoo/functions.sh
 
 export PATH="${HOME}/.local/bin:${PATH}" CC=clang CXX=clang++
 
-ldd=$(command -v ldd)
+lld=$(command -v lld)
 
 if [[ -n ${ldd} ]]; then
-    export LDFLAGS=-fuse-ld=${ldd}
+    export LDFLAGS=-fuse-ld=${lld}
 fi
 
 if [[ ! -d build ]]; then
-    meson setup -Dfuzz=enabled -Dtests=enabled build || exit $?
+    meson setup -Dfuzz=enabled -Dtests=enabled -Dbuildtype=debugoptimized -Ddocs=enabled build || exit $?
 fi
 
+meson compile -C build || exit $?
+
 ebegin "running check commands"
 parallel --halt soon,fail=1 --keep-order -j$(nproc) < check_commands.txt
 eend $? || exit $?

check_commands.txt

@@ -1,4 +1,5 @@
 /usr/bin/meson format --recursive --check-only
 rustfmt --edition 2024 --check $(find src -type f -name '*.rs')
+ninja rustdoc -C build
 ninja clippy -C build
-meson test unittests '*repo*' '*porthole*' -C build
+meson test unittests doctests '*repo*' '*porthole*' -C build

meson.build

@@ -28,3 +28,13 @@ endif
 if get_option('fuzz').enabled()
     subdir('fuzz')
 endif
+
+if get_option('docs').enabled()
+    rust.doctest(
+        'doctests',
+        gentoo_utils,
+        dependencies: [mon, get, itertools],
+        link_with: [thiserror],
+        args: ['--nocapture'],
+    )
+endif

meson.options

@@ -1,2 +1,3 @@
 option('fuzz', type: 'feature', value: 'disabled')
-option('tests', type: 'feature', value: 'disabled')
+option('tests', type: 'feature', value: 'disabled')
+option('docs', type: 'feature', value: 'disabled')

src/lib.rs

@@ -1,3 +1,17 @@
+//! Gentoo and PMS related utils.
+//!
+//! Currently implements:
+//! - parsers for atoms and DEPEND expressions
+//! - strongly typed representations of atoms, versions, etc
+//! - version comparison and equality impls
+//! - iterator over repos categories and ebuilds
+//!
+//! Planned features
+//! - profile evaluation
+//! - vdb reader
+//! - sourcing ebuilds with bash
+//!
+
 #![deny(clippy::pedantic, unused_imports)]
 #![allow(
     dead_code,
@@ -7,14 +21,71 @@
 )]
 #![feature(impl_trait_in_assoc_type)]
 
-use mon::{Parser, input::Input};
+use mon::{
+    Parser,
+    input::{Input, InputIter},
+};
 
 pub trait Parseable<'a, I: Input + 'a> {
     type Parser: Parser<I, Output = Self>;
 
     fn parser() -> Self::Parser;
+
+    fn parse(input: I) -> Result<Self, I>
+    where
+        Self: Sized,
+    {
+        Self::parser()
+            .parse_finished(InputIter::new(input))
+            .map_err(|e| e.rest())
+    }
 }
 
+/// Strongly typed atom and cpv representations.
+///
+/// Create atoms from parsers:
+/// ```
+/// use gentoo_utils::{Parseable, atom::Atom};
+///
+/// let emacs = Atom::parse("=app-editors/emacs-31.0-r1")
+///    .expect("failed to parse atom");
+///
+/// assert_eq!(emacs.to_string(), "=app-editors/emacs-31.0-r1");
+/// ````
+///
+/// Compare versions:
+/// ```
+/// use gentoo_utils::{Parseable, atom::Cpv};
+///
+/// let a = Cpv::parse("foo/bar-1.0").unwrap();
+/// let b = Cpv::parse("foo/bar-2.0").unwrap();
+///
+/// assert!(a < b);
+/// ```
 pub mod atom;
+
+/// Access to repos and ebuilds.
+///
+/// ```
+/// use gentoo_utils::repo::Repo;
+///
+/// let repo = Repo::new("/var/db/repos/gentoo");
+///
+/// for result in repo.categories().expect("failed to read categories") {
+///    let category = result.expect("failed to read category");
+///
+///    for result in category.ebuilds().expect("failed to read ebuilds") {
+///        let ebuild = result.expect("failed to read ebuild");
+///
+///        println!(
+///            "{}-{}: {}",
+///            ebuild.name(),
+///            ebuild.version(),
+///            ebuild.description().clone().unwrap_or("no description available".to_string())
+///        );
+///    }
+/// }
+///
+/// ```
 pub mod repo;
 pub mod useflag;