ironwork_rt/module/
programs.rs

1//! Writing and reading the programs of a module: the sections that split a `lir::Program` between them.
2
3use super::codec::{Decode, Encode, Reader, Writer};
4use super::{Module, ModuleError, ModuleWriter, Section, StringTable};
5use crate::bms::Mapset;
6use crate::codec_struct;
7use crate::lir::{
8    AbendText, Block, Code, Cond, Const, Debug, Edit, Expr, Item, ParaId, Paragraph, Place, Plans, Program, ProgramOptions, Range,
9    Services, SqlEntry, Storage, SymId,
10};
11
12/// A program's line in the `DIRECTORY` section (load-module.md §6).
13#[derive(Clone, Debug, PartialEq, Eq)]
14pub struct DirectoryEntry {
15    /// PROGRAM-ID exactly as written.
16    pub id: String,
17    /// A user-defined function's external name, which an invocation loads it by; None for a
18    /// program, which a CALL loads by `id`.
19    pub external: Option<String>,
20    /// The ordinal of the containing program.
21    pub parent: Option<u32>,
22    pub common: bool,
23    /// ENTRY names and the paragraphs they enter.
24    pub entries: Vec<(String, ParaId)>,
25    /// USING: true for BY VALUE, in order.
26    pub params: Vec<bool>,
27    pub returning: bool,
28    /// Visible to a dynamic CALL.
29    pub dynamic: bool,
30}
31
32codec_struct!(DirectoryEntry { id, external, parent, common, entries, params, returning, dynamic });
33
34impl DirectoryEntry {
35    /// The entry for a top-level program that no parse of nesting or ENTRY has refined.
36    pub fn top_level(program: &Program) -> Self {
37        Self {
38            id: program.symbols.get(program.id as usize).cloned().unwrap_or_default(),
39            external: None,
40            parent: None,
41            common: false,
42            entries: Vec::new(),
43            params: vec![false; program.storage.using.len()],
44            returning: program.storage.returning.is_some(),
45            dynamic: true,
46        }
47    }
48
49    /// The name a CALL or a function invocation finds it by.
50    pub fn load_name(&self) -> &str {
51        self.external.as_deref().unwrap_or(&self.id)
52    }
53}
54
55/// A file the compile read, as the run journal of a run of its source names it (load-module.md
56/// §9.2): the library it was found in, 0 the source's own directory and then each `-I` in order,
57/// its path from there, and its SHA-256 and length.
58#[derive(Clone, Debug, PartialEq, Eq)]
59pub struct SourceFile {
60    pub root: u32,
61    pub path: String,
62    pub sha256: [u8; 32],
63    pub bytes: u64,
64}
65
66codec_struct!(SourceFile { root, path, sha256, bytes } check source_file_valid);
67
68/// A path relative to its library, with `/` between its parts, so no record of one names a place
69/// outside it.
70fn source_file_valid(file: &SourceFile) -> Result<(), String> {
71    let relative = !file.path.contains('\\') && file.path.split('/').all(|part| !matches!(part, "" | "." | ".."));
72    if relative { Ok(()) } else { Err(format!("source file {:?} is not a path within its library", file.path)) }
73}
74
75/// The programs of a module, in ordinal order, with their directory, the mapsets they use, and
76/// for each program the file each source of its debug table names, None where the compiler
77/// supplied the member or no file was recorded.
78#[derive(Clone, Debug, PartialEq, Eq)]
79pub struct LoadedModule {
80    pub directory: Vec<DirectoryEntry>,
81    pub programs: Vec<Program>,
82    pub mapsets: Vec<Mapset>,
83    pub files: Vec<Vec<Option<SourceFile>>>,
84}
85
86/// Every field of a `Program`, listed once so a new field is a compile error here.
87struct Parts<'a> {
88    id: &'a SymId,
89    options: &'a ProgramOptions,
90    initial: &'a bool,
91    recursive: &'a bool,
92    storage: &'a Storage,
93    items: &'a Vec<Item>,
94    paragraphs: &'a Vec<Paragraph>,
95    procedure_start: &'a ParaId,
96    ranges: &'a Vec<Range>,
97    blocks: &'a Vec<Block>,
98    places: &'a Vec<Place>,
99    exprs: &'a Vec<Expr>,
100    conds: &'a Vec<Cond>,
101    consts: &'a Vec<Const>,
102    plans: &'a Plans,
103    services: &'a Services,
104    sql: &'a Vec<SqlEntry>,
105    abends: &'a Vec<AbendText>,
106    edits: &'a Vec<Edit>,
107    symbols: &'a Vec<String>,
108    debug: &'a Debug,
109}
110
111impl<'a> Parts<'a> {
112    fn of(program: &'a Program) -> Self {
113        let Program {
114            id, options, initial, recursive, storage, items, paragraphs, procedure_start, ranges, blocks, places,
115            exprs, conds, consts, plans, services, sql, abends, edits, symbols, debug,
116        } = program;
117        Self {
118            id, options, initial, recursive, storage, items, paragraphs, procedure_start, ranges, blocks, places,
119            exprs, conds, consts, plans, services, sql, abends, edits, symbols, debug,
120        }
121    }
122
123    fn encode_lir(&self, w: &mut Writer) {
124        self.id.encode(w);
125        self.initial.encode(w);
126        self.recursive.encode(w);
127        self.paragraphs.encode(w);
128        self.procedure_start.encode(w);
129        self.ranges.encode(w);
130        self.blocks.encode(w);
131        self.places.encode(w);
132        self.exprs.encode(w);
133        self.conds.encode(w);
134        self.consts.encode(w);
135        self.plans.encode(w);
136        self.services.encode(w);
137        self.abends.encode(w);
138        self.symbols.encode(w);
139    }
140}
141
142/// One program's record in the `LAYOUT` section.
143pub type LayoutRecord = (Storage, Vec<Item>, Vec<Edit>);
144
145/// One program's record in the `LIR` section: the fields of `Program` no other section holds.
146#[derive(Clone, Debug, PartialEq, Eq)]
147pub struct LirRecord {
148    pub id: SymId,
149    pub initial: bool,
150    pub recursive: bool,
151    pub paragraphs: Vec<Paragraph>,
152    pub procedure_start: ParaId,
153    pub ranges: Vec<Range>,
154    pub blocks: Vec<Block>,
155    pub places: Vec<Place>,
156    pub exprs: Vec<Expr>,
157    pub conds: Vec<Cond>,
158    pub consts: Vec<Const>,
159    pub plans: Plans,
160    pub services: Services,
161    pub abends: Vec<AbendText>,
162    pub symbols: Vec<String>,
163}
164
165impl LirRecord {
166    pub fn code(&self) -> Code<'_> {
167        Code {
168            id: self.id,
169            initial: self.initial,
170            recursive: self.recursive,
171            paragraphs: &self.paragraphs,
172            procedure_start: self.procedure_start,
173            ranges: &self.ranges,
174            blocks: &self.blocks,
175            places: &self.places,
176            exprs: &self.exprs,
177            conds: &self.conds,
178            consts: &self.consts,
179            plans: &self.plans,
180            services: &self.services,
181            abends: &self.abends,
182            symbols: &self.symbols,
183        }
184    }
185}
186
187impl Decode for LirRecord {
188    fn decode(r: &mut Reader<'_>) -> Result<Self, ModuleError> {
189        Ok(Self {
190            id: Decode::decode(r)?,
191            initial: Decode::decode(r)?,
192            recursive: Decode::decode(r)?,
193            paragraphs: Decode::decode(r)?,
194            procedure_start: Decode::decode(r)?,
195            ranges: Decode::decode(r)?,
196            blocks: Decode::decode(r)?,
197            places: Decode::decode(r)?,
198            exprs: Decode::decode(r)?,
199            conds: Decode::decode(r)?,
200            consts: Decode::decode(r)?,
201            plans: Decode::decode(r)?,
202            services: Decode::decode(r)?,
203            abends: Decode::decode(r)?,
204            symbols: Decode::decode(r)?,
205        })
206    }
207}
208
209/// Program count, then one record per program.
210fn per_program(w: &mut Writer, programs: &[Program], record: impl Fn(&Parts<'_>, &mut Writer)) {
211    w.count(programs.len());
212    for program in programs {
213        record(&Parts::of(program), w);
214    }
215}
216
217fn encode_module(programs: &[Program], directory: &[DirectoryEntry], mapsets: &[Mapset], files: &[Vec<Option<SourceFile>>]) -> Vec<u8> {
218    let mut m = ModuleWriter::new();
219    m.section(Section::DIRECTORY, |w| {
220        w.count(directory.len());
221        for entry in directory {
222            entry.encode(w);
223        }
224    });
225    m.section(Section::OPTIONS, |w| per_program(w, programs, |p, w| p.options.encode(w)));
226    m.section(Section::LAYOUT, |w| {
227        per_program(w, programs, |p, w| {
228            p.storage.encode(w);
229            p.items.encode(w);
230            p.edits.encode(w);
231        });
232    });
233    m.section(Section::LIR, |w| per_program(w, programs, |p, w| p.encode_lir(w)));
234    m.section(Section::SQL, |w| per_program(w, programs, |p, w| p.sql.encode(w)));
235    m.section(Section::BMS, |w| {
236        w.count(mapsets.len());
237        for mapset in mapsets {
238            mapset.encode(w);
239        }
240    });
241    m.section(Section::DEBUG, |w| {
242        w.count(programs.len());
243        for (program, files) in programs.iter().zip(files) {
244            Parts::of(program).debug.encode(w);
245            files.encode(w);
246        }
247    });
248    m.finish()
249}
250
251/// For each program, no file recorded for any source of its debug table.
252fn unrecorded(programs: &[Program]) -> Vec<Vec<Option<SourceFile>>> {
253    programs.iter().map(|p| vec![None; p.debug.sources.len()]).collect()
254}
255
256/// A module of `programs`, each a top-level program in the directory, with no mapsets and no files
257/// recorded. Same input, same bytes.
258pub fn write(programs: &[Program]) -> Vec<u8> {
259    let directory: Vec<_> = programs.iter().map(DirectoryEntry::top_level).collect();
260    encode_module(programs, &directory, &[], &unrecorded(programs))
261}
262
263/// A module with the caller's directory and mapsets and no files recorded, refused (as the reader
264/// would) if either, or a program, is invalid.
265pub fn write_with(programs: &[Program], directory: &[DirectoryEntry], mapsets: &[Mapset]) -> Result<Vec<u8>, ModuleError> {
266    let files = unrecorded(programs);
267    write_module(&LoadedModule { directory: directory.to_vec(), programs: programs.to_vec(), mapsets: mapsets.to_vec(), files })
268}
269
270/// The module `module` describes, refused (as the reader would) if its directory, mapsets, a
271/// program or a program's files are invalid.
272pub fn write_module(module: &LoadedModule) -> Result<Vec<u8>, ModuleError> {
273    let LoadedModule { directory, programs, mapsets, files } = module;
274    check_directory(directory, programs)?;
275    for program in programs {
276        crate::lir::program_valid(program).map_err(|reason| bad("LIR", reason))?;
277    }
278    check_mapsets(mapsets).map_err(|reason| bad(Section::BMS.name, reason))?;
279    check_files(files, programs).map_err(|reason| bad(Section::DEBUG.name, reason))?;
280    Ok(encode_module(programs, directory, mapsets, files))
281}
282
283/// One file, or none, for each source of each program's debug table.
284fn check_files(files: &[Vec<Option<SourceFile>>], programs: &[Program]) -> Result<(), String> {
285    if files.len() != programs.len() {
286        return Err(format!("files for {} programs of {}", files.len(), programs.len()));
287    }
288    for (ordinal, (files, program)) in files.iter().zip(programs).enumerate() {
289        if files.len() != program.debug.sources.len() {
290            return Err(format!("program {ordinal} records {} files for {} sources", files.len(), program.debug.sources.len()));
291        }
292        files.iter().flatten().try_for_each(source_file_valid)?;
293    }
294    Ok(())
295}
296
297/// Mapsets are held once each, in ascending order of name (load-module.md §5.3).
298fn check_mapsets(mapsets: &[Mapset]) -> Result<(), String> {
299    match mapsets.windows(2).find(|pair| pair[0].name >= pair[1].name) {
300        Some(pair) => Err(format!("mapset {} follows mapset {}", pair[1].name, pair[0].name)),
301        None => Ok(()),
302    }
303}
304
305fn bad(section: &'static str, reason: impl Into<String>) -> ModuleError {
306    ModuleError::Malformed { section, offset: 0, reason: reason.into() }
307}
308
309fn check_directory(directory: &[DirectoryEntry], programs: &[Program]) -> Result<(), ModuleError> {
310    let name = Section::DIRECTORY.name;
311    if directory.len() != programs.len() {
312        return Err(bad(name, format!("{} entries for {} programs", directory.len(), programs.len())));
313    }
314    for (ordinal, (entry, program)) in directory.iter().zip(programs).enumerate() {
315        let symbol = program.symbols.get(program.id as usize);
316        if symbol != Some(&entry.id) {
317            return Err(bad(name, format!("program {ordinal} is {symbol:?} in its symbols, {:?} in the directory", entry.id)));
318        }
319        if entry.parent.is_some_and(|p| p as usize >= ordinal) {
320            return Err(bad(name, format!("program {ordinal} has parent {}, which does not precede it", entry.parent.unwrap_or(0))));
321        }
322        if let Some((entry_name, _)) = entry.entries.iter().find(|(_, para)| *para as usize >= program.paragraphs.len()) {
323            return Err(bad(name, format!("program {ordinal} ENTRY {entry_name} names a paragraph it lacks")));
324        }
325    }
326    Ok(())
327}
328
329/// A section of a count and that many records, the count being the directory's.
330fn records<T: Decode>(module: &Module<'_>, strings: &StringTable, section: Section, expected: usize) -> Result<Vec<T>, ModuleError> {
331    let mut r = module.reader(section, strings)?;
332    let at = r.position();
333    let count = r.count()?;
334    if count != expected {
335        return Err(r.malformed(at, format!("{count} records for {expected} programs")));
336    }
337    let mut out = Vec::with_capacity(count);
338    for _ in 0..count {
339        out.push(T::decode(&mut r)?);
340    }
341    r.finish()?;
342    Ok(out)
343}
344
345/// Reads and checks a module; the bytes of every section are checksummed.
346pub fn read(bytes: &[u8]) -> Result<LoadedModule, ModuleError> {
347    let module = Module::read(bytes)?;
348    let strings = module.strings()?;
349    let mut r = module.reader(Section::DIRECTORY, &strings)?;
350    let directory = Vec::<DirectoryEntry>::decode(&mut r)?;
351    r.finish()?;
352    let count = directory.len();
353
354    let options = records::<ProgramOptions>(&module, &strings, Section::OPTIONS, count)?;
355    let layouts = records::<LayoutRecord>(&module, &strings, Section::LAYOUT, count)?;
356    let bodies = records::<LirRecord>(&module, &strings, Section::LIR, count)?;
357    let sql = records::<Vec<SqlEntry>>(&module, &strings, Section::SQL, count)?;
358    let (debug, files): (Vec<Debug>, Vec<Vec<Option<SourceFile>>>) = records::<(Debug, Vec<Option<SourceFile>>)>(&module, &strings, Section::DEBUG, count)?.into_iter().unzip();
359
360    let mut r = module.reader(Section::BMS, &strings)?;
361    let mapsets = Vec::<Mapset>::decode(&mut r)?;
362    r.finish()?;
363    check_mapsets(&mapsets).map_err(|reason| bad(Section::BMS.name, reason))?;
364
365    let parts = options.into_iter().zip(layouts).zip(bodies).zip(sql).zip(debug);
366    let mut programs = Vec::with_capacity(count);
367    for ((((options, (storage, items, edits)), body), sql), debug) in parts {
368        let LirRecord {
369            id, initial, recursive, paragraphs, procedure_start, ranges, blocks, places, exprs, conds, consts, plans,
370            services, abends, symbols,
371        } = body;
372        let program = Program {
373            id, options, initial, recursive, storage, items, paragraphs, procedure_start, ranges, blocks, places, exprs,
374            conds, consts, plans, services, sql, abends, edits, symbols, debug,
375        };
376        crate::lir::program_valid(&program).map_err(|reason| bad(Section::SQL.name, reason))?;
377        programs.push(program);
378    }
379    check_directory(&directory, &programs)?;
380    check_files(&files, &programs).map_err(|reason| bad(Section::DEBUG.name, reason))?;
381    Ok(LoadedModule { directory, programs, mapsets, files })
382}
ironwork_rt/module/programs.rs

ironwork_rt/module/
programs.rs
