annotate grep.xml @ 20:fbf99087e067 draft default tip

planemo upload for repository https://github.com/bgruening/galaxytools/tree/master/tools/text_processing/text_processing commit c4f50d1ee81c1618344ede1f04a46a28d8068bcc

<tool id="tp_grep_tool" name="Search in textfiles" version="@TOOL_VERSION@+galaxy@VERSION_SUFFIX@" profile="@PROFILE@">
    <description>(grep)</description>
    <macros>
        <import>macros.xml</import>
    </macros>
    <expand macro="creator"/>
    <requirements>
        <requirement type="package" version="3.11">grep</requirement>
        <requirement type="package" version="4.8">sed</requirement><!-- for ansi2html.sh -->
    </requirements>
    <stdio>
        <exit_code range="2:" level="fatal" description="grep failed" />
    </stdio>
    <version_command>grep --version | head -n 1</version_command>
    <command>
<![CDATA[
        #if str($color) == "COLOR":
            GREP_COLOR='1;34'
            grep
                --color=always
                $regex_type
                -A $lines_after
                -B $lines_before
                $invert
                $case_sensitive
                -- '${url_paste}'
                '${infile}' | '$__tool_directory__/ansi2html.sh' > '${output}'
        #else:
            grep
                $regex_type
                -A $lines_after
                -B $lines_before
                --no-group-separator
                $invert
                $case_sensitive
                 -- '${url_paste}'
                '${infile}' > '${output}'
        #end if
]]>
    </command>
    <inputs>
        <param name="infile" format="txt" type="data" label="Select lines from" />

        <param name="invert" type="select" label="that">
            <option value="">Match</option>
            <option value="-v">Don't Match</option>
        </param>

        <param name="regex_type" type="select" label="Type of regex">
            <option value="-G">Basic (-G)</option>
            <option value="-P" selected="true">Perl (-P)</option>
            <option value="-E">Extended (egrep -E)</option>
        </param>

        <param name="url_paste" type="text" label="Regular Expression" help="See below for more details">
            <sanitizer>
                <valid initial="string.printable">
                    <remove value="&apos;"/>
                </valid>
            </sanitizer>
        </param>

        <param name="case_sensitive" type="select" label="Match type" help="(-i)">
            <option value="-i">case insensitive</option>
            <option value="">case sensitive</option>
        </param>
        <param name="lines_before" type="integer" value="0"
            label="Show lines preceding the matched line" help="leave it at zero unless you know what you're doing. (-B)" />
        <param name="lines_after" type="integer" value="0"
            label="Show lines trailing the matched line" help="leave it at zero unless you know what you're doing. (-A)" />
        <param name="color" type="select"  label="Output">
            <option value="NOCOLOR">text file (for further processing)</option>
            <option value="COLOR">Highlighted HTML (for easier viewing)</option>
        </param>

    </inputs>
    <outputs>
        <data name="output" format_source="infile" metadata_source="infile">
            <change_format>
                <when input="color" value="COLOR" format="html"/>
            </change_format>
        </data>
    </outputs>
    <tests>
        <!-- grep a FASTA file for sequences with specific motif -->
        <test>
            <param name="infile" value="grep1.txt" />
            <param name="case_sensitive" value="case sensitive" />
            <param name="regex_type" value="-P" />
            <param name="invert" value="" />
            <param name="url_paste" value="AA.{2}GT" />
            <param name="lines_before" value="1" />
            <param name="lines_after" value="0" />
            <param name="color" value="NOCOLOR" />
            <output name="output" file="grep_results1.txt" />
        </test>
        <!-- grep a FASTA file for sequences with specific motif -
             show highlighed output -->
        <test>
            <param name="infile" value="grep1.txt" />
            <param name="case_sensitive" value="case sensitive" />
            <param name="regex_type" value="-P" />
            <param name="invert" value="" />
            <param name="url_paste" value="AA.{2}GT" />
            <param name="lines_before" value="0" />
            <param name="lines_after" value="0" />
            <param name="color" value="COLOR" />
            <output name="output" file="grep_results2.html" />
        </test>
        <!-- tests egrep -->
        <test>
            <param name="infile" value="egrep1.txt" />
            <param name="case_sensitive" value="case sensitive" />
            <param name="regex_type" value="-E" />
            <param name="invert" value="" />
            <param name="url_paste" value="[^ ]+" />
            <param name="lines_before" value="0" />
            <param name="lines_after" value="0" />
            <param name="color" value="NOCOLOR" />
            <output name="output" file="egrep_results1.txt" />
        </test>
        <!-- tests basic regex; + must be backslashed to match -->
        <test>
            <param name="infile" value="egrep1.txt" />
            <param name="case_sensitive" value="case sensitive" />
            <param name="regex_type" value="-G" />
            <param name="invert" value="" />
            <param name="url_paste" value="[^ ]\+" />
            <param name="lines_before" value="0" />
            <param name="lines_after" value="0" />
            <param name="color" value="NOCOLOR" />
            <output name="output" file="egrep_results1.txt" />
        </test>
        <!-- tests regex;matching nothing -->
        <test>
            <param name="infile" value="egrep1.txt" />
            <param name="case_sensitive" value="case sensitive" />
            <param name="regex_type" value="-G" />
            <param name="invert" value="" />
            <param name="url_paste" value="not existent pattern" />
            <param name="lines_before" value="0" />
            <param name="lines_after" value="0" />
            <param name="color" value="NOCOLOR" />
            <output name="output">
                <assert_contents>
                    <has_size value="0"/>
                </assert_contents>
            </output>
        </test>
        <!-- tests invalid regex; i.e. that we still get exit code 2 -->
        <test expect_failure="true" expect_exit_code="2">
            <param name="infile" value="egrep1.txt" />
            <param name="case_sensitive" value="case sensitive" />
            <param name="regex_type" value="-G" />
            <param name="invert" value="" />
            <param name="url_paste" value="\(" />
            <param name="lines_before" value="0" />
            <param name="lines_after" value="0" />
            <param name="color" value="NOCOLOR" />
        </test>
    </tests>
    <help>
<![CDATA[
**What it does**

This tool runs the unix **grep** command on the selected data file.

.. class:: infomark

**TIP:** This tool uses the **perl** regular expression syntax (same as running 'grep -P'). This is **NOT** the POSIX or POSIX-extended syntax (unlike the awk/sed tools).


**Further reading**

- Wikipedia's Regular Expression page (http://en.wikipedia.org/wiki/Regular_expression)
- Regular Expressions cheat-sheet (PDF) (http://www.addedbytes.com/cheat-sheets/download/regular-expressions-cheat-sheet-v2.pdf)
- Grep Tutorial (http://www.panix.com/~elflord/unix/grep.html)

-----

**Grep Examples**

- **AGC.AAT** would match lines with AGC followed by any character, followed by AAT (e.g. **AGCQAAT**, **AGCPAAT**, **AGCwAAT**)
- **C{2,5}AGC** would match lines with 2 to 5 consecutive Cs followed by AGC
- **TTT.{4,10}AAA** would match lines with 3 Ts, followed by 4 to 10 characters (any characeters), followed by 3 As.
- **^chr([0-9A-Za-z])+** would match lines that begin with chromsomes, such as lines in a BED format file.
- **(ACGT){1,5}** would match at least 1 "ACGT" and at most 5 "ACGT" consecutively.
- **hsa|mmu** would match lines containing "hsa" or "mmu" (or both).

-----

**Regular Expression Syntax**

The select tool searches the data for lines containing or not containing a match to the given pattern. A Regular Expression is a pattern descibing a certain amount of text.

- **( ) { } [ ] . * ? + \ ^ $** are all special characters. **\\** can be used to "escape" a special character, allowing that special character to be searched for.
- **^** matches the beginning of a string(but not an internal line).
- **\\d** matches a digit, same as [0-9].
- **\\D** matches a non-digit.
- **\\s** matches a whitespace character.
- **\\S** matches anything BUT a whitespace.
- **\\t** matches a tab.
- **\\w** matches an alphanumeric character ( A to Z, 0 to 9 and underscore )
- **\\W** matches anything but an alphanumeric character.
- **(** .. **)** groups a particular pattern.
- **\\Z** matches the end of a string(but not a internal line).
- **{** n or n, or n,m **}** specifies an expected number of repetitions of the preceding pattern.

  - **{n}** The preceding item is matched exactly n times.
  - **{n,}** The preceding item ismatched n or more times.
  - **{n,m}** The preceding item is matched at least n times but not more than m times.

- **[** ... **]** creates a character class. Within the brackets, single characters can be placed. A dash (-) may be used to indicate a range such as **a-z**.
- **.** Matches any single character except a newline.
- ***** The preceding item will be matched zero or more times.
- **?** The preceding item is optional and matched at most once.
- **+** The preceding item will be matched one or more times.
- **^** has two meaning:
  - matches the beginning of a line or string.
  - indicates negation in a character class. For example, [^...] matches every character except the ones inside brackets.
- **$** matches the end of a line or string.
- **\|** Separates alternate possibilities.

]]>
    </help>
    <expand macro="citations" />
</tool>