/ 
File-CodeSearch-v0.7.6
River stage zero No dependents
/ cs

NAME

cs - Search and/or replace text (with some intelligence)

VERSION

This documentation refers to cs version 0.7.6.

SYNOPSIS

  cs [option] search
  cs [option] search -r replace
  cr [option] search replace

OPTIONS:
 search         A perl regular expression. if it is written in multiple parts
                eg search this on the command line (ie no joinded together
                with quotes) the parts will be joined together with \s or
                if --all is used a regular expression will be written
                containing each part in every order, if --words the parts are
                seperated by .*'s.
 replace        The value to substitute for the values found by search

 Search:
  -a --all      Find all parts on regardless of order on the line
  -W --words    Similar to --all but with out the reordering
  -i --ignore-case
                Turn off case sensitive searching
  -w --whole    Makes the match only whole words (ie wraps with (?<\W) & (?=\W))
  -c --contains[=]re
                Only show matches if the file also matches this sub regex.
                This may be declared more that once and the results are ORed.
  -S --not-contains[=]re
                Ignore any files whoes contents match this regex.
  -m --smart    Converts multi part regexes baised on what is imput
                eg cs ss Class is converted to cs class Class
                   cs n func                   cs function func
                   cs b subroutine             cs sub subroutine
 Replace:
  -r --replace[=]string
                String to replace found text with
 Files:
  -p --path[=]string
                A colon seperated list of directories to search in, which may
                include globing but you must quote so the shell doesn't do
                the globbing itself.
                (Default is current directory)
  -l --follow-symlinks
                Follow symlinks to directories
     --no-follow-symlinks
                Don't follow symlinks to directories
     --recurse  Recurse into subdirectories (Default)
     --no-recurse
                Turns off recursing into subdirectories
  -n --file-include[=]string
                Only include files mathcing the regex (Multiple)
  -N --int[=]string
     --include-type[=]string
                Only include files the specified type (Mulitple)
                see perldoc File::TypeCategories available types
  -x --file-exclude[=]string
                Don't include files mathcing the regex (Multiple)
  -X --ext[=]string
     --exclude-type[=]string
                Don't include files the specified type (Mulitple)
                see perldoc File::TypeCategories available types
      --ignore[=]type
                Add type to the types to be ignored (multiples ok, overwrites default types)
   -d --ignore_add[=]type
                Add extra type to default types (multiples ok)
   -I --ignore_remove[=]type
                Remove type from default types (multiples ok)
 Output:
  -C --context[=]int
                Show int lines of context before and after a match
  -B --before[=]int
                Show int lines before a match
  -A --after[=]int
                Show int lines after a match
  -t --totals
                Show the total number of lines & files matched
  -f --files-only
                Show only the file names containg matches
  -L --last[=][function|class|sub]
                Show the last function, class or sub name found before the
                matched line.
  -q --quiet    Turn off warnings about unreadable files & directories.
  -u --unique   Show only unique matches (just the match not the whole line)
     --limit[=]int
                Only show this number of found search results
 Other:
  -E --execute[=]cmd
                Run this command with the found files as arguments
  -P --project[=]string
                Use the specified projects default settings
  -c --config[=]file
                Use the specified file as the config file instead of the
                deafult ~/.cs

  -v --verbose  Show more detailed option
     --VERSION  Prints the version information
     --help     Prints this help information
     --man      Prints the full documentation for cs with example usage

DESCRIPTION

The cs command is aimed at searching large quantities of text files with the ability to easily select searching files by type (or excluding files of a certain type). Also by default cs excludes version control directories eg .svn or .git.

Examples

cs --path lib:t query

This would search both the directories lib/ and t/ for files containing the work query.

cs --include-type=perl --smart b do_stuff

This would search only perl files (.pl, .pm and files with the first line containing perl eg #!/usr/bin/perl or #!/usr/bin/env perl) for any declaration of a subroutine who's name starts with do_stuff eg sub do_stuff_again.

cs --exclude-type=html input

Would search all non-html files (.html, .htm, .xhtml etc) for the word input

cs --after 5 text

This would show up to 5 lines of text following any links that match text

cs --files-oly text

This would show only the names of files that contain text. This can speed the search considerably as files are stopped being searched after a single match is found

cs --unique 'CONST_[A-Z0-9]'

This will search for all upper case words starting with CONST_ and show a unique list of matched words, no files or matched lines are shown.

SUBROUTINES/METHODS

DIAGNOSTICS

CONFIGURATION AND ENVIRONMENT

A configuration file placed in ~/.csrc (or specified through --conf) allows allows the setting of default values. See Config::General for full details of the file format.

Eg

<default>
    smart = 1
</default>

<file_types>
    <perl>
        definite    = [.]pl$  # Definite match regexps can be specified mulitple
        definite    = [.]pm$  # times to form a list of definit matches
        definite    = [.]pod$ # Note this replaces the predefined list
        definite    = [.]PL$

        possible    = [.]t$   # As can possiple matches
        possible    = [.]cgi$

        none        = 1       # set files with out a suffix to match as perl files
        bang        = perl    # Causes the reading of the first line of a file
                              # to check if it contains /perl/ (and there fore matches)
    </perl>
    <python>
        +definite   = [.]pthony$ # Adds this regexp to the default list of
                                 # regexps that definitly phyton files
    </python>
<file_types>

<project proj>
  exclude = /path/to/excluded/dir
</project>

<project other_work>
  file-exclude = large[.]file$
</project>

In the default section, default values for command line options can be specified.

In the file_types section, you can add new file types or override or change existing file types.

In the project section, you can add defaults specific to a project which can be specified on the command line as --project=proj

Pager

By default cs uses the command less -Rx4SFX if it can run other wise it falls back just writing to STDOUT. You can change this environment variable CS_PAGER_COLOR

DEPENDENCIES

Some of the --smart capabilities (ie paging output) require the less command to be installed other wise the paging wont available.

INCOMPATIBILITIES

BUGS AND LIMITATIONS

There are no known bugs in this module.

Please report problems to Ivan Wills (ivan.wills@gmail.com).

Patches are welcome.

ALSO SEE

grep -r - Recursive grep, can be much faster but will search into version control directories and has to be used with find to limit the searched files.

ack - This a very similar in syntax to grep but can't do replacements which cs can.

AUTHOR

Ivan Wills - (ivan.wills@gmail.com)

LICENSE AND COPYRIGHT

Copyright (c) 2009 Ivan Wills (14 Mullion Close, Hornsby Heights, NSW Australia 2077). All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.