saturnus-objects 0.4.0

HP 48/49 RPL objects for saturnus hosts: the exact object decoder and a read-only view of a paused machine's user memory (directories, stack, flags)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

# saturnus-objects

HP 48 and HP 49 RPL objects for hosts of the
[saturnus](https://github.com/ractive/saturnus) emulator core
([`saturnus-core`](https://crates.io/crates/saturnus-core)), with no I/O or
protocol stack: like the core it builds for `wasm32-unknown-unknown`.

- `object`: the typed object model (`Object`, JSON through serde) and an
  exact decoder of the calculator's nibble format.
- `ram`: a read-only view of a paused machine's user memory, straight
  from RAM (no Kermit server, nothing written): the HOME tree with each
  variable's type, size and checksum as `BYTES` reports them, the current
  directory, the data stack and the flags, plus a change counter for
  cheap polling. HP 48SX, 48GX and 49G.
- `names`: command names read at run time from the loaded ROM's own
  library tables.
- `decompile`: the calculator's text for programs, algebraics, units and
  data objects, in the display mode the flags select.
- `menus`: the ROM's built-in menus.
- `transfer`: the objects of Kermit transfers: binary transfer files
  (`HPHP48-x`, `HPHP49-x`) decoded and encoded, the text of programs and
  algebraics from the ASCII transfer of the same object, RPL source text
  for a host command. The Kermit exchange itself is the host's (for
  example [`kermit-proto`](https://crates.io/crates/kermit-proto)).
- `charset`: the HP character set as Unicode, and the ASCII trigraphs
  (`\->`) of host commands.

## Usage

```rust,no_run
use saturnus_core::{Machine, Model};
use saturnus_objects::{Settings, display, memory_tree, stack_objects};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let rom = std::fs::read("gxrom-r")?;
    let mut m = Machine::new(Model::Hp48gx, &rom)?;
    m.run_cycles(8_000_000).map_err(|h| format!("halted: {h:?}"))?;

    for var in memory_tree(&m)? {
        println!("{} ({}, {} bytes)", var.name, var.kind, var.size);
    }
    for (level, obj) in stack_objects(&m)?.iter().enumerate() {
        println!("{}: {}", level + 1, display(obj, &Settings::default()));
    }
    Ok(())
}
```

No ROM is included; see the
[saturnus repository](https://github.com/ractive/saturnus) for where to
get one legitimately.

## Licence

MIT. Parts of the code were generated by AI systems under human
supervision; see the repository's `AI_NOTICE`.