1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

// Copyright 2021 System76 <info@system76.com>
// SPDX-License-Identifier: MPL-2.0

//! # onagre-launcher-toolkit
//!
//! A toolkit to write pop-launcher client and plugin.
//!
//! ## Crates
//!  - **[`launcher`]:** re-export the pop-launcher crate, containing all the IPC message struct and
//!    some utility functions to locate plugins.
//!  - **[`service`]:** re-export the pop-launcher-service crate, containing deserializable plugin config struct.
//!    This is useful if your client needs to read user defined plugins configs.
//!  - **[`plugins`]:** re-export pop-launcher-plugins which defines all the default pop-launcher plugins.
//!    Useful if your client needs to read default plugin configs
//!
//! ## Writing a plugin
//!
//! Add the following to your Cargo.toml :
//!
//! ```toml
//! [dependencies]
//! tokio = { version = "1.18.2", features = ["rt"] }
//! onagre-launcher-toolkit = { git = "https://github.com/pop-os/launcher" }
//! ```
//!
//! And implement the [`PluginExt`] trait:
//!
//! [`PluginExt`]: plugin_trait::PluginExt
//!
//! ```rust
//! use pop_launcher_toolkit::launcher::{Indice, PluginResponse, PluginSearchResult};
//! use pop_launcher_toolkit::plugin_trait::{async_trait, PluginExt};
//! use pop_launcher_toolkit::plugins;
//!
//! // The plugin struct, here it holds the search result
//! pub struct MyPlugin {
//!   data: Vec<String>
//! }
//!
//! #[async_trait]
//! impl PluginExt for MyPlugin {
//!
//!   // Define the name of you plugin, this will be used
//!   // to generate a logfile in $XDG_STATE_HOME at runtime.
//!   fn name(&self) -> &str {
//!       "my_awesome_plugin"
//!   }
//!
//!   // Respond to `pop-launcher` 'search' query
//!   async fn search(&mut self, query: &str) {
//!      // `pop-launcher` dispatches request to plugins according to the regex defined in
//!      // the `plugin.ron` config file, here we get rid of the prefix
//!      // before processing the request.
//!      let query = query.strip_prefix("plug ").unwrap();
//!
//!      // Iterate through our internal search results with their indices.
//!      let search_results = self.data.iter()
//!         .enumerate()
//!         .filter(|(idx, data)| data.contains(query));
//!
//!      // Send our search results to `pop-launcher` using their indices as id.
//!      for (idx, search_result) in search_results {
//!         self.respond_with(PluginResponse::Append(PluginSearchResult {
//!             id: idx as u32,
//!             name: search_result.clone(),
//!             description: "".to_string(),
//!             keywords: None,
//!             icon: None,
//!             exec: None,
//!             window: None,
//!         })).await;
//!      }
//!
//!     // tell `pop-launcher` we are done with this request
//!     self.respond_with(PluginResponse::Finished).await;
//!   }
//!
//!   // Respond to `pop-launcher` 'activate' query
//!   async fn activate(&mut self, id: Indice) {
//!       // Get the selected entry
//!       let entry = self.data.get(id as usize).unwrap();
//!       // Here we use xdg_open to run the entry but this could be anything
//!       plugins::xdg_open(entry);
//!       // Tell pop launcher we are done
//!       self.respond_with(PluginResponse::Finished).await;
//!   }
//!
//!   // Respond to `pop-launcher` 'close' request.
//!   async fn quit(&mut self, id: Indice) {
//!       self.respond_with(PluginResponse::Close).await;
//!   }
//! }
//!
//! #[tokio::main(flavor = "current_thread")]
//! pub async fn main() {
//!
//!     // Here we declare our plugin with dummy values, and never mutate them.
//!     // In a real plugin we would probably use some kind of mutable shared reference to
//!     // update our search results.
//!     let mut plugin = MyPlugin {
//!         data: vec!["https://crates.io".to_string(), "https://en.wikipedia.org".to_string()],
//!     };
//!
//!     /// If you need to debug your plugin or display error messages use `tcracing` macros.
//!     tracing::info!("Starting my_awsome_plugin");
//!
//!     // Call the plugin entry point function to start
//!     // talking with pop_launcherc
//!     plugin.run().await;
//! }
//! ```

pub use onagre_launcher as launcher;
pub use onagre_launcher_plugins as plugins;
pub use onagre_launcher_service::{
    self as service, load::from_path as load_plugin_from_path,
    load::from_paths as load_plugins_from_paths,
};

/// A helper trait to quickly create `pop-launcher` plugins
pub mod plugin_trait;