====== LABELS ====== Labels give you a way fo quick navigation inside the document with [[view:pane:navigation|Navigation Bar]] (can be also called as Function List). It can be a method, a function definition, or an include definition. Generally, it can be any part of the code you want to refer.\\ Labels are described with help of regular expression.\\ HippoEDIT uses BOOST regular expression engine, which uses [[http://www.boost.org/doc/libs/1_61_0/libs/regex/doc/html/boost_regex/syntax/perl_syntax.html|Perl regular expression syntax]].\\ For testing of the label definition I am using [[http://regexlib.com/RETester.aspx|RegexLib service]]. ===== Main properties ===== ==== group ==== Group of the label, currently not used, but would be used later for displaying labels in Function List window grouped by label name. Value: //any string// ==== match ==== A regular expression describing the label. The expression can be a multi line and greedy. You can use sub matches (grouping) for later referring. Value: //any valid regular expression//. :!: - obligatory ==== name ==== Any string describing found label. //name// is displayed in left filtered list in [[view:pane:navigation|Navigation Bar]]. You can refer to results of the match using regular expression replace tags as %%\%%0 complete match, %%\%%1 - first group, %%\%%2 second and so on… Value: //any string// ==== descr ==== Wider description of found label. //descr// is displayed in right (description) field in [[view:pane:navigation|Navigation Bar]]. You can refer to results of the match using regular expression replace tags as %%\%%0 complete match, %%\%%1 - first group, %%\%%2 second and so on… Value: //any string// ==== descr_match ==== The additional regular expression for better resolving of the description. Applied to the result of the match. If exist, results of //descr_match// would be used for description back references. Value: //any valid regular expression// ==== image ==== Image associated with label. Image is displayed as in left list of [[view:pane:navigation|Navigation Bar]] as in right description field. Value: //[[syntax:images|enumeration from 5 till 20]]//\\ Default: //none=default=0// ==== sub_image ==== Sub-image associated with the label (image drawn on top of the main image). Usually used for visualization of label visibility (public, protected, private). Value: //[[syntax:images|enumeration from 2 till 4]]//\\ Default: //none=default=0// ==== scope ==== Defines relation of the label to any scope. * **0** - not related to scope; * **1** - label includes relevant scope start, * **2** - scope includes relevant scope end. If the label is related to scope (1|2) HippoEDIT would try to find the appropriate scope and associated label with it. Then you would see label description as the name of the scope while navigating in [[view:pane:navigation|Navigation Bar]] and in [[editing:navigation:scroll|Scroll Info Tip]]. Value: //0|1|2//\\ Default: //0// ==== navigation ==== If set, then label would be used in [[editing:navigation:smart_navigate|Smart Navigate]] and when Go button pressed in [[view:pane:navigation|Navigation Bar]]. For example to navigate to include file or to definition of label. Value: //true|false//\\ Default: //true// ==== visible ==== Indicates, if label shall be shown in the description field of [[view:pane:navigation|Navigation Bar]] when you place the cursor on it in the text editor. Works as //navigation// flag for rest. Can be used if you use label only for highlighting purposes. Value: //true|false//\\ Default: //true// ==== marker ==== Defines image id to be shown on indicator margin on the front of the label. Image id corresponds to image number for one of margin icons. Used for example, for displaying scope exits indicators. Value: //[-1..20]//\\ Default: //-1// ==== context ==== Technical flag, providing additional context for HippoEDIT, to select right logic for label. Can be any from predefined strings. Currently only used for [[view:scope-exits|scope exist]]. Value: //exit_scope|exit_all//\\ Default: //nothing// ==== style ==== Style id, to be used for syntax highlighting of label contents, when label parsing is done. Value: //one of [[syntax:styles|styles]] defined in this or parent syntax schema//\\ Default: //nothing// ==== highlight ==== Replacement regular expression, used to extract dynamic keyword for syntax highlighting. The result of replacement shall match conditions, used for [[syntax:styles:keywords|defining keywords]] (except of multi word support). Keywords extracted in such way are global, and can be highlighted in all [[syntax:styles|containers]] which accept [[syntax:styles|style]] provided in //style// attribute. Value: //any replacement regular expression//\\ Default: //contents of label name// ===== Conditions ===== In addition to listed before properties, you can have some overriding of the label properties, depending on regular expression match. ==== Skip ==== If you want to skip some labels depending on result of the match, you can use a //Skip// condition defined inside of Label node. === if === Regular expression with back references to match which would be compared to //equal// \\ Value: //some regular expression string with back references to match// === equal === String to compare with result of regular expression replace from attribute //if// \\ If //if// equals to //equal// the label would be skipped. ==== Scope ==== If you want to skip some labels depending on result of the match, you can use a //Skip// condition defined inside of Label node. === if === Regular expression with back references to match which would be compared to //equal// \\ Value: //some regular expression string with back references to match// === equal === String to compare with result of regular expression replace from attribute //if// === value === Enumeration value allowed for the label //scope// attribute. If //if// equals to //equal// the label scope attribute replaced by value defined in attribute //value//. ==== Image/SubImage/Marker ==== If you want to adopt image or sub_image based on result of label match, you can use //Image/SubImage// condition defined inside of Label node. === if === Regular expression with back references to match which would be compared to equal Value: //some regular expression string with back references to match// === equal === String to compare with result of regular expression replace from attribute //if// === value === Enumeration value of the image, sub image or marker. If //if// equals to //equal// the label would have image or sub image defined in //value//. ==== Highlight ==== If you need some more control of how label can be highlighted or want to define more than one highlighting rule for same label, you can use this condition. === in === Regular expression with back references to extract label part to be highlighted as keyword. If not defined, //highlight// attribute used for extracting. If //highlight// attribute is empty, //name// attribute is used for processing. If //all// and //first// attributes are empty/not defined, whole value of //in// (after appliying to match) used as keyword. === all === Regular expression, which, if defined, applies to //in// part and used for collecting all matches of //all// regexp in //in// attribute to be used as keywords for highlighting. === first === Regular expression, which, if defined, applies to //in// part and used for collecting **first** match of //first// regexp in //in// attribute to be used as keyword for highlighting. ==== style ==== Style id, which overwrites global //style// attributes defined for label. ==== global ==== Indicates, that keywords are global and shall be used in a whole document, independent from the scope. Currently, only **true** value is supported. ===== Containers ===== To restrict label for some style, you can also use [[syntax:containers|Containers]] node inside Label node.