|View script||License||Download documentation as: HTML or editable|
|Download script||History||Other scripts by: sunanda|
Script Library: 1238 scripts
Documentation for: skimp-my-altme.r
script: skimp-my-altme.r title: Index and search Altme worlds purpose: Easy and quick way of finding things in Altme worlds author: Sunanda date: 21-may-2007 Version: 0.0.2
doc updated needed callback -- what's new section
If you ever use Altme to access one or more worlds, this REBOL application could be of use to you.
It allows you to search the contents of all your Altme Worlds. It differs from the search function built into Altme in these important ways:
2. gui to come
A GUI is planned and the coding for it has been started. But it is unlikely to be available this side of DevCon 2007.
This command line version is being released now for several reasons:
The command line version requires you to do a little more typing than the GUI will. But the results are worth it!
3.1. download files
skimp-my-altme.r is a package that consists of four other library scripts and a couple of other files from the package.
If you use the package downloader....
....You should end up with these files:
You need to edit the sma-worlds.r file to add the worlds you want indexed. See immediately below.
3.2. edit sma-worlds.r
This file is a list of the Altme worlds you want indexed.
The downloaded version has two worlds as an example -- but they are from my test bed, so will not work for you.
The format of the files is a block with one or more objects. Each object is the details of one Altme world that you want indexed. There are four required fields in each object, and one optional one:
3.3. multiple indexes on the same world
You can do this by having multiple entries in sma-worlds. For example, for three distinct indexes on the world my-world you could have this:
make object! [ name: "mw-me" user-name: "me" path: %"/c/program files/altme/worlds/my-world/" index-folder: %/c/skimp-indexes/ ] make object! [ name: "mw-public" user-name: "guest" path: %"/c/program files/altme/worlds/my-world/" index-folder: %/c/skimp-indexes/ ] make object! [ name: "mw-me-music" user-name: "me" path: %"/c/program files/altme/worlds/my-world/" index-signatures: ["jazz" "garage" "baroque"] index-folder: %/c/skimp-indexes/ ]
The three indexes are:
4. preparing for searching
As skimp-my-altme.r is a command line utility, you need to type (or cut'n'paste) some commands as below.
4.1. starting up
4.2. preparing your worlds
This creates a block, world-list (or whatever you want to call it), that contains your sma-world.r entries (with some extra fields added).
As a sanity check, please check that all objects in world-list have a field active: true:
probe world-listIf you see active: false we have failed to open the world for some reason (perhaps the path was wrong). There may be a useful status message in the last-action block. Correct the problem, and try again.
4.3. building the indexes
Please run these three commands:
sma-api/aaw/get-groups-list world-list sma-api/aaw/get-updates-needed world-list sma-api/aaw/update-index/new-groups/old-groups/dead-groups world-list
Note that each command takes your world-list as an argument.nhey:
If your world-list includes the REBOL Community's main flagship world, REBOL3, expect the update to take between 10 minutes and an hour, depending on the speed of your machine. (There are some 120,000 messages in that world: your numbers may vary depending on the number of private messages you have).
If you have Graham's alternative world (REBOL-World), it'll take about a tenth as long: it's a smaller world.
The update process is not (in this version) interruptible, so please let it run to end.
The AAW in the path means action all worlds. There is a lower level API that works on individual worlds -- but, for now, that is undocumented.
Sanity check: given various garbage collection problems REBOL has, it is a good idea at this point to close your console and start another one.
do %skimp-my-altme.r world-list: sma-api/get-worlds
5. run some searches
5.1. first search
You are now ready to search your worlds. Try this:
sma-api/aaw/search-and-display world-list "happy"
With a bit of luck, you see something like this....
>> sma-api/aaw/search-and-display world-list "happy" 1-May-2007/08:06:50.203+1:00 searching.... 1-May-2007/08:06:50.203+1:00 converting.... 1-May-2007/08:06:50.656+1:00 generating html.... 1-May-2007/08:06:53.765+1:00 done == true
....And a browser window opens with the results. If not, please browse the file sma-results.html (in the same folder as skimp-my-altme.r).
There is a summary table listing each world and the number of hits (matches). Followed by a table for each world.
5.2. search results in context
It can help to see the messages before and after a match. Use the /context refinement for that. This example shows one post before and three posts after each match. In the HTML file, the matching lines are bolded. The "context" lines are not:
sma-api/aaw/search-and-display/context world-list "happy" 1x3
5.3. results window
If you search for "happy" on the REBOL3 world, you may see a summary table like this:
The key information here is that there were 370 hits on happy but only 200 are shown in the search results.
That's because the default window is to show results 1 to 200.
You can see more results in one of two ways:
First, have a very wide window -- here we've asked for results 1 through 9,999.
sma-api/aaw/search-and-display/context/window world-list "happy" 1x3 1x9999
Second, slide the window -- here we've asked for results 201 through 370.
sma-api/aaw/search-and-display/context/window world-list "happy" 1x3 201x370
5.4. searching for multiple words
The default operator is AND, so this searches for the two words happy and bug
sma-api/aaw/search-and-display world-list "happy bug"
5.5. not operator
Use the tilde ( ~ ) to search for posts that do not contain the word. In this example, carl but not sassenrath
sma-api/aaw/search-and-display world-list "carl ~sassenrath"
5.6. other search examples
sma-api/aaw/search-and-display world-list "http://www.rebol.org" ;; url sma-api/aaw/search-and-display world-list "first system/words" ;; path sma-api/aaw/search-and-display world-list "18-aug-2005" ;; date sma-api/aaw/search-and-display world-list "1x1" ;; pair
5.7. keeping your index up-to-date
Simply repeat the three commands in building the index above. Any new posts since the last update will be added to the indexes for each world.
5.8. excluding worlds from a search
If you want to search on only some of your worlds, the easier and safest way is to set the world's index as inactive in your world-list, eg to set the third world in your list as inactive:
sma-api/set-world-status world-list/3 "inactive"
Searches (and index update operations) will ignore your third world until you reactivate it:
sma-api/set-world-status world-list/3 "active"
6. notes for a gui api
A GUI front end is being prepared, but we have no date for that as yet.
If you fancy writing one -- perhaps to showcase your own GUI or GUI skins -- please feel free.
These notes are intended to help you if you want to do so. They are rather sketchy, so please ask me if you want to know more.
6.1. dynamically adding your world-list
You can add new worlds to your world-list block:
append world-list extend-an-object make object! [ name: path: user-name: index-folder: ] sma-api/world-template sma-api/set-world-status last world-list "active"
6.2. including / excluding worlds from a search
You could physically remove them from your world-list before callina any aaw API functions.
Or you can set individual entries as active or inactive:
sma-api/set-world-status world-list/4 "active" sma-api/set-world-status world-list/2 "inactive"
Only active worlds are searched.
6.3. saving the updated world-list
This will update sma-worlds.r. The file will include all internal fields for each world. When reloaded later, all internal status settings will be restored:
6.4. Callbacks for status reporting
By default, skimp-my-altme prints some progress information on the console. You can replace that with your own function like this:
sma-api/sma-callback: func [ world [object!] info [block!] ][ print "CALL-BACK" probe info return true ]
The info block contains either:
7. work to do
This is an unfinished version of skimp-my-altme.r There is stuff that still needs doing. Including:
Feedback is welcome!