Fixed line wrapping for the "long help" content in LLDB commands. Content is now dynamically wrapped for the column width of the current terminal. Lines that begin with whitespace will be indented identically on subsequent lines to maintain formatting.

Existing commands supplying this type of help content have been reworked to take advantage of the changes.  In addition to formatting changes, content was changes for accuracy and clarity purposes.
    
<rdar://problem/21269977>

llvm-svn: 242122

1 files changed, 114 insertions, 137 deletions

diff --git a/lldb/source/Commands/CommandObjectBreakpointCommand.cpp b/lldb/source/Commands/CommandObjectBreakpointCommand.cpp
index 180ab600a50..ac9c9a64188 100644
--- a/lldb/source/Commands/CommandObjectBreakpointCommand.cpp
+++ b/lldb/source/Commands/CommandObjectBreakpointCommand.cpp
@@ -49,143 +49,120 @@ public:
         m_options (interpreter)
     {
         SetHelpLong (
-"\nGeneral information about entering breakpoint commands\n\
-------------------------------------------------------\n\
-\n\
-This command will cause you to be prompted to enter the command or set of\n\
-commands you wish to be executed when the specified breakpoint is hit. You\n\
-will be told to enter your command(s), and will see a '> 'prompt. Because\n\
-you can enter one or many commands to be executed when a breakpoint is hit,\n\
-you will continue to be prompted after each new-line that you enter, until you\n\
-enter the word 'DONE', which will cause the commands you have entered to be\n\
-stored with the breakpoint and executed when the breakpoint is hit.\n\
-\n\
-Syntax checking is not necessarily done when breakpoint commands are entered.\n\
-An improperly written breakpoint command will attempt to get executed when the\n\
-breakpoint gets hit, and usually silently fail.  If your breakpoint command does\n\
-not appear to be getting executed, go back and check your syntax.\n\
-\n\
-Special information about PYTHON breakpoint commands\n\
-----------------------------------------------------\n\
-\n\
-You may enter either one line of Python, multiple lines of Python (including\n\
-function definitions), or specify a Python function in a module that has already,\n\
-or will be imported.  If you enter a single line of Python, that will be passed\n\
-to the Python interpreter 'as is' when the breakpoint gets hit.  If you enter\n\
-function definitions, they will be passed to the Python interpreter as soon as\n\
-you finish entering the breakpoint command, and they can be called later (don't\n\
-forget to add calls to them, if you want them called when the breakpoint is\n\
-hit).  If you enter multiple lines of Python that are not function definitions,\n\
-they will be collected into a new, automatically generated Python function, and\n\
-a call to the newly generated function will be attached to the breakpoint.\n\
-\n\
-\n\
-This auto-generated function is passed in three arguments:\n\
-\n\
-    frame:  a lldb.SBFrame object for the frame which hit breakpoint.\n\
-    bp_loc: a lldb.SBBreakpointLocation object that represents the breakpoint\n\
-            location that was hit.\n\
-    dict:   the python session dictionary hit.\n\
-\n\
-When specifying a python function with the --python-function option, you need\n\
-to supply the function name prepended by the module name. So if you import a\n\
-module named 'myutils' that contains a 'breakpoint_callback' function, you would\n\
-specify the option as:\n\
-\n\
-    --python-function myutils.breakpoint_callback\n\
-\n\
-The function itself must have the following prototype:\n\
-\n\
-def breakpoint_callback(frame, bp_loc, dict):\n\
-  # Your code goes here\n\
-\n\
-The arguments are the same as the 3 auto generation function arguments listed\n\
-above. Note that the global variable 'lldb.frame' will NOT be setup when this\n\
-function is called, so be sure to use the 'frame' argument. The 'frame' argument\n\
-can get you to the thread (frame.GetThread()), the thread can get you to the\n\
-process (thread.GetProcess()), and the process can get you back to the target\n\
-(process.GetTarget()).\n\
-\n\
-Important Note: Because loose Python code gets collected into functions, if you\n\
-want to access global variables in the 'loose' code, you need to specify that\n\
-they are global, using the 'global' keyword.  Be sure to use correct Python\n\
-syntax, including indentation, when entering Python breakpoint commands.\n\
-\n\
-As a third option, you can pass the name of an already existing Python function\n\
-and that function will be attached to the breakpoint. It will get passed the\n\
-frame and bp_loc arguments mentioned above.\n\
-\n\
-Example Python one-line breakpoint command:\n\
-\n\
-(lldb) breakpoint command add -s python 1\n\
-Enter your Python command(s). Type 'DONE' to end.\n\
-> print \"Hit this breakpoint!\"\n\
-> DONE\n\
-\n\
-As a convenience, this also works for a short Python one-liner:\n\
-(lldb) breakpoint command add -s python 1 -o \"import time; print time.asctime()\"\n\
-(lldb) run\n\
-Launching '.../a.out'  (x86_64)\n\
-(lldb) Fri Sep 10 12:17:45 2010\n\
-Process 21778 Stopped\n\
-* thread #1: tid = 0x2e03, 0x0000000100000de8 a.out`c + 7 at main.c:39, stop reason = breakpoint 1.1, queue = com.apple.main-thread\n\
-  36   	\n\
-  37   	int c(int val)\n\
-  38   	{\n\
-  39 ->	    return val + 3;\n\
-  40   	}\n\
-  41   	\n\
-  42   	int main (int argc, char const *argv[])\n\
-(lldb)\n\
-\n\
-Example multiple line Python breakpoint command, using function definition:\n\
-\n\
-(lldb) breakpoint command add -s python 1\n\
-Enter your Python command(s). Type 'DONE' to end.\n\
-> def breakpoint_output (bp_no):\n\
->     out_string = \"Hit breakpoint number \" + repr (bp_no)\n\
->     print out_string\n\
->     return True\n\
-> breakpoint_output (1)\n\
-> DONE\n\
-\n\
-\n\
-Example multiple line Python breakpoint command, using 'loose' Python:\n\
-\n\
-(lldb) breakpoint command add -s p 1\n\
-Enter your Python command(s). Type 'DONE' to end.\n\
-> global bp_count\n\
-> bp_count = bp_count + 1\n\
-> print \"Hit this breakpoint \" + repr(bp_count) + \" times!\"\n\
-> DONE\n\
-\n\
-In this case, since there is a reference to a global variable,\n\
-'bp_count', you will also need to make sure 'bp_count' exists and is\n\
-initialized:\n\
-\n\
-(lldb) script\n\
->>> bp_count = 0\n\
->>> quit()\n\
-\n\
-(lldb)\n\
-\n\
-\n\
-Your Python code, however organized, can optionally return a value.\n\
-If the returned value is False, that tells LLDB not to stop at the breakpoint\n\
-to which the code is associated. Returning anything other than False, or even\n\
-returning None, or even omitting a return statement entirely, will cause\n\
-LLDB to stop.\n\
-\n\
-Final Note:  If you get a warning that no breakpoint command was generated, but\n\
-you did not get any syntax errors, you probably forgot to add a call to your\n\
-functions.\n\
-\n\
-Special information about debugger command breakpoint commands\n\
---------------------------------------------------------------\n\
-\n\
-You may enter any debugger command, exactly as you would at the debugger prompt.\n\
-You may enter as many debugger commands as you like, but do NOT enter more than\n\
-one command per line.\n" );
+R"(
+General information about entering breakpoint commands
+------------------------------------------------------
+
+)" "This command will prompt for commands to be executed when the specified \
+breakpoint is hit.  Each command is typed on its own line following the '> ' \
+prompt until 'DONE' is entered." R"(
+
+)" "Syntactic errors may not be detected when initially entered, and many \
+malformed commands can silently fail when executed.  If your breakpoint commands \
+do not appear to be executing, double-check the command syntax." R"(
+
+)" "Note: You may enter any debugger command exactly as you would at the debugger \
+prompt.  There is no limit to the number of commands supplied, but do NOT enter \
+more than one command per line." R"(
+
+Special information about PYTHON breakpoint commands
+----------------------------------------------------
+
+)" "You may enter either one or more lines of Python, including function \
+definitions or calls to functions that will have been imported by the time \
+the code executes.  Single line breakpoint commands will be interpreted 'as is' \
+when the breakpoint is hit.  Multiple lines of Python will be wrapped in a \
+generated function, and a call to the function will be attached to the breakpoint." R"(
+
+This auto-generated function is passed in three arguments:
+
+    frame:  an lldb.SBFrame object for the frame which hit breakpoint.
+
+    bp_loc: an lldb.SBBreakpointLocation object that represents the breakpoint location that was hit.
+
+    dict:   the python session dictionary hit.
+
+)" "When specifying a python function with the --python-function option, you need \
+to supply the function name prepended by the module name:" R"(
+
+    --python-function myutils.breakpoint_callback
+
+The function itself must have the following prototype:
+
+def breakpoint_callback(frame, bp_loc, dict):
+  # Your code goes here
+
+)" "The arguments are the same as the arguments passed to generated functions as \
+described above.  Note that the global variable 'lldb.frame' will NOT be updated when \
+this function is called, so be sure to use the 'frame' argument. The 'frame' argument \
+can get you to the thread via frame.GetThread(), the thread can get you to the \
+process via thread.GetProcess(), and the process can get you back to the target \
+via process.GetTarget()." R"(
+
+)" "Important Note: As Python code gets collected into functions, access to global \
+variables requires explicit scoping using the 'global' keyword.  Be sure to use correct \
+Python syntax, including indentation, when entering Python breakpoint commands." R"(
+
+Example Python one-line breakpoint command:
+
+(lldb) breakpoint command add -s python 1
+Enter your Python command(s). Type 'DONE' to end.
+> print "Hit this breakpoint!"
+> DONE
+
+As a convenience, this also works for a short Python one-liner:
+
+(lldb) breakpoint command add -s python 1 -o 'import time; print time.asctime()'
+(lldb) run
+Launching '.../a.out'  (x86_64)
+(lldb) Fri Sep 10 12:17:45 2010
+Process 21778 Stopped
+* thread #1: tid = 0x2e03, 0x0000000100000de8 a.out`c + 7 at main.c:39, stop reason = breakpoint 1.1, queue = com.apple.main-thread
+  36
+  37   	int c(int val)
+  38   	{
+  39 ->	    return val + 3;
+  40   	}
+  41
+  42   	int main (int argc, char const *argv[])
+
+Example multiple line Python breakpoint command:
+
+(lldb) breakpoint command add -s p 1
+Enter your Python command(s). Type 'DONE' to end.
+> global bp_count
+> bp_count = bp_count + 1
+> print "Hit this breakpoint " + repr(bp_count) + " times!"
+> DONE
+
+Example multiple line Python breakpoint command, using function definition:
+
+(lldb) breakpoint command add -s python 1
+Enter your Python command(s). Type 'DONE' to end.
+> def breakpoint_output (bp_no):
+>     out_string = "Hit breakpoint number " + repr (bp_no)
+>     print out_string
+>     return True
+> breakpoint_output (1)
+> DONE
+
+)" "In this case, since there is a reference to a global variable, \
+'bp_count', you will also need to make sure 'bp_count' exists and is \
+initialized:" R"(
+
+(lldb) script
+>>> bp_count = 0
+>>> quit()
+
+)" "Your Python code, however organized, can optionally return a value.  \
+If the returned value is False, that tells LLDB not to stop at the breakpoint \
+to which the code is associated. Returning anything other than False, or even \
+returning None, or even omitting a return statement entirely, will cause \
+LLDB to stop." R"(
+
+)" "Final Note: A warning that no breakpoint command was generated when there \
+are no syntax errors may indicate that a function was declared but never called."
+        );
 
         CommandArgumentEntry arg;
         CommandArgumentData bp_id_arg;