Enhance GN diagnostic tools

tools/gn/functions.cc

 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #include "tools/gn/functions.h"
 
 #include <iostream>
 
 #include "base/environment.h"
 #include "base/strings/string_util.h"
@@ skipping 471 matching lines @@
 const char kSetSourcesAssignmentFilter_Help[] =
     "set_sources_assignment_filter: Set a pattern to filter source files.\n"
     "\n"
     "  The sources assignment filter is a list of patterns that remove files\n"
     "  from the list implicitly whenever the \"sources\" variable is\n"
     "  assigned to. This is intended to be used to globally filter out files\n"
     "  with platform-specific naming schemes when they don't apply, for\n"
     "  example, you may want to filter out all \"*_win.cc\" files on non-\n"
     "  Windows platforms.\n"
     "\n"
-    "  See \"gn help patterns\" for specifics on patterns.\n"
-    "\n"
     "  Typically this will be called once in the master build config script\n"
     "  to set up the filter for the current platform. Subsequent calls will\n"
     "  overwrite the previous values.\n"
     "\n"
     "  If you want to bypass the filter and add a file even if it might\n"
     "  be filtered out, call set_sources_assignment_filter([]) to clear the\n"
     "  list of filters. This will apply until the current scope exits\n"
     "\n"
-    "Example:\n"
+    "How to use patterns\n"
+    "\n"
+    "  File patterns are VERY limited regular expressions. They must match\n"
+    "  the entire input string to be counted as a match. In regular\n"
+    "  expression parlance, there is an implicit \"^...$\" surrounding your\n"
+    "  input. If you want to match a substring, you need to use wildcards at\n"
+    "  the beginning and end.\n"
+    "\n"
+    "  There are only two special tokens understood by the pattern matcher.\n"
+    "  Everything else is a literal.\n"
+    "\n"
+    "   * Matches zero or more of any character. It does not depend on the\n"
+    "     preceding character (in regular expression parlance it is\n"
+    "     equivalent to \".*\").\n"
+    "\n"
+    "  \\b Matches a path boundary. This will match the beginning or end of\n"
+    "     a string, or a slash.\n"
+    "\n"
+    "Pattern examples\n"
+    "\n"
+    "  \"*asdf*\"\n"
+    "      Matches a string containing \"asdf\" anywhere.\n"
+    "\n"
+    "  \"asdf\"\n"
+    "      Matches only the exact string \"asdf\".\n"
+    "\n"
+    "  \"*.cc\"\n"
+    "      Matches strings ending in the literal \".cc\".\n"
+    "\n"
+    "  \"\\bwin/*\"\n"
+    "      Matches \"win/foo\" and \"foo/win/bar.cc\" but not \"iwin/foo\".\n"
+    "\n"
+    "Sources assignment example\n"
+    "\n"
     "  # Filter out all _win files.\n"
-    "  set_sources_assignment_filter([ \"*_win.cc\", \"*_win.h\" ])\n";
+    "  set_sources_assignment_filter([ \"*_win.cc\", \"*_win.h\" ])\n"
+    "  sources = [ \"a.cc\", \"b_win.cc\" ]\n"
+    "  print(sources)\n"
+    "  # Will print [ \"a.cc\" ]. b_win one was filtered out.\n";
 
 Value RunSetSourcesAssignmentFilter(Scope* scope,
                                     const FunctionCallNode* function,
                                     const std::vector<Value>& args,
                                     Err* err) {
   if (args.size() != 1) {
     *err = Err(function, "set_sources_assignment_filter takes one argument.");
   } else {
     scoped_ptr<PatternList> f(new PatternList);
     f->SetFromValue(args[0], err);
@@ skipping 232 matching lines @@
       return Value();
     return result;
   }
 
   // Otherwise it's a no-block function.
   return found_function->second.no_block_runner(scope, function,
                                                 args.list_value(), err);
 }
 
 }  // namespace functions