The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

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.