Wire up Collection (#196)

* Prepare collection proxy

- Remove type alias `MatchArgs` 
- Add `ObjectMatchRule` and `ObjectMatchRuleBuilder`
- Add `IntoIterator` for `SateSet` and for `InterfaceSet`
- Add `FromIterator` for `StateSet` and for `InterfaceSet`, to `.collect` into a set.


* Update  type validation table
    -  `Live` is now known as `Politeness`
    -  `ObjectMatchRule` not verifiable due to `State` and `Role` being defined inconsistently.

* Implement `Default`  `InterfaceSet`

* Introduce `object_match` module and move all `ObjectMatchRule` related items there.

* Fix docs on `SortOrder`
* Add module level docs to CollectionProxy
* Document  `get_active_descendant`
* Document `get_matches`
* Document `get_matches_from`
* Document `get_matches_to`

atspi-common/src/interface.rs

@@ -111,11 +111,36 @@ impl InterfaceSet {
 		self.0.insert(other);
 	}
 
-	pub fn iter(self) -> impl Iterator<Item = Interface> {
+	#[must_use]
+	pub fn iter(&self) -> enumflags2::Iter<Interface> {
 		self.0.iter()
 	}
 }
 
+impl IntoIterator for InterfaceSet {
+	type IntoIter = enumflags2::Iter<Interface>;
+	type Item = Interface;
+
+	fn into_iter(self) -> Self::IntoIter {
+		self.iter()
+	}
+}
+
+impl IntoIterator for &InterfaceSet {
+	type IntoIter = enumflags2::Iter<Interface>;
+	type Item = Interface;
+
+	fn into_iter(self) -> Self::IntoIter {
+		self.iter()
+	}
+}
+
+impl Default for InterfaceSet {
+	fn default() -> Self {
+		Self::empty()
+	}
+}
+
 impl<'de> de::Deserialize<'de> for InterfaceSet {
 	fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
 	where
@@ -161,6 +186,18 @@ impl Type for InterfaceSet {
 	}
 }
 
+impl FromIterator<Interface> for InterfaceSet {
+	fn from_iter<T: IntoIterator<Item = Interface>>(iter: T) -> Self {
+		Self(BitFlags::from_iter(iter))
+	}
+}
+
+impl<'a> FromIterator<&'a Interface> for InterfaceSet {
+	fn from_iter<I: IntoIterator<Item = &'a Interface>>(iter: I) -> Self {
+		InterfaceSet(iter.into_iter().copied().collect())
+	}
+}
+
 impl From<Interface> for InterfaceSet {
 	fn from(value: Interface) -> Self {
 		Self(value.into())
@@ -249,4 +286,25 @@ mod tests {
 		let (decoded, _) = encoded.deserialize::<InterfaceSet>().unwrap();
 		assert!(object == decoded);
 	}
+
+	// The order of appearance of the interfaces is equal to the order in the enum.
+	#[test]
+	fn iterator_on_interface_set() {
+		let set =
+			InterfaceSet::new(Interface::Accessible | Interface::Action | Interface::Component);
+		let mut iter = set.into_iter();
+		assert_eq!(iter.next(), Some(Interface::Accessible));
+		assert_eq!(iter.next(), Some(Interface::Action));
+		assert_eq!(iter.next(), Some(Interface::Component));
+		assert_eq!(iter.next(), None);
+	}
+
+	#[test]
+	fn iterator_on_interface_set_ref() {
+		let set = InterfaceSet::new(Interface::Text | Interface::Collection | Interface::Component);
+		let mut iter = (&set).into_iter();
+		assert_eq!(iter.next(), Some(Interface::Collection));
+		assert_eq!(iter.next(), Some(Interface::Component));
+		assert_eq!(iter.next(), Some(Interface::Text));
+	}
 }

atspi-common/src/lib.rs

@@ -14,6 +14,8 @@ extern crate static_assertions;
 #[macro_use]
 pub(crate) mod macros;
 
+pub mod object_match;
+pub use object_match::{MatchType, ObjectMatchRule, SortOrder, TreeTraversalType};
 pub mod object_ref;
 pub use object_ref::ObjectRef;
 pub mod interface;
@@ -36,74 +38,8 @@ use zvariant::Type;
 
 pub type Result<T> = std::result::Result<T, AtspiError>;
 
-pub type MatchArgs<'a> = (
-	&'a [i32],
-	MatchType,
-	std::collections::HashMap<&'a str, &'a str>,
-	MatchType,
-	&'a [i32],
-	MatchType,
-	&'a [&'a str],
-	MatchType,
-	bool,
-);
-
 pub type TextSelection = (ObjectRef, i32, ObjectRef, i32, bool);
 
-#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, Type)]
-#[repr(u32)]
-/// Enumeration used by interface `CollectionProxy` to specify the way [`ObjectRef`]
-/// objects should be sorted.
-///
-/// [`ObjectRef`]: crate::object_ref::ObjectRef
-pub enum SortOrder {
-	/// Invalid sort order
-	Invalid,
-	/// Canonical sort order
-	Canonical,
-	/// Flow sort order
-	Flow,
-	/// Tab sort order
-	Tab,
-	/// Reverse canonical sort order
-	ReverseCanonical,
-	/// Reverse flow sort order
-	ReverseFlow,
-	/// Reverse tab sort order
-	ReverseTab,
-}
-
-/// Method of traversing a tree in the `CollectionProxy`.
-#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, Type)]
-#[repr(u32)]
-pub enum TreeTraversalType {
-	/// Restrict children tree traversal
-	RestrictChildren,
-	/// Restrict sibling tree traversal
-	RestrictSibling,
-	/// In-order tree traversal.
-	Inorder,
-}
-
-#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, Type)]
-#[repr(i32)]
-/// Enumeration used by [`MatchArgs`] to specify how to interpret [`ObjectRef`] objects.
-///
-/// [`ObjectRef`]: crate::object_ref::ObjectRef
-pub enum MatchType {
-	/// Invalid match type
-	Invalid,
-	/// true if all of the criteria are met.
-	All,
-	/// true if any of the criteria are met.
-	Any,
-	/// true if none of the criteria are met.
-	NA,
-	/// Same as [`Self::All`] if the criteria is non-empty;
-	/// for empty criteria this rule requires returned value to also have empty set.
-	Empty,
-}
-
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, Type)]
 #[repr(u32)]
 /// The coordinate type encodes the frame of reference.
@@ -293,16 +229,4 @@ mod tests {
 		let match_type_signature = rule_signature.slice(3..4);
 		assert_eq!(MatchType::signature(), match_type_signature);
 	}
-
-	#[test]
-	fn validate_tree_traversal_type_signature() {
-		let signature = method_args_signature!(member: "GetMatchesTo", interface: "org.a11y.atspi.Collection", argument: "tree");
-		assert_eq!(TreeTraversalType::signature(), signature);
-	}
-
-	#[test]
-	fn validate_sort_order_signature() {
-		let signature = method_args_signature!(member: "GetMatches", interface: "org.a11y.atspi.Collection", argument: "sortby");
-		assert_eq!(SortOrder::signature(), signature);
-	}
 }