SCRYDOSBox-XReferenceCommentscomment_writeAlso in MAME
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="", dest="", path="")
Try it
bricks.sym loaded, which names the routine brick_hit.Ask
Leave a note on the routine that removes a brick: AL is the row, BL the column.
Call
comment_write(method="add", ref="brick_hit", text="AL = row, BL = column of the brick that falls")Reply 3 of 5 fields
{
"summary": "comment_write add: brick_hit at 0x000090b8, stored",
"status": "ok",
"replaced_comments": []
}The comment is saved on brick_hit, which is the linear address 0x90b8. Nothing was there before, so replaced_comments is empty.
The whole reply
JSON
{
"summary": "comment_write add: brick_hit at 0x000090b8, stored",
"status": "ok",
"comment": {
"ref": "brick_hit",
"by": "symbol",
"cpu": {"available": false, "why": "a DOS machine has one cpu, and every row acts on it"},
"created_at": "<volatile>",
"origin": "<volatile>",
"inherited": false,
"age_s": "<volatile>",
"text": "AL = row, BL = column of the brick that falls",
"addr": "0x000090b8",
"state": "resolved"
},
"replaced_comments": [],
"declarations": {"persistent": true, "path": "<volatile>"}
}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 aSEG:OFF. - text string, default
"" - For
add: one printable line, at most 237 UTF-8 bytes. - 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 byref. They are gone from the file.- added
load: how many comments are new.unchangedcounts those already saved with the same text,parsedthe rows read.
All 13 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)
What it refuses
- An argument the method does not take (
bad_argument). add,deleteorloadwhile the program runs (not_stopped).- A
refthat is a pointer or adds an offset, or atextthat is empty, too long or not one printable line (bad_argument). - A name the symbol table defines twice (
ambiguous_ref). - 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
savewhile two comments sit on one address: delete one first (bad_argument). - A saved breakpoints file that cannot be written: nothing changes (
host_failed).
Why it works this way
One address shows one comment, however it is spelled: start, 0824:000B and 0814:010B can name one byte. An add where a comment exists replaces its text.
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 sets nothing in the debugger, so it never stops the program.
- A symbol the loaded symbol table lacks is saved
unresolved, and resolves once a table has it. - A raw
SEG:OFFcomment isstalewhile the build it was written over is not the one loaded, as a raw breakpoint is. - Comments a rebuild or a
loadbrought to one address are all kept. A call reaches the one whoserefit spells. - The file's
cpucolumn is written empty, since a DOS machine has one processor. A file that fills it is refused. - The file has no build column: a raw address is trusted for the build it is loaded into.
- A file saved before
symbols_load, or while the program runs, can hold two rows that a later stop resolves to one byte. - A
loadkeeps both such rows and names them innote. Asaverefuses them until one is deleted. - A
loadthat gives astaleraw comment the text it already holds adopts it into this session and build. - A row a
loadcannot resolve at this stop is keptunarmable, itswhynaming the stop it waits for. Anaddrefuses such an address. comments_total,dropped_totalandreplaced_totalcount the whole lists;truncatedsays a list was cut.declarationsnames the saved breakpoints file, as incomment_list.
Related tools
The contract your client receives
Text
Change this conf's comments.
`add`: `text` (one printable line, at most 237 UTF-8 bytes) on `ref`,
a symbol or a `SEG:OFF`; a second there replaces it. Reply: `comment`, `replaced_comments`,
`declarations`, `note`.
`delete`: the comment `ref` names. Reply: `deleted`, `declarations`, `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`, a `save` `dest` that is the declaration store's
file, compared without regard to case on any volume (`bad_argument`), a name defined twice
(`ambiguous_ref`), an unknown `ref` (`unknown_ref`), an unwritable store (`host_failed`).
Reference: REFERENCE.md, Breakpoints and watches.