Add slot documentation and create high-level project data structure

cli/src/check.rs

@@ -1,17 +1,17 @@
-use std::{error::Error, path::PathBuf, process::exit, time::Instant};
+use std::{error::Error, process::exit, time::Instant};
 
 use colored::Colorize;
-use spackle::core::{
-    config::Config,
-    template::{self, ValidateError},
+use spackle::{
+    core::template::{self, ValidateError},
+    Project,
 };
 
-pub fn run(project_dir: &PathBuf, config: &Config) {
+pub fn run(project: &Project) {
     println!("🔍 Validating project configuration...\n");
 
     let start_time = Instant::now();
 
-    match template::validate(&project_dir, &config.slots) {
+    match template::validate(&project.dir, &project.config.slots) {
         Ok(()) => {
             println!("  👌 {}\n", "Template files are valid".bright_green());
         }

cli/src/fill.rs

@@ -2,26 +2,21 @@ use std::{collections::HashMap, fs, path::PathBuf, process::exit, time::Instant}
 
 use colored::Colorize;
 use rocket::{futures::StreamExt, tokio};
-use spackle::core::{
-    config::Config,
-    copy,
-    hook::{self, HookError, HookResult, HookResultKind, HookStreamResult},
-    slot, template,
+use spackle::{
+    core::{
+        copy,
+        hook::{self, HookError, HookResult, HookResultKind, HookStreamResult},
+        slot, template,
+    },
+    Project,
 };
 use tokio::pin;
 
 use crate::{check, Cli};
 
-pub fn run(
-    slot: &Vec<String>,
-    hook: &Vec<String>,
-    project_dir: &PathBuf,
-    out: &PathBuf,
-    config: &Config,
-    cli: &Cli,
-) {
+pub fn run(slot: &Vec<String>, hook: &Vec<String>, project: &Project, out: &PathBuf, cli: &Cli) {
     // First, run spackle check
-    check::run(project_dir, config);
+    check::run(project);
 
     println!("");
 
@@ -42,7 +37,7 @@ pub fn run(
         .map(|(key, value)| (key.to_string(), value.to_string()))
         .collect::<HashMap<String, String>>();
 
-    match slot::validate_data(&slot_data, &config.slots) {
+    match slot::validate_data(&slot_data, &project.config.slots) {
         Ok(()) => {}
         Err(e) => {
             eprintln!(
@@ -89,7 +84,7 @@ pub fn run(
     let mut slot_data = slot_data.clone();
     slot_data.insert(
         "project_name".to_string(),
-        project_dir.file_name().unwrap().to_string_lossy().into(),
+        project.dir.file_name().unwrap().to_string_lossy().into(),
     );
 
     // CR(devin): when looking at the below code, this likely should be pushed
@@ -101,7 +96,7 @@ pub fn run(
 
     // TODO: refactor the data_entries and context boundaries after considering
     // the api surface area
-    match copy::copy(&project_dir, out, &config.ignore, &slot_data) {
+    match copy::copy(&project.dir, out, &project.config.ignore, &slot_data) {
         Ok(r) => {
             println!(
                 "{} {} {} {}",
@@ -147,7 +142,7 @@ pub fn run(
 
     let start_time = Instant::now();
 
-    match template::fill(&project_dir, &PathBuf::from(out), &slot_data) {
+    match template::fill(&project.dir, &PathBuf::from(out), &slot_data) {
         Ok(r) => {
             println!(
                 "{} {} {} {} {}\n",
@@ -215,8 +210,14 @@ pub fn run(
     };
 
     runtime.block_on(async {
-        let stream = match hook::run_hooks_stream(&config.hooks, out, &slot_data, &hook_data, None)
-        {
+        let stream = match hook::run_hooks_stream(
+            &project.config.hooks,
+            out,
+            &Vec::new(),
+            &slot_data,
+            &hook_data,
+            None,
+        ) {
             Ok(stream) => stream,
             Err(e) => {
                 fs::remove_dir_all(out).unwrap();

cli/src/main.rs

@@ -1,6 +1,6 @@
 use clap::{command, Parser, Subcommand};
 use colored::Colorize;
-use spackle::core::config::Config;
+use spackle::Project;
 use std::{path::PathBuf, process::exit};
 
 mod check;
@@ -73,8 +73,8 @@ fn main() {
     }
 
     // Load the config
-    let config = match spackle::load(&project_dir) {
-        Ok(config) => config,
+    let project = match spackle::load_project(&project_dir) {
+        Ok(p) => p,
         Err(e) => {
             eprintln!(
                 "❌ {}\n{}",
@@ -85,26 +85,24 @@ fn main() {
         }
     };
 
-    print_project_info(&project_dir, &config);
+    print_project_info(&project);
 
     match &cli.command {
-        Commands::Check => check::run(&project_dir, &config),
-        Commands::Info {} => info::run(&config),
-        Commands::Fill { slot, hook } => {
-            fill::run(slot, hook, &project_dir, &cli.out, &config, &cli)
-        }
+        Commands::Check => check::run(&project),
+        Commands::Info {} => info::run(&project.config),
+        Commands::Fill { slot, hook } => fill::run(slot, hook, &project, &cli.out, &cli),
     }
 }
 
-fn print_project_info(project_dir: &PathBuf, config: &Config) {
+fn print_project_info(project: &Project) {
     println!(
         "📂 {} {}\n{}\n{}\n",
         "Using project",
-        project_dir.to_string_lossy().bold(),
+        project.dir.to_string_lossy().bold(),
         format!(
             "  🕳️  {} {}",
-            config.slots.len(),
-            if config.slots.len() == 1 {
+            project.config.slots.len(),
+            if project.config.slots.len() == 1 {
                 "slot"
             } else {
                 "slots"
@@ -113,8 +111,8 @@ fn print_project_info(project_dir: &PathBuf, config: &Config) {
         .dimmed(),
         format!(
             "  🪝  {} {}",
-            config.hooks.len(),
-            if config.hooks.len() == 1 {
+            project.config.hooks.len(),
+            if project.config.hooks.len() == 1 {
                 "hook"
             } else {
                 "hooks"

docs/configuration.md

@@ -82,6 +82,7 @@ Hooks are defined by one or more `[[hooks]]` table entries in the `spackle.toml`
 name = "create file"
 command = ["touch", "new_file"]
 optional = { default = true }
+needs = ["foo"]
 if = "{{foo}} != 'bar'"
 name = "Create a new file"
 description = "Create a new file called new_file"
@@ -117,14 +118,28 @@ When defined, the user can toggle the hook. `default` describes the default stat
 optional = { default = true }
 ```
 
+### needs `string[]`
+
+The items on which the hook depends. The hook will only be executed if all the dependencies are satisfied. A dependency is satisfied if the dependency is enabled and all of its own dependencies are satisfied.
+
+A slot is considered enabled if it has a non-default value (default values include `""`, `0`, and `false` for example).
+
+> Note: Because `if` is evaluated only on hook run time, it is not taken into account when determining satisfaction of `needs`.
+
+```toml
+needs = ["some_hook", "other_slot"]
+```
+
 ### if `string` <span style="color: darkseagreen;">{s}</span>
 
-The condition to execute the hook. Accepts values from slots.
+The condition on which to execute the hook. Accepts values from slots.
 
 ```toml
 if = "{{ foo }} != 'bar'"
 ```
 
+> Note: The `if` condition is evaluated directly before the hook is executed.
+
 #### Dependencies on other hooks
 
 If you want to run a hook only if another hook has already been run, you can use the `hook_ran_{hook_key}` variable.