SCRYMAMEReferenceCommentscomment_writeAlso in DOSBox-X
comment_write
Change the saved comments: add or delete one, or save them all to a file and load them back.
comment_write(method, ref="", text="", cpu="", dest="", path="")
Try it
count_coin.Leave a note on the coin routine: a coin increments the credits, then the BCD copy.
comment_write(method="add", ref="count_coin", text="a coin: INC credits, then the BCD copy"){
"summary": "comment_write add: count_coin at :maincpu 0x0000b583, stored, persistent",
"status": "ok",
"replaced_comments": [],
"cpu": ":maincpu"
}The comment is saved on count_coin, which is 0xb583 on the main cpu, in a file that outlasts the session. Nothing was there before, so replaced_comments is empty.
The whole reply
{
"summary": "comment_write add: count_coin at :maincpu 0x0000b583, stored, persistent",
"status": "ok",
"comment": {
"ref": "count_coin",
"by": "symbol",
"cpu": ":maincpu",
"created_at": "<volatile>",
"origin": "<volatile>",
"inherited": false,
"age_s": "<volatile>",
"text": "a coin: INC credits, then the BCD copy",
"addr": "0x0000b583",
"state": "armed"
},
"replaced_comments": [],
"declarations": {"persistent": true, "path": "./tmp/demos/tour/gridlee-states/declarations.json"},
"cpu": ":maincpu"
}The four methods
| method | what it does |
|---|---|
add |
Puts text on ref. A comment already there is replaced. |
delete |
Removes the comment at ref. |
save |
Writes every comment to the file dest. |
load |
Reads the comment file at path into the saved comments, all or nothing. |
Arguments
- method one of
"add","delete","save","load", required add,delete,saveorload, as above.- ref string, default
"" - For
addanddelete: a symbol or a0xaddress. - text string, default
"" - For
add: one printable line, at most 237 UTF-8 bytes. - cpu string, default
"" - For
addanddelete: the cpu whose code is commented. Left empty, the one the debugger is showing. - dest string, default
"" - For
save: the file to write, an absolute or~-led path. A comment file already there is replaced; any other file is refused. - path string, default
"" - For
load: the comment file to read, an absolute path.
What comes back
- comment
add: the comment as saved, a row ascomment_listgives it.- replaced_comments
addandload: the comments whose text was replaced, as they were.- deleted
delete: the comment removed.- dropped_comments
save: comments only the replaced file held, each byrefandcpu. They are gone from the file.- added
load: how many comments are new.unchangedcounts those already saved with the same text,parsedthe rows read.- held_in_memory
truewhen the saved breakpoints file could not be written: the change lasts untilclose.
All 15 reply fields
added(integer)comment(object)comments_total(integer)declarations(object)deleted(object)dropped_comments(array)dropped_total(integer)parsed(integer)path(string)replaced_comments(array)replaced_total(integer)truncated(boolean)unchanged(integer)cpu(string)held_in_memory(boolean)
What it refuses
- An argument the method does not take (
bad_argument). add,deleteorloadwhile the program runs (not_stopped).- A
refthat is a pointer, an expression or aseg:off, or atextthat is empty, too long or not one printable line (bad_argument). - Bare hex that names no symbol, or a
deletewhoserefmatches no comment (unknown_ref). - A
destthat is the saved breakpoints file itself, a link, or a file that is not a comment file (bad_argument). - A
loadfile with a bad row or a cpu the machine lacks: nothing is loaded (bad_argument). - A saved breakpoints file that cannot be written: the change is kept in memory (
host_failed).
Why it works this way
The change is saved first, and MAME's disassembly is fed after. If the session breaks in between, the message says so, and the next start feeds the saved comments again.
One address shows one comment. An add where one exists replaces its text and keeps its ref, so a comment made by symbol keeps following its symbol.
save and load are how a project keeps its comments under version control beside its symbol file. load is all or nothing, and the file wins where both comment an address.
More on why
-
A comment's
stateisarmedonce MAME's disassembly shows it.unresolvednames a symbol this build lacks: the comment stays saved and is shown once a build has it. -
The file has no build column, so a raw address loaded into another build is trusted. Comment by symbol what must survive a rebuild.
-
A rebuild can bring several comments to one address. An
add,deleteorloadthere reaches the one whoserefit spells, else the one MAME's disassembly shows. -
A
stalecomment made the other way, by symbol where yours is by address or the reverse, is reached only by its own spelling. -
save'sdestis in a folder that exists, and its path holds no comma, semicolon, quote, space, bracket or control character. -
MAME's console cannot carry a text holding
"or ending in\: it is saved and readsunarmable. If it replaces one that was shown, the old text is cleared. -
A
deleteover instruction bytes that changed since leaves MAME holding the old text, hidden, untilclose. -
A file with two comments a rebuild put at one address loads both, so what
savewrites of them reads back. -
MAME writes its own comment files into a folder inside the session's temporary folder, so nothing deleted here comes back from them.
-
comments_total,dropped_totalandreplaced_totalcount the whole lists;truncatedsays a list was cut.declarationsnames the saved breakpoints file, as incomment_list. -
The file
savewrites is UTF-8 with no byte order mark, and its lines end in LF. -
Line 1 is exactly
# comments v1: ref<TAB>cpu<TAB>created_at<TAB>text, and each row after it holds those four columns. -
Rows are sorted by cpu, then by ref, so a diff shows only what changed.
-
cpuis the cpu's absolute tag, andcreated_atreadsYYYY-MM-DDTHH:MM:SS+00:00.
Related tools
The contract your client receives
Change the store's comments.
`add`: `text` (one printable line, at most 237 UTF-8 bytes) on `ref`,
a symbol or a linear `0x` address, of `cpu` (default the visible one); a second there
replaces it.
Reply: `comment`, `replaced_comments`, `declarations`, `cpu`, `note`.
`delete`: the comment at `ref`. Reply: `deleted`, `declarations`, `cpu`, `note`.
`save`: every comment to `dest`, an absolute or `~`-led path, replacing a comment file
there (rows only it held in `dropped_comments`); any other file is refused; answers on a
running machine. Reply: `path`, `comments_total`, `dropped_comments`, `dropped_total`,
`truncated`, `note`.
`load`: the comment file at `path`, all or nothing, the file winning. Reply: `path`,
`parsed`, `added`, `replaced_comments`, `replaced_total`, `truncated`, `unchanged`,
`comments_total`, `declarations`, `note`.
`add`, `delete` and `load` need the machine stopped. Refused: an argument the method
does not take, a misshapen `ref` or `text`, an unknown `ref` (`unknown_ref`), a `save`
`dest` that is the declaration store's file (compared without regard to case, on any
volume), an unwritable store (`host_failed`, `held_in_memory`).
Reference: REFERENCE.md, Breakpoints and watches.