========
PyCscope
========

:Copyright: Copyright 2012 Peter Portante.  See LICENSE for details.
:Author: Peter Portante
:Release: 1.1
:Date: 2012/10/01

Purpose
-------

A python script to generate a cscope index from a Python source
tree.  `pycscope` uses Python's own parser and (C)oncrete (S)yntax
(T)ree to generate the index, so it is a bit more accurate than
plain cscope.


Usage
-----

::

    pycscope.py [-D] [-R] [-S] [-V] [-t cnt] [-f reffile] [-i srclistfile] [files ...]
    -D              Dump the (C)oncrete (S)yntax (T)ree generated by the parser for each file
    -R              Recurse directories for files
    -S              Interpret simple strings as symbols
    -V              Print version and exit
    -t              Use 'cnt' threads (defaults to 1)
    -f reffile      Use 'reffile' as cross-ref file name instead of 'cscope.out'
    -i srclistfile  Use the contents of 'srclistfile' as the list of source files to scan

    
License
-------

Copyright 2012 Peter Portante

This program is free software; you can redistribute it and/or
modify it under the terms of version 2 of the GNU General
Public License as published by the Free Software Foundation.

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.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public
License along with this program; if not, write to the Free
Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA  02110-1301, USA


Install
-------

PyCscope uses Python's distutils package for installation.
Use the following command to install this package::

    % python setup.py install

    
Features
--------

PyCscope has the following features:

    - Supports both Python 2.7 and Python 3
    - Command line interface
    - Output can be used by the `CscopeFinder` plugin for jEdit
    - Marks for all files ending in `.py`
    - Marks for all `class` definitions
    - Marks for all defined functions
    - Marks for function calls (algorithm is not perfect)
    - Marks for end-of-function (no search uses this mark yet)
    - Marks for imported modules (use the search for #include)
    - Marks for symbol assignment

A *mark* is an indicator to the cscope utility that something
of interest follows.


History
-------

pycscope 0.3a and later are written and copyright Peter Portante.
pycscope 0.1 - 0.3 were originally written and copyright Dean Hall.


Status
------

It works well enough to generate an index file that can be used
by the `CscopeFinder` plugin for jEdit.  Other editors are not tested.


Release Notes
-------------

This is PyCscope release 1.1

==========  ========= ======  ====================================================
Date        Release   Trac    Changes
==========  ========= ======  ====================================================
2012/10/01  1.1       N/A     Fix Python3 support; enhance unit tests to run using
                              nose, generating coverage by default; fix broken
                              unit tests that were not properly run before the
                              switch to nose; add contrib area containing the
                              pyxcscope integration for (X)Emacs.
----------  --------- ------  ----------------------------------------------------
2012/09/20  1.0       N/A     Call it 1.0; update to use setuptools; drop .py from
                              installed script name; transition authorship from
                              Dean Hall to Peter Portante.
----------  --------- ------  ----------------------------------------------------
2012/09/19  0.3e-pajp N/A     Fix issues #7 and #8: we now properly handle symbols
                              closest to the assignment itself (rather than the
                              first one), and replace the crazy comma counting
                              method with a more stable pattern recognition method
                              that explicitly records which tuples should receive
                              the assignment mark; fixed handling of import state-
                              ments of the form, "from . import moda"
----------  --------- ------  ----------------------------------------------------
2012/09/18  0.3d-pajp N/A     Implement debugging help from Issue #9: dumpCst now
                              works on subtrees of tuples, not just lists.
----------  --------- ------  ----------------------------------------------------
2012/09/17  0.3c-pajp N/A     First pass fix of Issue #6 removing errant assertion
                              thus allowing symbol assignment marking to work as
                              coded (if not correctly, see Issue #7).
----------  --------- ------  ----------------------------------------------------
2012/09/11  0.3b-pajp N/A     Include changes from fspeech to get it working for
                              Python 3; add proper support for yield expression
                              following an augmented assignment; added support
                              for filename and line numbers when assertions fire;
                              fixed handling of commas on the left hand side of
                              assignment statements; gracefully handle errors
                              opening files.
                              GitHub issues: #5
----------  --------- ------  ----------------------------------------------------
2012/04/29  0.3a-pajp N/A     (NOTE: Failed to update version!)
                              Fix handling of DOS style line endings.
                              GitHub issues: #4
----------  --------- ------  ----------------------------------------------------
2012/04/13  0.3a-pajp N/A     (NOTE: Failed to update version!)
                              Fix handling of function definition decorators
                              GitHub issues: #2, #3
----------  --------- ------  ----------------------------------------------------
2012/03/11  0.3a-pajp N/A     (NOTE: Failed to update version!)
                              Change references from abstract syntax tree to
                              concrete syntax tree; fix handling of trailing
                              commas.
----------  --------- ------  ----------------------------------------------------
2012/03/05  0.3a-pajp N/A     Updated changes to support symbol assignment,
                              enhance unit test coverage, prepare code for PyCon
                              poster session.
----------  --------- ------  ----------------------------------------------------
2007/12/25  0.3       N/A     Included changes submitted by K. Rader of Google:
                              - Added the `-i` argument to specify a file-list 
                                file
                              - Fixups to the header and footer to make a valid 
                                file that cscope can read
----------  --------- ------  ----------------------------------------------------
2006/08/12  0.2       #33     Create 0.2 release.

                      #34     Change all "pyscope" to "pycscope"

                      #29     Make error reports less vague.

                      #23     Create distutils files.

                      #20     Create unit tests.

----------  --------- ------  ----------------------------------------------------
2006/08/02  0.1       None    Released to interested party by
                              email.

                      #19     Observe newlines even without
                              NEWLINE token.

                      #18     Newlines before MARK_FILE causes
                              exception.

                      #16     Work on "." default directory.

                      #10     Exception: TypeError in format.

                       #8     Class mark is incorrect.

                       #6     Create project space.
==========  ========= ======  ====================================================