Hi all,
I've put the last bit of planned functionality into the Tagging UI
(nodetags.py plugin) today. It's available in the latest commit. Here's
the new docstring:
----
Provides node tagging capabilities to Leo
By Jacob M. Peck
API
===
This plugin registers a controller object to c.theTagController, which
provides the following API::
tc = c.theTagController
tc.get_all_tags() # return a list of all tags used in the current
outline, automatically updated to be consistent
tc.get_tagged_nodes('foo') # return a list of positions tagged 'foo'
tc.get_tags(p) # return a list of tags applied to the node at
position p; returns [] if node has no tags
tc.add_tag(p, 'bar') # add the tag 'bar' to the node at position p
tc.remove_tag(p, 'baz') # remove the tag 'baz' from p if it is in
the tag list
Internally, tags are stored in `p.v.unknownAttributes['__node_tags']` as
a set.
UI
==
The "Tags" tab in the Log pane is the UI for this plugin. The bar at
the top is a search bar, editable to allow complex search queries. It
is pre-populated with all existing tags in the outline, and remembers
your custom searches within the given session. It also acts double duty
as an input box for the add (+) button, which adds the contents of the
search bar as a tag to the currently selected node.
The list box in the middle is a list of headlines of nodes which contain
the tag(s) defined by the current search string. These are clickable,
and doing so will center the focus in the outline pane on the selected node.
Below the list box is a dynamic display of tags on the currently
selected node. Left-clicking on any of these will populate the search
bar with that tag, allowing you to explore similarly tagged nodes.
Right-clicking on a tag will remove it from the currently selected node.
The status line at the bottom is purely informational.
The tag browser has set-algebra querying possible. Users may search for
strings like 'foo&bar', to get nodes with both tags foo and bar, or
'foo|bar' to get nodes with either or both. Set difference (-) and
symmetric set difference (^) are supported as well. These queries are
left-associative, meaning they are read from left to right, with no
other precedence. Parentheses are not supported. See below for more
details.
Searching
---------
Searching on tags in the UI is based on set algebra. The following
syntax is used::
<tag>&<tag> - return nodes tagged with both the given tags
<tag>|<tag> - return nodes tagged with either of the given tags (or
both)
<tag>-<tag> - return nodes tagged with the first tag, but not the
second tag
<tag>^<tag> - return nodes tagged with either of the given tags
(but *not* both)
These may be combined, and are applied left-associatively, building the
set from the left, such that the query `foo&bar^baz` will return only
nodes tagged both 'foo' and 'bar', or nodes tagged with 'baz', but *not*
tagged with all three.
Tag Limitations
---------------
The API is unlimited in tagging abilities. If you do not wish to use
the UI, then the API may be used to tag nodes with any arbitrary
strings. The UI, however, due to searching capabilities, may *not* be
used to tag (or search for) nodes with tags containing the special
search characters, `&|-^`. The UI also cannot search for tags of
zero-length, and it automatically removes surrounding whitespace
(calling .strip()).
----
Any comments would be welcome -- thanks!
-->Jake
--
You received this message because you are subscribed to the Google Groups
"leo-editor" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/d/optout.
