Metadata-Version: 2.1
Name: coccigrep
Version: 1.20
Summary: Semantic grep for C based on coccinelle
Home-page: http://home.regit.org/software/coccigrep/
Author: Eric Leblond
Author-email: eric@regit.org
License: UNKNOWN
Description: =========
        coccigrep
        =========
        
        Introduction
        ============
        
        Coccigrep is a semantic grep for the C and C++ languages based on
        Coccinelle (http://coccinelle.lip6.fr). It can be used to find where a given
        structure is used in code files. Coccigrep depends on the spatch
        program which comes with Coccinelle.
        
        Usage
        =====
        
        Run `coccigrep -h` for complete options.
        
        Examples
        ========
        
        To find where in a set of files the type named `Packet` is used, you
        can run ::
        
            $ coccigrep  -t Packet *c
            source-af-packet.c:272:         p = ptv->in_p;
            source-af-packet.c:300:     p->datalink = ptv->datalink;
            source-af-packet.c:758:     switch(p->datalink) {
        
        If you want to match on structure, you need to provide the complete name ::
        
            coccigrep -t 'struct seq_file' fs/seq_file.c
            fs/seq_file.c:654 (struct seq_file *seq): 	seq = f->private_data;
            fs/seq_file.c:655 (struct seq_file *seq): 	seq->private = private;
            fs/seq_file.c:537 (struct seq_file *m): 	if (m->count < m->size) {
        
        
        To find where in a set of files the `datalink` attribute is used in the structure
        named `Packet`, you can simply do ::
        
            $ coccigrep  -t Packet -a datalink  *c
            source-af-packet.c:300:     p->datalink = ptv->datalink;
            source-af-packet.c:758:     switch(p->datalink) {
            source-erf-dag.c:525:     p->datalink = LINKTYPE_ETHERNET;
        
        If you want to be more precise and find where this attribute is set, you can use 
        the operation flag (-o). One of its value is `set` which indicate we only want
        the match where the attribute is set ::
        
            $ coccigrep  -t Packet -a datalink -o set  source*c
            source-af-packet.c:300:     p->datalink = ptv->datalink;
            source-erf-dag.c:525:     p->datalink = LINKTYPE_ETHERNET;
        
        Installation
        ============
        
        The dependencies of coccigrep are spatch which comes with coccinelle. On python side, you
        need setuptools and optionally pygments (for colorized output). Happy Debian user can do ::
        
            aptitude install python-setuptools python-pygments
        
        To install coccigrep run ::
        
            sudo python ./setup.py install
        
        Configuration
        =============
        
        As from version 0.8, coccigrep can be configured via a configuration file. A complete sample of
        configuration file is available in the src/coccinelle.cfg.
        
        Hierarchical configuration
        --------------------------
        
        The configuration file system is hierarchical and the following files are parsed in that order
        
         - host config in /etc/coccigrep
         - user config in ~/.coccigrep
         - directory config in .coccigrep
        
        Thus, for example, the directory config settings will overwrite host config settings.
        
        Interesting options
        -------------------
        
        In the global section, the `concurrency_level` is the most interesting. It codes the number of
        spatch commands that will be launched in parallel. If multiple files are search, this will
        increase dramatically performances at the cost of a little increase of memory usage.
        
        If you want to add your own semantic patches, you just have to put them in a directory with
        name matchting the wanted operation name (`zeroed.cocci` will lead to the `zeroed` operation).
        Then add a `local_cocci_dir` pointing to this directory in the global section.
        
        For a description of the writing of semantic patches see `coccigrep homepage`_.
        
        .. _coccigrep homepage: http://home.regit.org/software/coccigrep/
        
        Other options are more explicit and are direct mapping of the associated command line option.
        
        Running coccigrep in vim
        ------------------------
        
        To use coccigrep in vim, you can use the `cocci-grep.vim` plugin provided in
        the `editors` directory. To do so you can simply copy it to your plugin directory
        which is usually `~/.vim/plugin/`. If your `coccigrep` script in not in your
        path, you can use the coccigrep_path variable to give complete path. For
        example, you can add to your `.vimrc` ::
        
            let g:coccigrep_path = '/usr/local/bin/coccigrep'
        
        And then you can run commands like ::
        
            :Coccigrep
            :Coccigrep Packet datalink source-*.c
            :Coccigrep Packet datalink set source-*.c
        
        First command will interactively ask you the value. Hit enter to use void
        value for type and/or attribute (only if operation does not need them).
        Second one will search all dereference of the datalink attribute for Packet
        structure. The last one will look where the set operation is done on the
        datalink attribute of Packet. To get the list of operations on your system,
        you can run `coccigrep -L` or look at the list provided when input for
        operation is asked in interactive mode.
        
        The matches will appear in the `quickfix list` and the file corresponding to first
        match will be opened at the corresponding line. Note that you can use completion on
        structure and attribute names based on tags (generated by `make tags`).
        
        To run a search in vim on a non-named structure, you must quote the spaces and
        thus run something like ::
        
            :Coccigrep "struct nfq_data"  s*c
        
        Please note that, in interactive mode, quoting is not necessary.
        
        You can also set the global variable `coccigrep_files` ::
        
            :let g:coccigrep_files = '~/myproject/src/flist'
        
        where `flist` is the file corresponding to the `-l` option.
        And then you can run commands like ::
        
            :Coccigrep Packet
            :Coccigrep Packet datalink set
        
        That is, you don't need to provide the last argument of the previous examples.
        This is particularly useful if you set vim's autochdir option.
        
        Running coccigrep in emacs
        --------------------------
        
        To use coccigrep in emacs, you need to load the `cocci-grep.el` module provided in the `editors`
        directory of the source code. For example, if you copy it in `~/.emacs.d/site-lisp/`, you
        can do ::
        
            (add-to-list 'load-path "~/.emacs.d/site-lisp/")
            (require 'cocci-grep)
        
        And then you can run something like ::
        
            Meta+x cocci-grep
        
        and answer to the questions which are
        
         - Type: The structure type you are searching
         - Attribut: The attribute in the structure
         - Operation: The operation on the structure. The set of commands include set,used,func,test,deref
         - Files: A blob expression that will match the file you want to search in
        
        The matches will appear in a buffer with mode set to `grep-mode` and you will thus be able to jump
        on occurence. History is available on the different parameters.
        
        Current limitations
        ===================
        
        - **Macros**: Coccigrep won't expand the macros for you, so code contained in them won't be matched.
        - **Nested functions**: Coccinelle might not match code inside a nested function,
          and so does coccigrep.
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development
Provides: coccigrep
Description-Content-Type: text/x-rst
