OK, now that we have python-calculate-indentation finished let's see who calls it (and hopefully work our way up to the point that tab cycling actually works).
So here are the call chains for python-calculate-indentation and a couple of related functions.
python-indent-line
python-indent-line-1
python-calculate-indentation
python-block-end-p
python-indent-region
python-indent-line-1
python-calculate-indentation
python-electric-colon
python-calculate-indentation
So our new functions we will bring over this time are:
python-block-end-p
python-indent-line-1
python-indent-line
python-indent-region
python-electric-colon
That's about 90 lines so that's good for one session. In addition to these functions we'll add a in the key mapping for python-electric-colon and the indent assignments within define-derived-mode (indent-line-function, indent-region-function).
Well, I don't know yet know *why*, but I can confirm that tab cycling works as I expected. Hopefully it will be clear as I go through the code what exactly is happening.
As for the electric colon, after experimenting around I was able to figure out a scenario which makes a line of code "outdent" as promised:
if foo:
bar
else:
My first instinct is to try to understand the tab cycling by digging down from the top and seeing how the tab key itself is bound.
TAB (translated from) runs the command indent-for-tab-command
which is an interactive compiled Lisp function in `indent.el'.
It is bound to TAB.
(indent-for-tab-command &optional arg)
Indent line in proper way for current major mode or insert a tab.
Depending on `tab-always-indent', either insert a tab or indent.
If initial point was within line's indentation, position after
the indentation. Else stay at same point in text.
The function actually called to indent is determined by the value of
`indent-line-function'.
So this points us to indent.el which is where the magic happens and defines why the major mode needs to define indent-line-function and indent-region-function.
My next step was to look for descriptions of this indent functionality in the emacs manual but I quickly got tired of poring over that. So back to looking at the code in the library.
So let's work through the functions above:
python-block-end-p
python-indent-line-1
python-indent-line
python-indent-region
python-electric-colon
- python-block-end-p
Check to see if the current line is the last line of an indented block. It's sort of surprising that this functionality hasn't been needed so far.
It checks that the current line is not a comment and that that either: it's for sure the end of a block (e.g. raise, etc) or the current indentation is less that the previous line's indentation.
That seems a little loose on the meaning of what I would expect a block-end checker to do. But from looking at how it is used in context I see that it probably is sufficient for it purpose. Basically it is simply being used to determine whether or not to display a message about what block is being closed by the position that the current indenting level. So close enough. Might be confusing if someone tried to use this function more generally.
- python-indent-line-1
The comments for this function indicate that this is how indenting would be done if there was no cycling. Which essentially means it will take the last value from the full list of possibilities and just use that.
- python-indent-line
So this is essentially the money function for doing tab cycling and now that I know so much more about the work going on underneath the covers it seems comically short. And I certainly wouldn't have really understood just how magical this function is without looking at the gory details myself.
The basic logic is to check if we are already cycling. If so then we move to the next known position and try to show what code block we are closing if that makes sense.
If we are just starting a tab cycle then we just call python-indent-line-1 and set up python-indent-index to be ready for cycling.
- python-indent-region
So this function is a little strange. According to the emacs manual indent-region-function is used to act as a fast way to indent lines. The default behavior is to just run the indent-line-function on each line. But this code just goes ahead and loops over every line and just runs python-indent-line for each. Nothing obvious in this code to indicate what the advantage of walking over each line by hand would be. A mystery.
- python-electric-colon
So this guy is mapped to ":" and usually just inserts a ":" unless we have the case I outlined above. The basic logic is to check if we are at the end of a line, whether we are in an outdentable context (python-outdent-p), not in a string or comment and we are past the point that it is predicted we should be indented to.
This function is followed by:
(put 'python-electric-colon 'delete-selection t)
Which as far as I can tell is related to delsel.el. Apparently delete-selection is used by this mode when you are deleting selected text a la windows behavior (ie delete selected text when you type).
Now that I have tab cycling pretty much wrapped up I have this hope that much of the rest of the code will be a little more straight forward.What can I say, I'm an optimist at heart.
As far as code coverage goes, I've copied over 33% of the code. Wow, I'm a third of the way done.
No comments:
Post a Comment