{namespace buck.glob}

/***/
{template .soyweb}
  {call buck.page}
    {param title: 'glob()' /}
    {param prettify: true /}
    {param description}
      The glob() function is used to specifiy a set of files using patterns.
    {/param}
    {param content}

{call buck.rule}
{param status: 'FROZEN' /}
{param overview}
The <code>glob()</code> function is used to specify a set of files
using patterns. A pattern should be structured as a relative path with
no repeated or trailing separators (<code>/</code>).

Patterns may contain shell-like wildcards <code>*</code>, <code>?</code>, <code>[charset]</code>.

Additionally, a path element <code>**</code> will match any subpath. For instance
{sp}<code>foo&#x2F;**/bar</code> is equivalent to <code>["foo/bar", "foo&#x2F;*/bar", "foo&#x2F;*&#x2F;*/bar",
...]</code>.
{/param}

{param args}

{call buck.functionArg}
  {param desc}
  The first argument is a list of strings, identifying file name patterns used
  to match against files under the current directory.
  {/param}
{/call}

{call buck.functionArg}
  {param name : 'excludes' /}
  {param default : '[]' /}
  {param desc}
  A list of patterns to identify files that should be removed from the set
  specified by the first argument.
  {/param}
{/call}

{call buck.functionArg}
  {param name : 'include_dotfiles' /}
  {param default : 'False' /}
  {param desc}
  Whether <code>*</code> and <code>**</code> patterns should capture file or directory names
  starting with a dot.
  {/param}
{/call}

{/param}

{param examples}

For the purpose of the examples, we call 'regular' a file is that is
not a 'dotfile'. A file is a 'dotfile' (relatively to some current
directory) if its relative path includes at least one path element
starting with a dot.

All of the regular <code>.java</code> files in this directory:
<pre class="prettyprint lang-py">glob(['*.java'])</pre>

All of the <code>.java</code> files in this directory (now including
dotfiles):
<pre class="prettyprint lang-py">glob(['*.java'], include_dotfiles=True)</pre>

All of the files under this directory:
<pre class="prettyprint lang-py">glob(['**&#x2F'], include_dotfiles=True)</pre>

All of the regular files under the directory '.git':
<pre class="prettyprint lang-py">glob(['.git&#x2F**/'])</pre>

All of the files starting with '.' under a regular (non-dot) directory:
<pre class="prettyprint lang-py">glob(['**&#x2F.*'])</pre>

All of the regular <code>.java</code> and <code>.aidl</code> files in this directory:
<pre class="prettyprint lang-py">glob(['*.java', '*.aidl'])</pre>

All of the regular <code>.java</code> files under this directory:
<pre class="prettyprint lang-py">glob(['**&#x2F;*.java'])</pre>

All of the regular files under this directory that end in <code>Test.java</code>:
<pre class="prettyprint lang-py">glob(['**&#x2F;*Test.java'])</pre>

All of the regular files under this directory that end in <code>Test.java</code>,
as well as <code>StringTests.java</code>:
<pre class="prettyprint lang-py">glob(['**&#x2F;*Test.java', 'StringTests.java'])</pre>

All of the regular files under this directory that end in <code>Test.java</code>,
except for <code>HaltingProblemTest.java</code>:
<pre class="prettyprint lang-py">glob(['**&#x2F;*Test.java'], excludes = ['HaltingProblemTest.java'])</pre>

All of the regular <code>.java</code> files under this directory, except for those
that end in <code>Test.java</code>:
<pre class="prettyprint lang-py">glob(['**&#x2F;*.java'], excludes = ['**&#x2F;*Test.java'])</pre>

{/param}

{/call} // buck.rule
    {/param} // content
  {/call}
{/template}