helper/command: Handle Tcl return values consistently 15/1815/7
authorPaul Fertser <fercerpav@gmail.com>
Thu, 4 Apr 2019 07:54:09 +0000 (09:54 +0200)
committerTomas Vanek <vanekt@fbl.cz>
Tue, 14 May 2019 18:38:22 +0000 (19:38 +0100)
commit7f260f5009a774f2d66b5f3037f8f595c6881d4d
treef32d57bd609570ad2c1f09d48b0dce937918e4b3
parent2caa3455ada686baea01a50d092e4244c461e101
helper/command: Handle Tcl return values consistently

Rationale:

1. There's logging output and there're return values;

2. If a function should return something, it should do it explicitly,
same for logging;

3. Interactive interfaces (telnet, Gdb and Tcl RPC) must always return
the result of the evaluation for the given expression. You can
suppress this output by adding ``; after 0'' to the end of your
expression.

4. Some commands "throw an exception" and if you want to be able to
collect both the return value (when it succeeds) and the log output
(when something goes wrong) you can use do like this:

set log_output [capture "catch {reset_config} return_value"]

So what I'm proposing is following:

1. Every jim_handler command should set the return value the standard
JimTcl way, without any tricks. If it needs to print some logging
output, it should use LOG_* functions.

2. The usual commands (COMMANDS) can easily construct their return
value by appending strings with command_print() and
command_print_sameline(). This required changing "struct
command_invocation" and passing a pointer to it to command_print*
functions.

The code is already functional, please test and comment.

TODO items:

1. Modify all jim_handler commands to properly return or log values
(some of them are commented out for now in this patch).

2. Properly document "capture" command and provide a convenience
function to automate log_output + return_value gathering.

3. Add appropriate Doxygen comments.

4. Add Tcl RPC interface description to the manual, all the example
clients in different languages (from the mailing list) to contrib/.

This change is the core part of http://openocd.zylin.com/1815 from
Paul Fertser. It has been extracted and rebased to simplify the
review and provided again as 1815.

Change-Id: I675c91aa9da1e4e7c6f0a8fe6112a00550b9e4db
Signed-off-by: Paul Fertser <fercerpav@gmail.com>
Signed-off-by: Tomas Vanek <vanekt@fbl.cz>
Signed-off-by: Antonio Borneo <borneo.antonio@gmail.com>
Reviewed-on: http://openocd.zylin.com/1815
Tested-by: jenkins
src/helper/command.c
src/helper/command.h