URLToys Tutorial: Custom Scripts
Introduction
So you've read the first tutorial, you've read the second tutorial, and you've read the FAQ. You've ran around and gotten all kinds of fun stuff with URLToys, and you catch yourself saying things like "Man, if only I could type one command instead of the same six, over and over." You can! This brief tutorial explains how to make your own commands. It requires only knowledge of URLToys, no requirements of knowing Perl necessary.
Installing a Script
Even if you don't plan to make your own, it's nice to know where they go. This is covered in a FAQ question, but we'll go over it briefly here.
Custom scripts are stored in a directory named ".urltoys", inside of your "HOME". In Unix, you should already know exactly where this is. For Windows users, since you don't have "HOME" set by default, the .urltoys directory will appear in the root of the drive you installed (like "c:\.urltoys").
For any OS, this directory will automatically be created when you type in config save for the first time at a URLToys prompt. Do this, then find the directory. If you're a Windows user and hate it in the root, read the FAQ on how to move it.
Writing Your First Script
"Scripts" are a really, really poor word for what these are. They are much more closely related to DOS batch files. You have a text file that has a list of commands that you'd like to execute in order. Any line that starts with a # symbol is ignored. This is useful for comments like "written by ____" or the like. A really simple script would look like this:
# This command calls "make" for you
make
Type those two lines into your favorite text editor (vi, Notepad, etc) and save it inside of your .urltoys folder (see above). The name of the file is important... whatever you name it will become the actual command you type in URLToys to call it, and the extension (the text after the period) must be ".u". Let's call this "m.u". If you are in Windows, be sure that you are naming it "m.u", and not "m.u.txt". Windows tends to tack on ".txt" if you are in Notepad. One way around this is to set "Save As Type" to "All Files" in the Save Dialog box. This should allow you to save it as "m.u".
Note:: Make sure you aren't naming the file a command that already exists in URLToys. For example, naming a file "show.u" will never be used, since URLToys already has a "show" command. To double check, type your command into URLToys before saving it, and make sure it comes back with "Unknown Command".
OK, so you wrote a two line text file with the text written above, and saved it as "m.u" in your ".urltoys" directory. Open URLToys, and type in help. You should see:
URLToys (0)> help
Command Listing:
help,h : This list
exit : Exit URLToys
[...]
undo,u : Undo last list-changing command
version : Show version number
----
m : This command calls "make" for you
[...]
Notice that after the dotted lines in the help command, there is a new command?URLToys has recognized your file, and since the first line of the file was a comment (began with #), it took that as the help line. Now to test the command, let's do this:
URLToys (0)> add http://urltoys.gotdoofed.com/coolpictures/coolpictures.html
URLToys (1)> m
Searching "http://urltoys.gotdoofed.com/coolpictures/coolpictures.html"...6 found.
URLToys (6)>
When you typed in m, it executed all of the lines in your file, which in this case consists solely of the command make. However, adding more lines to this would have been executed in order as if you just typed them in, one by one.
Let's try one with a parameter:
# This command calls the 'print' command
needparam 1 printthis [some text]
print ~0
Save this file as printthis.u in your .urltoys directory. Now open URLToys and type in help again, and you should see "This command calls the 'print' command" listed after printthis. Now you should see this:
URLToys (0)> printthis
printthis [some text]
URLToys (0)> printthis Hello There!
Hello There!
URLToys (0)>
When I typed in the command by itself, the first command it hit was needparam. This command is very simple ... you give it a number of parameters that it needs, followed by an error if it doesn't supply them. The line "needparam 1 printthis [some text]" means "If you don't type in at least one word after 'printthis', notify the user of this error message and stop using the script." That's why you saw "printthis [some text]" appear after typing in printthis by itself. If you did type in text (the second time the command is typed), It gets sent to the script in its entirety as ~0. Each word in the text can be referenced by ~1, ~2, and so on. This is in case you need to tell the script a few things. Many times people just want all of the text together though, and ~0 comes through for that.
The only thing left is what you can come up with it! If you come up with a nice script, I'll add it to the list of scripts on the left of this page for others to download and use.
|
