descriptions

Author: burrbull

svd-rs/CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Bump MSRV to 1.58.0
 
 - `array::names` returns custom names if specified
+- add `Description` trait and `array::descriptions`
 
 ## [v0.14.2] - 2023-04-04
 

svd-rs/src/array.rs

@@ -1,4 +1,4 @@
-use super::{DimElement, Name};
+use super::{Description, DimElement, Name};
 use core::ops::{Deref, DerefMut};
 
 /// A single SVD instance or array of instances
@@ -50,23 +50,50 @@ where
     }
 }
 
+impl<T> Description for MaybeArray<T>
+where
+    T: Description,
+{
+    fn description(&self) -> Option<&str> {
+        T::description(self)
+    }
+}
+
 /// Return list of names of instances in array
 pub fn names<'a, T: Name>(info: &'a T, dim: &'a DimElement) -> impl Iterator<Item = String> + 'a {
     let name = info.name();
     dim.indexes().map(move |i| {
         dim.dim_array_index
             .as_ref()
-            .map(|dai| {
+            .and_then(|dai| {
                 dai.values
                     .iter()
                     .find(|e| e.value.map(|v| v.to_string().as_str() == i.deref()) == Some(true))
             })
-            .flatten()
             .map(|n| n.name.clone())
             .unwrap_or_else(|| name.replace("[%s]", &i).replace("%s", &i))
     })
 }
 
+/// Return list of descriptions of instances in array
+pub fn descriptions<'a, T: Description>(
+    info: &'a T,
+    dim: &'a DimElement,
+) -> impl Iterator<Item = Option<String>> + 'a {
+    let description = info.description();
+    dim.indexes().map(move |i| {
+        dim.dim_array_index
+            .as_ref()
+            .and_then(|dai| {
+                dai.values
+                    .iter()
+                    .find(|e| e.value.map(|v| v.to_string().as_str() == i.deref()) == Some(true))
+            })
+            .and_then(|n| n.description.clone())
+            .or_else(|| description.map(|d| d.replace("[%s]", &i).replace("%s", &i)))
+    })
+}
+
 #[cfg(feature = "serde")]
 mod ser_de {
     use super::*;

svd-rs/src/cluster.rs

@@ -3,7 +3,7 @@ use super::{
         AllRegistersIter, AllRegistersIterMut, ClusterIter, ClusterIterMut, RegisterIter,
         RegisterIterMut,
     },
-    BuildError, DimElement, EmptyToNone, MaybeArray, Name, Register, RegisterCluster,
+    BuildError, Description, DimElement, EmptyToNone, MaybeArray, Name, Register, RegisterCluster,
     RegisterProperties, SvdError, ValidateLevel,
 };
 
@@ -320,3 +320,9 @@ impl Name for ClusterInfo {
         &self.name
     }
 }
+
+impl Description for ClusterInfo {
+    fn description(&self) -> Option<&str> {
+        self.description.as_deref()
+    }
+}

svd-rs/src/device.rs

@@ -1,5 +1,6 @@
 use super::{
-    BuildError, Cpu, EmptyToNone, Name, Peripheral, RegisterProperties, SvdError, ValidateLevel,
+    BuildError, Cpu, Description, EmptyToNone, Name, Peripheral, RegisterProperties, SvdError,
+    ValidateLevel,
 };
 
 /// Errors for [`Device::validate`]
@@ -402,3 +403,9 @@ impl Name for Device {
         &self.name
     }
 }
+
+impl Description for Device {
+    fn description(&self) -> Option<&str> {
+        Some(&self.description)
+    }
+}

svd-rs/src/enumeratedvalue.rs

@@ -1,4 +1,4 @@
-use super::{BuildError, EmptyToNone, Name, SvdError, ValidateLevel};
+use super::{BuildError, Description, EmptyToNone, Name, SvdError, ValidateLevel};
 
 /// Describes a single entry in the enumeration.
 #[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
@@ -152,3 +152,9 @@ impl Name for EnumeratedValue {
         &self.name
     }
 }
+
+impl Description for EnumeratedValue {
+    fn description(&self) -> Option<&str> {
+        self.description.as_deref()
+    }
+}

svd-rs/src/field.rs

@@ -1,6 +1,7 @@
 use super::{
-    bitrange, Access, BitRange, BuildError, DimElement, EmptyToNone, EnumeratedValues, MaybeArray,
-    ModifiedWriteValues, Name, ReadAction, SvdError, Usage, ValidateLevel, WriteConstraint,
+    bitrange, Access, BitRange, BuildError, Description, DimElement, EmptyToNone, EnumeratedValues,
+    MaybeArray, ModifiedWriteValues, Name, ReadAction, SvdError, Usage, ValidateLevel,
+    WriteConstraint,
 };
 
 /// Describes a field or fields of a [register](crate::RegisterInfo).
@@ -367,3 +368,9 @@ impl Name for FieldInfo {
         &self.name
     }
 }
+
+impl Description for FieldInfo {
+    fn description(&self) -> Option<&str> {
+        self.description.as_deref()
+    }
+}

svd-rs/src/interrupt.rs

@@ -1,4 +1,4 @@
-use super::{BuildError, Name, SvdError, ValidateLevel};
+use super::{BuildError, Description, Name, SvdError, ValidateLevel};
 
 /// Describes an interrupt in the device
 #[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
@@ -112,3 +112,9 @@ impl Name for Interrupt {
         &self.name
     }
 }
+
+impl Description for Interrupt {
+    fn description(&self) -> Option<&str> {
+        self.description.as_deref()
+    }
+}

svd-rs/src/lib.rs

@@ -253,3 +253,27 @@ where
         T::name(*self)
     }
 }
+
+/// Get SVD element description
+pub trait Description {
+    /// Get description
+    fn description(&self) -> Option<&str>;
+}
+
+impl<T> Description for &T
+where
+    T: Description,
+{
+    fn description(&self) -> Option<&str> {
+        T::description(*self)
+    }
+}
+
+impl<T> Description for &mut T
+where
+    T: Description,
+{
+    fn description(&self) -> Option<&str> {
+        T::description(*self)
+    }
+}

svd-rs/src/peripheral.rs

@@ -3,8 +3,8 @@ use super::{
         AllRegistersIter, AllRegistersIterMut, ClusterIter, ClusterIterMut, RegisterIter,
         RegisterIterMut,
     },
-    AddressBlock, BuildError, Cluster, DimElement, EmptyToNone, Interrupt, MaybeArray, Name,
-    Register, RegisterCluster, RegisterProperties, SvdError, ValidateLevel,
+    AddressBlock, BuildError, Cluster, Description, DimElement, EmptyToNone, Interrupt, MaybeArray,
+    Name, Register, RegisterCluster, RegisterProperties, SvdError, ValidateLevel,
 };
 
 /// A single peripheral or array of peripherals
@@ -479,3 +479,9 @@ impl Name for PeripheralInfo {
         &self.name
     }
 }
+
+impl Description for PeripheralInfo {
+    fn description(&self) -> Option<&str> {
+        self.description.as_deref()
+    }
+}

svd-rs/src/register.rs

@@ -1,6 +1,7 @@
 use super::{
-    Access, BuildError, DimElement, EmptyToNone, Field, MaybeArray, ModifiedWriteValues, Name,
-    ReadAction, RegisterProperties, SvdError, ValidateLevel, WriteConstraint,
+    Access, BuildError, Description, DimElement, EmptyToNone, Field, MaybeArray,
+    ModifiedWriteValues, Name, ReadAction, RegisterProperties, SvdError, ValidateLevel,
+    WriteConstraint,
 };
 
 /// A single register or array of registers. A register is a named, programmable resource that belongs to a [peripheral](crate::Peripheral).
@@ -372,3 +373,9 @@ impl Name for RegisterInfo {
         &self.name
     }
 }
+
+impl Description for RegisterInfo {
+    fn description(&self) -> Option<&str> {
+        self.description.as_deref()
+    }
+}