understanding the function outline-level

understanding the function outline-level

[Michael Brand]

Hi all

I am on the way of tracking down an (Org?) buglet and now
outline-level tries to strike me with my lack of experience with
"Match Data" of Emacs search and I would like to ask for some help to
understand.

M-: (outline-level) returns a value that I don't understand yet. The
number does not correspond to the amount of stars and is independent
of at the beginning of which line the point was before. And when I
look at the implementation of outline-level I am missing a function
that initializes the "Match Data". Where is that last search or match
operation?

Michael

Re: understanding the function outline-level

[Jambunathan K]

Michael Brand <michael.ch.brand@gmail.com> writes:

> Hi all
>
> I am on the way of tracking down an (Org?) buglet and now
> outline-level tries to strike me with my lack of experience with
> "Match Data" of Emacs search and I would like to ask for some help to
> understand.
>
> M-: (outline-level) returns a value that I don't understand yet. The
> number does not correspond to the amount of stars and is independent
> of at the beginning of which line the point was before. And when I
> look at the implementation of outline-level I am missing a function
> that initializes the "Match Data". Where is that last search or match
> operation?

(A quick hint. May not be complete though)

The typical call sequence seems to be:

1. Move the cursor to a headline.
2. Call outline-level.

It is (1) which presumably does a regexp search and ends up in the
headline.

So outline-level cannot be called in and of itself. It always need to be
preceded by some other call which positions the cursor in a headline in
the first place.

Cursory look suggests that there are multiple ways by which (1) could be
achieved - mostly they seem to be outline tree traversal functions.

Summary: Look at outline-level in source code. Jump a few lines above
and watch out for any sort of traversal functions.

,----[ C-h f outline-level RET ]
| outline-level is a compiled Lisp function in `outline.el'.
| 
| (outline-level)
| 
| Return the depth to which a statement is nested in the outline.
| Point must be at the beginning of a header line.
| This is actually either the level specified in `outline-heading-alist'
| or else the number of characters matched by `outline-regexp'.
| 
| [back]
`----



>
> Michael
>
>

-- 

Re: understanding the function outline-level

[Niels Giesen]

Hi Michael,

match data get set by searches. One can inhibit match-data being
cluttered by using the `save-match-data' macro (you should probably do
so when using searches in a lisp program).

Outline.el seems to make very frequent use of this 'global' data;
instead of passing this data on via function arguments or so, it
depends on this dynamically set data, which makes it very hard to see
who does what.

Some prodding about led me to believe the searching in
`outline-back-to-heading' is your suspect (but I have not investigated
this further). At least

(progn
  (outline-back-to-heading)
  (outline-level))

Returns a reasonable answer each time I run it.

(info "(Elisp)Match Data")

May be of interest to you.

On Tue, Jun 7, 2011 at 6:23 PM, Michael Brand
<michael.ch.brand@gmail.com> wrote:
> Hi all
>
> I am on the way of tracking down an (Org?) buglet and now
> outline-level tries to strike me with my lack of experience with
> "Match Data" of Emacs search and I would like to ask for some help to
> understand.
>
> M-: (outline-level) returns a value that I don't understand yet. The
> number does not correspond to the amount of stars and is independent
> of at the beginning of which line the point was before. And when I
> look at the implementation of outline-level I am missing a function
> that initializes the "Match Data". Where is that last search or match
> operation?
>
> Michael
>
>



-- 
http://pft.github.com

Re: understanding the function outline-level

[Michael Brand]

On Tue, Jun 7, 2011 at 20:33, Niels Giesen <niels.giesen@gmail.com> wrote:
> Some prodding about led me to believe the searching in
> `outline-back-to-heading' is your suspect (but I have not investigated
> this further). At least
>
> (progn
>  (outline-back-to-heading)
>  (outline-level))
>
> Returns a reasonable answer each time I run it.

Aha, yes this is what I was missing. I thought that o*-back-to-heading
is only to ensure that point is at the right place and that this could
be emulated by manually moving point, before calling outline-level.
Now I understand that there is more. Thank you all for the
explanations.

With this help I was able to track down the buglet for which I will
send a patch in a moment.

Michael

Re: understanding the function outline-level

[Carsten Dominik]

On Jun 7, 2011, at 8:33 PM, Niels Giesen wrote:

> Hi Michael,
> 
> match data get set by searches. One can inhibit match-data being
> cluttered by using the `save-match-data' macro (you should probably do
> so when using searches in a lisp program).
> 
> Outline.el seems to make very frequent use of this 'global' data;
> instead of passing this data on via function arguments or so, it
> depends on this dynamically set data, which makes it very hard to see
> who does what.
> 
> Some prodding about led me to believe the searching in
> `outline-back-to-heading' is your suspect (but I have not investigated
> this further). At least
> 
> (progn
>  (outline-back-to-heading)
>  (outline-level))

Or, alternatively, if you are already at the beginning of the headline

(and (looking-at outline-regexp)
     (funcall 'outline-level))

So outline-level needs to just have matched when calling that function.

IMPORTANT:

Using (funcall 'outline-level) is more general as major modes are allowed
to set their own function for level calculation. In fact, calling (outline-level)
in Org-mode will give the wrong result, because the regexp also
matches the space character after the stars, so the level is one less than the
length of the match string.

- Carsten


> 
> Returns a reasonable answer each time I run it.
> 
> (info "(Elisp)Match Data")
> 
> May be of interest to you.
> 
> On Tue, Jun 7, 2011 at 6:23 PM, Michael Brand
> <michael.ch.brand@gmail.com> wrote:
>> Hi all
>> 
>> I am on the way of tracking down an (Org?) buglet and now
>> outline-level tries to strike me with my lack of experience with
>> "Match Data" of Emacs search and I would like to ask for some help to
>> understand.
>> 
>> M-: (outline-level) returns a value that I don't understand yet. The
>> number does not correspond to the amount of stars and is independent
>> of at the beginning of which line the point was before. And when I
>> look at the implementation of outline-level I am missing a function
>> that initializes the "Match Data". Where is that last search or match
>> operation?
>> 
>> Michael
>> 
>> 
> 
> 
> 
> -- 
> http://pft.github.com
> 

- Carsten

Re: understanding the function outline-level

[Aankhen]

Hi Michael,

On Tue, Jun 7, 2011 at 21:53, Michael Brand <michael.ch.brand@gmail.com> wrote:
> I am on the way of tracking down an (Org?) buglet and now
> outline-level tries to strike me with my lack of experience with
> "Match Data" of Emacs search and I would like to ask for some help to
> understand.
>
> M-: (outline-level) returns a value that I don't understand yet. The
> number does not correspond to the amount of stars and is independent
> of at the beginning of which line the point was before. And when I
> look at the implementation of outline-level I am missing a function
> that initializes the "Match Data". Where is that last search or match
> operation?

Here’s a slightly more complicated alternative method:

,----
| (progn
|   (org-back-to-heading)
|   (org-reduced-level (org-current-level)))
`----

This will take into account `org-odd-levels-only'.

Aankhen