# UXN-TAL Assembler
A fast and comprehensive Rust library for assembling TAL (Tal Assembly Language) files into UXN ROM files.
This library provides functionality to parse TAL source code and generate bytecode compatible with the UXN virtual machine, with full symbol generation support for debugging.
## Features
### ✅ Complete UXN Support
- **Errors report with line numbers!**
- **All UXN Opcodes**: Full support for all 256 UXN instructions
- **Mode Flags**: Short mode (`2`), return mode (`r`), and keep mode (`k`)
- **Verified Compatibility**: Embedded official opcode table from UXN specification [uxntal_reference.html](https://wiki.xxiivv.com/site/uxntal_reference.html)
- **ROM Generation**: Compatible with `uxncli`, `uxnemu`, and other UXN emulators
### ✅ TAL Syntax Support
- **Literals**: Hex (`#12`, `#1234`), character (`'A'`), decimal, and binary
- **Labels**: Main labels (`@main`) and sublabels (`&loop`)
- **References**: Absolute (`;main`), relative (`,loop`), and sublabel references
- **Padding**: Address padding (`|0100`) and byte skipping (`$10`)
- **Raw Strings**: String literals with automatic null termination
- **Comments**: Parenthetical comments `( like this )`
### ✅ Symbol File Generation
- **Text Format**: Human-readable address-symbol pairs for debugging
- **Binary Format**: Compact binary format for tool integration
- **Debug Support**: Full symbol table extraction for development tools
### ✅ Ergonomic API
- **Single File Assembly**: Simple one-function assembly with symbol generation
- **Batch Processing**: Process entire directories of TAL files
- **Flexible Options**: With or without symbol file generation
- **Comprehensive Error Handling**: Detailed error messages with line numbers
## Quick Start
Add this to your `Cargo.toml`:
```toml
[dependencies]
uxn-tal = "0.1.0"
```
### Basic Usage
```rust
use uxn_tal::Assembler;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let tal_source = r#"
|0100 @main
#48 #65 #6c #6c #6f ( "Hello" )
#20 #57 #6f #72 #6c #64 #21 #0a ( " World!\n" )
BRK
"#;
let mut assembler = Assembler::new();
let rom = assembler.assemble(tal_source)?;
// Save ROM file
std::fs::write("hello.rom", rom)?;
// Generate symbol file
let symbols = assembler.generate_symbol_file();
std::fs::write("hello.sym", symbols)?;
Ok(())
}
```
### File-Based Assembly
```rust
use uxn_tal::assemble_file_with_symbols;
fn main() -> Result<(), Box<dyn std::error::Error>> {
// Assembles hello.tal -> hello.rom + hello.sym
let (rom_path, sym_path, size) = assemble_file_with_symbols("hello.tal")?;
println!("Generated {} bytes: {} + {}",
size,
rom_path.display(),
sym_path.display()
);
Ok(())
}
```
### Batch Processing
```rust
use uxn_tal::assemble_directory;
fn main() -> Result<(), Box<dyn std::error::Error>> {
// Process all .tal files in a directory
let results = assemble_directory("examples/", true)?; // true = generate symbols
for (tal_path, rom_path, sym_path, size) in results {
println!("✅ {} -> {} ({} bytes)",
tal_path.file_name().unwrap().to_string_lossy(),
rom_path.file_name().unwrap().to_string_lossy(),
size
);
if let Some(sym_path) = sym_path {
println!(" + {}", sym_path.file_name().unwrap().to_string_lossy());
}
}
Ok(())
}
```
## TAL Syntax Reference
### Literals
```tal
#12 ( hex byte literal )
#1234 ( hex short literal )
'A ( character literal )
42 ( decimal literal )
#b101010 ( binary literal )
```
### Labels and References
```tal
@main ( define main label )
&loop ( define sublabel under current main label )
;main ( absolute reference to main label )
,loop ( relative reference to sublabel )
/target ( relative reference to any label )
```
### Instructions with Mode Flags
```tal
ADD ( basic instruction )
ADD2 ( short mode - operates on 16-bit values )
ADDr ( return mode - operates on return stack )
ADDk ( keep mode - keeps operands on stack )
ADD2rk ( combined modes )
```
### Padding and Skipping
```tal
|0100 ( pad to absolute address 0x0100 )
$10 ( skip 16 bytes, filling with zeros )
```
### Raw Strings
```tal
"Hello World! 00 ( raw string with explicit null terminator )
```
## Symbol File Format
### Text Format (.sym)
```
0100 main
010A main/loop
0115 data
0125 end
```
### Binary Format
Compact binary format with:
- Address as little-endian `u16`
- Symbol name as null-terminated string
- Repeating for each symbol
## API Reference
### Core Types
#### `Assembler`
Main assembler instance for processing TAL source code.
```rust
impl Assembler {
pub fn new() -> Self
pub fn assemble(&mut self, source: &str) -> Result<Vec<u8>, AssemblerError>
pub fn generate_symbol_file(&self) -> String
pub fn generate_symbol_file_binary(&self) -> Vec<u8>
pub fn symbols(&self) -> &HashMap<String, Symbol>
}
```
#### `AssemblerError`
Comprehensive error types with detailed messages:
- `SyntaxError { line: usize, message: String }`
- `UnknownOpcode { opcode: String }`
- `UndefinedLabel { label: String }`
- `DuplicateLabel { label: String }`
- `InvalidNumber { value: String }`
- `Io(std::io::Error)`
### Convenience Functions
```rust
// Assemble single file
pub fn assemble_file<P: AsRef<Path>>(input_path: P) -> Result<Vec<u8>, AssemblerError>
// Assemble file to ROM
pub fn assemble_file_to_rom<P: AsRef<Path>, Q: AsRef<Path>>(
input_path: P,
output_path: Q
) -> Result<usize, AssemblerError>
// Auto-generate ROM with same basename
pub fn assemble_file_auto<P: AsRef<Path>>(
input_path: P
) -> Result<(PathBuf, usize), AssemblerError>
// Assemble with symbol generation
pub fn assemble_file_with_symbols<P: AsRef<Path>>(
input_path: P
) -> Result<(PathBuf, PathBuf, usize), AssemblerError>
// Batch process directory
pub fn assemble_directory<P: AsRef<Path>>(
dir_path: P,
generate_symbols: bool
) -> Result<Vec<(PathBuf, PathBuf, Option<PathBuf>, usize)>, AssemblerError>
```
## Examples
The `examples/` directory contains comprehensive demonstrations:
- `comprehensive_demo.rs` - Complete feature showcase
- `batch_assembler.rs` - Batch processing with CLI options
- `test_symbols.rs` - Symbol generation testing
- `hello_world.rs` - Basic usage example
Run examples with:
```bash
cargo run --example comprehensive_demo
cargo run --example batch_assembler -- --symbols
```
## Testing
The library includes comprehensive tests covering all functionality:
```bash
# Run all tests
cargo test
# Run specific test
cargo test test_skip_directive
# Run with verbose output
cargo test -- --nocapture
```
## Compatibility
### Verified Compatible
- ✅ `uxncli` - Command-line UXN emulator
- ✅ `uxnemu` - UXN emulator with GUI
- ✅ Official UXN opcode specification
### Generated ROMs
- Compatible with all standard UXN emulators
- Proper memory layout and addressing
- Correctly trimmed ROM files (excludes zero page padding)
## Current Limitations
**Important**: This assembler currently supports core TAL syntax but **cannot compile most existing TAL programs** that use advanced features. The following are not yet implemented:
- **Macros** (`%MACRO { ... }`) - Preprocessor-style definitions (used in most demos)
- **Device Access** (`.Screen/width`) - Direct device port access syntax (ubiquitous in UXN programs)
- **Inline Assembly** (`[ LIT2 01 -Screen/auto ]`) - Raw bytecode blocks (common optimization)
- **Include Files** - File inclusion directives
**Reality Check**: The demo TAL files in `uxn/projects/examples/demos` all failed to assemble because they extensively use these features. This assembler is currently best suited for:
- Learning UXN assembly fundamentals
- Simple educational programs
- Basic ROM generation experiments
- Projects that stick to core instruction sets
For production UXN development, consider using the official `uxnasm` or `ruxnasm` assemblers until these features are implemented.
## Performance
- **Fast Assembly**: Optimized two-pass assembler
- **Memory Efficient**: Minimal memory usage during assembly
- **Batch Processing**: Efficient directory processing
- **Error Recovery**: Detailed error reporting with line numbers
## Contributing
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass: `cargo test`
5. Submit a pull request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Related Projects
- [UXN](https://100r.co/site/uxn.html) - The UXN virtual machine
- [uxnasm](https://git.sr.ht/~rabbits/uxn) - Original C implementation
- [ruxnasm](https://github.com/bellinitte/ruxnasm) - Another Rust implementation
## Acknowledgments
- **Devine Lu Linvega** - Creator of UXN and TAL
- **UXN Community** - Documentation and examples
- **100 Rabbits** - UXN ecosystem development
- **Binary**: `#b10101010`
- **Character**: `'A`, `'B`
- **Strings**: `"Hello World"`
### Labels and References
- **Label Definition**: `@main`, `@loop`
- **Label Reference**: `;main`, `;data`
- **Sublabel Definition**: `&loop`, `&end`
- **Sublabel Reference**: `,loop`, `,end`
- **Relative Reference**: `/loop` (for short jumps)
### Instructions
All UXN instructions are supported with mode flags:
- **Base Instructions**: `ADD`, `SUB`, `MUL`, `DIV`, `JMP`, `JSR`, etc.
- **Short Mode**: `ADD2`, `LDA2`, `STA2` (operates on 16-bit values)
- **Return Mode**: `ADDr`, `LDAr` (uses return stack)
- **Keep Mode**: `ADDk`, `LDAk` (doesn't consume stack values)
- **Combined Modes**: `ADD2rk`, `LDA2k`, etc.
### Directives
- **Padding**: `|0100` (pad to address 0x0100)
- **Comments**: `( this is a comment )`
## Examples
### Hello World
```tal
( Hello World Program )
|0100 @reset
;hello-world print-string
BRK
@print-string ( string* -- )
&loop
LDAk #18 DEO INC2
LDAk ,&loop JCN
POP2 JMP2r
@hello-world
"Hello 20 "World! 0a 00
```
### Counter Program
```tal
( Counter Program )
|0100 @reset
#00 ;counter STA
&main-loop
;counter LDA
DUP #30 ADD #18 DEO ( print digit )
#20 #18 DEO ( print space )
INC DUP ;counter STA
#0a LTH ,&main-loop JCN
#0a #18 DEO ( newline )
BRK
@counter $1
```
## Running Examples
```bash
# Run the hello world example
cargo run --example hello_world
# Run the counter example
cargo run --example counter
```
## Testing
Run the test suite:
```bash
cargo test
```
## Architecture
The assembler uses a two-pass approach:
1. **First Pass**: Tokenize source, parse into AST, collect label definitions, and generate initial code
2. **Second Pass**: Resolve forward references and patch addresses
### Modules
- **`lexer`**: Tokenizes TAL source code
- **`parser`**: Converts tokens into Abstract Syntax Tree
- **`opcodes`**: UXN instruction definitions and mode handling
- **`assembler`**: Main assembly logic with symbol table management
- **`rom`**: ROM file generation and binary output
- **`error`**: Comprehensive error types with detailed messages
## Error Handling
The library provides detailed error messages for common issues:
- Syntax errors with line numbers
- Undefined label references
- Duplicate label definitions
- Invalid number formats
- Unknown opcodes
- ROM size limits
- Invalid addressing modes
## Current Limitations
**Update**: This assembler now supports core TAL syntax **and** advanced features found in most production TAL programs. The following features are now implemented:
- **Macros** (`%MACRO { ... }`): Preprocessor-style definitions
- **Device Access** (`.Screen/width`): Direct device port access syntax
- **Inline Assembly** (`[ ... ]`): Raw bytecode blocks
- **Include Files**: File inclusion directives
You can now assemble most existing TAL programs, including those from official UXN projects and demos.
## New Feature Support
- **Macros**: Write and use macros for reusable code blocks
- **Device Access**: Use device port syntax for direct hardware access
- **Inline Assembly**: Embed raw bytecode blocks for optimization
- **Include Files**: Modularize programs with file inclusion
## Performance & Error Handling
- **Fast Assembly**: Optimized two-pass assembler
- **Memory Efficient**: Minimal memory usage during assembly
- **Batch Processing**: Efficient directory processing
- **Error Reporting**: Detailed error messages with line numbers, file names, and source context
## Error Handling
All errors include file name, line number, position, and source line for actionable debugging. Common error types:
- Syntax errors (with file, line, position, and source context)
- Undefined label references
- Duplicate label definitions
- Invalid number formats
- Unknown opcodes
- ROM size limits
- Invalid addressing modes
#### `Assembler`
Main assembler instance for processing TAL source code.
```rust
impl Assembler {
pub fn new() -> Self
pub fn assemble(&mut self, source: &str, context: Option<String>) -> Result<Vec<u8>, AssemblerError>
pub fn generate_symbol_file(&self) -> String
pub fn generate_symbol_file_binary(&self) -> Vec<u8>
pub fn symbols(&self) -> &HashMap<String, Symbol>
}
```
#### `AssemblerError`
Comprehensive error types with detailed messages:
- `SyntaxError { path: String, line: usize, position: usize, message: String, source_line: String }`
- `UnknownOpcode { opcode: String }`
- `UndefinedLabel { label: String }`
- `DuplicateLabel { label: String }`
- `InvalidNumber { value: String }`
- `Io(std::io::Error)`
## License
This project is licensed under the MIT License - see the LICENSE file for details.
The repository includes ROMs and TAL files from the `uxn` reference
implementation, which are © Devine Lu Linvega and released under the MIT
license
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Related Projects
- [UXN](https://100r.co/site/uxn.html) - The UXN virtual machine
- [TAL](https://wiki.xxiivv.com/site/tal.html) - TAL assembly language documentation