Readme/Help for PyPE (Python Programmer's Editor)
http://pype.sourceforge.net
http://come.to/josiah

PyPE is copyright 2003-2005 Josiah Carlson.
Contributions are copyright their respective authors.

This software is licensed under the GPL (GNU General Public License) as it
appears here: http://www.gnu.org/copyleft/gpl.html
It is also included with this archive as gpl.txt.

The included STCStyleEditor.py, which is used to support styles, was released
under the wxWindows license and is copyright (c) 2001 - 2002 Riaan Booysen.
The copy included was also distributed with wxPython version 2.4.1.2 for
Python 2.2, and was not modified in any form.

The included stc-styles.rc.cfg was slightly modified from the original version
in order to not cause exceptions during style changes, and was also
distributed with wxPython version 2.4.1.2 for Python 2.2

If you do not also receive a copy of gpl.txt with your version of this
software, please inform the me of the violation at the web page at the top of
this document.


#------------------------------- Requirements --------------------------------
PyPE 2.x has only been tested on Python 2.3 and wxPython 2.5.3.1.  It should
work on later versions of Python and wxPython.  If you are having issues, file
a bug report on http://sourceforge.net/projects/pype .

#----------------------------------- Help ------------------------------------
What the heck is a Trigger?
Let us say that you writing a web page from scratch.  Let us also say that
typing in everything has gotten a bit tiresome, so you want to offer yourself
a few macro-like expansions, like 'img' -> '<img src="">'.
1. Go to: Document->Set Triggers.
2. Click on 'New Trigger'.
3. In the 'enter' column of the new trigger, type in 'img' (without quotes).
4. In the 'left' column, type in '<img src="' (without single-quotes).
5. In the 'right' column, type in '">' (without single quotes).

In the future, if you type in 'img' (wihout quotes) and use
Edit->Perform Trigger, it will expand itself to '<img src="">' (without single
quotes) with your cursor between the two double quotes.

What other nifty things are possible?  How about automatic curly and square
brace matching with [, [, ] and {, {, }?  Note that triggers with a single
character in the 'enter' column are automatically done as you type, but
triggers with multiple characters in the 'enter' column require using
Edit->Perform Trigger (or its equivalent hotkey if you have assigned one).

The semantics for string escapes are identical to that of standard string
escapes in Python.



What happens when "Smart Case" is enabled during a replace?
If the found string is all upper or lower case, it will be replaced by a
string that is also all upper or lower case.

Else if the length of the found string is the same length as the replacement
string, you can replace one string for another, preserving capitalization.

For example...

    def handleFoo(foo, arg2):
        tfOO = fcn(foo)
        tFOO2 = fcn2(tfOO)
        return fcn3(tfOO, tFOO2, foo)

...becomes...

    def handleGoo(goo, arg2):
        tgOO = fcn(goo)
        tGOO2 = fcn2(tgOO)
        return fcn3(tgOO, tGOO2, goo)

...by enabling "Smart Case", and putting 'foo' and 'goo' in the find/replace
boxes.

Otherwise if the first letter of the found string is upper or lowercase, then its
replacement will have the first letter be upper or lowercase respectively.


What is up with the "Enable File Drops" checkbox in the 'Edit' menu?
1. Select some text.
2. Now click on it.
Q: Do you want the selection to go away, and your cursor to be close to where
   you clicked?
If yes, uncheck the box and restart if necessary.
If no, check the box and restart if necessary.
(The check is effective for any opened document from then on, but does not
change the behavior of already opened documents.)
One should always be able to drag and drop text.  One should always be able to
drag and drop files everywhere, except for the text editor portion.  If
checked, you can drop files on the editor portion, if unchecked, you won't be
able to drop files on the text editor portion.



How do I use the 'Todo' list?
On a line by itself (any amount of leading spaces), place something that
matches the following regular expression: #([a-zA-Z0-9 ]+):(.*)
The first group (after a .strip().lower() translation) will become category in
the 'Cateogry' column, the second group (after a .strip()) becomes the todo in
the 'Todo' column, and the number of exclamation points will become the number
in the '!' column.

Well, it is a bit smarter, it tosses all entries with a 'Category' that is
also a keyword (keyword.kwlist), or one of the following: http, ftp, mailto,
news, gopher, and telnet.

The following lines are all valid todos;
# todo: fix the code below
        #todo:fix the code below!
    #        TODo: fix the code below
  #bug:I am a big ugly bug...no, I really am, but I'm also a todo
# this thing can even have spaces: but it cannot have punctuation!

#I am not a valid todo...: because there is punctuation on the left



What are the currently known bugs within PyPE's parser?
Well, it basically splits the file into lines, does a check to see if there is
a function, class, or comment on that line, then saves the heirarchy
information based on the level of indentation and what came before it.  This
can be innaccurate, as it will mistakenly believe that the below function
'enumerate' is a method of MyException.

class MyException(exceptions.Exception):
    pass
try:
    enumerate
except:
    def enumerate(inp):
        return zip(range(len(inp)), inp)

It also doesn't know anything about multi-line strings, so the definition nada
in the following line would be seen as a function, and not part of a string.

old = 'this used to be a function\
def nada(inp):\
    return None'

Ah well, one has to give up something for speed.  Another thing given up is
that the parser will not pull out doc strings or handle multi-line function
definitions properly.  This may be changed in the future (parsing is an
entertaining and educational topic), but it will likely ALWAYS be inaccurate.



Calltips:
How do you get usable Calltips?  Easy.  Hit F5.  This will also rebuild the
browsable source tree, autocomplete listing, and todo list.



Autocompletion:
How do you get autocompletion?  Easy.  In the 'Document' menu, there is an
entry for 'Show autocomplete'.  Make sure there is a check by it, and you are
set.  If you want to get a new listing of functions, hit the F5 key on your
keyboard.



CRLF/LF/CR line endings:
PyPE will attempt to figure out what kind of file was opened, it does this by
counting the number of different kinds of line endings.  Which ever line
ending appears the most in an open file will set the line ending support for
viewing and editing in the window.  Also, any new lines will have that line
ending.  New files will have the same line endings as the host operating
system.

Additionally, copying from an open document will not change the line-endings.
Future versions of PyPE may support the automatic translation of text during
copying and pasting to/from the host operating system's native line endings.

Converting between line endings is a menu item that is available in the
'Document' menu.



STCStyleEditor.py:
As I didn't write this, I can offer basically no support for it.  It seems to
work to edit python colorings, and if you edit some of the last 30 or so lines
of it, you can actually use the editor to edit some of the other styles that
are included.

If it just doesn't work for you, I suggest you revert to the copy of the
editor and stc-styles.rc.cfg that is included with the distribution of PyPE
you received.  As it is a known-good version, use it.



Expandable/collapseable/foldable code:
Since the beginning, there have been expandable and collapseale scopes thanks
to wxStyledTxtCtrl.  How to use them...
Given the below...
- class nada:
-     def funct(self):
-         if 1:
|             #do something
|             pass
Shift-clicking the '-' next to the class does this...
- class nada:
+     def funct(self):

Or really, it's like ctrl-clicking on each of the functions declared in the
scope of the definition.
Shift-clicking on the '-' a second time does nothing.
Shift-clicking on a '+' expands that item completely.

Control-clicking on a '+' or '-' collapses or expands the entirety of the
scopes contained within.

I don't know about you, but I'm a BIG fan of shift-clicking classes.  Yeah.
Play around with them, you may like them.



Find/Replace bars:
One big thing to note is how the find/replace bars work.  For those of you who
are annoyed with one's normal inability to enter in things like newlines, this
will be a great thing for you.

If you have ' or " as the last character in a find or find/replace entry, and
what you entered is a proper string declaration in Python, PyPE will use the
compiler module to parse and discover the the string.  For example, to
discover Unix LF charactesr, use "\n" including quotes.



Converting between tabs and spaces:
So, you got tabs and you want spaces, or you have spaces and want to make them
tabs.  As it is not a menu option, you're probably wondering "how in the hell
am I going to do this".  Well, if you read the above stuff about replacing, it
would be trivial.
Both should INCLUDE the quotation marks.
To convert from tabs to 8 spaces per tab; replace "\t" with "        "
To convert from 8 spaces to one tab; replace "        " with "\t"

#-------------------------- How did PyPE come about --------------------------
The beginnings of PyPE was written from 10:30PM on the 2nd of July through
10:30PM on the 3rd of July, 2003.  Additional features were put together on
the 4th of July along with some bug fixing and more testing for version 1.0.
Truthfully, I've been using it to edit itself since the morning of the 3rd of
July, and believe it is pretty much feature-complete (in terms of standard
Python source editing).  There are a few more things I think it would be nice
to have, and they will be added in good time (if I have it).

On the most part, this piece of software should work exactly the way you
expect it to...or at least the way I expect it to.  That is the way I wrote
it.  As a result, you don't get much help in using it (mostly because I am
lazy).  When questions are asked, I'll add the question and answer into the
FAQ, which is at the end of this document.  There has been discussion of a
PyPE wiki, so who knows, maybe documentation will get better.


The majority of the things that this editor can do are in the menus.  Hot-keys
for things that have them are listed next to their menu items.  As I am still
learning all the neat things one can do with wxStyledTxtCtrl, I don't know all
the built-in features, and this is likely as much of a learning experience for
me as you.


#------------------------------------ FAQ ------------------------------------
What's the deal with the version numbering scheme?
Early in development, PyPE raised version numbers very quickly.  From 1.0 to
1.5, not much more than 2 months passed.  In that time, most of the major
architectural changes that were to happen, happened.  This is not the reason
for the version number change.  Really it was so that the MAJOR versions could
have their own point release (1.0 being the first), and minor bugfixes on the
point releases would get a minor release number (like 1.0.1).

Then, at around PyPE 1.4.2, I had this spiffy idea.  What if I were to release
a series of PyPE versions with the same version numbers as classic Doom?  I
remembered updating to 1.1, then to 1.2a, etc.  My favorite was 1.666.  Ah hah!
PyPE 1.6.6.6, the best version of PyPE ever.

I decided that I would slow version number advancement, if only so that people
didn't get sick of new releases of PyPE being numbered so much higher, being
that there are other projects where version 1.0 (if it is ever released) would
be the perfect release, that there is no more changes to be made.

Then the more I thought about it, the more I realized that it doesn't matter
at all, I mean, Emacs is on version 20+.  *shrug*

When PyPE 1.9.3 came out, I had a few other ideas for what I wanted to happen,
but since major changes needed to happen, it really should get a major number
bump to 2.0.  After spending 3 months not working on it May-July 2004, I got
some time to muck around with it here and there.  After another few months of
trying to rebuild it to only require a single STC (with multiple document
pointers, ...) I realized that I'd have to rebuild too much of PyPE to be able
to get 2.0 out the door by 2010.  So I started modifying 1.9.3.  All in all,
around 85% of what I wanted made it into PyPE 2.0, the rest was either
architectural (ick), or questionable as to whether or not anyone would even
want to use the feature (even me).


#-------------------------------- Thank Yous ---------------------------------
Certainly there are some people I should thank, because without them, the
piece of software you are using right now, just wouldn't be possible.

Guido van Rossum - without Guido, not only would I not have Python, I also
wouldn't have had some of the great inspiration that IDLE has offered.  IDLE
is a great editor, has some excellent ideas in terms of functionality, but it
unfortunately does not offer the extended functionality I want, and it hurts
my brain to use tk, so I cannot add it myself.  Guido, my hat goes off to you.

The people writing wxWindows and wxPython - without you, this also would not
have been possible.  You have made the most self-consistent GUI libraries that
I have ever used, made them easy to use, and offer them on every platform that
I would ever want or need.  You rock.

Neil Hodgson and others who work on Scintilla.  As wxStyledTextCtrl is a
binding for scitilla in wxWindows, which then has bindings for wxPython,
basically ALL the REAL functionality of the editor you are now using is the
result of Scintilla.  The additional things like tabbed editing, hotkeys,
etc., they are mere surface decorations in comparison to what it would take to
write everything required for a text editor from scratch.  Gah, an editor
widget that just works?  Who would have figured?

To everyone who I have already thanked: thank you for making PyPE an almost
trivial task.  It would have been impossible to go so far so fast by hand in
any other language using any other GUI toolkit or bindings.

And my wife - because without her, I would likely be a pathetic shell of a
man...or at least single, bored, and uncouth.
#------------------------------- End of file. --------------------------------
