use super::{
MANUAL,
goal::Goal,
perform::Perform,
steps::{ALL_GROUPS, Group},
};
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum GuideCategory {
GettingStarted,
Tiers,
Solving,
Optimizing,
Viewing,
Output,
Library,
Preferences,
BuildThisDesign,
}
impl GuideCategory {
pub const ALL: [Self; 9] = [
Self::GettingStarted,
Self::Tiers,
Self::Solving,
Self::Optimizing,
Self::Viewing,
Self::Output,
Self::Library,
Self::Preferences,
Self::BuildThisDesign,
];
#[must_use]
pub const fn label(self) -> &'static str {
match self {
Self::GettingStarted => "Getting started",
Self::Tiers => "Tiers",
Self::Solving => "Solving",
Self::Optimizing => "Optimizing",
Self::Viewing => "Viewing",
Self::Output => "Output",
Self::Library => "Library",
Self::Preferences => "Preferences",
Self::BuildThisDesign => "Built from the library",
}
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum StartingState {
CurrentDesign,
RequiresOpenDesign,
NewEmpty,
Template(usize),
LibraryDesign(i64),
}
#[derive(Clone, Debug)]
pub struct GuideStep {
pub title: String,
pub intro: String,
pub actions: Vec<String>,
pub check: String,
pub why: String,
pub waiting: String,
pub highlight_target: String,
pub goal: Goal,
pub allow: Vec<Group>,
pub perform: Option<Perform>,
}
impl GuideStep {
#[must_use]
pub fn new(title: impl Into<String>, intro: impl Into<String>) -> Self {
Self {
title: title.into(),
intro: intro.into(),
actions: Vec::new(),
check: String::new(),
why: String::new(),
waiting: String::new(),
highlight_target: String::new(),
goal: Goal::Manual,
allow: ALL_GROUPS.to_vec(),
perform: None,
}
}
#[must_use]
pub fn actions<I, S>(mut self, actions: I) -> Self
where
I: IntoIterator<Item = S>,
S: Into<String>,
{
self.actions = actions.into_iter().map(Into::into).collect();
self
}
#[must_use]
pub fn check(mut self, check: impl Into<String>) -> Self {
self.check = check.into();
self
}
#[must_use]
pub fn why(mut self, why: impl Into<String>) -> Self {
self.why = why.into();
self
}
#[must_use]
pub fn goal(mut self, goal: Goal, waiting: impl Into<String>) -> Self {
self.goal = goal;
self.waiting = waiting.into();
self
}
#[must_use]
pub fn highlight(mut self, target: impl Into<String>) -> Self {
self.highlight_target = target.into();
self
}
#[must_use]
pub fn allow(mut self, allow: &[Group]) -> Self {
self.allow = allow.to_vec();
self
}
#[must_use]
pub fn perform(mut self, perform: Perform) -> Self {
self.perform = Some(perform);
self
}
#[must_use]
pub const fn is_manual(&self) -> bool {
self.goal.is_manual()
}
#[must_use]
pub const fn can_perform(&self) -> bool {
self.perform.is_some()
}
#[must_use]
pub fn completion_key(&self, index: usize) -> String {
if self.is_manual() {
MANUAL.to_owned()
} else {
format!("goal:{index}")
}
}
}
#[derive(Clone, Debug)]
pub struct Guide {
pub id: String,
pub title: String,
pub summary: String,
pub category: GuideCategory,
pub starting_state: StartingState,
pub steps: Vec<GuideStep>,
}
impl Guide {
#[must_use]
pub fn new(
id: impl Into<String>,
title: impl Into<String>,
summary: impl Into<String>,
category: GuideCategory,
) -> Self {
Self {
id: id.into(),
title: title.into(),
summary: summary.into(),
category,
starting_state: StartingState::CurrentDesign,
steps: Vec::new(),
}
}
#[must_use]
pub const fn starting(mut self, state: StartingState) -> Self {
self.starting_state = state;
self
}
#[must_use]
pub fn step(mut self, step: GuideStep) -> Self {
self.steps.push(step);
self
}
#[must_use]
pub fn problem(&self) -> Option<String> {
guide_problem(self)
}
}
pub const BUILD_ID_PREFIX: &str = "build:";
const MAX_BUILD_KEY_LEN: usize = 300;
#[must_use]
pub fn is_valid_guide_id(id: &str) -> bool {
if let Some(key) = id.strip_prefix(BUILD_ID_PREFIX) {
return !key.is_empty()
&& key.len() <= MAX_BUILD_KEY_LEN
&& key.chars().all(|c| c.is_ascii_graphic());
}
!id.is_empty()
&& !id.starts_with('-')
&& !id.ends_with('-')
&& !id.contains("--")
&& id
.chars()
.all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-')
}
fn guide_problem(guide: &Guide) -> Option<String> {
if !is_valid_guide_id(&guide.id) {
return Some(format!("{:?} is not a valid guide id", guide.id));
}
if guide.title.trim().is_empty() || guide.summary.trim().is_empty() {
return Some(format!("guide {:?} needs a title and a summary", guide.id));
}
if guide.steps.is_empty() {
return Some(format!("guide {:?} has no steps", guide.id));
}
for (index, step) in guide.steps.iter().enumerate() {
if let Some(problem) = step_problem(step) {
return Some(format!(
"guide {:?}, step {} ({:?}): {problem}",
guide.id,
index + 1,
step.title
));
}
if guide.steps[..index].iter().any(|s| s.title == step.title) {
return Some(format!(
"guide {:?} has two steps titled {:?}",
guide.id, step.title
));
}
}
None
}
fn step_problem(step: &GuideStep) -> Option<String> {
if step.title.trim().is_empty() || step.intro.trim().is_empty() {
return Some("needs a title and an intro".to_owned());
}
if step.actions.iter().any(|action| action.trim().is_empty()) {
return Some("has a blank action line".to_owned());
}
if !super::HIGHLIGHT_TARGETS.contains(&step.highlight_target.as_str()) {
return Some(format!(
"unknown highlight target {:?}",
step.highlight_target
));
}
if let Some(problem) = step.goal.problem() {
return Some(problem);
}
if let Some(perform) = &step.perform {
if step.is_manual() {
return Some("a reading step has nothing to perform".to_owned());
}
if let Some(problem) = perform.problem() {
return Some(format!("its perform is not fit to run: {problem}"));
}
}
if !step.is_manual() {
if step.actions.is_empty() {
return Some("an automatic step needs at least one action".to_owned());
}
if step.waiting.trim().is_empty() {
return Some("an automatic step needs its \"waiting for\" text".to_owned());
}
if step.check.trim().is_empty() {
return Some("an automatic step needs a \"look for\" line".to_owned());
}
}
None
}