pypersrc design

©2005  Jim E. Brooks  http://www.jimbrooks.org/hypersrc/

See also pypersrc implementation.

Contents

• Implementation
• Basic Features
• Advanced Features
• hypersrc behavior not to be continued in pypersrc
• Improvements and changes relative to hypersrc
• Command-line interface
• Viewing and projects
• Filtering (digest)
• Annotations
• Command results history

Implementation

See also pypersrc implementation.

Shall be implemented mostly in Python using (hopefully) the Tkinter GUI toolkit. C++ shall be used for performance and to overcome any Python deficiencies.

Shall be decoupled from the presentation and be GUI-neutral as much as practical. A concern is if Tkinter has deficiencies that necessitate switching to PyGtk. An option may be to execute pypersrc as a UNIX filter and output HTML per a cmd-line arg rather than running in GUI mode.

Basic Features

• Text widget shows HTML-like hyperlinks.
• Show various representations of source code (digest/filtering).
• Command-line interface inside the GUI which can produce HTML-like results.
• Annotate source files.
• Bookmarks.
• Marking source code.
• Project state.
• Track function calls (display graphs of execution flow).
• Expand function calls or bookmarks into a scratchpad.

Advanced Features

• Save persistent state

This can save time by skipping re-gathering and re-tagging. The user can click Refresh if the source directory was changed since the last save (re-gather will be redone but most tagging will be skipped).

• Show the contents of the text widget history similar to emacs's *Buffer List*.
• Render hyperlinks that were visited in a different color (eg purple).
• Bookmarks (esp. for func defs).
• Persistently mark blocks of code.

Marked blocks shall be shown in a highlight color and anchored to contexts (a few lines of surrounding code rather just line numbers).

• Expand into a text widget all of the code of every function that is called by one function.

The idea is to avoid even trying to jump around from one tag to another: all of the code is there in one window.

• When mouse is hovering over a func in a tree view, show that function's one-line comment.
• Count how many times a function call appears, then ignore the most called ones on the assumption that is an uninteresting function such as a log message.
• Show tree of derived methods. In Python esp. (Java too?), that a method is derived isn't apparent (because Python has no "virtual" keyword).
• Editable configuration.

Show something similar to a results widget that lists all the configuration variables as hyperlinks. The hyperlinks, when clicked, opens an entry widget (perhaps the Command entry can be reused for this and given a special color and its label changes from "Command" to "Edit [var]").

• Working set.

The user can mark tags which appear in a "working set" list. This lets the user to browse a few functions that are of interest.

hypersrc behavior not to be continued in pypersrc

• Eliminate the global tags list widget because it has proven to be overwhelming.

Perhaps instead provide a per-file tags list widget. Tags list widget has been replaced by Tk underlined hyperlinks.

• Duality of text widgets.

In pypersrc, the top text widget is the primary one. Clicking a hyperlink always loads the aux one. The user will learn to expect this behavior. hypersrc's duality of text widgets, ie, ability to hyperjump from one to the other, v.v, became confusing and you could easily lose the spot you were browsing.

Improvements and changes relative to hypersrc

• Let user browse more source files using a GUI file dialog.

The dialog can select an entire directory. Supporting this means the data structures must be more flexible than those in CHypersrc.

• Smarter handling of hyperlinks.
• Shall use the context surrounding the hyperlink to select the most appropriate tag.

For example:

    class MyClass
    {
        void Init( void );           <-- if this is clicked...
    };
    void MyClass::Init( void )     ...then this should be selected
    {
    }
    void Init( void )              ...but not this one
    {
    }
    

• Likewise for Python:

    class MyClass:

       __init__(self):
           self.ProcessArgs()   # hyperlink to ProcessArgs of this class only
    

• Shall notice which kind of source file was clicked so that a tag in a different kind of source file won't selected (eg if C++ and Python source files are both being browsed).

• Editing files shall be supported.
• Shall auto-update (or provide a Refresh button) when any source file being browsed is changed.
• class::method() should be shown in tree view, not as merely method().

This will require following the syntax that leads to the method, ie, understanding object reference/pointer variables, eg: pObj->Func() or worse p1->p2->m3.Func().

Command-line interface

A Tk text widget or text entry will receive commands from the user. The output may contain HTML-like results (clickable tags).

For example, if this command is given...

find tag *Init*

...then all tags that containing Init will be shown in a text widget using Tk underlined hyperlinks (as the main text widget currently does).

Tentative list of commands:

h [help]
b [browse]     <file or dir>
f [find]       <text>
ft [find tag]  <tag>

The cmd-line interface shall have a history buffer. When Pg Up is pressed, the previous page is shown, including the command that was given and its results.

Viewing and projects

Shall maintain different viewing contexts and offer the user to ability to flip back and forth (similar to browsing web pages).

Shall maintain project states which can be saved and reloaded. Shall cope with project source files being changed while the program wasn't running.

Filtering (digest)

Show source file in digested forms inside text widget:

• Digest (normal):

Ignore local vars, comments, etc: show just function calls. Calls which are conditional are shown with a '?' prefix.

• Digest (func defs):

Show only names of function definitions.

• Digest (comments):

Show mostly comments, no code.

• Digest (objects):

Show objects created within a function (???).

Annotations

• Show a "[type]" in italics after every name.

  status [mem] = false;
  foo( result [local] );

• Show a "Affects these globals:" above digested function definitions.

Command results history

(2005/01/17)
The prototype originally had a simple flipping between two states of text widget #2 when F12 was pressed. It was replaced by a history list (of the results of commands the user gave) that could be cycled by pressing F11 and F12. The history list was a bad GUI design and using it became confusing. For a time, the history list mixed source files and results which in itself was confusing. When a new set of results was produced, it was appended to the list, but if I cycled towards the middle of the history list, then entered a new command, the new results, since it was appended, was far away from the middle of the history list I was viewing. In short, cycling became too confusing and disorienting.

I decided to discard the mechanism for cylcling thru the history list and replace it by _showing_ the entire history list in text widget #2 in a way that is similar to emacs's *Buffer List*. This causes no confusion. The most recent set of results are shown at the top of the text widget.

Last modified: Sat May 7 22:28:53 EDT 2005