Skip to main content

assembler/
driver.rs

1//! Invoke the various passes of the assembler.
2mod output;
3
4#[cfg(test)]
5mod tests;
6
7use std::collections::BTreeMap;
8use std::ffi::OsStr;
9use std::fs::OpenOptions;
10use std::io::{BufReader, BufWriter, Read};
11use std::path::{Path, PathBuf};
12
13use chumsky::error::Rich;
14use tracing::{Level, event, span};
15
16#[cfg(test)]
17use super::ast::{
18    ArithmeticExpression, Atom, CommaDelimitedFragment, HoldBit, InstructionFragment,
19    InstructionSequence, LiteralValue, TaggedProgramInstruction, UntaggedProgramInstruction,
20};
21use super::ast::{Origin, RcUpdater};
22use super::collections::OneOrMore;
23use super::directive::Directive;
24use super::eval::Evaluate;
25use super::eval::HereValue;
26use super::eval::ScopeIdentifier;
27use super::eval::{EvaluationContext, RcBlock, extract_final_equalities};
28use super::lexer;
29use super::listing::{Listing, ListingLine, ListingWithBody};
30#[cfg(test)]
31use super::manuscript::ManuscriptBlock;
32#[cfg(test)]
33use super::manuscript::PunchCommand;
34use super::manuscript::SourceFile;
35use super::memorymap::{
36    BlockPosition, MemoryMap, RcAllocator, RcWordAllocationFailure, RcWordSource,
37};
38use super::parser::parse_source_file;
39use super::source::Source;
40use super::source::{LineAndColumn, WithLocation};
41#[cfg(test)]
42use super::span::span;
43use super::span::{Span, Spanned};
44use super::state::NumeralMode;
45use super::symbol::SymbolName;
46use super::symtab::{
47    ExplicitSymbolTable, FinalSymbolDefinition, FinalSymbolTable, FinalSymbolType,
48    ImplicitSymbolTable, IndexRegisterAssigner, assign_default_rc_word_tags,
49};
50use super::types::{AssemblerFailure, IoAction, IoFailed, IoTarget, ProgramError};
51use base::prelude::{Address, IndexBy, Unsigned18Bit, Unsigned36Bit};
52use base::subword;
53pub use output::write_user_program;
54
55#[cfg(test)]
56use base::charset::Script;
57#[cfg(test)]
58use base::u36;
59
60/// Represents the meta commands which are still relevant in the
61/// directive.  Excludes things like the PUNCH meta command.
62#[derive(Debug, Clone, PartialEq, Eq)]
63pub enum DirectiveMetaCommand {
64    Invalid, // e.g."☛☛BOGUS"
65    BaseChange(NumeralMode),
66}
67
68/// Indicates what kind of output the user wants.
69#[derive(Debug, Clone, PartialEq, Eq, Default)]
70pub struct OutputOptions {
71    // TODO: implement arguments of the LIST, PLIST, TYPE
72    // metacommands.
73    pub list: bool,
74}
75
76impl OutputOptions {
77    // Merge two `OutputOptions` instances.  We deliberately consume
78    // both `self` and `other` in order to force the caller to use
79    // only the returned result.
80    #![allow(clippy::needless_pass_by_value)]
81    #[must_use]
82    fn merge(self, other: OutputOptions) -> OutputOptions {
83        OutputOptions {
84            list: self.list || other.list,
85        }
86    }
87}
88
89/// Pass 1 converts the program source into an abstract syntax representation.
90fn assemble_pass1<'src, 'sourceobj>(
91    source_file_body: &'src str,
92) -> (
93    Option<SourceFile>,
94    Vec<Rich<'src, lexer::Token>>,
95    OutputOptions,
96)
97where
98    'src: 'sourceobj,
99{
100    let span = span!(Level::ERROR, "assembly pass 1");
101    let _enter = span.enter();
102    let options = OutputOptions { list: false };
103
104    let (mut sf, mut errors) = parse_source_file(source_file_body);
105
106    if let Some(source_file) = sf.as_mut()
107        && let Err(tag_errors) = source_file.build_local_symbol_tables()
108    {
109        errors.extend(
110            tag_errors
111                .into_iter()
112                .map(|tag_err| Rich::custom(tag_err.span(), tag_err.to_string())),
113        );
114    }
115    (sf, errors, options)
116}
117
118/// Describes the result of running the first (and possibly the
119/// second) pass of the assembler.
120#[derive(Debug, PartialEq, Eq)]
121enum AssemblerPass1Or2Output<'a> {
122    Pass1Failed(Result<OneOrMore<Rich<'a, lexer::Token>>, AssemblerFailure>),
123    Pass2Failed(AssemblerFailure),
124    Success(Vec<Rich<'a, lexer::Token>>, OutputOptions, Pass2Output<'a>),
125}
126
127/// Assemble a non-empty input.
128fn assemble_nonempty_input<'a, 'b: 'a>(input: &'b Source<'a>) -> AssemblerPass1Or2Output<'a> {
129    let (maybe_source_file, errors, output_options) = assemble_pass1(input.as_str());
130    match maybe_source_file {
131        None => match OneOrMore::try_from_vec(errors) {
132            Ok(errors) => AssemblerPass1Or2Output::Pass1Failed(Ok(errors)),
133            Err(_) => {
134                unreachable!(
135                    "assemble_pass1 returned no SourceFile instance but there were no output errors either"
136                );
137            }
138        },
139        Some(source_file) => match assemble_pass2(source_file, input) {
140            Err(e) => AssemblerPass1Or2Output::Pass2Failed(e),
141            Ok(p2output) => AssemblerPass1Or2Output::Success(errors, output_options, p2output),
142        },
143    }
144}
145
146/// This test helper is defined here so that we don't have to expose
147/// `assemble_pass1` or `assemble_pass2`.
148#[cfg(test)]
149pub(crate) fn assemble_nonempty_valid_input(
150    input: &str,
151) -> (
152    Directive,
153    ExplicitSymbolTable,
154    ImplicitSymbolTable,
155    MemoryMap,
156    IndexRegisterAssigner,
157) {
158    let input_source = Source::new(input);
159    match assemble_nonempty_input(&input_source) {
160        AssemblerPass1Or2Output::Pass1Failed(Err(e)) => {
161            panic!("pass 1 failed with an error result: {e}");
162        }
163        AssemblerPass1Or2Output::Pass1Failed(Ok(errors)) => {
164            panic!("pass 1 failed with diagnostics: {errors:?}");
165        }
166        AssemblerPass1Or2Output::Pass2Failed(e) => {
167            panic!("pass 2 failed with an error result: {e}");
168        }
169        AssemblerPass1Or2Output::Success(errors, _output_options, p2output) => {
170            if errors.is_empty() {
171                match p2output {
172                    Pass2Output {
173                        directive: None, ..
174                    } => {
175                        panic!("directive is None but no errors were reported");
176                    }
177                    Pass2Output {
178                        directive: Some(directive),
179                        explicit_symbols,
180                        implicit_symbols,
181                        memory_map,
182                        index_register_assigner,
183                        errors,
184                    } => {
185                        if errors.is_empty() {
186                            (
187                                directive,
188                                explicit_symbols,
189                                implicit_symbols,
190                                memory_map,
191                                index_register_assigner,
192                            )
193                        } else {
194                            panic!("input should be valid: {errors:?}");
195                        }
196                    }
197                }
198            } else {
199                panic!("pass 2 failed with diagnostics: {errors:?}");
200            }
201        }
202    }
203}
204
205/// A contiguous sequence of words at some starting address.
206#[derive(Debug, Clone, PartialEq, Eq, Default)]
207pub struct BinaryChunk {
208    /// Starting address
209    pub address: Address,
210    /// The words in the chunk.
211    pub words: Vec<Unsigned36Bit>,
212}
213
214impl BinaryChunk {
215    #[must_use]
216    pub fn is_empty(&self) -> bool {
217        self.words.is_empty()
218    }
219
220    fn count_words(&self) -> usize {
221        self.words.len()
222    }
223
224    pub fn push(&mut self, w: Unsigned36Bit) {
225        self.words.push(w);
226    }
227}
228
229impl From<RcBlock> for BinaryChunk {
230    fn from(block: RcBlock) -> Self {
231        BinaryChunk {
232            address: block.address,
233            words: block
234                .words
235                .into_iter()
236                .map(|(_source, word)| word)
237                .collect(),
238        }
239    }
240}
241
242/// The assembled program; a sequence of [`BinaryChunk`] instances
243/// with an optional entry point.
244#[derive(Debug, Clone, PartialEq, Eq, Default)]
245pub struct Binary {
246    entry_point: Option<Address>,
247    chunks: Vec<BinaryChunk>,
248}
249
250impl Binary {
251    fn count_words(&self) -> usize {
252        self.chunks().iter().map(BinaryChunk::count_words).sum()
253    }
254
255    fn entry_point(&self) -> Option<Address> {
256        self.entry_point
257    }
258
259    fn set_entry_point(&mut self, address: Address) {
260        self.entry_point = Some(address);
261    }
262
263    pub fn add_chunk(&mut self, chunk: BinaryChunk) {
264        self.chunks.push(chunk);
265    }
266
267    fn chunks(&self) -> &[BinaryChunk] {
268        &self.chunks
269    }
270
271    fn is_empty(&self) -> bool {
272        self.chunks.is_empty()
273    }
274}
275
276/// Output of pass 2 of the assembler.
277#[derive(Debug, PartialEq, Eq)]
278struct Pass2Output<'a> {
279    /// An abstract representation of the source code.
280    directive: Option<Directive>,
281    /// Explicit symbol definitions ("equalities")
282    explicit_symbols: ExplicitSymbolTable,
283    /// Information about symbols which are known but lack a definition.
284    implicit_symbols: ImplicitSymbolTable,
285    /// Location of the blocks of the program.
286    memory_map: MemoryMap,
287    /// Provides for default-assignment of symbols used only in an
288    /// index context.
289    index_register_assigner: IndexRegisterAssigner, // not cloneable
290    /// Syntac or semantic errors diagnosed so far.  We use this
291    /// instead of `Result<T,E>` so that we can diagnose more than one
292    /// error.
293    errors: Vec<Rich<'a, lexer::Token>>,
294}
295
296fn initial_symbol_table<'a>(
297    source_file: &SourceFile,
298) -> Result<(ExplicitSymbolTable, ImplicitSymbolTable), OneOrMore<Rich<'a, lexer::Token>>> {
299    let mut errors = Vec::new();
300    // TODO: split these out into separate functions.
301    let mut explicit_symbols = ExplicitSymbolTable::new();
302    // All explicit definitions in the program take effect either
303    // locally (for the bodies of macro expansions) or globally (for
304    // everything else).  So, before we can enumerate all global
305    // symbol references, we need to identidy which symbol references
306    // are references to something defined in a local scope.  And so
307    // we need to enumerate definitions before references.
308    for r in source_file.global_symbol_definitions() {
309        match r {
310            Ok((symbol, span, definition)) => {
311                match explicit_symbols.define(symbol.clone(), definition.clone()) {
312                    Ok(()) => (),
313                    Err(e) => {
314                        errors.push(Rich::custom(
315                            span,
316                            format!("bad symbol definition for {symbol}: {e}"),
317                        ));
318                    }
319                }
320            }
321            Err(e) => {
322                let span: Span = e.span();
323                errors.push(Rich::custom(span, e.to_string()));
324            }
325        }
326    }
327    let mut implicit_symbols = ImplicitSymbolTable::default();
328    for r in source_file.global_symbol_references() {
329        match r {
330            Ok((symbol, span, context)) => {
331                if !explicit_symbols.is_defined(&symbol)
332                    && let Err(e) = implicit_symbols.record_usage_context(&symbol, &context)
333                {
334                    errors.push(Rich::custom(span, e.to_string()));
335                }
336            }
337            Err(e) => {
338                let span: Span = e.span();
339                errors.push(Rich::custom(span, e.to_string()));
340            }
341        }
342    }
343    match OneOrMore::try_from_vec(errors) {
344        Ok(errors) => Err(errors),
345        Err(_) => Ok((explicit_symbols, implicit_symbols)),
346    }
347}
348
349/// Pass 2 converts the abstract syntax representation into a
350/// `Directive`, which is closer to binary code.
351///
352/// The `source_file` input is essentially an abstract syntax
353/// representation.  The output is a symbol table and a "directive"
354/// which is a sequence of blocks of code of known position and size
355/// (but the contents of which are not yet populated).
356fn assemble_pass2<'s>(
357    source_file: SourceFile,
358    source_file_body: &Source<'s>,
359) -> Result<Pass2Output<'s>, AssemblerFailure> {
360    let span = span!(Level::ERROR, "assembly pass 2");
361    let _enter = span.enter();
362
363    let mut memory_map = MemoryMap::new(source_file.blocks.iter().map(|block| {
364        let span: Span = block.origin_span();
365        (span, block.origin.clone(), block.instruction_count())
366    }));
367
368    let (mut explicit_symbols, mut implicit_symbols) = match initial_symbol_table(&source_file) {
369        Ok(syms) => syms,
370        Err(errors) => {
371            return Err(AssemblerFailure::BadProgram(fail_with_diagnostics(
372                source_file_body,
373                errors,
374            )));
375        }
376    };
377    let mut index_register_assigner: IndexRegisterAssigner = IndexRegisterAssigner::default();
378    let mut no_rc_allocation = NoRcBlock {
379        why_blocked: "we don't expect origin computation to require RC-word allocation",
380    };
381    let tmp_blocks: Vec<BlockPosition> = memory_map.iter().cloned().collect();
382    for block_position in tmp_blocks {
383        let mut ctx = EvaluationContext {
384            explicit_symtab: &mut explicit_symbols,
385            implicit_symtab: &mut implicit_symbols,
386            memory_map: &memory_map,
387            here: HereValue::NotAllowed,
388            index_register_assigner: &mut index_register_assigner,
389            rc_updater: &mut no_rc_allocation,
390            lookup_operation: Default::default(),
391        };
392        let scope = ScopeIdentifier::global();
393        match block_position.evaluate(&mut ctx, scope) {
394            Ok(value) => {
395                if !ctx.index_register_assigner.is_empty() {
396                    return Err(AssemblerFailure::InternalError(format!(
397                        "While determining the addresses of {0}, we assigned an index register.  Block origins should not depend on index registers",
398                        block_position.block_identifier
399                    )));
400                }
401
402                let address: Address = subword::right_half(value).into();
403                memory_map.set_block_position(block_position.block_identifier, address);
404            }
405            Err(e) => {
406                let prog_error: ProgramError = e.into_program_error();
407                return Err(prog_error.into_assembler_failure(source_file_body));
408            }
409        }
410    }
411
412    let directive = source_file.into_directive(&memory_map);
413    if let Some(instruction_count) = directive
414        .blocks
415        .values()
416        .try_fold(Unsigned18Bit::ZERO, |acc, b| {
417            acc.checked_add(b.emitted_word_count())
418        })
419    {
420        event!(
421            Level::INFO,
422            "assembly pass 2 generated {instruction_count} instructions"
423        );
424    }
425    Ok(Pass2Output {
426        directive: Some(directive),
427        explicit_symbols,
428        implicit_symbols,
429        memory_map,
430        index_register_assigner,
431        errors: Vec::new(),
432    })
433}
434
435/// Placeholder for the RC-block which will not allocate words.
436///
437/// The job of this struct is to prevent allocation of words in the
438/// RC-block while we are still trying to compute the origin of each
439/// block of the program.
440struct NoRcBlock {
441    why_blocked: &'static str,
442}
443
444impl RcAllocator for NoRcBlock {
445    fn allocate(
446        &mut self,
447        _source: RcWordSource,
448        _value: Unsigned36Bit,
449    ) -> Result<Address, RcWordAllocationFailure> {
450        panic!(
451            "Cannot allocate an RC-word before we know the address of the RC block: {}",
452            self.why_blocked
453        );
454    }
455}
456
457impl RcUpdater for NoRcBlock {
458    fn update(&mut self, _address: Address, _value: Unsigned36Bit) {
459        panic!(
460            "Cannot update an RC-word in an RC-block which cannot allocate words: {}",
461            self.why_blocked
462        );
463    }
464}
465
466/// Pass 3 generates binary code.
467fn assemble_pass3(
468    mut directive: Directive,
469    explicit_symtab: &mut ExplicitSymbolTable,
470    implicit_symtab: &mut ImplicitSymbolTable,
471    memory_map: &mut MemoryMap,
472    index_register_assigner: &mut IndexRegisterAssigner,
473    body: &Source,
474    listing: &mut Listing,
475) -> Result<(Binary, FinalSymbolTable), AssemblerFailure> {
476    let span = span!(Level::ERROR, "assembly pass 3");
477    let _enter = span.enter();
478    let mut binary = Binary::default();
479    if let Some(address) = directive.entry_point() {
480        binary.set_entry_point(address);
481    }
482
483    let mut rcblock = RcBlock {
484        address: directive.position_rc_block(),
485        words: Vec::new(),
486    };
487
488    let Directive {
489        mut blocks,
490        equalities,
491        entry_point: _,
492    } = directive;
493
494    // TODO: we should be able to convert implicit_symtab into
495    // final_symbols (and drop implicit_symtab).
496    let mut final_symbols = FinalSymbolTable::default();
497    let mut bad_symbol_definitions: BTreeMap<SymbolName, ProgramError> = Default::default();
498    // TODO: consider moving this into pass 2.
499    for block in blocks.values() {
500        if let Some(Origin::Symbolic(span, symbol_name)) = block.origin.as_ref()
501            && !explicit_symtab.is_defined(symbol_name)
502        {
503            final_symbols.define_if_undefined(
504                symbol_name.clone(),
505                FinalSymbolType::Tag, // actually origin
506                body.extract(span.start..span.end).to_string(),
507                FinalSymbolDefinition::PositionIndependent(block.location.into()),
508            );
509        }
510    }
511
512    // We call extract_final_equalities here is to ensure that we
513    // diagnose all looping definitions of equalities and get the data
514    // we need for the listing, if there will be one.  It isn't
515    // actually needed to generate the output binary.
516    extract_final_equalities(
517        equalities.as_slice(),
518        body,
519        explicit_symtab,
520        implicit_symtab,
521        memory_map,
522        index_register_assigner,
523        &mut rcblock,
524        &mut final_symbols,
525        &mut bad_symbol_definitions,
526    )?;
527
528    let convert_rc_failure = |e: RcWordAllocationFailure| -> AssemblerFailure {
529        match e {
530            RcWordAllocationFailure::RcBlockTooBig { source, .. } => {
531                let span: Span = source.span();
532                let location: LineAndColumn = body.location_of(span.start);
533                AssemblerFailure::BadProgram(OneOrMore::new(WithLocation {
534                    location,
535                    inner: ProgramError::RcBlockTooLong(source),
536                }))
537            }
538            ref e @ RcWordAllocationFailure::InconsistentTag {
539                ref tag_name,
540                span,
541                explanation: _,
542            } => {
543                let location: LineAndColumn = body.location_of(span.start);
544                AssemblerFailure::BadProgram(OneOrMore::new(WithLocation {
545                    location,
546                    inner: ProgramError::InconsistentTag {
547                        name: tag_name.clone(),
548                        span,
549                        msg: e.to_string(),
550                    },
551                }))
552            }
553        }
554    };
555
556    for directive_block in blocks.values_mut() {
557        if let Err(e) =
558            directive_block.allocate_rc_words(explicit_symtab, implicit_symtab, &mut rcblock)
559        {
560            return Err(convert_rc_failure(e));
561        }
562    }
563
564    // Now that RC-word allocation is complete, we no longer need to
565    // mutate the explicit symbol table.
566    let explicit_symtab: &ExplicitSymbolTable = &*explicit_symtab;
567
568    for name in implicit_symtab.symbols() {
569        match (implicit_symtab.get(name), explicit_symtab.get(name)) {
570            (Some(implicit), Some(explicit)) => {
571                panic!(
572                    "symbol {name} appears in both the implicit ({implicit:#?} and the explicit ({explicit:#?} symbol tables"
573                );
574            }
575            (Some(_), None) | (None, Some(_)) => (),
576            (None, None) => {
577                panic!(
578                    "symbol {name} is returned by ImplicitSymbolTable::symbols() but is not defined there"
579                );
580            }
581        }
582    }
583
584    if let Err(e) = assign_default_rc_word_tags(implicit_symtab, &mut rcblock, &mut final_symbols) {
585        return Err(convert_rc_failure(e));
586    }
587
588    // Emit the binary code.
589    for (block_id, directive_block) in blocks {
590        event!(
591            Level::DEBUG,
592            "{block_id} in output has address {0:#o} and length {1:#o}",
593            directive_block.location,
594            directive_block.emitted_word_count(),
595        );
596        if let Some(origin) = directive_block.origin.clone() {
597            // This is an origin (Users Handbook section 6-2.5) not a
598            // tag (6-2.2).
599            let span = origin.span();
600            listing.push_line(ListingLine {
601                span: Some(span),
602                rc_source: None,
603                content: None,
604            });
605        }
606
607        let words = directive_block.build_binary_block(
608            directive_block.location,
609            explicit_symtab,
610            implicit_symtab,
611            memory_map,
612            index_register_assigner,
613            &mut rcblock,
614            &mut final_symbols,
615            body,
616            listing,
617            &mut bad_symbol_definitions,
618        )?;
619        if words.is_empty() {
620            event!(
621                Level::DEBUG,
622                "{block_id} will not be included in the output because it is empty"
623            );
624        } else {
625            binary.add_chunk(BinaryChunk {
626                address: directive_block.location,
627                words,
628            });
629        }
630    }
631
632    // If the RC-word block is non-empty, emit it.
633    if !rcblock.words.is_empty() {
634        for (i, (rc_source, word)) in rcblock.words.iter().enumerate() {
635            let address = rcblock.address.index_by(
636                Unsigned18Bit::try_from(i)
637                    .expect("RC block size should be limite to physical address space"),
638            );
639
640            listing.push_rc_line(ListingLine {
641                span: None,
642                rc_source: Some(rc_source.clone()),
643                content: Some((address, *word)),
644            });
645        }
646    }
647    let chunk: BinaryChunk = rcblock.into();
648    if chunk.is_empty() {
649        event!(
650            Level::DEBUG,
651            "The RC-word block is empty, and so it will not be emitted.",
652        );
653    } else {
654        event!(
655            Level::DEBUG,
656            "Emitting RC-word block of length {:#o} words at address {:#o}.",
657            chunk.words.len(),
658            &chunk.address,
659        );
660        binary.add_chunk(chunk);
661    }
662
663    match OneOrMore::try_from_iter(bad_symbol_definitions.into_values().map(|program_error| {
664        let span = program_error.span();
665        let location = body.location_of(span.start);
666        WithLocation {
667            location,
668            inner: program_error,
669        }
670    })) {
671        Ok(errors) => Err(AssemblerFailure::BadProgram(errors)),
672        Err(_) => Ok((binary, final_symbols)),
673    }
674}
675
676/// Pass-through a `String` instance; the output quotes [control
677/// characters](char::is_control) and backslashes.
678fn cleanup_control_chars(input: String) -> String {
679    fn needs_escape(ch: char) -> bool {
680        ch == '\\' || ch.is_control()
681    }
682    let extra = input.chars().filter(|ch: &char| needs_escape(*ch)).count();
683    if extra > 0 {
684        let mut output: String = String::with_capacity(input.len().saturating_add(extra));
685        for ch in input.chars() {
686            if needs_escape(ch) {
687                output.extend(ch.escape_default());
688            } else {
689                output.push(ch);
690            }
691        }
692        output
693    } else {
694        // No need to escape anything, return the input unchanged.
695        input
696    }
697}
698
699#[test]
700fn test_cleanup_control_chars_not_control() {
701    for input in &["", "hello", "12", "X Y"] {
702        let input = (*input).to_string();
703        let output = cleanup_control_chars(input.clone());
704        assert_eq!(output, input);
705    }
706}
707
708#[test]
709fn test_cleanup_control_chars_quotes() {
710    for input in &["They're", "\"hello\"", "\"\"", "''", "Un\"balanced"] {
711        let input = (*input).to_string();
712        let output = cleanup_control_chars(input.clone());
713        assert_eq!(output, input);
714    }
715}
716
717#[test]
718fn test_cleanup_control_chars_backslash() {
719    assert_eq!(
720        cleanup_control_chars(String::from("First line\nsecond line")),
721        String::from("First line\\nsecond line")
722    );
723    assert_eq!(
724        cleanup_control_chars(String::from("\\")),
725        String::from("\\\\")
726    );
727}
728
729/// Convert raw parse errors into instances of `ProgramError`.
730fn fail_with_diagnostics(
731    source_file_body: &Source,
732    errors: OneOrMore<Rich<lexer::Token>>,
733) -> OneOrMore<WithLocation<ProgramError>> {
734    errors.into_map(|e| {
735        let span: Span = *e.span();
736        WithLocation {
737            location: source_file_body.location_of(span.start),
738            inner: ProgramError::SyntaxError {
739                span,
740                msg: cleanup_control_chars(e.to_string()),
741            },
742        }
743    })
744}
745
746/// Run all the passes of assembly, generating an output-ready
747/// [`Binary`].
748///
749/// # Arguments
750///
751/// - `source_file_body` - the contents (body) of the source file
752/// - `options` - what kind of output the user wants
753///
754/// # Errors
755///
756/// - [`AssemblerFailure::BadTapeBlock`] - output program block is too big
757/// - [`AssemblerFailure::BadProgram`] - Syntax or semantic error
758/// - [`AssemblerFailure::MachineLimitExceeded`] - Program is too large in some way
759/// - [`AssemblerFailure::InternalError`] - Encountered a bug in the parser
760pub(crate) fn assemble_source(
761    source_file_body: &str,
762    mut options: OutputOptions,
763) -> Result<Binary, AssemblerFailure> {
764    let source_file_body = Source::new(source_file_body);
765    let mut p2output = match assemble_nonempty_input(&source_file_body) {
766        AssemblerPass1Or2Output::Pass1Failed(Ok(errors)) => {
767            return Err(AssemblerFailure::BadProgram(fail_with_diagnostics(
768                &source_file_body,
769                errors,
770            )));
771        }
772        AssemblerPass1Or2Output::Pass1Failed(Err(e)) | AssemblerPass1Or2Output::Pass2Failed(e) => {
773            return Err(e);
774        }
775        AssemblerPass1Or2Output::Success(
776            errors,
777            _output_options,
778            Pass2Output {
779                directive: None, ..
780            },
781        ) if errors.is_empty() => {
782            panic!("assembly pass1 generated no errors, a directive should have been returned");
783        }
784        AssemblerPass1Or2Output::Success(errors, output_options, p2output) => {
785            if let Ok(errors) = OneOrMore::try_from_vec(errors) {
786                return Err(AssemblerFailure::BadProgram(fail_with_diagnostics(
787                    &source_file_body,
788                    errors,
789                )));
790            }
791            // No errors.
792            options = options.merge(output_options);
793            p2output
794        }
795    };
796
797    // Now we do pass 3, which generates the binary output
798    let binary = {
799        let mut listing = Listing::default();
800        let (binary, final_symbols) = assemble_pass3(
801            p2output
802                .directive
803                .expect("directive should have already been checked for None-ness"),
804            &mut p2output.explicit_symbols,
805            &mut p2output.implicit_symbols,
806            &mut p2output.memory_map,
807            &mut p2output.index_register_assigner,
808            &source_file_body,
809            &mut listing,
810        )?;
811
812        listing.set_final_symbols(final_symbols);
813        if options.list {
814            println!(
815                "{0}",
816                ListingWithBody {
817                    listing: &listing,
818                    body: &source_file_body,
819                }
820            );
821        }
822        binary
823    };
824
825    event!(
826        Level::INFO,
827        "assembly pass 3 generated {} words of binary output (not counting the reader leader)",
828        binary.count_words()
829    );
830    Ok(binary)
831}
832
833#[cfg(test)]
834fn atom_to_fragment(atom: Atom) -> InstructionFragment {
835    InstructionFragment::Arithmetic(ArithmeticExpression::from(atom))
836}
837
838#[test]
839fn test_assemble_pass1() {
840    let input = concat!("14\n", "☛☛PUNCH 26\n");
841    let expected_directive_entry_point = Some(Address::new(Unsigned18Bit::from(0o26_u8)));
842    let expected_block = ManuscriptBlock {
843        origin: None,
844        sequences: vec![InstructionSequence {
845            local_symbols: None,
846            instructions: vec![TaggedProgramInstruction {
847                span: span(0..2),
848                tags: Vec::new(),
849                instruction: UntaggedProgramInstruction::from(OneOrMore::new(
850                    CommaDelimitedFragment {
851                        leading_commas: None,
852                        holdbit: HoldBit::Unspecified,
853                        span: span(0..2),
854                        fragment: atom_to_fragment(Atom::from(LiteralValue::from((
855                            span(0..2),
856                            Script::Normal,
857                            u36!(0o14),
858                        )))),
859                        trailing_commas: None,
860                    },
861                )),
862            }],
863        }],
864    };
865
866    let (source_file, errors, options) = assemble_pass1(input);
867    assert_eq!(
868        source_file,
869        Some(SourceFile {
870            punch: Some(PunchCommand(expected_directive_entry_point)),
871            blocks: vec![expected_block],
872            global_equalities: Default::default(), // no equalities
873            macros: Default::default(),
874        })
875    );
876    assert_eq!(options, OutputOptions { list: false });
877    assert_eq!(errors.as_slice(), []);
878}
879
880/// Assemble input file, producing a tape image.
881///
882/// # Arguments
883///
884/// - `input_file_name` - name of the source code file
885/// - `outputoptions` - where to write the tape image
886/// - `options` - what kind of output the user wants (in
887///   addition to the tape image)
888///
889/// # Errors
890///
891/// - `AssemblerFailure::Io` - failed to read input / write output
892/// - [`AssemblerFailure::BadTapeBlock`] - output program block is too big
893/// - [`AssemblerFailure::BadProgram`] - Syntax or semantic error
894/// - [`AssemblerFailure::MachineLimitExceeded`] - Program is too large in some way
895/// - [`AssemblerFailure::InternalError`] - Encountered a bug in the parser
896///    -
897pub fn assemble_file(
898    input_file_name: &OsStr,
899    output_file_name: &Path,
900    options: OutputOptions,
901) -> Result<(), AssemblerFailure> {
902    let input_file = OpenOptions::new()
903        .read(true)
904        .open(input_file_name)
905        .map_err(|e| {
906            AssemblerFailure::Io(IoFailed {
907                action: IoAction::Read,
908                target: IoTarget::File(PathBuf::from(input_file_name)),
909                error: e,
910            })
911        })?;
912
913    let source_file_body: String = {
914        let mut body = String::new();
915        match BufReader::new(input_file).read_to_string(&mut body) {
916            Err(e) => {
917                return Err(AssemblerFailure::Io(IoFailed {
918                    action: IoAction::Read,
919                    target: IoTarget::File(PathBuf::from(input_file_name)),
920                    error: e,
921                }));
922            }
923            Ok(_) => body,
924        }
925    };
926
927    let user_program: Binary = assemble_source(&source_file_body, options)?;
928
929    // The Users Guide explains on page 6-23 how the punched binary
930    // is created (and read back in).
931    let output_file = OpenOptions::new()
932        .create(true)
933        .write(true)
934        .truncate(true)
935        .open(output_file_name)
936        .map_err(|e| {
937            AssemblerFailure::Io(IoFailed {
938                action: IoAction::Write,
939                target: IoTarget::File(PathBuf::from(output_file_name)),
940                error: e,
941            })
942        })?;
943    let mut writer = BufWriter::new(output_file);
944    write_user_program(&user_program, &mut writer, output_file_name)
945}
946
947#[test]
948fn test_duplicate_global_tag() {
949    let input = concat!("TGX->0\n", "TGX->0\n");
950    let input_source = Source::new(input);
951    match assemble_nonempty_input(&input_source) {
952        AssemblerPass1Or2Output::Pass2Failed(AssemblerFailure::BadProgram(errors)) => {
953            dbg!(&errors);
954            match errors.first() {
955                WithLocation {
956                    inner: ProgramError::SyntaxError { msg, span: _ },
957                    ..
958                } => {
959                    assert!(
960                        msg.contains(
961                            "bad symbol definition for TGX: TGX is defined more than once"
962                        )
963                    );
964                }
965                other => {
966                    panic!("expected a syntax error report, got {other:?}");
967                }
968            }
969        }
970        AssemblerPass1Or2Output::Success(errors, _output_options, p2output) => {
971            dbg!(&errors);
972            dbg!(&p2output);
973            panic!("assembler unexpectedly succeeded with a bad input {input}");
974        }
975        unexpected => {
976            panic!("assembly failed, but not in the way expected by this test: {unexpected:?}");
977        }
978    }
979}