Types crate v2

.github/workflows/ci.yml

@@ -64,8 +64,10 @@ jobs:
       - name: Install Dependencies
         run: |
           sudo apt -y install at-spi2-core systemd
-      - name: Run Tests
-        run: cargo test --features=unstable-traits
+      - name: Run Tests (tokio)
+        run: cargo test --workspace --no-default-features --features=unstable-traits,tokio -- --nocapture
+      - name: Run Tests (async-std)
+        run: cargo test --workspace --no-default-features --features=unstable-traits,async-std -- --nocapture
   rustfmt:
     runs-on: ubuntu-latest
     steps:
@@ -101,7 +103,7 @@ jobs:
         with:
           toolchain: nightly
       - name: Generate Documentation
-        run: cargo doc --all-features --no-deps
+        run: cargo doc --workspace --features unstable-traits --no-deps
   no-unused-dependencies:
     runs-on: ubuntu-latest
     steps:
@@ -154,7 +156,7 @@ jobs:
         # no default features so that it uses native Rust TLS instead of trying to link with system TLS.
         run: cargo install cargo-semver-checks --no-default-features
       - name: Check Semver Compliance
-        run: cargo semver-checks check-release -p atspi
+        run: cargo semver-checks check-release -p atspi --default-features
   msrv-compliance:
     runs-on: ubuntu-latest
     steps:
@@ -180,7 +182,7 @@ jobs:
       - name: Install Cargo MSRV Verifier
         run: cargo install cargo-msrv
       - name: Check MSRV Compliance
-        run: cargo msrv verify
+        run: cargo msrv --path atspi verify
   coverage:
     runs-on: ubuntu-latest
     steps:
@@ -189,7 +191,7 @@ jobs:
       - name: Install nightly
         uses: dtolnay/rust-toolchain@master
         with:
-          toolchain: nightly
+          toolchain: stable
           components: llvm-tools-preview
       - name: cargo install cargo-llvm-cov
         uses: taiki-e/install-action@cargo-llvm-cov
@@ -200,7 +202,7 @@ jobs:
         run: |
           sudo apt -y install at-spi2-core systemd
       - name: cargo llvm-cov
-        run: cargo llvm-cov --doctests --locked --features=unstable-traits --lcov --output-path lcov.info
+        run: cargo llvm-cov --workspace --locked --features=unstable-traits --lcov --output-path lcov.info
       - name: Upload to codecov.io
         uses: codecov/codecov-action@v3
         with:

Cargo.toml

@@ -1,47 +1,14 @@
-[package]
-name = "atspi"
-version = "0.15.1"
-authors = ["Michael Connor Buchan <mikey@blindcomputing.org>", "Tait Hoyem <tait@tait.tech>", "Alberto Tirla <albertotirla@gmail.com>", "DataTriny <datatriny@gmail.com>", "Luuk Duim <luukvanderduim@gmail.com>"]
-description = "Pure-Rust, zbus-based AT-SPI2 protocol implementation."
-license = "Apache-2.0 OR MIT" # For ease of integration in the Rust ecosystem.
-readme = "README.md"
-repository = "https://github.com/odilia-app/atspi"
-homepage = "https://github.com/odilia-app/atspi"
-keywords = ["screen-reader", "accessibility", "a11y", "tts", "linux"]
-categories = ["accessibility", "api-bindings"]
-edition = "2021"
-rust-version = "1.65"
-include = ["src/**/*", "atspi-macros/**/*", "LICENSE-*", "README.md"]
-
-[package.metadata.release]
-release = true
-publish = true
-
-[features]
-default = ["async-io", "client-accessories"]
-async-io = ["zbus/async-io"]
-gvariant = ["zbus/gvariant"]
-tokio = ["zbus/tokio"]
-client-accessories = ["dep:tracing", "dep:futures-lite"]
-unstable-traits = ["atspi-macros/unstable_atspi_proxy_macro", "atspi-macros/tokio", "dep:static_assertions", "dep:async-trait"]
-
-[dependencies]
-atspi-macros = { version = "0.3.0", path = "atspi-macros" }
-enumflags2 = "^0.7.7"
-serde = { version = "^1.0", default-features = false, features = ["derive"] }
-zbus = { version = "^3.6.2", default-features = false }
-# optioanl dependencies
-futures-lite = { version = "1.12", default-features = false, optional = true }
-tracing = { version = "^0.1.37", optional = true }
-static_assertions = { version = "^1.1.0", optional = true }
-async-trait = { version = "^0.1.59", optional = true }
-
-[dev-dependencies]
-byteorder = "1.4"
-serde_plain = "1.0.1"
-lazy_static = "1.0"
-tokio-stream = "0.1"
-tokio = { version = "1", default_features = false, features = ["macros", "rt-multi-thread"] }
-async-std = { version = "1", features = ["attributes"] }
-futures-lite = { version = "1.12", default-features = false }
-tokio-test = "0.4.2"
+[workspace]
+members = [
+  "atspi",
+	"atspi-proxies",
+	"atspi-common",
+	"atspi-macros",
+  "atspi-connection",
+  "atspi-client"
+]
+
+[workspace.dependencies]
+zbus = "3.12.0"
+tracing = "0.1.37"
+enumflags2 = "0.7.7"

atspi-client/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "atspi-client"
+version = "0.1.0"
+edition = "2021"
+description = "Client extensions for the atspi crate."
+readme = "README.md"
+categories = ["accessibility"]
+keywords = ["screen-reader", "accessibility", "a11y", "linux"]
+license = "Apache-2.0 OR MIT"
+repository = "https://github.com/odilia-app/atspi/"
+homepage = "https://github.com/odilia-app/atspi/"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[features]
+default = ["async-std"]
+tokio = ["atspi-proxies/tokio", "atspi-common/tokio"]
+async-std = ["atspi-proxies/async-std", "atspi-common/async-std"]
+
+[dependencies]
+async-trait = "0.1.68"
+static_assertions = "1.1.0"
+atspi-common = { path = "../atspi-common/", default-features = false }
+atspi-proxies = { path = "../atspi-proxies", default-features = false, features = ["unstable-traits"] }
+zbus.workspace = true

atspi-client/REAMDE.md

@@ -0,0 +1,6 @@
+# `atspi-client`
+
+For all AT-related extensions to `atspi`.
+
+This employs the use of some additional traits and implementations to make the creation of e.g. a screen reader more simple for developers.
+This is intended to work primarily with the Odilia screen reader, but others may find some use.

src/accessible_ext.rs → atspi-client/src/accessible_ext.rs

@@ -1,23 +1,19 @@
-use crate::{
-	accessible::{
-		Accessible, AccessibleBlocking, AccessibleProxy, AccessibleProxyBlocking, RelationType,
-		Role,
-	},
-	collection::MatchType,
-	convertable::{Convertable, ConvertableBlocking},
+use crate::convertable::{Convertable, ConvertableBlocking};
+use async_trait::async_trait;
+use atspi_common::{AtspiError as Error, MatcherArgs, ObjectPair, RelationType, Role};
+use atspi_proxies::{
+	accessible::{Accessible, AccessibleBlocking, AccessibleProxy, AccessibleProxyBlocking},
 	hyperlink::Hyperlink,
 	text::{Text, TextBlocking},
-	InterfaceSet,
 };
-use async_trait::async_trait;
 use std::collections::HashMap;
 
-pub type MatcherArgs =
-	(Vec<Role>, MatchType, HashMap<String, String>, MatchType, InterfaceSet, MatchType);
-
 #[async_trait]
 pub trait AccessibleExt {
 	type Error: std::error::Error;
+	async fn get_application_ext<'a>(&self) -> Result<Self, Self::Error>
+	where
+		Self: Sized;
 	async fn get_parent_ext<'a>(&self) -> Result<Self, Self::Error>
 	where
 		Self: Sized;
@@ -43,21 +39,20 @@ pub trait AccessibleExt {
 		&self,
 		matcher_args: &MatcherArgs,
 		backward: bool,
+		already_visited: &'a mut Vec<ObjectPair>,
 	) -> Result<Option<Self>, Self::Error>
 	where
 		Self: Sized;
-	async fn get_relation_set_ext<'a>(
-		&self,
-	) -> Result<HashMap<RelationType, Vec<Self>>, Self::Error>
+	/// Get all edges for a given accessible object.
+	/// This means: all children, siblings, and parent, in that order.
+	/// If a direction is specified, then it will only get the appicable matching siblings/children.
+	/// This also checks if the element supports the text interface, and then checks if the caret position is contained within the string, if it is, then children are also handled by direction.
+	async fn edges<'a>(&self, backward: Option<bool>) -> Result<Vec<Self>, Self::Error>
 	where
 		Self: Sized;
-	async fn find_inner<'a>(
+	async fn get_relation_set_ext<'a>(
 		&self,
-		after_or_before: i32,
-		matcher_args: &MatcherArgs,
-		backward: bool,
-		recur: bool,
-	) -> Result<Option<Self>, <Self as AccessibleExt>::Error>
+	) -> Result<HashMap<RelationType, Vec<Self>>, Self::Error>
 	where
 		Self: Sized;
 	async fn match_(
@@ -78,6 +73,9 @@ pub trait AccessibleExtError: Accessible + Convertable {
 		+ From<std::num::TryFromIntError>
 		+ Send;
 }
+impl AccessibleExtError for AccessibleProxy<'_> {
+	type Error = Error;
+}
 
 #[allow(clippy::module_name_repetitions)]
 pub trait AccessibleBlockingExtError: AccessibleBlocking + ConvertableBlocking {
@@ -88,10 +86,22 @@ pub trait AccessibleBlockingExtError: AccessibleBlocking + ConvertableBlocking {
 		+ From<<<Self as ConvertableBlocking>::Text as TextBlocking>::Error>
 		+ From<std::num::TryFromIntError>;
 }
+impl AccessibleBlockingExtError for AccessibleProxyBlocking<'_> {
+	type Error = Error;
+}
 
 #[async_trait]
-impl<T: Accessible + Convertable + AccessibleExtError + Send + Sync> AccessibleExt for T {
+impl<T: Accessible + Convertable + AccessibleExtError + Send + Sync + Clone> AccessibleExt for T
+where
+	ObjectPair: for<'c> TryFrom<&'c T>,
+{
 	type Error = <T as AccessibleExtError>::Error;
+	async fn get_application_ext<'a>(&self) -> Result<Self, Self::Error>
+	where
+		Self: Sized,
+	{
+		Ok(self.get_application().await?)
+	}
 	async fn get_parent_ext<'a>(&self) -> Result<Self, Self::Error>
 	where
 		Self: Sized,
@@ -130,7 +140,8 @@ impl<T: Accessible + Convertable + AccessibleExtError + Send + Sync> AccessibleE
 		Self: Sized,
 	{
 		let parent = self.parent().await?;
-		let index = self.get_index_in_parent().await?.try_into()?;
+		let pin = self.get_index_in_parent().await?;
+		let index = pin.try_into()?;
 		// Clippy false positive: Standard pattern for excluding index item from list.
 		#[allow(clippy::if_not_else)]
 		let children: Vec<Self> = parent
@@ -194,39 +205,68 @@ impl<T: Accessible + Convertable + AccessibleExtError + Send + Sync> AccessibleE
 		}
 		Ok(children_after_before)
 	}
+	async fn edges<'a>(&self, backward: Option<bool>) -> Result<Vec<Self>, Self::Error>
+	where
+		Self: Sized,
+	{
+		let mut edge_elements = Vec::new();
+		let children = match backward {
+			Some(backward) => {
+				if let Ok(caret_children) = self.get_children_caret(backward).await {
+					caret_children
+				} else {
+					self.get_children().await?
+				}
+			}
+			None => self.get_children().await?,
+		};
+		children.into_iter().for_each(|child| edge_elements.push(child));
+		let siblings = match backward {
+			Some(false) => self.get_siblings_before().await?,
+			Some(true) => self.get_siblings_after().await?,
+			None => self.get_siblings().await?,
+		};
+		siblings.into_iter().for_each(|sibling| edge_elements.push(sibling));
+		let parent = self.get_parent_ext().await?;
+		edge_elements.push(parent);
+		Ok(edge_elements)
+	}
 	async fn get_next<'a>(
 		&self,
 		matcher_args: &MatcherArgs,
 		backward: bool,
+		visited: &'a mut Vec<ObjectPair>,
 	) -> Result<Option<Self>, Self::Error>
 	where
 		Self: Sized,
 	{
-		// TODO if backwards, check here
-		let caret_children = self.get_children_caret(backward).await?;
-		for child in caret_children {
-			if child.match_(matcher_args).await? {
-				return Ok(Some(child));
-			} else if let Some(found_sub) =
-				child.find_inner(0, matcher_args, backward, true).await?
-			{
-				return Ok(Some(found_sub));
+		let mut stack: Vec<T> = Vec::new();
+		let edges = self.edges(Some(backward)).await?;
+		edges.into_iter().for_each(|edge| stack.push(edge));
+		while let Some(item) = stack.pop() {
+			// TODO: properly bubble up error
+			let Ok(identifier) = ObjectPair::try_from(&item) else {
+				return Ok(None);
+			};
+			// the top of the hirearchy for strctural navigation.
+			if visited.contains(&identifier) {
+				continue;
 			}
-		}
-		let mut last_parent_index = self.get_index_in_parent().await?;
-		if let Ok(mut parent) = self.get_parent_ext().await {
-			while parent.get_role().await? != Role::InternalFrame {
-				let found_inner_child = parent
-					.find_inner(last_parent_index, matcher_args, backward, false)
-					.await?;
-				if found_inner_child.is_some() {
-					return Ok(found_inner_child);
-				}
-				last_parent_index = parent.get_index_in_parent().await?;
-				parent = parent.get_parent_ext().await?;
+			visited.push(identifier);
+			if item.get_role().await? == Role::InternalFrame {
+				return Ok(None);
+			}
+			// if it matches, then return it
+			if item.match_(matcher_args).await? {
+				return Ok(Some(item));
 			}
+			// if it doesnt match, add all edges
+			self.edges(Some(backward))
+				.await?
+				.into_iter()
+				.for_each(|edge| stack.push(edge));
 		}
-		Ok(None)
+		return Ok(None);
 	}
 	async fn get_relation_set_ext<'a>(
 		&self,
@@ -245,42 +285,6 @@ impl<T: Accessible + Convertable + AccessibleExtError + Send + Sync> AccessibleE
 		}
 		Ok(relations)
 	}
-	async fn find_inner<'a>(
-		&self,
-		after_or_before: i32,
-		matcher_args: &MatcherArgs,
-		backward: bool,
-		recur: bool,
-	) -> Result<Option<Self>, <Self as AccessibleExt>::Error>
-	where
-		Self: Sized,
-	{
-		let children = if backward {
-			let mut vec = self.get_children_ext().await?;
-			vec.reverse();
-			vec
-		} else {
-			self.get_children_ext().await?
-		};
-		for child in children {
-			let child_index = child.get_index_in_parent().await?;
-			if !recur
-				&& ((child_index <= after_or_before && !backward)
-					|| (child_index >= after_or_before && backward))
-			{
-				continue;
-			}
-			if child.match_(matcher_args).await? {
-				return Ok(Some(child));
-			}
-			/* 0 here is ignored because we are recursive; see the line starting with if !recur */
-			if let Some(found_decendant) = child.find_inner(0, matcher_args, backward, true).await?
-			{
-				return Ok(Some(found_decendant));
-			}
-		}
-		Ok(None)
-	}
 	// TODO: make match more broad, allow use of other parameters; also, support multiple roles, since right now, multiple will just exit immediately with false
 	async fn match_(
 		&self,