Documention for: rtags.r Created by: btiffin on: 10-Nov-2007 Last updated by: btiffin on: 10-Nov-2007 Format: text/editable Downloaded on: 28-Mar-2024 Using %rtags.r ctags for REBOL Source code by Ernie van der Meer ===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. ===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. ---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. ===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. ---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. ===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, ---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. ---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. ---Start your engines So with rtags.r under your belt, it's time to write the next big thing. ===Credits \table File Author URL =row rtags.r Ernie van der Meer http://www.rebol.org/library/scripts/rtags.r =row rtags documentation Brian Tiffin http://www.rebol.org =row file-list.r Gregg Irwin http://www.rebol.org/library/scripts/file-list.r =row include.r Ladislav Mecir http://www.fm.vslib.cz/~ladislav/rebol/include.r =row vi Bill Joy http://en.wikipedia.org/wiki/Vi =row ctags Ken Arnold http://en.wikipedia.org/wiki/Ctags =row REBOL Carl Sassenrath, REBOL Technologies http://www.rebol.com /table