Using %rtags.r
ctags for REBOL
Source code by Ernie van der Meer
Contents:
1. Introduction to %rtags.r
2. Running rtags.r
2.1 Get a copy of rtags.r
3. Building tags
3.1 Building blocks with filenames
4. Using tags
4.1 More than one definition
4.2 Many more features
4.3 Start your engines
5. Credits
1. Introduction to %rtags.r
ctags is an aging but still vibrant utility for referencing C source code with tags. The tagging feature was built into the vi and emacs text editors. ctags was developed by some real luminaries of the computing field including Ken Arnold and Bill Joy. With the advent of Exuberant ctags, support for many programming languages has been added but the format remains the same. Now REBOL can benefit from rtags.r.
I'll only discuss the indexing usage as it pertains to vi. To coin a phrase "emacs is a great operating system, but it needs a good editor". Other editors will also support ctags indexing, but vi is where it's at.
See ctags wikipediafor a starting point at learning more about ctags and vi wikipediafor more about vi.
Tagging really comes into play with multiple source file REBOL projects, but can come in handy even for smaller one-file applications that grow to more than a page or two.
2. Running rtags.r
Unlike many REBOL applications, rtags.r is useful both from the Operating System command shell, and the REBOL console itself. rtags.r expects it's filename inputs in system/script/args, and these are set when the script is invoked along with REBOL from the operating system or with do/args.
>> do/args rtags.r "-o tagfile file1.r file2.r"
$ rebol rtags.r -o tagfile *.r
We will look at both usage scenarios.
2.1 Get a copy of rtags.r
One thing every REBOL developer should do is download a copy of the rebol.org Desktop Librarian.
From a browser Download: Desktop. This is not absolutely necessary, but it's a handy thing to have.
Another way is a direct download of the script with download rtags
It can even be executed directly from the library with
>> do/args http://www.rebol.org/library/scripts/rtags.r "files go here"
but a local copy will probably be more efficient for long term use.
3. Building tags
Be default, vi will look for a file called tags in the current working directory and it's location can be controlled with the vi/ex command :set tags, for example
:set tags=./tags,tags,/home/user/commontags
tells vi to look in the current working directory, then the directory where the source file was loaded from and then from a default file in a home directory.
rtags.r will by default output tags but can be told to output to another file with the -o tagfile command line option. For now, we'll assume no override and just use tags.
rtags.r creates a tags index entry for all the set-word! definitions in REBOL source code. There is a bug and rtags.r will also generate an index entry for set words inside comments, but you'll find that is not too big a problem when using :tselect from vi.
First, determine what files you wish to tag. I usually tag everything so it is usually;
$ cd /home/development/working/project
$ cp /home/development/library/scripts/rtags.r .
$ rebol -s rtags.r *.r
That will generate a tags file for all the REBOL source in the project directory.
$ cd /home/development/working/project
$ rebol
>> do/args %rtags.r form remove-each file read %./ [not %.r = suffix? file]
There are other ways of getting a list of files from REBOL, just as long as the list is passed to do/args as a string. So in the above form is fairly crucial.
3.1 Building blocks with filenames
If you find that you need to include files from many directories, try taking a look at Gregg Irwin's nifty and powerful file-list.r documented at
file-list docsand sourced in the rebol.org library at file-list.r.
file-list.r uses Ladislav Mecir's most awesome include function. This should be a staple in every REBOL developers toolkit. Find it's documentation at include.htmland the source at include.r. Get a copy of this and then load it as part of your user.r. It's just too handy.
This is an example of some of the behind the scenes work that goes on
in the REBOL community. Gregg and Ladislav are but two of the unsung
heroes.
4. Using tags
$ cd /home/development/working/project
$ vi cool.r
When you find you want to see how something is defined; just use Ctrl-], that is Control key and close bracket together. vi will take you to the first definition.
Note: ctags was built for C code. If there is a minus character "-"
in the definition vi can get confused and will only look for a string
upto the "-" No worries. Use the Visual mode v, highlight the
entire reference and then use Ctrl-] or the ex command
:tag ref,
4.1 More than one definition
There may well be more than one definition found in the tags file. In that case use
:tselect reference-string
and you'll get a list of choices. vi is efficient, so :ts will work as well.
4.2 Many more features
In vi using
:help tag
will bring up a plethora of information on the various keys and features that can be used for using tagging.
4.3 Start your engines
So with rtags.r under your belt, it's time to write the next big thing.
5. Credits
| 
