improv: localization improvements

wiiznokes · web-flow · commit 452fad6f3d2e · 2024-06-04T00:44:30.000+02:00
diff --git a/README.md b/README.md
@@ -1,17 +1,24 @@
 # Freedesktop Desktop Entry Specification
 
+[![crates.io](https://img.shields.io/crates/v/freedesktop_desktop_entry?style=flat-square&logo=rust)](https://crates.io/crates/freedesktop_desktop_entry)
+[![docs.rs](https://img.shields.io/badge/docs.rs-freedesktop_desktop_entry-blue?style=flat-square&logo=docs.rs)](https://docs.rs/freedesktop_desktop_entry)
+
 This crate provides a library for efficiently parsing [Desktop Entry](https://specifications.freedesktop.org/desktop-entry-spec/latest/index.html) files.
 
 ```rust
 use std::fs;
 
-use freedesktop_desktop_entry::{default_paths, DesktopEntry, Iter, PathSource};
+use freedesktop_desktop_entry::{
+    default_paths, get_languages_from_env, DesktopEntry, Iter, PathSource,
+};
 
 fn main() {
+    let locales = get_languages_from_env();
+
     for path in Iter::new(default_paths()) {
         let path_src = PathSource::guess_from(&path);
         if let Ok(bytes) = fs::read_to_string(&path) {
-            if let Ok(entry) = DesktopEntry::decode(&path, &bytes) {
+            if let Ok(entry) = DesktopEntry::decode_from_str(&path, &bytes, &locales) {
                 println!("{:?}: {}\n---\n{}", path_src, path.display(), entry);
             }
         }
diff --git a/examples/all_files.rs b/examples/all_files.rs
@@ -8,12 +8,12 @@ use freedesktop_desktop_entry::{
 };
 
 fn main() {
-    let locale = get_languages_from_env();
+    let locales = get_languages_from_env();
 
     for path in Iter::new(default_paths()) {
         let path_src = PathSource::guess_from(&path);
         if let Ok(bytes) = fs::read_to_string(&path) {
-            if let Ok(entry) = DesktopEntry::decode_from_str(&path, &bytes, &locale) {
+            if let Ok(entry) = DesktopEntry::decode_from_str(&path, &bytes, &locales) {
                 println!("{:?}: {}\n---\n{}", path_src, path.display(), entry);
             }
         }
diff --git a/examples/specific_file.rs b/examples/specific_file.rs
@@ -4,7 +4,7 @@ use freedesktop_desktop_entry::DesktopEntry;
 
 fn main() {
     let path = Path::new("tests/org.mozilla.firefox.desktop");
-    let locales = &["fr", "en"];
+    let locales = &["fr_FR", "en", "it"];
 
     // if let Ok(bytes) = fs::read_to_string(path) {
     //     if let Ok(entry) = DesktopEntry::decode_from_str(path, &bytes, locales) {
diff --git a/src/decoder.rs b/src/decoder.rs
@@ -33,13 +33,15 @@ impl<'a> DesktopEntry<'a> {
         let mut active_group = Cow::Borrowed("");
         let mut ubuntu_gettext_domain = None;
 
+        let locales = add_generic_locales(locales);
+
         for line in input.lines() {
             process_line(
                 line,
                 &mut groups,
                 &mut active_group,
                 &mut ubuntu_gettext_domain,
-                locales,
+                &locales,
                 Cow::Borrowed,
             )
         }
@@ -60,8 +62,9 @@ impl<'a> DesktopEntry<'a> {
         L: AsRef<str>,
     {
         let mut buf = String::new();
+        let locales = add_generic_locales(locales);
 
-        paths.map(move |path| decode_from_path_with_buf(path, locales, &mut buf))
+        paths.map(move |path| decode_from_path_with_buf(path, &locales, &mut buf))
     }
 
     /// Return an owned [`DesktopEntry`]
@@ -73,7 +76,8 @@ impl<'a> DesktopEntry<'a> {
         L: AsRef<str>,
     {
         let mut buf = String::new();
-        decode_from_path_with_buf(path, locales, &mut buf)
+        let locales = add_generic_locales(locales);
+        decode_from_path_with_buf(path, &locales, &mut buf)
     }
 }
 
@@ -188,3 +192,20 @@ where
         ubuntu_gettext_domain,
     })
 }
+
+/// Ex: if a locale equal fr_FR, add fr
+fn add_generic_locales<'a, L: AsRef<str>>(locales: &'a [L]) -> Vec<&'a str> {
+    let mut v = Vec::with_capacity(locales.len() + 1);
+
+    for l in locales {
+        let l = l.as_ref();
+
+        v.push(l);
+
+        if let Some(start) = memchr::memchr(b'_', l.as_bytes()) {
+            v.push(l.split_at(start).0)
+        }
+    }
+
+    v
+}
diff --git a/src/iter.rs b/src/iter.rs
@@ -9,6 +9,7 @@ pub struct Iter {
 }
 
 impl Iter {
+    /// Directories will be processed in order, starting from the end.
     pub fn new(directories_to_walk: Vec<PathBuf>) -> Self {
         Self {
             directories_to_walk,
@@ -25,8 +26,7 @@ impl Iterator for Iter {
             let mut iterator = match self.actively_walking.take() {
                 Some(dir) => dir,
                 None => {
-                    while !self.directories_to_walk.is_empty() {
-                        let path = self.directories_to_walk.remove(0);
+                    while let Some(path) = self.directories_to_walk.pop() {
                         match fs::read_dir(&path) {
                             Ok(directory) => {
                                 self.actively_walking = Some(directory);
@@ -37,6 +37,7 @@ impl Iterator for Iter {
                             Err(_) => continue,
                         }
                     }
+                
 
                     return None;
                 }
@@ -48,7 +49,7 @@ impl Iterator for Iter {
 
                     if let Ok(file_type) = entry.file_type() {
                         if file_type.is_dir() {
-                            self.directories_to_walk.insert(0, path);
+                            self.directories_to_walk.push(path);
                         } else if (file_type.is_file() || file_type.is_symlink())
                             && path.extension().map_or(false, |ext| ext == "desktop")
                         {
diff --git a/src/lib.rs b/src/lib.rs
@@ -70,61 +70,80 @@ impl<'a> DesktopEntry<'a> {
 }
 
 impl<'a> DesktopEntry<'a> {
-    pub fn action_entry(&'a self, action: &str, key: &str) -> Option<&'a Cow<'a, str>> {
+    /// An action is defined as `[Desktop Action actions-name]` where `action-name`
+    /// is defined in the `Actions` field of `[Desktop Entry]`.
+    /// Example: to get the `Name` field of this `new-window` action
+    /// ```txt
+    /// [Desktop Action new-window]
+    /// Name=Open a New Window
+    /// ```
+    /// you will need to call
+    /// ```rust
+    /// entry.action_entry("new-window", "Name")
+    /// ```
+    pub fn action_entry(&'a self, action: &str, key: &str) -> Option<&'a str> {
         let group = self
             .groups
             .get(["Desktop Action ", action].concat().as_str());
 
         Self::entry(group, key)
     }
 
-    pub fn action_entry_localized(
+    pub fn action_entry_localized<L: AsRef<str>>(
         &'a self,
         action: &str,
         key: &str,
-        locale: Option<&str>,
+        locales: &[L],
     ) -> Option<Cow<'a, str>> {
         let group = self
             .groups
             .get(["Desktop Action ", action].concat().as_str());
 
-        Self::localized_entry(self.ubuntu_gettext_domain.as_deref(), group, key, locale)
+        Self::localized_entry(self.ubuntu_gettext_domain.as_deref(), group, key, locales)
     }
 
-    pub fn action_exec(&'a self, action: &str) -> Option<&'a Cow<'a, str>> {
+    pub fn action_exec(&'a self, action: &str) -> Option<&'a str> {
         self.action_entry(action, "Exec")
     }
 
-    pub fn action_name(&'a self, action: &str, locale: Option<&str>) -> Option<Cow<'a, str>> {
-        self.action_entry_localized(action, "Name", locale)
+    pub fn action_name<L: AsRef<str>>(
+        &'a self,
+        action: &str,
+        locales: &[L],
+    ) -> Option<Cow<'a, str>> {
+        self.action_entry_localized(action, "Name", locales)
     }
 
+    /// Return actions separated by `;`
     pub fn actions(&'a self) -> Option<&'a str> {
         self.desktop_entry("Actions")
     }
 
+    /// Return categories separated by `;`
     pub fn categories(&'a self) -> Option<&'a str> {
         self.desktop_entry("Categories")
     }
 
-    pub fn comment(&'a self, locale: Option<&str>) -> Option<Cow<'a, str>> {
-        self.desktop_entry_localized("Comment", locale)
+    pub fn comment<L: AsRef<str>>(&'a self, locales: &[L]) -> Option<Cow<'a, str>> {
+        self.desktop_entry_localized("Comment", locales)
     }
 
+    /// A desktop entry field is any field under the
+    /// `[Desktop Entry]` line
     pub fn desktop_entry(&'a self, key: &str) -> Option<&'a str> {
         Self::entry(self.groups.get("Desktop Entry"), key).map(|e| e.as_ref())
     }
 
-    pub fn desktop_entry_localized(
+    pub fn desktop_entry_localized<L: AsRef<str>>(
         &'a self,
         key: &str,
-        locale: Option<&str>,
+        locales: &[L],
     ) -> Option<Cow<'a, str>> {
         Self::localized_entry(
             self.ubuntu_gettext_domain.as_deref(),
             self.groups.get("Desktop Entry"),
             key,
-            locale,
+            locales,
         )
     }
 
@@ -136,8 +155,8 @@ impl<'a> DesktopEntry<'a> {
         self.desktop_entry("X-Flatpak")
     }
 
-    pub fn generic_name(&'a self, locale: Option<&str>) -> Option<Cow<'a, str>> {
-        self.desktop_entry_localized("GenericName", locale)
+    pub fn generic_name<L: AsRef<str>>(&'a self, locales: &[L]) -> Option<Cow<'a, str>> {
+        self.desktop_entry_localized("GenericName", locales)
     }
 
     pub fn icon(&'a self) -> Option<&'a str> {
@@ -148,16 +167,18 @@ impl<'a> DesktopEntry<'a> {
         self.appid.as_ref()
     }
 
-    pub fn keywords(&'a self) -> Option<Cow<'a, str>> {
-        self.desktop_entry_localized("Keywords", None)
+    /// Return keywords separated by `;`
+    pub fn keywords<L: AsRef<str>>(&'a self, locales: &[L]) -> Option<Cow<'a, str>> {
+        self.desktop_entry_localized("Keywords", locales)
     }
 
+    /// Return mime types separated by `;`
     pub fn mime_type(&'a self) -> Option<&'a str> {
         self.desktop_entry("MimeType")
     }
 
-    pub fn name(&'a self, locale: Option<&str>) -> Option<Cow<'a, str>> {
-        self.desktop_entry_localized("Name", locale)
+    pub fn name<L: AsRef<str>>(&'a self, locales: &[L]) -> Option<Cow<'a, str>> {
+        self.desktop_entry_localized("Name", locales)
     }
 
     pub fn no_display(&'a self) -> bool {
@@ -192,33 +213,42 @@ impl<'a> DesktopEntry<'a> {
         self.desktop_entry(key).map_or(false, |v| v == "true")
     }
 
-    fn entry(group: Option<&'a KeyMap<'a>>, key: &str) -> Option<&'a Cow<'a, str>> {
-        group.and_then(|group| group.get(key)).map(|key| &key.0)
+    fn entry(group: Option<&'a KeyMap<'a>>, key: &str) -> Option<&'a str> {
+        group
+            .and_then(|group| group.get(key))
+            .map(|key| key.0.as_ref())
     }
 
-    pub(crate) fn localized_entry(
+    pub(crate) fn localized_entry<L: AsRef<str>>(
         ubuntu_gettext_domain: Option<&'a str>,
         group: Option<&'a KeyMap<'a>>,
         key: &str,
-        locale: Option<&str>,
+        locales: &[L],
     ) -> Option<Cow<'a, str>> {
-        group.and_then(|group| group.get(key)).and_then(|key| {
-            locale
-                .and_then(|locale| match key.1.get(locale).cloned() {
-                    Some(value) => Some(value),
-                    None => {
-                        if let Some(pos) = locale.find('_') {
-                            key.1.get(&locale[..pos]).cloned()
-                        } else {
-                            None
+        let Some(group) = group else {
+            return None;
+        };
+
+        let Some((default_value, locale_map)) = group.get(key) else {
+            return None;
+        };
+
+        for locale in locales {
+            match locale_map.get(locale.as_ref()) {
+                Some(value) => return Some(value.clone()),
+                None => {
+                    if let Some(pos) = memchr::memchr(b'_', locale.as_ref().as_bytes()) {
+                        if let Some(value) = locale_map.get(&locale.as_ref()[..pos]) {
+                            return Some(value.clone());
                         }
                     }
-                })
-                .or_else(|| {
-                    ubuntu_gettext_domain.map(|domain| Cow::Owned(dgettext(domain, &key.0)))
-                })
-                .or(Some(key.0.clone()))
-        })
+                }
+            }
+        }
+        if let Some(domain) = ubuntu_gettext_domain {
+            return Some(Cow::Owned(dgettext(domain, &default_value)));
+        }
+        return Some(default_value.clone());
     }
 }
 
@@ -292,6 +322,7 @@ impl PathSource {
 
 /// Returns the default paths in which desktop entries should be searched for based on the current
 /// environment.
+/// Paths are sorted by priority, in reverse, e.i the path with the greater priority will be at the end.
 ///
 /// Panics in case determining the current home directory fails.
 pub fn default_paths() -> Vec<PathBuf> {
@@ -300,40 +331,31 @@ pub fn default_paths() -> Vec<PathBuf> {
     data_dirs.push(base_dirs.get_data_home());
     data_dirs.append(&mut base_dirs.get_data_dirs());
 
-    data_dirs.iter().map(|d| d.join("applications")).collect()
+    data_dirs
+        .iter()
+        .map(|d| d.join("applications"))
+        .rev()
+        .collect()
 }
 
-fn dgettext(domain: &str, message: &str) -> String {
+pub(crate) fn dgettext(domain: &str, message: &str) -> String {
     use gettextrs::{setlocale, LocaleCategory};
     setlocale(LocaleCategory::LcAll, "");
     gettextrs::dgettext(domain, message)
 }
 
-// todo: support more variable syntax like fr_FR.
-// This will require some work in decode and values query
-// for now, just remove the _* part, cause it seems more common
-
 /// Get the configured user language env variables.
 /// See https://wiki.archlinux.org/title/Locale#LANG:_default_locale for more information
 pub fn get_languages_from_env() -> Vec<String> {
     let mut l = Vec::new();
 
-    if let Ok(mut lang) = std::env::var("LANG") {
-        if let Some(start) = memchr::memchr(b'_', lang.as_bytes()) {
-            lang.truncate(start);
-            l.push(lang)
-        } else {
-            l.push(lang);
-        }
+    if let Ok(lang) = std::env::var("LANG") {
+        l.push(lang);
     }
 
     if let Ok(lang) = std::env::var("LANGUAGES") {
         lang.split(':').for_each(|lang| {
-            if let Some(start) = memchr::memchr(b'_', lang.as_bytes()) {
-                l.push(lang.split_at(start).0.to_owned())
-            } else {
-                l.push(lang.to_owned());
-            }
+            l.push(lang.to_owned());
         })
     }
 
diff --git a/src/matching.rs b/src/matching.rs
diff --git a/src/test.rs b/src/test.rs

Original file line number	Diff line number	Diff line change
`@@ -8,12 +8,12 @@ use freedesktop_desktop_entry::{`
`8`	`8`	`};`
`9`	`9`
`10`	`10`	`fn main() {`
`11`		`- let locale = get_languages_from_env();`
	`11`	`+ let locales = get_languages_from_env();`
`12`	`12`
`13`	`13`	`for path in Iter::new(default_paths()) {`
`14`	`14`	`let path_src = PathSource::guess_from(&path);`
`15`	`15`	`if let Ok(bytes) = fs::read_to_string(&path) {`
`16`		`- if let Ok(entry) = DesktopEntry::decode_from_str(&path, &bytes, &locale) {`
	`16`	`+ if let Ok(entry) = DesktopEntry::decode_from_str(&path, &bytes, &locales) {`
`17`	`17`	`println!("{:?}: {}\n---\n{}", path_src, path.display(), entry);`
`18`	`18`	`}`
`19`	`19`	`}`
Original file line number	Diff line number	Diff line change
`@@ -9,6 +9,7 @@ pub struct Iter {`
`9`	`9`	`}`
`10`	`10`
`11`	`11`	`impl Iter {`
	`12`	`+ /// Directories will be processed in order, starting from the end.`
`12`	`13`	`pub fn new(directories_to_walk: Vec<PathBuf>) -> Self {`
`13`	`14`	`Self {`
`14`	`15`	`directories_to_walk,`
`@@ -25,8 +26,7 @@ impl Iterator for Iter {`
`25`	`26`	`let mut iterator = match self.actively_walking.take() {`
`26`	`27`	`Some(dir) => dir,`
`27`	`28`	`None => {`
`28`		`- while !self.directories_to_walk.is_empty() {`
`29`		`- let path = self.directories_to_walk.remove(0);`
	`29`	`+ while let Some(path) = self.directories_to_walk.pop() {`
`30`	`30`	`match fs::read_dir(&path) {`
`31`	`31`	`Ok(directory) => {`
`32`	`32`	`self.actively_walking = Some(directory);`
`@@ -37,6 +37,7 @@ impl Iterator for Iter {`
`37`	`37`	`Err(_) => continue,`
`38`	`38`	`}`
`39`	`39`	`}`
	`40`	`+`
`40`	`41`
`41`	`42`	`return None;`
`42`	`43`	`}`
`@@ -48,7 +49,7 @@ impl Iterator for Iter {`
`48`	`49`
`49`	`50`	`if let Ok(file_type) = entry.file_type() {`
`50`	`51`	`if file_type.is_dir() {`
`51`		`- self.directories_to_walk.insert(0, path);`
	`52`	`+ self.directories_to_walk.push(path);`
`52`	`53`	`} else if (file_type.is_file() \|\| file_type.is_symlink())`
`53`	`54`	`&& path.extension().map_or(false, \|ext\| ext == "desktop")`
`54`	`55`	`{`