archive/php-src
1
0
Fork 0
mirror of https://github.com/php/php-src.git synced 2025-08-20 17:34:35 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Update help content and refactor new routine in php_help.c

Browse source 
*  I've added more content to the help to expand desciption for new-to-phpdbg
   developers.

*  After a code review of the new routines that I've added to the help module,
   I've decided that the implementation was unnecessarily convolved and that
   Keep-It-Simple-Stupid would be more understandable, maintainable and have
   no material performance hit.
This commit is contained in:
Terry Ellison 2014-02-05 00:04:21 +00:00
parent 88bd558a73
commit ebdfef807a
3 changed files with 243 additions and 217 deletions
Download patch file Download diff file Expand all files Collapse all files

328
phpdbg_help.c
View file

@ -22,12 +22,6 @@
#include "phpdbg.h"
#include "phpdbg_help.h"
#include "phpdbg_prompt.h"
#include "phpdbg_print.h"
#include "phpdbg_utils.h"
#include "phpdbg_break.h"
#include "phpdbg_list.h"
#include "phpdbg_info.h"
#include "phpdbg_set.h"
#include "zend.h"
ZEND_EXTERN_MODULE_GLOBALS(phpdbg);
@ -45,8 +39,9 @@ const phpdbg_command_t phpdbg_help_commands[] = {
PHPDBG_END_COMMAND
}; /* }}} */
/* {{{ pretty_format. Takes a text string, expands any formatting escapes and wrap the text */
static char *pretty_format(char *text TSRMLS_DC) {
/* {{{ pretty_print. Formatting escapes and wrapping text in a string before printing it. */
void pretty_print(char *text TSRMLS_DC)
{
char *new, *p, *q;
const char *prompt_escape = phpdbg_get_prompt(TSRMLS_C);
@ -135,120 +130,122 @@ static char *pretty_format(char *text TSRMLS_DC) {
if ((q-new)>size) {
phpdbg_error("Output overrun of %lu bytes", ((q-new) - size));
}
return new;
(void) phpdbg_write("%s\n", new);
efree(new);
} /* }}} */
/* {{{ summary_print. Print a summary line giving, the command, its alias and tip */
void summary_print(phpdbg_command_t const * const cmd TSRMLS_DC)
{
char *summary;
spprintf(&summary, 0, "Command: **%s** Alias: **%c** **%s**\n",
cmd->name, cmd->alias, cmd->tip);
pretty_print(summary TSRMLS_CC);
efree(summary);
}
/* {{{ get_help. Retries and formats text from the phpdbg help text table */
static char *get_help(const char * const key TSRMLS_DC) {
phpdbg_help_text_t *p = phpdbg_help_text;
static char *get_help(const char * const key TSRMLS_DC)
{
phpdbg_help_text_t *p;
/* note that phpdbg_help_text is collated in key order */
for( ;p->key[0]<key[0]; p++ ) {} /* skip to matching first char */
/* Note that phpdbg_help_text is not assumed to be collated in key order. This is an
inconvience that means that help can't be logically grouped Not worth
the savings */
while (p->key[0]==key[0]) {
if (!strcmp(p->key+1, key+1)) {
for (p = phpdbg_help_text; p->key; p++) {
if (!strcmp(p->key, key)) {
return p->text;
}
p++;
}
return estrdup(""); /* return empty string to denote no match found */
return ""; /* return empty string to denote no match found */
} /* }}} */
/* {{{ get_command. Return one or more matching commands from a command table.
/* {{{ get_command. Return number of matching commands from a command table.
* Unlike the command parser, the help search is sloppy that is partial matches can occur
* * Any single character key is taken as an alias and only an exact match is allowed
* * Any single character key is taken as an alias.
* * Other keys are matched again the table on the first len characters.
* * This means that non-unique keys can generate multiple matches
* * The command summary is an emalloced string containing one line for each match
* * The function only returns a command entry if a unique match occurs.
*
* The rationale here is to assist users in finding help on commands. So "h fr" will
* generate a summary line for "help frame" and return the frame record. But "h cl" will
* generate two summary records for the "clear" and "clean" and a NULL command record.
* * This means that non-unique keys can generate multiple matches.
* * The first matching command is returned as an OUT parameter. *
* The rationale here is to assist users in finding help on commands. So unique matches
* will be used to generate a help message but non-unique one will be used to list alternatives.
*/
#define ALIAS_FMT "Command: **%s** Alias: **%c** **%s**\n"
static const phpdbg_command_t *get_command(
static int get_command(
const char *key, size_t len, /* pointer and length of key */
char **command_summary, /* address of command summary text */
const phpdbg_command_t * const commands /* command table to be scanned */
TSRMLS_DC) {
const phpdbg_command_t *c, *c_found;
phpdbg_command_t const **command, /* address of first matching command */
phpdbg_command_t const * const commands /* command table to be scanned */
TSRMLS_DC)
{
const phpdbg_command_t *c;
unsigned int num_matches = 0;
char *summary;
if (len == 1) {
for (c=commands; c->name; c++) {
if (c->alias == key[0]) {
num_matches++;
if (command_summary) {
spprintf(&summary, 0, ALIAS_FMT, c->name, c->alias, c->tip);
if ( num_matches == 1 && command) {
*command = c;
}
c_found = c;
break;
}
}
} else {
for (c=commands; c->name; c++) {
if (!strncmp(c->name, key, len)) {
++num_matches;
c_found = c;
if (command_summary) {
if (num_matches == 1) {
spprintf(&summary, 0, ALIAS_FMT, c->name, c->alias, c->tip);
} else { /* num_matches > 1 */
/* very rare so "keep it simple" string concat of summaries */
char *tmp = summary;
spprintf(&summary, 0, "%s" ALIAS_FMT, tmp, c->name, c->alias, c->tip);
efree(tmp);
}
if ( num_matches == 1 && command) {
*command = c;
}
}
}
}
if (command_summary) {
*command_summary = (num_matches > 0) ? summary : NULL;
}
return (num_matches == 1) ? c_found : NULL; /* NULL return denotes no single match found */
return num_matches;
} /* }}} */
PHPDBG_COMMAND(help) /* {{{ */
{
char *banner, *help_text, *pretty_banner, *pretty_help_text;
const phpdbg_command_t *cmd;
phpdbg_command_t const *cmd;
int n;
if (param->type == EMPTY_PARAM) {
char * help_text = pretty_format(get_help("_overview" TSRMLS_CC) TSRMLS_CC);
phpdbg_write("\n%s\n", help_text);
efree(help_text);
pretty_print(get_help("overview!" TSRMLS_CC) TSRMLS_CC);
return SUCCESS;
}
if (param->type == STR_PARAM) {
cmd = get_command( param->str, param->len, &banner, phpdbg_prompt_commands TSRMLS_CC);
n = get_command( param->str, param->len, &cmd, phpdbg_prompt_commands TSRMLS_CC);
if (banner) {
pretty_banner = pretty_format(banner TSRMLS_CC);
help_text = get_help((cmd ? cmd->name : "_ZZ_duplicate") TSRMLS_CC);
pretty_help_text = pretty_format(help_text TSRMLS_CC);
phpdbg_write("%s\n%s\n", pretty_banner, pretty_help_text);
efree(banner);
efree(pretty_banner);
efree(pretty_help_text);
if (n==1) {
summary_print(cmd TSRMLS_CC);
pretty_print(get_help(cmd->name TSRMLS_CC) TSRMLS_CC);
return SUCCESS;
} else if (param->type == STR_PARAM) {
cmd = get_command( param->str, param->len, NULL, phpdbg_help_commands TSRMLS_CC);
if (cmd) {
char *name;
spprintf(&name, cmd->name_len+2, "_%s", cmd->name);
help_text = get_help(name TSRMLS_CC);
pretty_help_text = pretty_format(help_text TSRMLS_CC);
phpdbg_write("%s\n", pretty_help_text);
efree(pretty_help_text);
efree(name);
} else if (n>1) {
if (param->len > 1) {
for (cmd=phpdbg_prompt_commands; cmd->name; cmd++) {
if (!strncmp(cmd->name, param->str, param->len)) {
summary_print(cmd TSRMLS_CC);
}
}
pretty_print(get_help("duplicate!" TSRMLS_CC) TSRMLS_CC);
return SUCCESS;
} else {
phpdbg_error("Internal help error, non-unique alias \"%c\"", param->str[0]);
return FAILURE;
}
} else { /* no prompt command found so try help topic */
n = get_command( param->str, param->len, &cmd, phpdbg_help_commands TSRMLS_CC);
if (n>0) {
if (cmd->alias == 'a') { /* help aliases executes a canned routine */
return cmd->handler(param, NULL TSRMLS_CC);
} else {
pretty_print(get_help(cmd->name TSRMLS_CC) TSRMLS_CC);
return SUCCESS;
}
}
}
}
@ -256,13 +253,11 @@ PHPDBG_COMMAND(help) /* {{{ */
phpdbg_error("No help can be found for the subject \"%s\"", param->str);
return FAILURE;
} /* }}} */
PHPDBG_HELP(aliases) /* {{{ */
{
const phpdbg_command_t *c, *c_sub;
char *help_text;
int len;
/* Print out aliases for all commands except help as this one comes last */
@ -278,14 +273,17 @@ PHPDBG_HELP(aliases) /* {{{ */
c->alias, c_sub->alias, c->name, len, c_sub->name, c_sub->tip);
}
}
phpdbg_writeln(EMPTY);
}
}
}
/* Print out aliases for help as this one comes last, with the added text on how aliases are used */
c = get_command( "h", 1, NULL, phpdbg_prompt_commands TSRMLS_CC);
(void) get_command( "h", 1, & c, phpdbg_prompt_commands TSRMLS_CC);
/* In function ‘phpdbg_do_help_aliases’:
274:2: warning: passing argument 3 of ‘get_command’ from incompatible pointer type [enabled by default]
180:12: note: expected ‘struct phpdbg_command_t **’ but argument is of type ‘const struct phpdbg_command_t **’ */
phpdbg_writeln(" %c %-20s %s\n", c->alias, c->name, c->tip);
len = 20 - 1 - c->name_len;
for(c_sub = c->subs; c_sub->alias; c_sub++) {
if (c_sub->alias) {
@ -293,10 +291,8 @@ PHPDBG_HELP(aliases) /* {{{ */
c->alias, c_sub->alias, c->name, len, c_sub->name, c_sub->tip);
}
}
help_text = pretty_format(get_help("_ZZ_aliases" TSRMLS_CC) TSRMLS_CC);
phpdbg_write("\n%s\n", help_text);
efree(help_text);
pretty_print(get_help("aliases!" TSRMLS_CC) TSRMLS_CC);
return SUCCESS;
} /* }}} */
@ -312,10 +308,60 @@ PHPDBG_HELP(aliases) /* {{{ */
* Text will be wrapped according to the STDOUT terminal width, so paragraphs are
* flowed using the C stringizing and the CR definition. Also note that entries
* are collated in alphabetic order on key.
*
* Also note the convention that help text not directly referenceable as a help param
* has a key ending in !
*/
#define CR "\n"
phpdbg_help_text_t phpdbg_help_text[] = {
{"_options",
/******************************** General Help Topics ********************************/
{"overview!", CR
"**phpdbg** is a lightweight, powerful and easy to use debugging platform for PHP5.4+" CR
"It supports the following commands:" CR CR
"**Information**" CR
" **list** list PHP source" CR
" **info** displays information on the debug session" CR
" **help** provide help on a topic" CR
" **print** print argument " CR
" **frame** select a stack frame and print a stack frame summary" CR CR
"**Compilation**" CR
" **compile** compile a PHP source" CR CR
"**Starting and Stopping Execution**" CR
" **exec** set execution context" CR
" **clean** clean the execution environment" CR
" **run** attempt execution" CR
" **eval** evaluate some code" CR
" **step** Enable or disable per opcode stepping mode" CR
" **next** continue execution" CR
" **until** continue execution up to the given location" CR
" **finish** continue up to end of the current execution frame" CR
" **leave** continue up to end of the current execution frame and halt after the calling instruction" CR
" **break** set a breakpoint at the specified target" CR
" **clear** clear one or all breakpoints" CR CR
"**Miscellaneous**" CR
" **quiet** silence some output" CR
" **set** set the phpdbg configuration" CR
" **source** execute a phpdbginit script" CR
" **register** register a phpdbginit function as a command alias" CR
" **shell** shell a command" CR
" **quit** exit phpdbg" CR CR
"Type **help <command>** or (**help alias**) to get detailed help on any of the above commands, "
"for example **help list** or **h l**. Note that help will also match partial commands if unique "
"(and list out options if not unique), so **help clea** will give help on the **clean** command, "
"but **help cl** will list the summary for **clean** and **clear**." CR CR
"Type **help aliases** to show a full alias list, including any registered phpdginit functions" CR
"Type **help syntax** for a general introduction to the command syntax." CR
"Type **help options** for a list of phpdbg command line options." CR
"Type **help phpdbginit** to show how to customise the debugger environment."
},
{"options", CR
"Below are the command line options supported by phpdbg" CR CR
/* note the extra 4 space index in because of the extra **** */
"**Command Line Options and Flags**" CR
@ -351,52 +397,7 @@ phpdbg_help_text_t phpdbg_help_text[] = {
"Specify both stdin and stdout with -lstdin/stdout; by default stdout is stdin * 2."
},
{"_overview",
"**phpdbg** is a lightweight, powerful and easy to use debugging platform for PHP5.4+" CR
"It supports the following commands:" CR CR
"**Information**" CR
" **list** list PHP source" CR
" **info** displays information on the debug session" CR
" **help** provide help on a topic" CR
" **print** print argument " CR
" **frame** select a stack frame and print a stack frame summary" CR CR
"**Compilation**" CR
" **compile** compile a PHP source" CR CR
"**Starting and Stopping Execution**" CR
" **exec** set execution context" CR
" **clean** clean the execution environment" CR
" **run** attempt execution" CR
" **eval** evaluate some code" CR
" **stepping** Enable or disable per opcode stepping mode" CR
" **next** continue execution" CR
" **until** continue execution up to the given location" CR
" **finish** continue up to end of the current execution frame" CR
" **leave** continue up to end of the current execution frame and halt after the calling instruction" CR
" **break** set a breakpoint at the specified target" CR
" **clear** clear one or all breakpoints" CR CR
"**Miscellaneous**" CR
" **quiet** silence some output" CR
" **set** set the phpdbg configuration" CR
" **source** execute a phpdbginit script" CR
" **register** register a phpdbginit function as a command alias" CR
" **shell** shell a command" CR
" **quit** exit phpdbg" CR CR
"Type **help <command>** or (**help alias**) to get detailed help on any of the above commands, "
"for example **help list** or **h l**. Note that help will also match partial commands if unique "
"(and list out options if not unique), so **help clea** will give help on the **clean** command, "
"but **help cl** will list the summary for **clean** and **clear**." CR CR
"Type **help aliases** to show a full alias list, including any registered phpdginit functions" CR
"Type **help syntax** for a general introduction to the command syntax." CR
"Type **help options** for a list of phpdbg command line options." CR
"Type **help phpdbginit** to show how to customise the debugger environment."
},
{"_phpdbginit",
{"phpdbginit", CR
"Phpdgb uses an debugger script file to initialize the debugger context. By default, phpdbg looks "
"for the file named **.phpdbginit** in the current working directory. This location can be "
"overridden on the command line using the **-i** switch (see **help options** for a more "
@ -404,14 +405,21 @@ phpdbg_help_text_t phpdbg_help_text[] = {
"Debugger scripts can also be executed using the **script** command." CR CR
"A script file can contain a sequence of valid debugger commands, comments and embedded PHP code. " "Comment lines are prefixed by the **#** character. PHP code is delimited by the start and end "
"escape tags **<:** and **:>**." CR CR
"A script file can contain a sequence of valid debugger commands, comments and embedded PHP "
"code. " CR CR
"**Examples**" CR CR
//********Need decent script example
"Comment lines are prefixed by the **#** character. Note that comments are only allowed in script "
"files and not in interactive sessions." CR CR
"PHP code is delimited by the start and end escape tags **<:** and **:>**. PHP code can be used "
"to define application context for a debugging session and also to extend the debugger by defining "
"and **register** PHP functions as new commands." CR CR
"Also note that executing a **clear** command will cause the current **phpdbginit** to be reparsed "
"/ reloaded."
},
{"_syntax",
{"syntax", CR
"All **phpdbg** commands are case sensitive. Commands start with a keyword, and some keywords "
"(**break**, **info**, **set**, **print** and **list**) may include a subcommand keyword. All "
"keywords have a single letter alias (most lowercase, some uppercase) that may be used instead "
@ -456,17 +464,19 @@ phpdbg_help_text_t phpdbg_help_text[] = {
" Comments introduced by the **#** character are only allowed in **phpdbginit** script files."
},
{"_ZZ_aliases",
/******************************** Help Codicils ********************************/
{"aliases!", CR
"Note that aliases can be used for either command or sub-command keywords or both, so **info b** "
"is a synomyn for **info break** and **l func** for **list func**, etc." CR CR
"Note that help will also accept any alias as a parameter and provide help on that command, for example **h p** will provide help on the print command."
},
{"_ZZ_duplicate",
{"duplicate!", CR
"Parameter is not unique. For detailed help select help on one of the above commands."
},
/******************************** Help on Commands ********************************/
{"back",
"Provide a formatted backtrace using the standard debug_backtrace() functionality. An optional "
"unsigned integer argument specifying the maximum number of frames to be traced; if omitted then "
@ -590,7 +600,7 @@ phpdbg_help_text_t phpdbg_help_text[] = {
},
{"compile",
"The execution context can be pre-compiled before execution, to provide the opportunity to "
"The execution context may be pre-compiled before execution to provide an opportunity to "
"inspect the generated opcode output. The execution context must be defined before the compile "
"command can be used. Use the command **exec** to set the execution context." CR CR
@ -601,12 +611,11 @@ phpdbg_help_text_t phpdbg_help_text[] = {
"Note: Then that it is usually necessary to issue a **clean** command to reset the environment prior "
"to compilation."
},
//********** Needs rewriting -- don't like -- careful thought -- what happens if you evaluate a function during execution, with and without breakpoints, with and without stepping ??
{"eval",
"The **eval** command takes a string expression which it evaluates and then displays. Note that "
"**eval** allows assignments and other write statements, thus enabling you to change the "
"environment during execution, so care is needed here." CR CR
"The **eval** command takes a string expression which it evaluates and then displays. It "
"evaluates in the context of the lowest (that is the executing) frame, unless this has first "
"been explicitly changed by issuing a **frame** command. " CR CR
"**Examples**" CR CR
" $P eval $variable" CR
@ -617,16 +626,16 @@ phpdbg_help_text_t phpdbg_help_text[] = {
" $P E $variable = \"Hello phpdbg :)\"" CR
" Will set $variable in the current scope" CR CR
"Note: **eval** will evaluate in the lowest (that is the executing) frame, unless this has first "
"been explicitly changed by issuing a **frame** command. " CR CR
"Note that **eval** allows any valid PHP expression including assignments, function calls and "
"other write statements. This enables you to change the environment during execution, so care "
"is needed here. You can even call PHP functions which have breakpoints defined. " CR CR
"Note: **eval** will always show the result; do not prefix the code with **return**"
"Note: **eval** will always show the result, so do not prefix the code with **return**"
},
{"exec",
"The **exec** command sets the execution context, that is the script to be executed." CR
"The execution context must be defined either by executing the **exec** command or by using the "
"The **exec** command sets the execution context, that is the script to be executed. The "
"execution context must be defined either by executing the **exec** command or by using the "
"**-e** command line option before the script can be compiled or run." CR CR
"Note that the **exec** command also can be used to replace a previously defined execution "
@ -646,6 +655,9 @@ phpdbg_help_text_t phpdbg_help_text[] = {
"will then continue until the next breakpoint after leaving the stack frame or unitil "
"completion of the script" CR CR
"Note when **step**ping is enabled, any opcode steps within the current stack frame are also "
"skipped. "CR CR
"Note **finish** will trigger a \"not executing\" error if not executing."
},
@ -690,6 +702,11 @@ phpdbg_help_text_t phpdbg_help_text[] = {
" $P leave" CR
" $P L" CR CR
"Note when **step**ping is enabled, any opcode steps within the current stack frame are also "
"skipped. "CR CR
"Note **leave** will trigger a \"not executing\" error if not executing."
},
{"list",
@ -897,17 +914,26 @@ phpdbg_help_text_t phpdbg_help_text[] = {
" $P s 1" CR
" Will enable stepping" CR CR
"While stepping is enabled you are presented with an interactive prompt after the execution of each opcode"
"While stepping is enabled you are presented with an interactive prompt after the execution of "
"each opcode." CR CR
"Note that when executing the **finish** and **leave** commands, and oplines within the current "
"execution frame will be skipped in line with the command behaviour. Stepping will resume on exit "
"from the current frame."
},
{"until",
//******* More explanation needed -- how does until play with step 1 ??
"The **until** command causes control to be passed back to the vm, continuing execution. Any "
"breakpoints that are encountered before the the next source line will be skipped. Execution "
"breakpoints that are encountered before the next source line will be skipped. Execution "
"will then continue until the next breakpoint or completion of the script" CR CR
"Note when **step**ping is enabled, any opcode steps within the current line are also skipped. "CR CR
"Note that if the next line is **not** executed then **all** subsequent breakpoints will be "
"skipped. " CR CR
"Note **until** will trigger a \"not executing\" error if not executing."
},
{"|", NULL /* end of table marker */}
{NULL, NULL /* end of table marker */}
}; /* }}} */