xref: /php-src/sapi/phpdbg/phpdbg_help.c (revision ccd27879)
1 /*
2    +----------------------------------------------------------------------+
3    | Copyright (c) The PHP Group                                          |
4    +----------------------------------------------------------------------+
5    | This source file is subject to version 3.01 of the PHP license,      |
6    | that is bundled with this package in the file LICENSE, and is        |
7    | available through the world-wide-web at the following url:           |
8    | https://www.php.net/license/3_01.txt                                 |
9    | If you did not receive a copy of the PHP license and are unable to   |
10    | obtain it through the world-wide-web, please send a note to          |
11    | license@php.net so we can mail you a copy immediately.               |
12    +----------------------------------------------------------------------+
13    | Authors: Felipe Pena <felipe@php.net>                                |
14    | Authors: Joe Watkins <joe.watkins@live.co.uk>                        |
15    | Authors: Bob Weinand <bwoebi@php.net>                                |
16    | Authors: Terry Ellison <terry@ellisons.org.uk>                       |
17    +----------------------------------------------------------------------+
18 */
19 
20 #include "phpdbg.h"
21 #include "phpdbg_help.h"
22 #include "phpdbg_prompt.h"
23 #include "zend.h"
24 
25 ZEND_EXTERN_MODULE_GLOBALS(phpdbg)
26 
27 /* {{{ Commands Table */
28 #define PHPDBG_COMMAND_HELP_D(name, tip, alias, action) \
29 	{PHPDBG_STRL(#name), tip, sizeof(tip)-1, alias, action, &phpdbg_prompt_commands[16], 0, NULL, (bool) 0}
30 
31 const phpdbg_command_t phpdbg_help_commands[] = {
32 	PHPDBG_COMMAND_HELP_D(aliases,    "show alias list", 'a', phpdbg_do_help_aliases),
33 	PHPDBG_COMMAND_HELP_D(options,    "command line options", 0, NULL),
34 	PHPDBG_COMMAND_HELP_D(overview,   "help overview", 0, NULL),
35 	PHPDBG_COMMAND_HELP_D(phpdbginit, "phpdbginit file format", 0, NULL),
36 	PHPDBG_COMMAND_HELP_D(syntax,     "syntax overview", 0, NULL),
37 	PHPDBG_END_COMMAND
38 };  /* }}} */
39 
40 /* {{{ pretty_print.  Formatting escapes and wrapping text in a string before printing it. */
pretty_print(const char * text)41 static void pretty_print(const char *text)
42 {
43 	char *new, *q;
44 
45 	const char  *prompt_escape = phpdbg_get_prompt();
46 	size_t prompt_escape_len = strlen(prompt_escape);
47 	size_t prompt_len = strlen(PHPDBG_G(prompt)[0]);
48 
49 	const char  *bold_on_escape  = PHPDBG_G(flags) & PHPDBG_IS_COLOURED ? "\033[1m" : "";
50 	const char  *bold_off_escape = PHPDBG_G(flags) & PHPDBG_IS_COLOURED ? "\033[0m" : "";
51 	size_t bold_escape_len = strlen(bold_on_escape);
52 
53 	uint32_t term_width = phpdbg_get_terminal_width();
54 	uint32_t size = 0;
55 
56 	int in_bold = 0;
57 
58 	char *last_new_blank = NULL;  /* position in new buffer of last blank char */
59 	uint32_t last_blank_count = 0;    /* printable char offset of last blank char */
60 	uint32_t line_count = 0;          /* number printable chars on current line */
61 
62 	/* First pass calculates a safe size for the pretty print version */
63 	const char *p;
64 	for (p = text; *p; p++) {
65 		if (UNEXPECTED(p[0] == '*') && p[1] == '*') {
66 			size += bold_escape_len - 2;
67 			p++;
68 		} else if (UNEXPECTED(p[0] == '$') && p[1] == 'P') {
69 			size += prompt_escape_len - 2;
70 			p++;
71 		} else if (UNEXPECTED(p[0] == '\\')) {
72 			p++;
73 		}
74 	}
75 	size += (p-text)+1;
76 
77 	new = emalloc(size);
78 	/*
79 	 * Second pass substitutes the bold and prompt escape sequences and line wrap
80 	 *
81 	 * ** toggles bold on and off if PHPDBG_IS_COLOURED flag is set
82 	 * $P substitutes the prompt sequence
83 	 * Lines are wrapped by replacing the last blank with a CR before <term width>
84 	 * characters.  (This defaults to 100 if the width can't be detected).  In the
85 	 * pathological case where no blanks are found, then the wrap occurs at the
86 	 * first blank.
87 	 */
88 	for (p = text, q = new; *p; p++) {
89 		if (UNEXPECTED(*p == ' ')) {
90 			last_new_blank = q;
91 			last_blank_count = line_count++;
92 			*q++ = ' ';
93 		} else if (UNEXPECTED(*p == '\n')) {
94 			last_new_blank = NULL;
95 			*q++ = *p;
96 			last_blank_count = 0;
97 			line_count = 0;
98 		} else if (UNEXPECTED(p[0] == '*') && p[1] == '*') {
99 			if (bold_escape_len) {
100 				in_bold = !in_bold;
101 				q = zend_mempcpy(q, in_bold ? bold_on_escape : bold_off_escape, bold_escape_len);
102 				/* bold on/off has zero print width so line count is unchanged */
103 			}
104 			p++;
105 		} else if (UNEXPECTED(p[0] == '$') && p[1] == 'P') {
106 			q = zend_mempcpy(q, prompt_escape, prompt_escape_len);
107 			line_count += prompt_len;
108 			p++;
109 		} else if (UNEXPECTED(p[0] == '\\')) {
110 			p++;
111 			*q++ = *p;
112 			line_count++;
113 		} else {
114 			*q++ = *p;
115 			line_count++;
116 		}
117 
118 		if (UNEXPECTED(line_count>=term_width) && last_new_blank) {
119 			*last_new_blank = '\n';
120 			last_new_blank = NULL;
121 			line_count -= last_blank_count;
122 			last_blank_count = 0;
123 		}
124 	}
125 	*q++ = '\0';
126 
127 	if ((q-new)>size) {
128 		phpdbg_error("Output overrun of %" PRIu32 " bytes", (uint32_t) ((q - new) - size));
129 	}
130 
131 	phpdbg_out("%s\n", new);
132 	efree(new);
133 }  /* }}} */
134 
135 /* {{{ summary_print.  Print a summary line giving, the command, its alias and tip */
summary_print(phpdbg_command_t const * const cmd)136 void summary_print(phpdbg_command_t const * const cmd)
137 {
138 	char *summary;
139 	spprintf(&summary, 0, "Command: **%s**  Alias: **%c**  **%s**\n", cmd->name, cmd->alias, cmd->tip);
140 	pretty_print(summary);
141 	efree(summary);
142 }
143 
144 /* {{{ get_help. Retries and formats text from the phpdbg help text table */
get_help(const char * const key)145 static const char *get_help(const char * const key)
146 {
147 	const phpdbg_help_text_t *p;
148 
149 	/* Note that phpdbg_help_text is not assumed to be collated in key order.  This is an
150 	   inconvenience that means that help can't be logically grouped Not worth
151 	   the savings */
152 
153 	for (p = phpdbg_help_text; p->key; p++) {
154 		if (!strcmp(p->key, key)) {
155 			return p->text;
156 		}
157 	}
158 	return "";   /* return empty string to denote no match found */
159 } /* }}} */
160 
161 /* {{{ get_command.  Return number of matching commands from a command table.
162  * Unlike the command parser, the help search is sloppy that is partial matches can occur
163  *   * Any single character key is taken as an alias.
164  *   * Other keys are matched again the table on the first len characters.
165  *   * This means that non-unique keys can generate multiple matches.
166  *   * The first matching command is returned as an OUT parameter. *
167  * The rationale here is to assist users in finding help on commands. So unique matches
168  * will be used to generate a help message but non-unique one will be used to list alternatives.
169  */
get_command(const char * key,size_t len,phpdbg_command_t const ** command,phpdbg_command_t const * commands)170 static int get_command(
171 	const char *key, size_t len,      /* pointer and length of key */
172 	phpdbg_command_t const **command, /* address of first matching command  */
173 	phpdbg_command_t const * commands /* command table to be scanned */
174 	)
175 {
176 	const phpdbg_command_t *c;
177 	unsigned int num_matches = 0;
178 
179 	if (len == 1) {
180 		for (c=commands; c->name; c++) {
181 			if (c->alias == key[0]) {
182 				num_matches++;
183 				if ( num_matches == 1 && command) {
184 					*command = c;
185 				}
186 			}
187 		}
188 	} else {
189 		for (c=commands; c->name; c++) {
190 			if (!strncmp(c->name, key, len)) {
191 				++num_matches;
192 				if ( num_matches == 1 && command) {
193 					*command = c;
194 				}
195 			}
196 		}
197 	}
198 
199 	return num_matches;
200 
201 } /* }}} */
202 
phpdbg_do_help_cmd(const char * type)203 void phpdbg_do_help_cmd(const char *type) { /* {{{ */
204 	const char *help;
205 
206 	if (!type) {
207 		pretty_print(get_help("overview!"));
208 		return;
209 	}
210 
211 	help = get_help(type);
212 
213 	if (!help || memcmp(help, "", sizeof("")) == SUCCESS) {
214 		pretty_print(get_help("overview!"));
215 		pretty_print(
216 			"\nrequested help page could not be found");
217 		return;
218 	}
219 
220 	pretty_print(help);
221 } /* }}} */
222 
PHPDBG_COMMAND(help)223 PHPDBG_COMMAND(help) /* {{{ */
224 {
225 	phpdbg_command_t const *cmd;
226 	int n;
227 
228 	if (!param || param->type == EMPTY_PARAM) {
229 		pretty_print(get_help("overview!"));
230 		return SUCCESS;
231 	}
232 
233 	if (param && param->type == STR_PARAM) {
234 	    n = get_command(param->str, param->len, &cmd, phpdbg_prompt_commands);
235 
236 		if (n==1) {
237 			summary_print(cmd);
238 			pretty_print(get_help(cmd->name));
239 			return SUCCESS;
240 
241 		} else if (n>1) {
242 			if (param->len > 1) {
243 				for (cmd=phpdbg_prompt_commands; cmd->name; cmd++) {
244 					if (!strncmp(cmd->name, param->str, param->len)) {
245 						summary_print(cmd);
246 					}
247 				}
248 				pretty_print(get_help("duplicate!"));
249 				return SUCCESS;
250 			} else {
251 				phpdbg_error("Internal help error, non-unique alias \"%c\"", param->str[0]);
252 				return FAILURE;
253 			}
254 
255 		} else { /* no prompt command found so try help topic */
256 		    n = get_command( param->str, param->len, &cmd, phpdbg_help_commands);
257 
258 			if (n>0) {
259 				if (cmd->alias == 'a') {   /* help aliases executes a canned routine */
260 					return cmd->handler(param);
261 				} else {
262 					pretty_print(get_help(cmd->name));
263 					return SUCCESS;
264 				}
265 			} else {
266 			    phpdbg_error("No help topic found for %s", param->str);
267 			}
268 		}
269 	}
270 
271 	return FAILURE;
272 
273 } /* }}} */
274 
PHPDBG_HELP(aliases)275 PHPDBG_HELP(aliases) /* {{{ */
276 {
277 	const phpdbg_command_t *c, *c_sub;
278 	int len;
279 
280 	/* Print out aliases for all commands except help as this one comes last */
281 	phpdbg_writeln("Below are the aliased, short versions of all supported commands");
282 
283 	for(c = phpdbg_prompt_commands; c->name; c++) {
284 		if (c->alias && c->alias != 'h') {
285 			phpdbg_writeln(" %c     %-20s  %s", c->alias, c->name, c->tip);
286 			if (c->subs) {
287 				len = 20 - 1 - c->name_len;
288 				for(c_sub = c->subs; c_sub->alias; c_sub++) {
289 					if (c_sub->alias) {
290 						phpdbg_writeln(" %c %c   %s %-*s  %s",
291 							c->alias, c_sub->alias, c->name, len, c_sub->name, c_sub->tip);
292 					}
293 				}
294 			}
295 		}
296 	}
297 
298 	/* Print out aliases for help as this one comes last, with the added text on how aliases are used */
299 	get_command("h", 1, &c, phpdbg_prompt_commands);
300 	phpdbg_writeln(" %c     %-20s  %s\n", c->alias, c->name, c->tip);
301 
302 	len = 20 - 1 - c->name_len;
303 	for(c_sub = c->subs; c_sub->alias; c_sub++) {
304 		if (c_sub->alias) {
305 			phpdbg_writeln(" %c %c   %s %-*s  %s",
306 				c->alias, c_sub->alias, c->name, len, c_sub->name, c_sub->tip);
307 		}
308 	}
309 
310 	pretty_print(get_help("aliases!"));
311 	return SUCCESS;
312 } /* }}} */
313 
314 
315 /* {{{ Help Text Table
316  * Contains help text entries keyed by a lowercase ascii key.
317  * Text is in ascii and enriched by a simple markup:
318  *   ** toggles bold font emphasis.
319  *   $P insert an bold phpdbg> prompt.
320  *   \  escapes the following character. Note that this is itself escaped inside string
321  *      constants so \\\\ is required to output a single \ e.g. as in namespace names.
322  *
323  * Text will be wrapped according to the STDOUT terminal width, so paragraphs are
324  * flowed using the C stringizing and the CR definition.  Also note that entries
325  * are collated in alphabetic order on key.
326  *
327  * Also note the convention that help text not directly referenceable as a help param
328  * has a key ending in !
329  */
330 #define CR "\n"
331 const phpdbg_help_text_t phpdbg_help_text[] = {
332 
333 /******************************** General Help Topics ********************************/
334 {"overview!", CR
335 "**phpdbg** is a lightweight, powerful and easy to use debugging platform for PHP" CR
336 "It supports the following commands:" CR CR
337 
338 "**Information**" CR
339 "  **list**      list PHP source" CR
340 "  **info**      displays information on the debug session" CR
341 "  **print**     show opcodes" CR
342 "  **frame**     select a stack frame and print a stack frame summary" CR
343 "  **generator** show active generators or select a generator frame" CR
344 "  **back**      shows the current backtrace" CR
345 "  **help**      provide help on a topic" CR CR
346 
347 "**Starting and Stopping Execution**" CR
348 "  **exec**      set execution context" CR
349 "  **stdin**     set executing script from stdin" CR
350 "  **run**       attempt execution" CR
351 "  **step**      continue execution until other line is reached" CR
352 "  **continue**  continue execution" CR
353 "  **until**     continue execution up to the given location" CR
354 "  **next**      continue execution up to the given location and halt on the first line after it" CR
355 "  **finish**    continue up to end of the current execution frame" CR
356 "  **leave**     continue up to end of the current execution frame and halt after the calling instruction" CR
357 "  **break**     set a breakpoint at the specified target" CR
358 "  **watch**     set a watchpoint on $variable" CR
359 "  **clear**     clear one or all breakpoints" CR
360 "  **clean**     clean the execution environment" CR CR
361 
362 "**Miscellaneous**" CR
363 "  **set**       set the phpdbg configuration" CR
364 "  **source**    execute a phpdbginit script" CR
365 "  **register**  register a phpdbginit function as a command alias" CR
366 "  **sh**        shell a command" CR
367 "  **ev**        evaluate some code" CR
368 "  **quit**      exit phpdbg" CR CR
369 
370 "Type **help <command>** or (**help alias**) to get detailed help on any of the above commands, "
371 "for example **help list** or **h l**.  Note that help will also match partial commands if unique "
372 "(and list out options if not unique), so **help exp** will give help on the **export** command, "
373 "but **help ex** will list the summary for **exec** and **export**." CR CR
374 
375 "Type **help aliases** to show a full alias list, including any registered phpdbginit functions" CR
376 "Type **help syntax** for a general introduction to the command syntax." CR
377 "Type **help options** for a list of phpdbg command line options." CR
378 "Type **help phpdbginit** to show how to customize the debugger environment."
379 },
380 {"options", CR
381 "Below are the command line options supported by phpdbg" CR CR
382                           /* note the extra 4 space index in because of the extra **** */
383 "**Command Line Options and Flags**" CR
384 "  **Option**  **Example Argument**    **Description**" CR
385 "  **-c**      **-c**/my/php.ini       Set php.ini file to load" CR
386 "  **-d**      **-d**memory_limit=4G   Set a php.ini directive" CR
387 "  **-n**                          Disable default php.ini" CR
388 "  **-q**                          Suppress welcome banner" CR
389 "  **-v**                          Enable oplog output" CR
390 "  **-b**                          Disable colour" CR
391 "  **-i**      **-i**my.init           Set .phpdbginit file" CR
392 "  **-I**                          Ignore default .phpdbginit" CR
393 "  **-r**                          Run execution context" CR
394 "  **-rr**                         Run execution context and quit after execution (not respecting breakpoints)" CR
395 "  **-e**                          Generate extended information for debugger/profiler" CR
396 "  **-E**                          Enable step through eval, careful!" CR
397 "  **-s**      **-s=**, **-s**=foo         Read code to execute from stdin with an optional delimiter" CR
398 "  **-S**      **-S**cli               Override SAPI name, careful!" CR
399 "  **-p**      **-p**, **-p=func**, **-p* **   Output opcodes and quit" CR
400 "  **-z**      **-z**extlib            Load Zend extension" CR
401 "  **-h**                          Print the help overview" CR
402 "  **-V**                          Print version number" CR
403 "  **--**      **--** arg1 arg2        Use to delimit phpdbg arguments and php $argv; append any $argv "
404 "argument after it" CR CR
405 
406 "**Reading from stdin**" CR CR
407 
408 "The **-s** option allows inputting a script to execute directly from stdin. The given delimiter "
409 "(\"foo\" in the example) needs to be specified at the end of the input on its own line, followed by "
410 "a line break. If **-rr** has been specified, it is allowed to omit the delimiter (**-s=**) and "
411 "it will read until EOF. See also the help entry for the **stdin** command." CR CR
412 
413 "**Opcode output**" CR CR
414 
415 "Outputting opcodes requires that a file path is passed as last argument. Modes of execution:" CR
416 "**-p** Outputs the main execution context" CR
417 "**-p* **Outputs all opcodes in the whole file (including classes and functions)" CR
418 "**-p=function_name** Outputs opcodes of a given function in the file" CR
419 "**-p=class_name::** Outputs opcodes of all the methods of a given class" CR
420 "**-p=class_name::method** Outputs opcodes of a given method"
421 },
422 
423 {"phpdbginit", CR
424 "Phpdbg uses an debugger script file to initialize the debugger context.  By default, phpdbg looks "
425 "for the file named **.phpdbginit** in the current working directory.  This location can be "
426 "overridden on the command line using the **-i** switch (see **help options** for a more "
427 "details)." CR CR
428 
429 "Debugger scripts can also be executed using the **source** command." CR CR
430 
431 "A script file can contain a sequence of valid debugger commands, comments and embedded PHP "
432 "code. " CR CR
433 
434 "Comment lines are prefixed by the **#** character.  Note that comments are only allowed in script "
435 "files and not in interactive sessions." CR CR
436 
437 "PHP code is delimited by the start and end escape tags **<:** and **:>**. PHP code can be used "
438 "to define application context for a debugging session and also to extend the debugger by defining "
439 "and **register** PHP functions as new commands." CR CR
440 
441 "Also note that executing a **clear** command will cause the current **phpdbginit** to be reparsed "
442 "/ reloaded."
443 },
444 
445 {"syntax", CR
446 "Commands start with a keyword, and some (**break**, "
447 "**info**, **set**, **print** and **list**) may include a subcommand keyword.  All keywords are "
448 "lower case but also have a single letter alias that may be used as an alternative to typing in the"
449 "keyword in full.  Note some aliases are uppercase, and that keywords cannot be abbreviated other "
450 "than by substitution by the alias." CR CR
451 
452 "Some commands take an argument.  Arguments are typed according to their format:" CR
453 "     *  **omitted**" CR
454 "     *  **address**      **0x** followed by a hex string" CR
455 "     *  **number**       an optionally signed number" CR
456 "     *  **method**       a valid **Class::methodName** expression" CR
457 "     *  **func#op**      a valid **Function name** follow by # and an integer" CR
458 "     *  **method#op**    a valid **Class::methodName** follow by # and an integer" CR
459 "     *  **string**       a general string" CR
460 "     *  **function**     a valid **Function name**" CR
461 "     *  **file:line**    a valid **filename** follow by : and an integer" CR CR
462 
463 "In some cases the type of the argument enables the second keyword to be omitted." CR CR
464 
465 "Type **help** for an overview of all commands and type **help <command>** to get detailed help "
466 "on any specific command." CR CR
467 
468 "**Valid Examples**" CR CR
469 
470 "     $P quit" CR
471 "     $P q" CR
472 "     Quit the debugger" CR CR
473 
474 "     $P ev $total[2]" CR
475 "     Evaluate and print the variable $total[2] in the current stack frame" CR
476 "    " CR
477 "     $P break 200" CR
478 "     $P b my_source.php:200" CR
479 "     Break at line 200 in the current source and in file **my_source.php**. " CR CR
480 
481 "     $P b @ ClassX::get_args if $arg[0] == \"fred\"" CR
482 "     $P b ~ 3" CR
483 "     Break at ClassX::get_args() if $arg[0] == \"fred\" and delete breakpoint 3" CR CR
484 
485 "**Examples of invalid commands**" CR
486 
487 "     $P #This is a comment" CR
488 "     Comments introduced by the **#** character are only allowed in **phpdbginit** script files."
489 },
490 
491 /******************************** Help Codicils ********************************/
492 {"aliases!", CR
493 "Note that aliases can be used for either command or sub-command keywords or both, so **info b** "
494 "is a synonym for **info break** and **l func** for **list func**, etc." CR CR
495 
496 "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."
497 },
498 
499 {"duplicate!", CR
500 "Parameter is not unique. For detailed help select help on one of the above commands."
501 },
502 
503 /******************************** Help on Commands ********************************/
504 {"back",
505 "Provide a formatted backtrace using the standard debug_backtrace() functionality.  An optional "
506 "unsigned integer argument specifying the maximum number of frames to be traced; if omitted then "
507 "a complete backtrace is given." CR CR
508 
509 "**Examples**" CR CR
510 "    $P back 5" CR
511 "    $P t " CR
512 " " CR
513 "A backtrace can be executed at any time during execution."
514 },
515 
516 {"break",
517 "Breakpoints can be set at a range of targets within the execution environment.  Execution will "
518 "be paused if the program flow hits a breakpoint.  The break target can be one of the following "
519 "types:" CR CR
520 
521 "  **Target**   **Alias** **Purpose**" CR
522 "  **at**       **@**     specify breakpoint by location and condition" CR
523 "  **del**      **~**     delete breakpoint by breakpoint identifier number" CR CR
524 
525 "**Break at** takes two arguments. The first is any valid target. The second "
526 "is a valid PHP expression which will trigger the break in "
527 "execution, if evaluated as true in a boolean context at the specified target." CR CR
528 
529 "Note that breakpoints can also be disabled and re-enabled by the **set break** command." CR CR
530 
531 "**Examples**" CR CR
532 "    $P break test.php:100" CR
533 "    $P b test.php:100" CR
534 "    Break execution at line 100 of test.php" CR CR
535 
536 "    $P break 200" CR
537 "    $P b 200" CR
538 "    Break execution at line 200 of the currently PHP script file" CR CR
539 
540 "    $P break \\\\mynamespace\\\\my_function" CR
541 "    $P b \\\\mynamespace\\\\my_function" CR
542 "    Break execution on entry to \\\\mynamespace\\\\my_function" CR CR
543 
544 "    $P break classX::method" CR
545 "    $P b classX::method" CR
546 "    Break execution on entry to classX::method" CR CR
547 
548 "    $P break 0x7ff68f570e08" CR
549 "    $P b 0x7ff68f570e08" CR
550 "    Break at the opline at the address 0x7ff68f570e08" CR CR
551 
552 "    $P break my_function#14" CR
553 "    $P b my_function#14" CR
554 "    Break at the opline #14 of the function my_function" CR CR
555 
556 "    $P break \\\\my\\\\class::method#2" CR
557 "    $P b \\\\my\\\\class::method#2" CR
558 "    Break at the opline #2 of the method \\\\my\\\\class::method" CR CR
559 
560 "    $P break test.php:#3" CR
561 "    $P b test.php:#3" CR
562 "    Break at opline #3 in test.php" CR CR
563 
564 "    $P break if $cnt > 10" CR
565 "    $P b if $cnt > 10" CR
566 "    Break when the condition ($cnt > 10) evaluates to true" CR CR
567 
568 "    $P break at phpdbg::isGreat if $opt == 'S'" CR
569 "    $P break @ phpdbg::isGreat if $opt == 'S'" CR
570 "    Break at any opcode in phpdbg::isGreat when the condition ($opt == 'S') is true" CR CR
571 
572 "    $P break at test.php:20 if !isset($x)" CR
573 "    Break at every opcode on line 20 of test.php when the condition evaluates to true" CR CR
574 
575 "    $P break ZEND_ADD" CR
576 "    $P b ZEND_ADD" CR
577 "    Break on any occurrence of the opcode ZEND_ADD" CR CR
578 
579 "    $P break del 2" CR
580 "    $P b ~ 2" CR
581 "    Remove breakpoint 2" CR CR
582 
583 "Note: Conditional breaks are costly in terms of runtime overhead. Use them only when required "
584 "as they significantly slow execution." CR CR
585 
586 "Note: An address is only valid for the current compilation."
587 },
588 
589 {"clean",
590 "Classes, constants or functions can only be declared once in PHP.  You may experience errors "
591 "during a debug session if you attempt to recompile a PHP source.  The clean command clears "
592 "the Zend runtime tables which holds the sets of compiled classes, constants and functions, "
593 "releasing any associated storage back into the storage pool.  This enables recompilation to "
594 "take place." CR CR
595 
596 "Note that you cannot selectively trim any of these resource pools. You can only do a complete "
597 "clean."
598 },
599 
600 {"clear",
601 "Clearing breakpoints means you can once again run code without interruption." CR CR
602 
603 "Note: use break delete N to clear a specific breakpoint." CR CR
604 
605 "Note: if all breakpoints are cleared, then the PHP script will run until normal completion."
606 },
607 
608 {"ev",
609 "The **ev** command takes a string expression which it evaluates and then displays. It "
610 "evaluates in the context of the lowest (that is the executing) frame, unless this has first "
611 "been explicitly changed by issuing a **frame** command. " CR CR
612 
613 "**Examples**" CR CR
614 "    $P ev $variable" CR
615 "    Will print_r($variable) on the console, if it is defined" CR CR
616 
617 "    $P ev $variable = \"Hello phpdbg :)\"" CR
618 "    Will set $variable in the current scope" CR CR
619 
620 "Note that **ev** allows any valid PHP expression including assignments, function calls and "
621 "other write statements.  This enables you to change the environment during execution, so care "
622 "is needed here.  You can even call PHP functions which have breakpoints defined. " CR CR
623 
624 "Note: **ev** will always show the result, so do not prefix the code with **return**"
625 },
626 
627 {"exec",
628 "The **exec** command sets the execution context, that is the script to be executed.  The "
629 "execution context must be defined either by executing the **exec** command or by using the "
630 "**-e** command line option." CR CR
631 
632 "Note that the **exec** command also can be used to replace a previously defined execution "
633 "context." CR CR
634 
635 "**Examples**" CR CR
636 
637 "    $P exec /tmp/script.php" CR
638 "    $P e /tmp/script.php" CR
639 "    Set the execution context to **/tmp/script.php**"
640 },
641 
642 {"stdin",
643 "The **stdin** command takes a string serving as delimiter. It will then read all the input from "
644 "stdin until encountering the given delimiter on a standalone line. It can also be passed at "
645 "startup using the **-s=** command line option (the delimiter then is optional if **-rr** is "
646 "also passed - in that case it will just read until EOF)." CR
647 "This input will be then compiled as PHP code and set as execution context." CR CR
648 
649 "**Example**" CR CR
650 
651 "    $P stdin foo" CR
652 "    <?php" CR
653 "    echo \"Hello, world!\\n\";" CR
654 "    foo"
655 },
656 
657 //*********** Does F skip any breakpoints lower stack frames or only the current??
658 {"finish",
659 "The **finish** command causes control to be passed back to the vm, continuing execution.  Any "
660 "breakpoints that are encountered within the current stack frame will be skipped.  Execution "
661 "will then continue until the next breakpoint after leaving the stack frame or until "
662 "completion of the script" CR CR
663 
664 "Note when **step**ping is enabled, any opcode steps within the current stack frame are also "
665 "skipped. "CR CR
666 
667 "Note **finish** will trigger a \"not executing\" error if not executing."
668 },
669 
670 {"frame",
671 "The **frame** takes an optional integer argument. If omitted, then the current frame is displayed. "
672 "If specified, then the current scope is set to the corresponding frame listed in a **back** trace. "
673 "This can be used to allowing access to the variables in a higher stack frame than that currently being executed." CR CR
674 
675 "**Examples**" CR CR
676 "    $P frame 2" CR
677 "    $P ev $count" CR
678 "    Go to frame 2 and print out variable **$count** in that frame" CR CR
679 
680 "Note that this frame scope is discarded when execution continues, with the execution frame "
681 "then reset to the lowest executing frame."
682 },
683 
684 {"generator",
685 "The **generator** command takes an optional integer argument. If omitted, then a list of the "
686 "currently active generators is displayed. If specified then the current scope is set to the frame "
687 "of the generator with the corresponding object handle. This can be used to inspect any generators "
688 "not in the current **back** trace." CR CR
689 
690 "**Examples**" CR CR
691 "    $P generator" CR
692 "    List of generators, with the #id being the object handle, e.g.:" CR
693 "    #3: my_generator(argument=\"value\") at test.php:5" CR
694 "    $P g 3" CR
695 "    $P ev $i" CR
696 "    Go to frame of generator with object handle 3 and print out variable **$i** in that frame" CR CR
697 
698 "Note that this frame scope is discarded when execution continues, with the execution frame "
699 "then reset to the lowest executing frame."
700 },
701 
702 {"info",
703 "**info** commands provide quick access to various types of information about the PHP environment" CR
704 "By default general information about environment and PHP build is shown." CR
705 "Specific info commands are show below:" CR CR
706 
707 "  **Target**   **Alias**  **Purpose**" CR
708 "  **break**      **b**      show current breakpoints" CR
709 "  **files**      **F**      show included files" CR
710 "  **classes**    **c**      show loaded classes" CR
711 "  **funcs**      **f**      show loaded functions" CR
712 "  **error**      **e**      show last error" CR
713 "  **constants**  **d**      show user-defined constants" CR
714 "  **vars**       **v**      show active variables" CR
715 "  **globals**    **g**      show superglobal variables" CR
716 "  **literal**    **l**      show active literal constants" CR
717 "  **memory**     **m**      show memory manager stats"
718 },
719 
720 // ******** same issue about breakpoints in called frames
721 {"leave",
722 "The **leave** command causes control to be passed back to the vm, continuing execution.  Any "
723 "breakpoints that are encountered within the current stack frame will be skipped.  In effect a "
724 "temporary breakpoint is associated with any return opcode, so that a break in execution occurs "
725 "before leaving the current stack frame. This allows inspection / modification of any frame "
726 "variables including the return value before it is returned" CR CR
727 
728 "**Examples**" CR CR
729 
730 "    $P leave" CR
731 "    $P L" CR CR
732 
733 "Note when **step**ping is enabled, any opcode steps within the current stack frame are also "
734 "skipped. "CR CR
735 
736 "Note **leave** will trigger a \"not executing\" error if not executing."
737 },
738 
739 {"list",
740 "The list command displays source code for the given argument.  The target type is specified by "
741 "a second subcommand keyword:" CR CR
742 
743 "  **Type**     **Alias**  **Purpose**" CR
744 "  **lines**    **l**      List N lines from the current execution point" CR
745 "  **func**     **f**      List the complete source for a specified function" CR
746 "  **method**   **m**      List the complete source for a specified class::method" CR
747 "  **class**    **c**      List the complete source for a specified class" CR CR
748 
749 "Note that the context of **lines**, **func** and **method** can be determined by parsing the "
750 "argument, so these subcommands are optional.  However, you must specify the **class** keyword "
751 "to list off a class." CR CR
752 
753 "**Examples**" CR CR
754 "    $P list 2" CR
755 "    $P l l 2" CR
756 "    List the next 2 lines from the current file" CR CR
757 
758 "    $P list my_function" CR
759 "    $P l f my_function" CR
760 "    List the source of the function **my_function**" CR CR
761 
762 //************ ????
763 "    $P list func .mine" CR
764 "    $P l f .mine" CR
765 "    List the source of the method **mine** from the active class in scope" CR CR
766 
767 "    $P list m my::method" CR
768 "    $P l my::method" CR
769 "    List the source of **my::method**" CR CR
770 
771 "    $P list c myClass" CR
772 "    $P l c myClass" CR
773 "    List the source of **myClass**" CR CR
774 
775 "Note that functions and classes can only be listed if the corresponding classes and functions "
776 "table in the Zend executor has a corresponding entry.  You can use the compile command to "
777 "populate these tables for a given execution context."
778 },
779 
780 {"continue",
781 "Continue with execution after hitting a break or watchpoint" CR CR
782 
783 "**Examples**" CR CR
784 "    $P continue" CR
785 "    $P c" CR
786 "    Continue executing until the next break or watchpoint" CR CR
787 
788 "Note **continue** will trigger a \"not running\" error if not executing."
789 },
790 
791 {"print",
792 "By default, print will show the opcodes of the current execution context." CR
793 "Other printing commands give access to instruction information." CR
794 "Specific printers loaded are show below:" CR CR
795 
796 "  **Type**    **Alias**  **Purpose**" CR
797 "  **exec**    **e**      print out the instructions in the execution context" CR
798 "  **opline**  **o**      print out the instruction in the current opline" CR
799 "  **class**   **c**      print out the instructions in the specified class" CR
800 "  **method**  **m**      print out the instructions in the specified method" CR
801 "  **func**    **f**      print out the instructions in the specified function" CR
802 "  **stack**   **s**      print out the instructions in the current stack" CR CR
803 
804 "In case passed argument does not match a specific printing command, it will treat it as function or method name and print its opcodes" CR CR
805 
806 "**Examples**" CR CR
807 "    $P print class \\\\my\\\\class" CR
808 "    $P p c \\\\my\\\\class" CR
809 "    Print the instructions for the methods in \\\\my\\\\class" CR CR
810 
811 "    $P print method \\\\my\\\\class::method" CR
812 "    $P p m \\\\my\\\\class::method" CR
813 "    Print the instructions for \\\\my\\\\class::method" CR CR
814 
815 "    $P print func .getSomething" CR
816 "    $P p f .getSomething" CR
817 //************* Check this local method scope
818 "    Print the instructions for ::getSomething in the active scope" CR CR
819 
820 "    $P print func my_function" CR
821 "    $P p f my_function" CR
822 "    Print the instructions for the global function my_function" CR CR
823 
824 "    $P print opline" CR
825 "    $P p o" CR
826 "    Print the instruction for the current opline" CR CR
827 
828 "    $P print exec" CR
829 "    $P p e" CR
830 "    Print the instructions for the execution context" CR CR
831 
832 "    $P print stack" CR
833 "    $P p s" CR
834 "    Print the instructions for the current stack"
835 },
836 
837 {"register",
838 //******* Needs a general explanation of the how registered functions work
839 "Register any global function for use as a command in phpdbg console" CR CR
840 
841 "**Examples**" CR CR
842 "    $P register scandir" CR
843 "    $P R scandir" CR
844 "    Will register the scandir function for use in phpdbg" CR CR
845 
846 "Note: arguments passed as strings, return (if present) print_r'd on console"
847 },
848 
849 {"run",
850 "Enter the vm, starting execution. Execution will then continue until the next breakpoint "
851 "or completion of the script. Add parameters you want to use as $argv. Add a trailing "
852 "**< filename** for reading STDIN from a file." CR CR
853 
854 "**Examples**" CR CR
855 
856 "    $P run" CR
857 "    $P r" CR
858 "    Will cause execution of the context, if it is set" CR CR
859 "    $P r test < foo.txt" CR
860 "    Will execute with $argv[1] == \"test\" and read from the foo.txt file for STDIN" CR CR
861 
862 "Note that the execution context must be set. If not previously compiled, then the script will "
863 "be compiled before execution."
864 },
865 
866 {"set",
867 "The **set** command is used to configure how phpdbg looks and behaves.  Specific set commands "
868 "are as follows:" CR CR
869 
870 "   **Type**    **Alias**    **Purpose**" CR
871 "   **prompt**     **p**     set the prompt" CR
872 "   **color**      **c**     set color  <element> <color>" CR
873 "   **colors**     **C**     set colors [<on|off>]" CR
874 "   **break**      **b**     set break **id** <on|off>" CR
875 "   **breaks**     **B**     set breaks [<on|off>]" CR
876 "   **quiet**      **q**     set quiet [<on|off>]" CR
877 "   **stepping**   **s**     set stepping [<opcode|line>]" CR
878 "   **refcount**   **r**     set refcount [<on|off>] " CR CR
879 
880 "Valid colors are **none**, **white**, **red**, **green**, **yellow**, **blue**, **purple**, "
881 "**cyan** and **black**.  All colours except **none** can be followed by an optional "
882 "**-bold** or **-underline** qualifier." CR CR
883 
884 "Color elements can be one of **prompt**, **notice**, or **error**." CR CR
885 
886 "**Examples**" CR CR
887 "     $P S C on" CR
888 "     Set colors on" CR CR
889 
890 "     $P set p >" CR
891 "     $P set color prompt white-bold" CR
892 "     Set the prompt to a bold >" CR CR
893 
894 "     $P S c error red-bold" CR
895 "     Use red bold for errors" CR CR
896 
897 "     $P S refcount on" CR
898 "     Enable refcount display when hitting watchpoints" CR CR
899 
900 "     $P S b 4 off" CR
901 "     Temporarily disable breakpoint 4.  This can be subsequently re-enabled by a **S b 4 on**." CR
902 //*********** check oplog syntax
903 },
904 
905 {"sh",
906 "Direct access to shell commands saves having to switch windows/consoles" CR CR
907 
908 "**Examples**" CR CR
909 "    $P sh ls /usr/src/php-src" CR
910 "    Will execute ls /usr/src/php-src, displaying the output in the console"
911 //*********** what does this mean????Note: read only commands please!
912 },
913 
914 {"source",
915 "Sourcing a **phpdbginit** script during your debugging session might save some time." CR CR
916 
917 "**Examples**" CR CR
918 
919 "    $P source /my/init" CR
920 "    $P < /my/init" CR
921 "    Will execute the phpdbginit file at /my/init" CR CR
922 },
923 
924 {"export",
925 "Exporting breakpoints allows you to share, and or save your current debugging session" CR CR
926 
927 "**Examples**" CR CR
928 
929 "    $P export /my/exports" CR
930 "    $P > /my/exports" CR
931 "    Will export all breakpoints to /my/exports" CR CR
932 },
933 
934 {"step",
935 "Execute opcodes until next line" CR CR
936 
937 "**Examples**" CR CR
938 
939 "    $P s" CR
940 "    Will continue and break again in the next encountered line" CR CR
941 },
942 {"next",
943 "The **next** command causes control to be passed back to the vm, continuing execution. Any "
944 "breakpoints that are encountered before the next source line will be skipped. Execution will"
945 "be stopped when that line is left." CR CR
946 
947 "Note when **step**ping is enabled, any opcode steps within the current line are also skipped. "CR CR
948 
949 "Note that if the next line is **not** executed then **all** subsequent breakpoints will be "
950 "skipped. " CR CR
951 
952 "Note **next** will trigger a \"not executing\" error if not executing."
953 
954 },
955 {"until",
956 "The **until** command causes control to be passed back to the vm, continuing execution. Any "
957 "breakpoints that are encountered before the next source line will be skipped. Execution "
958 "will then continue until the next breakpoint or completion of the script" CR CR
959 
960 "Note when **step**ping is enabled, any opcode steps within the current line are also skipped. "CR CR
961 
962 "Note that if the next line is **not** executed then **all** subsequent breakpoints will be "
963 "skipped. " CR CR
964 
965 "Note **until** will trigger a \"not executing\" error if not executing."
966 
967 },
968 {"watch",
969 "Sets watchpoints on variables as long as they are defined" CR
970 "Passing no parameter to **watch**, lists all actually active watchpoints" CR CR
971 
972 "**Format for $variable**" CR CR
973 "   **$var**      Variable $var" CR
974 "   **$var[]**    All array elements of $var" CR
975 "   **$var->**    All properties of $var" CR
976 "   **$var->a**   Property $var->a" CR
977 "   **$var[b]**   Array element with key b in array $var" CR CR
978 
979 "Subcommands of **watch**:" CR CR
980 
981 "   **Type**     **Alias**      **Purpose**" CR
982 "   **array**       **a**       Sets watchpoint on array/object to observe if an entry is added or removed" CR
983 "   **recursive**   **r**       Watches variable recursively and automatically adds watchpoints if some entry is added to an array/object" CR
984 "   **delete**      **d**       Removes watchpoint" CR CR
985 
986 "Note when **recursive** watchpoints are removed, watchpoints on all the children are removed too" CR CR
987 
988 "**Examples**" CR CR
989 "     $P watch" CR
990 "     List currently active watchpoints" CR CR
991 
992 "     $P watch $array" CR
993 "     $P w $array" CR
994 "     Set watchpoint on $array" CR CR
995 
996 "     $P watch recursive $obj->" CR
997 "     $P w r $obj->" CR
998 "     Set recursive watchpoint on $obj->" CR CR
999 
1000 "     $P watch delete $obj->a" CR
1001 "     $P w d $obj->a" CR
1002 "     Remove watchpoint $obj->a" CR CR
1003 
1004 "Technical note: If using this feature with a debugger, you will get many segmentation faults, each time when a memory page containing a watched address is hit." CR
1005 "                You then you can continue, phpdbg will remove the write protection, so that the program can continue." CR
1006 "                If phpdbg could not handle that segfault, the same segfault is triggered again and this time phpdbg will abort."
1007 },
1008 {NULL, NULL /* end of table marker */}
1009 };  /* }}} */
1010