[Docs] [Qt] RPC-Console nested commands documentation #11698

lmlsna commented at 10:07 PM on November 15, 2017: contributor

This PR would close issue #9195 by adding documentation for the debug console features (mainly nested commands) which were added in PR [#7783](/bitcoin-bitcoin/7783/).

The following changes were made to QT debug console code:

Added a line to the initial message text at the top of the debug console:

For more information on using this console type help-console.

Added a pseudo-command help-console which is hooked after parsing the request, but before actually executing the RPC thread. It prints the following text to the console as if it were a valid RPC response.

This console accepts RPC commands using the standard syntax. example: getblockhash 8 This console can also accept RPC commands using bracketed syntax. example: getblockhash(8) A space or a comma can be used to separate arguments for either syntax. example: sendtoaddress <address> <amount> sendtoaddress,<address>,<amount> Commands may be nested when specified with the bracketed syntax. example: getblockinfo(getblockhash(0),true). Result values can be queried with a non-quoted string in brackets. example: getblock(getblockhash(0) true)[height]

This seemed like a reasonably sane way to introduce a fake RPC help command, but

fanquake added the label GUI on Nov 15, 2017

fanquake added the label Docs and Output on Nov 15, 2017

in src/qt/rpcconsole.cpp:414 in 7ce45b8247 outdated

 409 | +
 410 | +                "Commands may be nested when specified with the bracketed syntax.\n"
 411 | +                "   example:    getblockinfo(getblockhash(0),true).\n\n"
 412 | +
 413 | +                "Result values can be queried with a non-quoted string in brackets.\n"
 414 | +                "   example:    getblock(getblockhash(0) true)[height]\n\n" )));

jonasschnelli commented at 6:30 AM on November 16, 2017:

maybe add an example that uses access-by-index like getblock(getblockhash(0) true)[tx][0]?

lmlsna commented at 6:48 AM on November 16, 2017:

Agreed, should have included that.

laanwj commented at 3:43 PM on November 16, 2017:

Here the use of "bracket" is correct, referring to the [].

jonasschnelli commented at 6:43 AM on November 16, 2017: contributor

Works as intended. I think it's not prominent enough,... maybe an icon (unsure) or a clickable text (link) in the console text would make more sense. At least it should auto-complete help-console when typing in the prompt line.

lmlsna commented at 7:25 AM on November 16, 2017: contributor

I figured that it made sense (at least thematically 😅) for console help to be available from the inside the console, but that's basically just my personal preference. I'm guessing the subset of users interested in nested rpc commands are probably more command-line-centric that then the average user. Though a clickable link in the first bit of text might well be a better/cleaner solution.

If kept as a command, I for sure think it should be added to the autocomplete list. I can add that in as well, I just didn't want to go overboard before getting some feedback.

If implemented as a button/link, what should it reference/do? Pop a new window with text (like help > commands) in the file menu?

laanwj commented at 2:48 PM on November 16, 2017: member

Thanks for doing this! will test.

laanwj commented at 3:39 PM on November 16, 2017: member

I figured that it made sense (at least thematically 😅) for console help to be available from the inside the console,

Agree, I kind of like it as a command. An icon could be added later, but this is what I had in mind. Only have a few comments on the text.

in src/qt/rpcconsole.cpp:403 in 7ce45b8247 outdated

 398 | +        {
 399 | +            Q_EMIT reply(RPCConsole::CMD_REPLY, QString(("\n"
 400 | +                "This console accepts RPC commands using the standard syntax.\n"
 401 | +                "   example:    getblockhash 8\n\n"
 402 | +
 403 | +                "This console can also accept RPC commands using bracketed syntax.\n"

laanwj commented at 3:40 PM on November 16, 2017:

This is parenthesized not bracketed syntax, I'd say?

in src/qt/rpcconsole.cpp:406 in 7ce45b8247 outdated

 401 | +                "   example:    getblockhash 8\n\n"
 402 | +
 403 | +                "This console can also accept RPC commands using bracketed syntax.\n"
 404 | +                "   example:    getblockhash(8)\n\n"
 405 | +
 406 | +                "A space or a comma can be used to separate arguments for either syntax.\n"

laanwj commented at 3:42 PM on November 16, 2017:

Maybe "delimit" instead of "separate"?

in src/qt/rpcconsole.cpp:775 in 7ce45b8247 outdated

 768 | @@ -747,10 +769,12 @@ void RPCConsole::clear(bool clearHistory)
 769 |  #else
 770 |      QString clsKey = "Ctrl-L";
 771 |  #endif
 772 | -	 
 773 | +
 774 |      message(CMD_REPLY, (tr("Welcome to the %1 RPC console.").arg(tr(PACKAGE_NAME)) + "<br>" +
 775 |                          tr("Use up and down arrows to navigate history, and %1 to clear screen.").arg("<b>"+clsKey+"</b>") + "<br>" +
 776 | -                        tr("Type <b>help</b> for an overview of available commands.")) +
 777 | +                        tr("Type <b>help</b> for an overview of available commands.<br>") +

laanwj commented at 3:43 PM on November 16, 2017:

Please keep the <br> out of the translation message, as it frequently gets lost by translators.

lmlsna commented at 4:21 PM on November 16, 2017:

I totally agree with all of this.

laanwj changes_requested

lmlsna commented at 4:17 PM on November 16, 2017: contributor

I have the autocomplete working and will make the suggested changes to the help text. I'll push a revision today or tomorrow. Thanks for the input guys!

jonasschnelli commented at 6:39 PM on November 17, 2017: contributor

Thanks! Looks good! utACK after squash.

lmlsna force-pushed on Nov 17, 2017

lmlsna commented at 7:00 PM on November 17, 2017: contributor

squished

promag commented at 7:14 PM on November 17, 2017: member

utACK 5305dda.

jonasschnelli commented at 8:08 PM on November 17, 2017: contributor

utACK 5305dda4c3f2d0b9d6a1bf9d5c4cc1c6215ed475

in src/qt/rpcconsole.cpp:416 in 5305dda4c3 outdated

 411 | +                "               getblockhash,0\n\n"
 412 | +
 413 | +                "Named result objects can be queried with a non-quoted key string.\n"
 414 | +                "   example:    getblock(getblockhash(0) true)[tx]\n\n"
 415 | +
 416 | +                "Numeric result objects can be queried with an index integer in brackets.\n"

meshcollider commented at 3:23 AM on November 18, 2017:

I'm not too sure about calling them "numeric result objects", numeric just sounds like it's a type of number, rather than an unnamed list/array or something

lmlsna commented at 4:03 AM on November 18, 2017:

Yeah, good point. You think changing those last 2 lines to just "Results can be queried with..." is better?

lmlsna commented at 4:07 AM on November 18, 2017:

I'll change that last bit and resquash with a better commit message.

meshcollider commented at 3:25 AM on November 18, 2017: contributor

utACK https://github.com/bitcoin/bitcoin/commit/5305dda4c3f2d0b9d6a1bf9d5c4cc1c6215ed475

Commit message needs modification though, perhaps "Add help-console command to Qt debug console" or something

lmlsna force-pushed on Nov 18, 2017

Add help-console command to Qt debug console

     - Added `help-console` to the list of autocompletion strings
     - Implemented requested changes to help message:
       - Added an example that uses access-by-index `getblock(getblockhash(0) true)[tx][0]`
       - Replace "bracketed syntax" to "parenthesized syntax" where applicable
       - Replace "separate" with "delimit"
       - Removed `<br>` and `<b>help/help-console</b>` from translation strings, since these parts don't change between languages
       - Changed examples to be based off `getblock 0` so they will work even with pruned/no blockchain and `disablewallet` if copied and pasted
       - Clarified syntax for queries of named/unnamed result objects.

c3055bbea1

lmlsna force-pushed on Nov 18, 2017

meshcollider commented at 7:50 AM on November 18, 2017: contributor

re-utACK https://github.com/bitcoin/bitcoin/pull/11698/commits/c3055bbea1255cd791564b855b6951a9f4c510f9

laanwj approved

laanwj merged this on Nov 19, 2017

laanwj closed this on Nov 19, 2017

laanwj referenced this in commit 7293d06413 on Nov 19, 2017

in src/qt/rpcconsole.cpp:397 in c3055bbea1

 391 | @@ -392,11 +392,37 @@ void RPCExecutor::request(const QString &command)
 392 |      {
 393 |          std::string result;
 394 |          std::string executableCommand = command.toStdString() + "\n";
 395 | +
 396 | +        // Catch the console-only-help command before RPC call is executed and reply with help text as-if a RPC reply.
 397 | +        if(executableCommand == "help-console\n")

MarcoFalke commented at 4:08 PM on November 27, 2017:

nit: Should use .starts_with("help-console") to ignore trailing white space. Though, can wait, since that seems to be part of cpp20

Edit: Could use QString::fromStdString(executableCommand).startsWith("help-console")

MarcoFalke commented at 4:10 PM on November 27, 2017: member

post merge ACK c3055bbea1255cd791564b855b6951a9f4c510f9

PastaPastaPasta referenced this in commit 7ffbf8143d on Jan 17, 2020

PastaPastaPasta referenced this in commit 29ec248a03 on Jan 22, 2020

PastaPastaPasta referenced this in commit 9733330f78 on Jan 22, 2020

PastaPastaPasta referenced this in commit 97adc728da on Jan 29, 2020

PastaPastaPasta referenced this in commit 8977118599 on Jan 29, 2020

PastaPastaPasta referenced this in commit c7b8b2b35c on Jan 29, 2020

ckti referenced this in commit 953ed59806 on Mar 28, 2021

random-zebra referenced this in commit eeb1632b05 on May 11, 2021

MarcoFalke locked this on Sep 8, 2021