Split run_tool.py into run_tool.py, extract_edits.py and apply_edits.py

docs/clang_tool_refactoring.md

 # Clang Tool Refactoring
 
 [TOC]
 
 ## Introduction
 
 Clang tools can help with global refactorings of Chromium code. Clang tools can
 take advantage of clang's AST to perform refactorings that would be impossible
 with a traditional find-and-replace regexp:
 
@@ skipping 51 matching lines @@
        ...
 
 ==== END EDITS ====
 ```
 
 The header and footer are required. Each line between the header and footer
 represents one edit. Fields are separated by `:::`, and the first field must
 be `r` (for replacement). In the future, this may be extended to handle header
 insertion/removal. A deletion is an edit with no replacement text.
 
-The edits are applied by [`run_tool.py`](#Running), which understands certain
+The edits are applied by [`apply_edits.py`](#Running), which understands certain
 conventions:
 
 *   The tool should munge newlines in replacement text to `\0`. The script
     knows to translate `\0` back to newlines when applying edits.
 *   When removing an element from a 'list' (e.g. function parameters,
     initializers), the tool should emit a deletion for just the element. The
     script understands how to extend the deletion to remove commas, etc. as
     needed.
 
 TODO: Document more about `SourceLocation` and how spelling loc differs from
@@ skipping 28 matching lines @@
 It is important to use --bootstrap as there appear to be [bugs](https://crbug.com/580745)
 in the clang library this script produces if you build it with gcc, which is the default.
 
 ## Running
 First, build all Chromium targets to avoid failures due to missing dependencies
 that are generated as part of the build:
 
 ```shell
 ninja -C out/Debug  # For non-Windows
 ninja -d keeprsp -C out/Debug  # For Windows
+
+# experimental:
+$gen_targets = $(ninja -C out/gn -t targets all \
+                 | grep '^gen/[^: ]*\.[ch][pc]*:' \
+                 | cut -f 1 -d :`)
+ninja -C out/Debug $gen_targets
 ```
 
 On Windows, generate the compile DB first, and after making any source changes.
 Then omit the `--generate-compdb` in later steps.
 
 ```shell
 tools/clang/scripts/generate_win_compdb.py out/Debug
 ```
 
-Then run the actual tool:
+Then run the actual clang tool to generate a list of edits:
 
 ```shell
 tools/clang/scripts/run_tool.py <toolname> \
   --generate-compdb
-  out/Debug <path 1> <path 2> ...
+  out/Debug <path 1> <path 2> ... >/tmp/list-of-edits

[danakj, 2016/12/23 15:45:06]

suggest putting debug in the output file name for good role modelling

[Łukasz Anforowicz, 2016/12/27 22:33:26]

Done.

 ```
 
 `--generate-compdb` can be omitted if the compile DB was already generated and
 the list of build flags and source files has not changed since generation.
 
 `<path 1>`, `<path 2>`, etc are optional arguments to filter the files to run
 the tool across. This is helpful when sharding global refactorings into smaller
 chunks. For example, the following command will run the `empty_string` tool
 across just the files in `//base`:
 
 ```shell
 tools/clang/scripts/run_tool.py empty_string  \
   --generated-compdb \
-  out/Debug base
+  out/Debug base >/tmp/list-of-edits

[danakj, 2016/12/23 15:45:06]

same

[Łukasz Anforowicz, 2016/12/27 22:33:26]

Done.

+```
+
+Finally - apply the edits as follows:

[dcheng, 2016/12/27 07:30:14]

Super minor nit: comma instead of a dash

[Łukasz Anforowicz, 2016/12/27 22:33:26]

Done.

+
+```shell
+cat /tmp/list-of-edits \

[danakj, 2016/12/23 15:45:06]

same

[Łukasz Anforowicz, 2016/12/27 22:33:26]

Done.

+  | tools/clang/scripts/extract_edits.py \
+  | tools/clang/scripts/apply_edits.py out/Debug <optional paths to filter by>

[danakj, 2016/12/23 15:45:06]

Why are there filter paths here and for run_tool.py, i guess this can only be a
subset of those? If so maybe mention this in the text above when saying "apply
the edits"

[Łukasz Anforowicz, 2016/12/27 22:33:26]

I tried to explain this better in the newest patchset.

1. filters passed to run_tool.py control which source files the clang tool is
run against.  the tool can emit edits that apply to *any* files anywhere
(run_tool.py doesn't look at the output of the clang tool at all - the tool can
legitimately produce edits somewhere "outside" [e.g. when processing a .cc file
under //net it can generate edits for an included header file under //base]).

2. filters passed to apply_edits.py controls which files get edited

 ```
 
 ## Debugging
 Dumping the AST for a file:
 
 ```shell
 clang++ -cc1 -ast-dump foo.cc
 ```
 
 Using `clang-query` to dynamically test matchers (requires checking out
@@ skipping 20 matching lines @@
 
 ```shell
 tools/clang/scripts/test_tool.py <tool name>
 ```
 
 The name of the tool binary and the subdirectory for the tool in
 `//tools/clang` must match. The test runner finds all files that match the
 pattern `//tools/clang/<tool name>/tests/*-original.cc`, runs the tool across
 those files, and compared it to the `*-expected.cc` version. If there is a
 mismatch, the result is saved in `*-actual.cc`.