Added a blog page with a description and tutorial on using the new "command regex"
command.
git-svn-id: https://llvm.org/svn/llvm-project/llvdb/trunk@129898 91177308-0d34-0410-b5e6-96231b3b80d8
diff --git a/www/blog.html b/www/blog.html
new file mode 100755
index 0000000..74db053
--- /dev/null
+++ b/www/blog.html
@@ -0,0 +1,128 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+<link href="style.css" rel="stylesheet" type="text/css" />
+<title>LLDB FAQ</title>
+</head>
+
+<body>
+<div class="www_title">
+ The <strong>LLDB</strong> Debugger
+</div>
+
+<div id="container">
+<div id="content">
+ <!--#include virtual="sidebar.incl"-->
+
+ <div id="middle">
+ <div class="post">
+ <h1 class ="postheader"><div align="right" padding=20>April 20, 2011 </div><div align="left">Regular Expression Commands</div></h1>
+ <div class="postcontent">
+ <p>Greetings LLDB users. I want to start writing regular blog posts
+ for the new and cool features and things you can do in LLDB. Today I
+ will start with one that was just added: <b>regular expression commands</b>.
+ What is a regular expression command? It is a command that you can
+ define by giving it a command name, where the command will have its raw arguments be
+ matched against one or more regular expressions. The first regular
+ expression to match your command's raw arguments wins and gets to
+ use substitutions to place argument snippets into a new command that
+ will get executed.</p>
+
+ <p>Lets supposed we want to use the <code>"f"</code> as a command to
+ select a frame by frame index. The command to select a frame by the
+ frame index is the <code>"frame select <num>"</code> command
+ which you might not always want to type out (even with out command
+ completion).
+ We can make this a bit easier this using a regular expression command:
+ <p>
+ <code>(lldb) command regex f 's/([0-9]+)/frame select %1/'</code>
+ </p>
+
+ <p><code>"command regex f"</code> tells the interpreter to create a new
+ regex command named <code>"f"</code>, and when a command is entered
+ on the command line that starts with <code>"f"</code>, it will match
+ the remaining command text against the regular expression
+ <code>"([0-9]+)"</code>, and it if matches, it will substitute any
+ parenthesized subexpressions as needed. Here we enclosed the number
+ regular expression <code>"[0-9]+"</code> in parentheses which will
+ save the results in the first match and allow the matching string
+ to be substitued into the result <code>"frame select %1"</code>.
+ So now we can use our new command and it will show us what command
+ resulted from our regular expression substitution:
+ <p>
+ <p>
+ <code>(lldb) f 12<br>
+ frame select 12
+ </code>
+ </p>
+ <p>Leading spaces will always be stripped, but there may be trailing spaces
+ since we are processing the remaining raw command string that follows
+ the initial <code>f</code> command name, plus any leading spaces. The regular expression
+ is also just looking for any sequence of one or more digits. Our
+ current regular expression will actually match <code>"f 11 22 33"</code>:
+ <p>
+ <code>(lldb) f 11 22 33<br>
+ frame select 11
+ </code>
+ </p>
+ Since this isn't desired, we should make the regular expression more complete by checking for
+ the start of the line (<code>^</code>) and the end of the line (<code>$</code>)
+ and also allow for zero or more spaces (<code>[[:space:]]*</code>)
+ to come after the number. Our newer and safer regular expression command line looks like:
+ <p>
+ <code>(lldb) command regex f 's/^([0-9]+)[[:space:]]*$/frame select %1/'</code>
+ </p>
+ <p>Now we can type in a command as <code>"f 12 "</code> (note the trailing
+ spaces), and still get correct substitutions, while our previous
+ example of <code>"f 11 22 33"</code> will no longer match:
+ <p>
+ <code>(lldb) f 11 22 33<br>
+ error: Command contents '11 22 33' failed to match any regular expression in the 'f' regex command.
+ </code>
+ <p>Lets take this a bit further by also using the <code>f</code> command
+ to emulate GDB's <code>finish</code> command when it is typed without
+ any arguments. We will also modify this command to watch for a single
+ "+" or "-" followed by a digit to signify a relative frame change
+ using the frame select command with the --relative option:
+ </p>
+ <p>
+ <code>(lldb) frame select --relative <offset></code>
+ <p>
+ Multiple regular expressions can be entered in on the command line
+ or using the multi-line mode when typing in a live LLDB debug session.
+ Below the text in bold is user entered:
+ <p>
+ <code>
+ (lldb) <b>commands regex f</b><br>
+ Enter regular expressions in the form 's/<regex>/<subst>/' and terminate with an empty line:<br>
+ <b>s/^([0-9]+)[[:space:]]*$/frame select %1/<br>
+ s/^([+-][0-9]+)[[:space:]]*$/frame select --relative=%1/<br>
+ s/^[[:space:]]*$/finish/</b><br>
+<br>
+ (lldb) <b>f</b><br>
+ finish<br>
+ ...<br>
+ (lldb) <b>f -1</b><br>
+ frame select --relative=-1<br>
+ ...<br>
+ (lldb) <b>f +1</b><br>
+ frame select --relative=+1<br>
+ ...<br>
+ (lldb) <b>f 12</b><br>
+ frame select 12<br>
+ </code>
+ </p>
+ <p>I hope you can see the possilbities in how you can customize your
+ command line experience in LLDB using these commands. You can add
+ any regular expression commands to your <b>~/.lldbinit</b> file to
+ always have your regular expression commands defined in your debug
+ sessions.
+
+ </div>
+ <div class="postfooter"></div>
+</div>
+</div>
+</div>
+</body>
+</html>
\ No newline at end of file
diff --git a/www/sidebar.incl b/www/sidebar.incl
index ee47327..167c193 100644
--- a/www/sidebar.incl
+++ b/www/sidebar.incl
@@ -4,6 +4,7 @@
<h1 class="headerbar">Goals and Status</h1>
<ul>
<li><a href="index.html">About</a></li>
+ <li><a href="blog.html">Blog</a></li>
<li><a href="goals.html">Goals</a></li>
<li><a href="features.html">Features</a></li>
<li><a href="status.html">Status</a></li>