HippoEDIT explained: "Navigation Bar", "Function List", "Code Browser"

[Stefan]

Welcome to "HippoEDIT explained"

Today we will learn something about  "Navigation Bar" (see picture on the end)

Navigation bar and Labels.
How much time you want to navigate between classes in
you CSS, functions in your C file or sections in INI
file? Now it is possible with help of Navigation bar
and Labels. If you have Labels defined for your syntax,
Navigation Bar, located on top go your document, would
show you list of the labels found in the document.
Helps to filter and navigate to any label, see current
label when navigating in source code, go fast to label
definition in the document with one mouse click. You
can think about Navigation Bar and Labels as about
Function List, used in other editors, but they are much
more powerful. With Label you can define any regular
expression that should represent label, use result of
the match to form Name of the Label and Description,
select which image should be used depending on result
of additional evaluation, or define sub image that can
represent, for example, visibility of label (Private,
Protected or Public). You can bind Label with Scope and
it would be shown on Hierarchy Bar and in Scroll Tip.
Found labels are also used for Smart Navigate, so if
you would call the command on some usage of the label,
you would be driven to label definition.

Please note that Alex have explain the basic about this in the topic "Adding new Language Syntax" already.
I only take this information and test it how this works to get an better understanding for it.
This may be from interest for others, so i share here my experiences on the way to succeed  
(Please note that english isn't my mother language, so perhaps something may be not well written)


Navigation Bar could also be called "Function List" or "Code Browser"
Basically a place where you see a list of functions, variables modules and classes in currently active file.

You can enable the "Navigation Bar" by checking the menu option "View > Panes > [X] Navigation Bar"

The Navigation Bar can be used mostly in any syntax.
It depends (configured) on labels definitions from syntax schema.
See this other topic "Adding new Language Syntax" for more information about this.

For example:
<LABELS>
   <Label group="Subroutine" match="\&lt;(sub|function)[\s\[]+(\w+)[\s\]]*(\([^)]*\))" name="\2" descr="\1 \2 \3" image="8" scope="1">
      <Image if="\1" equal="sub" value="8"/>
   </Label>
   <Label group="Class" match="\&lt;(public|private)?\s+class\s+(\w+)\s*" name="\2" descr="Class \2" image="4" scope="1">
      <SubImage if="\1" equal="public" value="1"/>
   </Label>
</LABELS>

Here the label "Subroutine" will match lines containing "Sub" and "Function" words.
Next i will try to explain the RegEx a bit...


Example source code line:
typedef struct _infobox {

Label definition in HippoEDIT syntax file:
<Label group="Structure" match="struct\s+(\w+)[^\;{]*\{" name="\1" scope="1" image="9"/>
     
The RegEx (regular expression) term to match an string for an "struct" definition in *.c is defined here as:
     match="struct\s+(\w+)[^\;{]*\{"
The RegEx we use is the part between the both "..." quotes.
To understand this syntax you may want to learn something about RegEx first, if you not already know it.
Good place to learn are for example:
http://en.wikipedia.org/wiki/Regular_expression
http://de.wikipedia.org/wiki/Regul%C3%A4rer_Ausdruck
http://www.boost.org/doc/libs/1_40_0/libs/regex/doc/html/boost_regex/syntax/perl_syntax.html
http://www.regular-expressions.info/
http://regexlib.com/


- - -

I will try to explain this RegEx as good as i can, but i doesn't want to copy an regular expression HowTo here.

The RegEx "struct\s+(\w+)[^\;{]*\{" can be split into several parts:
struct
\s+
(\w+)
[^\;{]*
\{


That means:
struct      find the chars 'struct' literally
\s+          followed by 'one or more' (+) 'whitespace' (\s)
(\w+)      followed by 'one or more' (+) 'alphabetic chars' (\w). This part is grouped by (...) to back reference to later.
[^\;{]*      NOT followed by 'null or more' (*) of any of the signs found between [...], as this are ';' and '{'
\{          but followed by an '}' sign.
     
     
The "Name" -part of the definition is used to give the found source code line an Name, displayed in the Navigation Bar.     
name="\1"   '\1' means: take that what was found with  (\w+), what is  "_infobox" in our case


- - -

Note:
If the Navigation Bar do not show you anything for some syntax, probably labels are not defined for this syntax.
In this case you can add the labels by yourself.
See this other topic "Adding new Language Syntax" > here < for more information about this.

- - -


Note:
The HippoEDIT syntax engine (HSE) would use an LABEL only in "normal" style.

So if we want to use our LABEL with an other STYLE such as "comment" style for example,
we have to told HSE to use the LABEL in that style too.

We do that by adding an CONTAINER advice to the LABEL definition: <Containers open="comment"/>

Example:
Here i have created an LABEL in my VBS syntax.
The term here to catch is "'//ToDo:"
This means, i want to write '//todo: in my code and the "match"-RegEx of the following  label definition
should match this term and show it into the "Navigation Bar", so i can jump through all ToDo's line in my code.

Now, because this ToDo lines are of course commented out in my code
i had to advice the HSE to match my label in comments too.
I have done this by adding the string "<Containers open="comment"/>" to my LABEL:
  <LABELS>
         <Label group="ToDo" match="//ToDo:\s*(\w*?)\s+(.*?)$" name="ToDoName \1" descr="ToDoDesc \1 \2" image="6" scope="1">
            <Image if="\1" equal="ToDo" value="9"/>
            <Containers open="comment"/>
         </Label>
      </LABELS>

The CONTAINER "comment" again do point to an STYLE named "comment" in an <lang>_spec syntax xml.

This comment style for my VBS syntax is inherited from "basic_spec.xml"
and looks like this:

     <Style id="comment" name="Comments" text="1" bold="0" italic="1" underline="0" clr="Comments" bkclr="#FFFFFFFF">
        <Blocks>
          <Block open="'" close="\n"/>
          <Block open="REM" close="\n"/>
        </Blocks>
That means that ' and REM are comment signs.

- -

If you want that this LABEL works for different STYLES
you can add one or more CONTAINER for every STYLE you want.

You can add your own STYLE definition or go the "inherit - way" back to look for an existing STYLE.

My vbs_spec.xml is inherited from "basic_spec.xml",
that is inherited from "defsource_spec.xml"
which is inherited again from "def_spec.xml"

Examples:

--- Use the label in normal style only:
     No container needed here.
        <Label group="ToDo" match="" name="" descr="" image="6" scope="1">
            <Image if="\1" equal="ToDo" value="9"/>
         </Label>

--- Use the label in, f.ex. comment style only:
        <Label group="ToDo" match="" name="" descr="" image="6" scope="1">
            <Image if="\1" equal="ToDo" value="9"/>
           <Containers open="comment"/>
         </Label>

--- Use the label in comment AND normal style:
        <Label group="ToDo" match="" name="" descr="" image="6" scope="1">
            <Image if="\1" equal="ToDo" value="9"/>
           <Containers open="comment"/>
            <Containers open="normal"/>
         </Label>


See this other topic "Adding new Language Syntax" for more information about this.

- - -

[Stefan]

B

[Stefan]

Hi, i want to add an item into the "Navigation Bar" (can be also called as "Function List" or "Code Browser")

As Alex explained here http://forum.hippoedit.com/index.php/topic,272.msg1057.html#msg1057

Navigation Bar can be used mostly in any syntax. It depends (configured) on labels definitions from syntax schema.

i tried this:

IN X:\HippoEDIT\data\syntax\basic_spec.xml i have found:

Code:

  <SYNTAX id="basic" name="Basic" inherit="def_source" inherit_url="defsource_spec.xml">
    <SPECIFICATION>
    </SPECIFICATION>
    <FORMAT>
    </FORMAT>
    <SCOPES>
    </SCOPES>
    <LABELS>
      <Label group="Subroutine" match="\&lt;(public|private)?\s*(sub|function)\s+(\w+)(?:\s*(\([^)]*\)))?" name="\3" descr="\2 \3 \4" image="6" scope="1">
        <Image if="\2" equal="sub" value="9"/>
        <SubImage if="\1" equal="public" value="2"/>
        <SubImage if="\1" equal="private" value="4"/>
      </Label>
    </LABELS>
    <STYLES>

Based on this information i have done,
to add ToDo-items for VBS files into the "Navigation Bar",
i added into
X:\HippoEDIT\data\syntax\vbs_spec.xml

Code:

  <SYNTAX id="vbs" name="Visual Basic Script" inherit="basic" inherit_url="basic_spec.xml">
    <SPECIFICATION>
    </SPECIFICATION>
<LABELS>
  <Label group="ToDo" match="//(ToDo)" name="ToDoName" descr="ToDoDesc" image="6" scope="1">
<Image if="\1" equal="ToDo" value="9"/>
  </Label>
</LABELS>
    <STYLES>

Question:
The found lines containing "ToDo" are shown on the right in "Overview Bar" only.
But not in the "Navigation Bar" on top?
What do i wrong?

Like to see the functions in the "Navigation Bar" i want to see all ToDo-lines there too.

[alex]

Hi Stefan,

first, thanks a lot for a good tutorial and explanation of all bars and panes. This is very useful for everybody, because I have not time yet to even update with new functionality the web site (and of course, documentation )

Now about Todo question:
- not your case, but do not forget navigation="false" hides label from list and only show it in description part of the navigation bar
- Containers are missing. As for styles, if you do not specify "container", engine would accept label only in normal style. So probably, because you todos are in comments you need to add something like this.

Code:

<Containers open="comment"/>

- if you specify container, you do not need to place // before. I think, you need something like this match="\&lt;todo\s+(.*)$". Because language is not case sensitive, regexp is also not case sensitive. Sorry, I understood, you just want different images.
- scope="1". Mean that match intersects with begin of some scope (HE normally would try to associate label with found scope and use as scope name). This is not you case - remove it.
- match="//(ToDo)". Do you have in vb // as comment?

So, I think you problem is missing containers.

Best regards,
Alex.

[Stefan]

A> As for styles, if you do not specify "container", engine would accept label only in normal style.
Aha, That is it. If i doesn't use the comment sign it works.

A> - match="//(ToDo)". Do you have in vb // as comment?
No, the // are only signs to see an comment better and to make the 'ToDo' unique, for exact match, that's why i use the term '//ToDo

A> - scope="1".
Yes, this was only an try to see why it doesn't  works.

A> you need something like this match="\&lt;todo\s+(.*)$".
Why "\&lt;" ?  It means <?





Since the ToDo's should be commented out,  (looks for VBS code like this: 'ToDo, or as i have defined this: '//ToDo:)
i have added an advise to use this Label for <Style id="comment" (found in the leavings basic_spec.xml syntax )
by adding an Container with keyword 'Comment', as you told me:


    </SPECIFICATION>
    <LABELS>
         <Label group="ToDo" match="//ToDo:\s*(\w*?)\s+(.*?)$" name="ToDoName \1" descr="ToDoDesc \1 \2" image="6" scope="1">
            <Image if="\1" equal="ToDo" value="9"/>
            <Containers open="comment"/>
         </Label>
      </LABELS>
    <STYLES>

Now this works too. Next i take an closer look at the images.


Explanation:
match="//ToDo:\s*(\w*?)\s+(.*?)$" means:

//ToDo:   literally match '//ToDo:' , non case sensitive
\s*      followed by 'null or more' (*)  whitespace (\s)
(\w*?)   followed by 'null or more' (*)  'alphabetic char' (\w) , but 'non-greedy' (?)
\s+      followed by 'one or more'  (+)  whitespace (\s)
(.*?)      followed by 'null or more' (*) 'any char' (.) , but 'non-greedy' (?)
$      Stop at End Of Line


name="ToDoName \1"  is the part to display in the left box of the "Navigation Bar".
For this HowTo i let show the word 'ToDoName' followed by that what is catch from the RegEx in the first match group.

descr="ToDoDesc \1 \2"  is displayed in the right box. Here i have decided to see 'ToDoDesc' there, followed by the catch content of match group 1 again, completed with group 2 (the rest of the line)

Agree, not that useful for real work, but maybe good to show how this is designed to work?

THANKS for your great support Alex.

Ahrrg.
Fantastic!   
Yummy 
NOW i see there is already an TODOs  label in the underlaying basic_spec.xml syntax !
NOW i know why i see always the term 'TODOs'  while i have used always 'ToDo'  :'(
Trapped 

[Stefan]

Question:
If i want to match ToDo in "normal" AND in "comment" style... do i have to copy the label... or is there an AND-advice?

Ah, i think i get it:
go the inherit_url way back and look if an wanted style is specified. Then use this style.

vbs_spec.xml is inherited from "basic_spec.xml",
that is inherited from "defsource_spec.xml"
which is inherited again from "def_spec.xml"

I have found an "normal" style in the underlying def_spec.xml.
So i would us this:

--- Use the label in normal style only:
        <Label group="ToDo" match="" name="" descr="" image="6" scope="1">
            <Image if="\1" equal="ToDo" value="9"/>
         </Label>

--- Use the label in, f.ex. comment style only:
        <Label group="ToDo" match="" name="" descr="" image="6" scope="1">
            <Image if="\1" equal="ToDo" value="9"/>
           <Containers open="comment"/>
         </Label>

--- Use the label in comment AND normal style:
        <Label group="ToDo" match="" name="" descr="" image="6" scope="1">
            <Image if="\1" equal="ToDo" value="9"/>
           <Containers open="comment"/>
            <Containers open="normal"/>
         </Label>

Right?

[alex]

Yes. Everything is correct
You can define several containers. All are collected.