Merge pull request #33 from ethagnawl/publicize-struct-fields

Publicize struct fields

Author: ethagnawl

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "rmuxinator"
-version = "0.1.0"
+version = "1.0.0"
 authors = ["Peter Doherty <[email protected]>"]
 edition = "2018"
 description = "tmux project configuration utility"

Cargo.toml

@@ -122,6 +122,53 @@ session using a path to a project config file:
 Start a tmux session using a path to a project config file:
 `rmuxinator start Example.toml`
 
+### Use as a library
+rmuxinator can also be used as a library by other programs.
+
+There are two ways to achieve this:
+
+#### Config::new_from_config_path
+This option accepts a path to an rmuxinator config file and is how the rmuxinator binary works. This is how this project's binary entrypoint works.
+
+Example:
+
+```
+let config = rmuxinator::Config::new_from_config_path(&String::from("/home/pi/foo.toml")).map_err(|error| format!("Problem parsing config file: {}", error))?;
+rmuxinator::run_start(config).map_err(|error| format!("Application error: {}", error));
+```
+
+#### Config constructor
+This option allows the caller to create an rmuxinator `Config` struct and then pass it to the `run_start` function.
+
+The [pi-wall-utils](https://github.com/ethagnawl/pi-wall-utils) project (also maintained by [ethagnawl](https://github.com/ethagnawl)) does this and can be used as a reference.
+
+
+Example:
+
+```
+let rmuxinator_config = rmuxinator::Config {
+    hooks: vec![],
+    layout: None,
+    name: String::from("rmuxinator-library-example"),
+    windows: vec![
+        rmuxinator::Window {
+            layout: None,
+            name: None,
+            panes: vec![rmuxinator::Pane {
+                commands: vec![
+                    String::from("echo 'hello!'"),
+                ],
+                name: None,
+                start_directory: None,
+            }],
+            start_directory: None,
+    }
+    ];
+
+};
+rmuxinator::run_start(rmuxinator_config).map_err(|error| format!("Rmuxinator error: {}", error))
+```
+
 ## Known Issues and Workarounds
 ### Indexes
 rmuxinator currently assumes that both `base-index` and `pane-base-index` are
@@ -169,13 +216,13 @@ remove themselves in order to prevent duplicate events.
 - Handle shell failures -- `tmux kill-window` was failing silently
 - Can commands can all be moved into structs and computed up front? This might
 require writing a custom Serde deserializer for the Config type.
+- Start detached tmux session
 - Select window on attach (can this be handled by a pre-existing hook?)
 - Attach if session exists instead of creating sesssion
 - Search for project config file on disk (XDG_CONFIG?) instead of parsing
 config (I'm not convinced this is necessary)
 - Other CLI commands? (stop session, create/edit/delete project)
 - Use named args in calls to format! where possible
-- Cut v0.0.1 release and publish binaries
 
 ## Platforms
 Here are the platforms rmuxinator is known to work on:

README.md

@@ -7,7 +7,7 @@ use std::process::Command;
 use std::str::FromStr;
 
 use clap::{App, AppSettings, Arg, SubCommand};
-use serde::Deserialize;
+use serde::{Deserialize, Serialize};
 
 extern crate toml;
 
@@ -417,12 +417,15 @@ impl FromStr for CliCommand {
 #[derive(Debug, PartialEq)]
 pub struct CliArgs {
     pub command: CliCommand,
+    // TODO: `project_name` is currently overloaded and also used as the config
+    // path. We should either make this more explicit or introduce separate
+    // args.
     pub project_name: String,
 }
 
-#[derive(Clone, Copy, Debug, Deserialize)]
+#[derive(Clone, Copy, Debug, Deserialize, Serialize)]
 #[serde(rename_all = "kebab-case")]
-enum Layout {
+pub enum Layout {
     EvenHorizontal,
     EvenVertical,
     MainHorizontal,
@@ -440,23 +443,23 @@ impl fmt::Display for Layout {
 
 type StartDirectory = Option<String>;
 
-#[derive(Debug, Default, Deserialize)]
-struct Pane {
-    commands: Vec<String>,
-    name: Option<String>,
-    start_directory: StartDirectory,
+#[derive(Debug, Default, Deserialize, Serialize)]
+pub struct Pane {
+    pub commands: Vec<String>,
+    pub name: Option<String>,
+    pub start_directory: StartDirectory,
 }
 
-#[derive(Debug, Default, Deserialize)]
-struct Window {
-    layout: Option<Layout>,
-    name: Option<String>,
+#[derive(Debug, Default, Deserialize, Serialize)]
+pub struct Window {
+    pub layout: Option<Layout>,
+    pub name: Option<String>,
     #[serde(default)]
-    panes: Vec<Pane>,
-    start_directory: StartDirectory,
+    pub panes: Vec<Pane>,
+    pub start_directory: StartDirectory,
 }
 
-#[derive(Debug, Deserialize)]
+#[derive(Debug, Deserialize, Serialize)]
 #[serde(rename_all = "kebab-case")]
 enum HookName {
     // TODO: Does this make sense? If not, document exclusion.
@@ -530,29 +533,29 @@ impl fmt::Display for HookName {
     }
 }
 
-#[derive(Debug, Deserialize)]
-struct Hook {
+#[derive(Debug, Deserialize, Serialize)]
+pub struct Hook {
     command: String,
     name: HookName,
 }
 
-#[derive(Debug, Deserialize)]
+#[derive(Debug, Deserialize, Serialize)]
 pub struct Config {
-    pane_name_user_option: Option<String>,
+    pub pane_name_user_option: Option<String>,
     #[serde(default)]
-    hooks: Vec<Hook>,
-    layout: Option<Layout>,
-    name: String,
-    start_directory: StartDirectory,
+    pub hooks: Vec<Hook>,
+    pub layout: Option<Layout>,
+    pub name: String,
+    pub start_directory: StartDirectory,
     #[serde(default)]
-    windows: Vec<Window>,
+    pub windows: Vec<Window>,
 }
 
 impl Config {
-    pub fn new(cli_args: &CliArgs) -> Result<Config, String> {
+    pub fn new_from_file_path(config_path: &String) -> Result<Config, String> {
         // Need to return String in failure case because toml::from_str may
         // return a toml::de::Error.
-        let mut config_file = match File::open(&cli_args.project_name) {
+        let mut config_file = match File::open(&config_path) {
             Ok(file) => file,
             Err(_) => return Err(String::from("Unable to open config file.")),
         };

src/lib.rs

@@ -14,7 +14,7 @@ fn main() -> Result<(), String> {
 
     let cli_args = parse_args(env::args_os());
 
-    let config = Config::new(&cli_args)
+    let config = Config::new_from_file_path(&cli_args.project_name)
         .map_err(|error| format!("Problem parsing config file: {}", error))?;
 
     match cli_args.command {