Add support for target-specific custom enums in disassembler

This adds robust support for custom enums, allowing users to replace raw numeric values (immediate operands, data bytes, and data words) with semantic names across all supported assemblers (64tass, KickAssembler, ca65, and ACME) in a target-specific way.

- 64tass formats enums using named dictionaries (e.g., Colors.BLACK)
- KickAssembler formats enums inside .enum blocks (e.g., Colors.BLACK)
- ca65 formats enums inside .enum blocks and double-colon scopes (e.g., Colors::BLACK)
- ACME formats enums using flat underscore namespaces (e.g., Colors_BLACK)

Precedence models shadow local > global > built-in, and enums are cloned and embedded permanently on use to guarantee portable, self-contained saves.

Fixes #22

TAG=agy
BUG=#22
CONV=168d6e0d-4484-483b-b051-42b81fefbdaf

Author: ricardoquesada

crates/regenerator2000-core/assets/enums/enum-vic_colors.toml

@@ -0,0 +1,19 @@
+name = "VIC_Colors"
+
+[variants]
+"0" = "BLACK"
+"1" = "WHITE"
+"2" = "RED"
+"3" = "CYAN"
+"4" = "PURPLE"
+"5" = "GREEN"
+"6" = "BLUE"
+"7" = "YELLOW"
+"8" = "ORANGE"
+"9" = "BROWN"
+"10" = "LIGHT_RED"
+"11" = "DARK_GREY"
+"12" = "GREY"
+"13" = "LIGHT_GREEN"
+"14" = "LIGHT_BLUE"
+"15" = "LIGHT_GREY"

crates/regenerator2000-core/src/assets.rs

@@ -1,4 +1,4 @@
-use crate::state::{Label, LabelKind, LabelType};
+use crate::state::{EnumDefinition, Label, LabelKind, LabelType, RawEnumDefinition};
 use anyhow::{Context, Result};
 use directories::ProjectDirs;
 use include_dir::{Dir, include_dir};
@@ -7,6 +7,7 @@ use std::collections::{BTreeMap, HashMap};
 use std::path::{Path, PathBuf};
 
 static SYSTEMS_DIR: Dir = include_dir!("$CARGO_MANIFEST_DIR/assets/systems");
+static ENUMS_DIR: Dir = include_dir!("$CARGO_MANIFEST_DIR/assets/enums");
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct LabelOption {
@@ -362,6 +363,104 @@ pub fn load_excludes(system: &str) -> Vec<u16> {
     excludes
 }
 
+// =============================================================================
+// Enum Assets Loading & Dumping
+// =============================================================================
+
+/// Returns the path to the user's config directory for custom global enums.
+#[must_use]
+pub fn user_config_enums_dir() -> Option<PathBuf> {
+    ProjectDirs::from("", "", "regenerator2000").map(|d| d.config_dir().to_path_buf())
+}
+
+/// Load all built-in enums from the embedded `assets/enums/` directory.
+#[must_use]
+pub fn load_builtin_enums() -> BTreeMap<String, EnumDefinition> {
+    let mut enums = BTreeMap::new();
+    for file in ENUMS_DIR.files() {
+        let Some(filename) = file.path().file_name().and_then(|s| s.to_str()) else {
+            continue;
+        };
+        if !filename.starts_with("enum-") || !filename.ends_with(".toml") {
+            continue;
+        }
+        let Some(content) = file.contents_utf8() else {
+            continue;
+        };
+        match toml::from_str::<RawEnumDefinition>(content) {
+            Ok(raw) => {
+                let def = EnumDefinition::from(raw);
+                enums.insert(def.name.clone(), def);
+            }
+            Err(e) => {
+                log::warn!("Failed to parse built-in enum {filename}: {e}");
+            }
+        }
+    }
+    enums
+}
+
+/// Load all custom global enums from the user's preferences directory.
+#[must_use]
+pub fn load_global_enums(dir: &Path) -> BTreeMap<String, EnumDefinition> {
+    let mut enums = BTreeMap::new();
+    let Ok(entries) = std::fs::read_dir(dir) else {
+        return enums;
+    };
+
+    for entry in entries.filter_map(Result::ok) {
+        let path = entry.path();
+        let Some(filename) = path.file_name().and_then(|s| s.to_str()) else {
+            continue;
+        };
+        if !filename.starts_with("enum-") || !filename.ends_with(".toml") {
+            continue;
+        }
+        match std::fs::read_to_string(&path) {
+            Ok(content) => match toml::from_str::<RawEnumDefinition>(&content) {
+                Ok(raw) => {
+                    let def = EnumDefinition::from(raw);
+                    log::info!("Loaded global enum: {} from {path:?}", def.name);
+                    enums.insert(def.name.clone(), def);
+                }
+                Err(e) => {
+                    log::warn!("Failed to parse enum file {path:?}: {e}");
+                }
+            },
+            Err(e) => {
+                log::warn!("Failed to read enum file {path:?}: {e}");
+            }
+        }
+    }
+
+    enums
+}
+
+/// Dump all embedded `enum-*.toml` files into `dest_dir`.
+///
+/// # Errors
+/// Returns an error if the directory cannot be created or if writing any file fails.
+pub fn dump_enum_files(dest_dir: &Path) -> Result<()> {
+    std::fs::create_dir_all(dest_dir)
+        .with_context(|| format!("Failed to create directory {dest_dir:?}"))?;
+
+    for file in ENUMS_DIR.files() {
+        let Some(filename) = file.path().file_name() else {
+            continue;
+        };
+        let filename_str = filename.to_string_lossy();
+        if !filename_str.starts_with("enum-") || !filename_str.ends_with(".toml") {
+            continue;
+        }
+        let dest_path = dest_dir.join(filename);
+        std::fs::write(&dest_path, file.contents())
+            .with_context(|| format!("Failed to write {dest_path:?}"))?;
+        println!("Wrote {dest_path:?}");
+    }
+
+    Ok(())
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

crates/regenerator2000-core/src/commands.rs

@@ -1,4 +1,4 @@
-use crate::state::{Addr, AppState, BlockType, ImmediateFormat, Label};
+use crate::state::{Addr, AppState, BlockType, EnumDefinition, ImmediateFormat, Label};
 use std::collections::BTreeMap;
 
 #[derive(Debug, Clone)]
@@ -75,6 +75,16 @@ pub enum Command {
         old_labels: BTreeMap<Addr, Vec<crate::state::Label>>,
         old_cross_refs: BTreeMap<Addr, Vec<Addr>>,
     },
+    SetEnumUsage {
+        address: Addr,
+        new_enum: Option<String>,
+        old_enum: Option<String>,
+    },
+    SetEnumDefinition {
+        name: String,
+        new_definition: Option<EnumDefinition>,
+        old_definition: Option<EnumDefinition>,
+    },
     Batch(Vec<Command>),
 }
 
@@ -225,6 +235,36 @@ impl Command {
             } => {
                 state.scopes.remove(address);
             }
+            Command::SetEnumUsage {
+                address,
+                new_enum,
+                old_enum: _,
+            } => {
+                if let Some(enum_name) = new_enum {
+                    state.enum_usages.insert(*address, enum_name.clone());
+                    // Embed pre-defined global/built-in enum into local project enums if not present
+                    if !state.enums.contains_key(enum_name) {
+                        if let Some(def) = state.user_global_enums.get(enum_name) {
+                            state.enums.insert(enum_name.clone(), def.clone());
+                        } else if let Some(def) = state.builtin_enums.get(enum_name) {
+                            state.enums.insert(enum_name.clone(), def.clone());
+                        }
+                    }
+                } else {
+                    state.enum_usages.remove(address);
+                }
+            }
+            Command::SetEnumDefinition {
+                name,
+                new_definition,
+                old_definition: _,
+            } => {
+                if let Some(def) = new_definition {
+                    state.enums.insert(name.clone(), def.clone());
+                } else {
+                    state.enums.remove(name);
+                }
+            }
             Command::Batch(commands) => {
                 for command in commands {
                     command.apply(state);
@@ -381,6 +421,28 @@ impl Command {
             Command::RemoveScope { address, old_end } => {
                 state.scopes.insert(*address, *old_end);
             }
+            Command::SetEnumUsage {
+                address,
+                new_enum: _,
+                old_enum,
+            } => {
+                if let Some(enum_name) = old_enum {
+                    state.enum_usages.insert(*address, enum_name.clone());
+                } else {
+                    state.enum_usages.remove(address);
+                }
+            }
+            Command::SetEnumDefinition {
+                name,
+                new_definition: _,
+                old_definition,
+            } => {
+                if let Some(def) = old_definition {
+                    state.enums.insert(name.clone(), def.clone());
+                } else {
+                    state.enums.remove(name);
+                }
+            }
             Command::Batch(commands) => {
                 for command in commands.iter().rev() {
                     command.undo(state);

crates/regenerator2000-core/src/core.rs

@@ -1200,6 +1200,9 @@ impl Core {
             } => {
                 self.handle_apply_comment(address, text, kind, &mut events);
             }
+            AppAction::ApplyEnumUsage { address, enum_name } => {
+                self.handle_apply_enum_usage(address, enum_name.as_deref(), &mut events);
+            }
             AppAction::CyclePane => {
                 use crate::view_state::ActivePane;
                 self.view.active_pane = match self.view.active_pane {
@@ -2286,6 +2289,36 @@ impl Core {
         events.push(CoreEvent::DialogDismissalRequested);
     }
 
+    fn handle_apply_enum_usage(
+        &mut self,
+        address: Addr,
+        enum_name: Option<&str>,
+        events: &mut Vec<CoreEvent>,
+    ) {
+        let old_enum = self.state.enum_usages.get(&address).cloned();
+        let new_enum = enum_name.map(String::from);
+
+        let command = crate::commands::Command::SetEnumUsage {
+            address,
+            new_enum: new_enum.clone(),
+            old_enum,
+        };
+
+        command.apply(&mut self.state);
+        self.state.push_command(command);
+
+        events.push(CoreEvent::StatusMessage(if new_enum.is_none() {
+            "Enum removed".to_string()
+        } else {
+            format!("Enum '{}' applied", new_enum.unwrap_or_default())
+        }));
+
+        self.state.disassemble();
+        events.push(CoreEvent::StateChanged);
+        events.push(CoreEvent::ViewChanged);
+        events.push(CoreEvent::DialogDismissalRequested);
+    }
+
     fn handle_apply_comment(
         &mut self,
         address: Addr,

crates/regenerator2000-core/src/disassembler.rs

@@ -320,6 +320,8 @@ impl Disassembler {
         splitters: &BTreeSet<Addr>,
         scopes: &BTreeMap<Addr, Addr>,
     ) -> Vec<DisassemblyLine> {
+        let empty_enums = BTreeMap::new();
+        let empty_usages = BTreeMap::new();
         let ctx = DisassemblyContext {
             data,
             block_types,
@@ -334,6 +336,10 @@ impl Disassembler {
             collapsed_blocks,
             splitters,
             scopes,
+            enums: &empty_enums,
+            enum_usages: &empty_usages,
+            user_global_enums: &empty_enums,
+            builtin_enums: &empty_enums,
         };
         self.disassemble_ctx(&ctx)
     }
@@ -873,6 +879,10 @@ impl Disassembler {
                         current_scope_name: current_scope_name.as_deref(),
                         scope_separator: formatter.scope_resolution_separator(),
                         local_prefix: formatter.local_label_prefix(),
+                        enums: ctx.enums,
+                        enum_usages: ctx.enum_usages,
+                        user_global_enums: ctx.user_global_enums,
+                        builtin_enums: ctx.builtin_enums,
                     };
                     let (mnemonic, operand_str) = formatter.format_instruction(&ctx);
 
@@ -1087,7 +1097,14 @@ impl Disassembler {
 
             let b = data[current_pc];
             bytes.push(b);
-            operands.push(formatter.format_byte(b));
+            let formatted_val = if let Some((enum_name, variant_name)) =
+                ctx.resolve_enum_value(current_address, b as u16)
+            {
+                formatter.format_enum_reference(&enum_name, &variant_name)
+            } else {
+                formatter.format_byte(b)
+            };
+            operands.push(formatted_val);
             count += 1;
         }
 
@@ -1179,7 +1196,14 @@ impl Disassembler {
 
             bytes.push(low);
             bytes.push(high);
-            operands.push(formatter.format_address(Addr(val)));
+            let formatted_val = if let Some((enum_name, variant_name)) =
+                ctx.resolve_enum_value(current_address, val)
+            {
+                formatter.format_enum_reference(&enum_name, &variant_name)
+            } else {
+                formatter.format_address(Addr(val))
+            };
+            operands.push(formatted_val);
             count += 1;
         }
 

crates/regenerator2000-core/src/disassembler/context.rs

@@ -1,4 +1,4 @@
-use crate::state::{Addr, BlockType, DocumentSettings, Label};
+use crate::state::{Addr, BlockType, DocumentSettings, EnumDefinition, Label};
 use std::collections::{BTreeMap, BTreeSet};
 
 use super::formatter::Formatter;
@@ -18,6 +18,12 @@ pub struct DisassemblyContext<'a> {
     pub collapsed_blocks: &'a [(usize, usize)],
     pub splitters: &'a BTreeSet<Addr>,
     pub scopes: &'a BTreeMap<Addr, Addr>,
+
+    // Enums references
+    pub enums: &'a BTreeMap<String, EnumDefinition>,
+    pub enum_usages: &'a BTreeMap<Addr, String>,
+    pub user_global_enums: &'a BTreeMap<String, EnumDefinition>,
+    pub builtin_enums: &'a BTreeMap<String, EnumDefinition>,
 }
 
 /// Per-iteration values computed in the disassembly loop and passed to each handler.
@@ -50,6 +56,10 @@ impl<'a> DisassemblyContext<'a> {
         collapsed_blocks: &'a [(usize, usize)],
         splitters: &'a BTreeSet<Addr>,
         scopes: &'a BTreeMap<Addr, Addr>,
+        enums: &'a BTreeMap<String, EnumDefinition>,
+        enum_usages: &'a BTreeMap<Addr, String>,
+        user_global_enums: &'a BTreeMap<String, EnumDefinition>,
+        builtin_enums: &'a BTreeMap<String, EnumDefinition>,
     ) -> Self {
         Self {
             data,
@@ -65,9 +75,25 @@ impl<'a> DisassemblyContext<'a> {
             collapsed_blocks,
             splitters,
             scopes,
+            enums,
+            enum_usages,
+            user_global_enums,
+            builtin_enums,
         }
     }
 
+    #[must_use]
+    pub fn resolve_enum_value(&self, address: Addr, value: u16) -> Option<(String, String)> {
+        let enum_name = self.enum_usages.get(&address)?;
+        let enum_def = self
+            .enums
+            .get(enum_name)
+            .or_else(|| self.user_global_enums.get(enum_name))
+            .or_else(|| self.builtin_enums.get(enum_name))?;
+        let variant = enum_def.variants.get(&value)?;
+        Some((enum_name.clone(), variant.clone()))
+    }
+
     #[must_use]
     pub fn is_virtual_splitter(&self, addr: Addr) -> bool {
         if self.splitters.contains(&addr) {