1GEOQO(1) User Contributed Perl Documentation GEOQO(1)
2
6 geoqo - Geocaching DataBase
7
9 The geoqo program is designed to be:
10 - usable with a graphical user interface
12 - usable on the command line
13 - fast (uses a database (mysql, postgresql, sqlite2 or sqlite supported)
14 - highly extensible. It's easy to:
15 - add new search types
16 - add new import routines
17 - add new export routines
18 - add new display routines
19 - add new modification plugins
20 - ...
21 - A very extensive scripting ability that can automatically create
22 GUI screens from script definitions.
23 - In summary, you should be able to control your data.
24
26 The documentation uses the following structures for examples:
27 > geoqo -argument value
29 output line 1
30 output line 2
31 In the above example, ">" is the command prompt. "geoqo -argument
33 value" is an example command, and "output line 1" (and 2) would be the
34 example output it might give.
35 Tutorials and Other Documentation
37 Make sure you check out the wiki pages as well, which provide tutori‐
39 als, tips and tricks, FAQs, and other documentation:
40 http://www.geoqo.org/wiki/
42 This document discusses how to use geoqo using the command line syntax.
44 For instructions on using the GUI, please see the tutorial on the wiki
45 web page above which contains screen-shot walk throughs.
46
48 Import a file:
49 geoqo -i filetoimport.gpx
51 Search for and list all caches owned by Yamar
53 geoqo -s cache:owner_name=Yamar -d list
55 Display result number 3 from the last search:
57 geoqo -s 3 -d show
59 Export your search to a new file (in this case, the last search
61 [Yamar's caches] since a new -s flag wasn't specified)
62 geoqo -e filetoexport.gpx
64 List geocache data sets (includes imports, searches, etc)
66 geoqo -d sets
68 Show stats about your data:
70 geoqo -d stats
72
74 GeoQO is very powerful. Thus, you'll find that this manual is long.
75 It's divided up into sections based on the types of things geoqo can
76 do: setup, import, search, display, modify, and export.
77 Make sure you check out the wiki pages as well, which provide tips and
79 tricks, FAQs, and other documentation:
80 http://www.geoqo.org/wiki/
82 Have I mentioned the wiki yet?
84 Help Is Nearby
86 The -d switch (you'll learn about this later) displays things. One of
88 the things it can display is "help". To get help at any time, run:
89 > geoqo -d help
91 To get started with the help system. To get help about a particular
93 topic, include the major type and a slash (/) and the subtype. For
94 example, Get get information about importing gpx files:
95 > geoqo -d help:topic=import/gpx
97 To get a list of the particular subtypes for a given section, look up
99 the major section:
100 > geoqo -d help:topic=import
102 And it will list all of the subtyes (in the example above, it would
104 display a list of all the import types).
105
107 Database setup is automatic for the default database. You can, how‐
108 ever, create as many databases using other file names as you want (but
109 why?).
110 > geoqo --db-name otherdb --setup-database
112
114 To import an existing pocket query or other gpx file, simply use the -i
115 switch:
116 > geoqo -i somefile.gpx
118 You can import multiple files:
120 > geoqo -i somefile.gpx,someotherfile.zip
122 Note that most importing plugins do store things in "sets". See sec‐
124 tions further below for more details on what a "set" is and how useful
125 they can be.
126 File import types currently available:
128 Import Gpx:
130 > geoqo -i myfile.gpx
132 > geoqo -i gpx:setname=myname:myfile.gpx
134 The gpx importer imports gpx files taken from the geocaching.com site
136 (and probably many other sites too, but only geocaching.com GPX files
137 have been tested so for) and imports the data into your geoqo database.
138 Options:
140 setname:
142 Uses setname as the name of geoqo SET to create based on the data.
143 Normally this is extracted from the name field within the gpx file
144 itself and prepended with "import:". IE, if you had a pocket query
145 named "my search" then, when you imported the gpx file into geoqo,
146 you'd get a new set named "import:my search".
147 Import Zip:
149 > geoqo -i myfile.zip
151 The zip importer allows you to simply specify a zip file for importing
153 instead of having to unzip it yourself. It expects the contents of the
154 zip file to be named similar to the zip file itself, just like ground‐
155 speak sends them out for geocaching.com pocket queries. IE, if you
156 import "111111.zip" it'll try to unzip it and then import the contained
157 111111.gpx file. It'll also try to import the 1111111-wpts.gpx file,
158 if one existed as well.
159 Note: using this importer requires you to have unzip installed on your
161 system.
162 Options:
164 setname:
166 Uses setname as the name of geoqo SET to create based on the data.
167 Normally this is extracted from the name field within the gpx file
168 itself and prepended with "import:". IE, if you had a pocket query
169 named "my search" then, when you imported the gpx file into geoqo,
170 you'd get a new set named "import:my search".
171 tmpdir:
173 The zip importer works by copying the zip file to a tmpdir and then
174 unzipping it there. This is normally set to $HOME/.geoqo/tmpdir.
175 This option lets you override that default.
176 default: /users/hardaker/.geoqo/temp
178 Import Loc:
180 > geoqo -i myfile.loc
182 > geoqo -i loc:setname=myname:myfile.loc
184 The loc importer imports loc files taken from the geocaching.com and
186 waymarking.com site (and probably many other sites too, but only geo‐
187 caching.com and waymarking.com LOC files have been tested so for) and
188 imports the data into your geoqo database.
189 Options:
191 setname:
193 Uses setname as the name of geoqo SET to create based on the data.
194 Normally this is extracted from the name field within the gpx file
195 itself and prepended with "import:". IE, if you had a pocket query
196 named "my search" then, when you imported the gpx file into geoqo,
197 you'd get a new set named "import:my search".
198 Import Wigle:
200 > geoqo -i myfile.wigle
202 > geoqo -i wigle:setname=myname:mywiglefile
204 The wigle importer imports wigle files taken from the geocaching.com
206 and waymarking.com site (and probably many other sites too, but only
207 geocaching.com and waymarking.com WIGLE files have been tested so for)
208 and imports the data into your geoqo database.
209 Options:
211 setname:
213 Uses setname as the name of geoqo SET to create based on the data.
214 Import System:
216 > geoqo -i "system:gpsbabel -i garmin -f /dev/ttyS0 -o gpx -F %{file:gpx}"
218 The system importer allows you to simply specify a command to run which
220 generates a file of a type that geoqo can actually import. For exam‐
221 ple, the above command runs gpsbabel to import all the waypoints stored
222 in a GPS on a unix system (/dev/ttyS0 is the name of a serial device on
223 a linux machine).
224 Options:
226 cmd:
228 It must contain a %{file:TYPE} string that indicates where the out‐
229 put file will be stored, but the path and the name of that file
230 will be created by geoqo. Example gpsbable arguments would be -o
231 gpx -F %{file:gpx}
232 setname:
234 Uses setname as the name of geoqo SET to create based on the data.
235 Normally this is extracted from the name field within the gpx file
236 itself and prepended with "import:". IE, if you had a pocket query
237 named "my search" then, when you imported the gpx file into geoqo,
238 you'd get a new set named "import:my search". However if your sys‐
239 tem command doesn't properly name the resulting file, this can be
240 used to override it.
241 tmpdir:
243 The temporary directory to use
244 default: /users/hardaker/.geoqo/temp
246 Import Create:
248 > geoqo -i create:ident=home,lat=N38
250 The create import plugin lets you create new waypoints and inserts them
252 into the database. The list of options is quite long as each type sup‐
253 ported by a given supported waypoint system (geocaching, geodining,
254 ...) requires an appropriate set of fields. Running geoqo simply as:
255 > geoqo -i create
257 should bring up a GUI form which will prompt you for the needed infor‐
259 mation. Leave anything out that isn't appropriate for the waypoint
260 type you're creating.
261 Options:
263 type:
265 default: Waypoint
266 ident:
268 setname:
269 default: created
270 desc:
272 lat:
273 lon:
274 sym:
275 time:
276 subtype:
277 url:
278 urlname:
279 cmt:
280 Import Average:
282 > geoqo -i average:ident=newwaypoint,from1=oldwaypoint1,from2=oldwaypoint2
284 The average import plugin lets you create a new waypoint by averaging
286 the latitude and longitude of a number of other waypoints. Useful to
287 find the center of a number of waypoints, which is required for a num‐
288 ber of geocaching puzzle caches.
289 Options:
291 ident:
293 type:
294 default: Waypoint
295 from1:
297 from2:
298 setname:
299 default: created
300
302 The search system in geoqo is highly flexible and extensible. It sup‐
303 ports multiple types of searching, which are documented below. The
304 "-s" or "--search". The format of the search field is as follows:
305 type:terms
307 Type is the type of search you want to do. This can be any of the
309 types shown further below, or any types provided by a plugin. For
310 those that want to write search plugins, please run "perldoc
311 GeoDB::Search" to learn how to write search plugins.
312 Note: searching does nothing if you're not going to act on the results.
314 Thus, you should at least provide a -l, -S or -e flag to list, show, or
315 export the results. All the examples below are using the -l flag.
316 Search types are as follows:
318 Search Cache:
320 > geoqo -s cache:name=unusual -d count
322 Search/Set Count: 6
323 Searchs the database for only waypoints that are of type 'Geocache' and
325 conform to the terms given. See the documentation on the waypoint:
326 search type for further details on how to use it because everything
327 else is the same.
328 Possible search columns for geocaches include the following, beyond
330 those listed in the waypoint section:
331 available
333 archived
334 groundspeak_name
335 groundspeak_placed_by
336 groundspeak_owner_id
337 groundspeak_owner_name
338 groundspeak_type
339 groundspeak_container
340 groundspeak_difficulty
341 groundspeak_terrain
342 groundspeak_country
343 groundspeak_state
344 groundspeak_short_description_html
345 groundspeak_short_description
346 groundspeak_long_description_html
347 groundspeak_long_description
348 groundspeak_encoded_hints
349 Search Waymark:
351 > geoqo -s waymark:name=unusual -d count
353 Search/Set Count: 6
354 Searches the database for only waypoints that are of type 'Waymark' and
356 conform to the terms given. See the documentation on the waypoint:
357 search type for further details on how to use it, because everything
358 else is the same.
359 Possible search columns for waymarks include the following beyond those
361 listed in the waypoint section:
362 waymark_owner_name
364 When waymarking.com starts releasing more data in .gpx files, this will
366 get significantly longer, of course.
367 Search Geodining:
369 > geoqo -s geodining:resturant_name=Cafe -d count
371 Search/Set Count: 6
372 Searches the database for only waypoints that are of type 'Geodining'
374 and conform to the terms given. See the documentation on the waypoint:
375 search type for further details on how to use it, because everything
376 else is the same.
377 Possible search columns for geodining waypoints include the following
379 beyond those listed in the waypoint section:
380 geodining_restaurant_name
382 geodining_submitted_by
383 geodining_price
384 geodining_service
385 geodining_continent
386 geodining_country
387 geodining_state
388 geodining_city
389 geodining_zip
390 geodining_address
391 geodining_description
392 geodining_details
393 Search Wigle:
395 > geoqo -s wigle:name=unusual -d count
397 Search/Set Count: 6
398 Searches the database for only waypoints that are of type 'Wigle' and
400 conform to the terms given. See the documentation on the waypoint:
401 search type for further details on how to use it, because everything
402 else is the same.
403 Possible search columns for wigles include the following beyond those
405 listed in the waypoint section:
406 wigle_ssid
408 wigle_netid
409 wigle_discover
410 wigle_channel
411 wigle_type
412 wigle_freenet
413 wigle_firsttime
414 wigle_sep
415 wigle_comment
416 wigle_qos
417 wigle_lastupdt
418 wigle_paynet
419 wigle_userfound
420 Search Waypoint:
422 > geoqo -s waypoint:name=unusual -d count
424 Search/Set Count: 6
425 The waypoint search type is for searching for primary fields in a way‐
427 point record. Possible search terms include anything in the type-spe‐
428 cific searches (since waypoint: searches include everything) and the
429 following fields which apply to all waypoints regardless of specific
430 type:
431 desc
433 lat
434 lon
435 sym
436 time
437 type
438 subtype
439 url
440 urlname
441 cmt
442 The following are some examples of how to use the waypoint: search
444 type. Note that cache: and waymark: searches work the exact same way
445 and also do everything below, but limit your search to just waypoints
446 of those types.
447 The format for using the waypoint (or similarily for cache: or way‐
449 mark:) search terms is:
450 geqo -s waypoint:I<TERMS>
452 where TERMS are a comma separated list of search terms. Normally these
454 would be specified like:
455 waypoint:FIELDNAME=VALUE
457 The FIELDNAME indicates the field name you want to search (see below),
459 and the VALUE is the value you want to search for. The value field is
460 actually surrounded by wildcards, and thus searching for "me" will
461 match any value with "me" somewhere in it including "He and I went to
462 the store" and "sometimes". Using two equals signs turns off the auto‐
463 matic wildcard support (ie, name==me means search for a name that is
464 just "me").
465 An example: find all waypoints with a urlname field containing
467 "unusual":
468 > geoqo -s waypoint:urlname=tubular -d list
470 num GCID Name
471 1 GCDFE0 Hidden Headstones
472 2 GCE29A Celebrated Cemetery
473 3 GCHW9M The eyes have it (Yamar's unusual #1)
474 4 GCJ491 O where art thou (Yamar's unusual #2)
475 5 GCJ5DV Inverted Cache (Yamar's unusual #3)
476 6 GCJ66H Gone Fishin' (Yamar's unusual #4)
477 7 GCQEBQ Yamar's Unusual #6: The ORB
478 8 GCB284 Don't Be A Drip!
479 An example: find all geocaches owned by 'Spelunk':
481 > geoqo -s cache:owner_name=spelunk -d list
483 num GCID Name
484 1 GCJVTR Here's to Your Health Cache
485 2 GCJY4V Sumac Grove Cache
486 3 GCJZ2N Wildlife View Cache
487 4 GCKNZB Misplaced Seed Cache
488 5 GCKQBN Out-N-About Cache
489 6 GCKVFW We Give-A-Hoot Cache
490 7 GCNWM9 BUG JAR
491 8 GCP5YP Greenbelt Hideaway
492 9 GCPZK3 Davis Shopping Spree
493 10 GCQ6Q8 BUG JAR II
494 11 GCQ6TV Great Experience Cache
495 12 GCQ87Z Here's to the Greenbelts
496 13 GCQFYJ Toby & Willie's Friends
497 14 GCQH1M Connect the Dots Cache
498 15 GCTCC5 Canal Cache
499 16 GCTFJH The Micro Equalizer Cache
500 17 GCVVWY Spelunk's 'Fishy' Doings
501 18 GCW26F Mountain or Desert? Cache
502 Note that terms will match anything beyond the underscore ("_"). IE,
504 if you do a search for:
505 waypoint:short=some text
507 It will search the short description for "some text" even though the
509 actual field name it'll search is "groundspeak_short_description".
510 Using an exact fully spelled out field name is the most precise, but
511 you can truncate names for convience.
512 Finally, you can use '*'s to indicate wildcard spots (u*sal would match
514 "unusual" and "unit of sale"). By default geoqo already adds a * to
515 both the front and the back of your search time (ie, name=unusual is
516 actually interpreted as name=*unusual*).
517 You can also use the folling ARGUMENT types when searching for field
519 values in a waypoint:
520 field ARGUMENT value
522 field=value
524 Fuzzy match on value. The value will be surrounding by wildcards,
525 as previously discussed so searching for "desc=blowfish" will actu‐
526 ally search the desc field for "*blowfish*".
527 waypoint:desc=blowfish
529 field==value
531 Also as mentioned above, if you don't want to use the automatic
532 wild card searching discussed above, you can use 2 equal signs to
533 indicate this. Thus if you search for "desc=blowfish" it will
534 search the desc fields for an exact match on the word "blowfish"
535 (IE, must not contain any other words).
536 You should use == searches for numeric values too, or else some‐
538 thing like "difficult=3" will also match difficult numbers like
539 3.5.
540 waypoint:desc==blowfish
542 field<value and field>value
544 Allows you to search on less than or greater than numeric values.
545 IE:
546 waypoint:lon<42.123
548 or
550 waypoint:terrain>2
552 <> If you use both, it becomes "not equal to". IE:
554 waypoint:type<>unusual
556 Will list all waypoints without the word unusual in their desc
558 field. This is also doing the same automatic wildcard matching
559 like the = sign does, and thus the above search is actually search‐
560 ing for "*unusual*".p
561 <=> This is also "not equal to", but is an exact match and thus:
563 waypoint:desc<=>blowfish
565 will match any type of cache that doesn't have a desc field of
567 "blowfish". It will include, in the search, caches with a desc
568 field of "blowfish dinner" however because it's not an exact match.
569 Search Ident:
571 > geoqo -s ident:gcabcd,gcefgh,gcijkl -d count
573 Search/Set Count: 3
574 > geoqo -s ident:abcd,efgh,ijkl -d count
576 Search/Set Count: 3
577 The ident plugin merely lets you quickly list a bunch of waypoint iden‐
579 tifiers you want to select with geodb.
580 The identifiers do have a wild card inserted before them so you can
582 leave off a common prefix, as shown in the second example above, and
583 still match the list (saves typing).
584 Really, the ident: search type is just a faster way to type:
586 > geoqo -s waypoint:ident=abcd⎪⎪waypoint:ident=efgh⎪⎪...
588 Options:
590 idents:
592 A comma separated list of identifiers to search for
593 Search Log:
595 The log: search type lets you search waypoint log entries for waypoints
597 matching a criteria. As an example, you can search for all waypoints
598 in you database found by Yamar (me):
599 > geoqo -s 'log:finder=Yamar' -d list
601 num GCID Name
602 1 GCJVTR Here's to Your Health Cache
603 ...
604 Log tokens to search by:
606 id
608 ident
609 date
610 type
611 logger_id
612 logger
613 text_encoded
614 text
615 Special tokens to search by (makes sure a log was made by someone of a
617 particular type):
618 finder
620 noter
621 dnfer
622 WARNING: this may be amazingly slow on a mysql server. I think. Post‐
624 gresql or sqlite2 (the defualt) database backends are just zippy, how‐
625 ever.
626 Search Attr:
628 Attr searches attributes that you yourself have placed on a cache using
630 the modify setattr module.
631 > geoqo -s ident:gcabcd -m setattr:found=1 --save
633 > geoqo -s attr:found=1 -d count
635 Search Result Count: 1
636 Search Rating:
638 The rating plugin lets you search ratings that may have been placed on
640 a cache using the modify rate module.
641 > geoqo -s ident:gcabcd -m rate:fun=8
643 > geoqo -s "rating:fun>5" -d count
645 Search Result Count: 1
646 If you have downloaded average ratings from the ratings server, you can
648 search by those as well by prefixing the name with "others:" to search
649 by the average rating given to the cache by others:
650 > geoqo -s "rating:others:fun>5"
652 If you want to search for all caches that you have not rated for a par‐
654 ticular category, use:
655 > geoqo -s "rating:fun=-"
657 Search Tag:
659 Tag searches tags that you yourself or others have placed on a cache.
661 You can place them using the Tag Modify plugin:
663 > geoqo -s ident:gcabcd -m tag:cool/awesome
665 > geoqo -s tag:cool -d count:
667 Search Result Count: 1
668 Prefix the tag names with "mine:" if you want to search just you tags,
670 or "others:" if you want to search other people's tags.
671 > geoqo -s tag:mine:cool -d count:
673 Search Result Count: 1
674 > geoqo -s tag:others:cool -d count:
676 Search Result Count: 2
677 Search Set:
679 Sets, which are described further below, are a bunch of waypoints all
681 with an identically named "tag". As an example, if your geocaching.com
682 pocket query was named "my query" and you import it into geoqo using
683 the -i switch the waypoints contained in that gpx file will be assigned
684 to the "import:my query" set. You can use the set:setname search type
685 to load these waypoints.
686 > geoqo -s "set:import:my query" -d count
688 Search Result Count: 500
689 This command would count everything in the database that was in the
691 "import:my query" set name (that was likely imported from a pocket
692 query). See the Advanced Searching section in the geoqo documentation
693 for other examples of combining set: searches and waypoint: (or other)
694 searches so you can search for "all waypoints matching a criteia within
695 a set" for example.
696 If you prefix the name with a minus sign (-) then it will include all
698 caches NOT in that set. For example to find all caches that are in
699 seta but not in setb then the following expression would accomplish
700 that:
701 > geoqo -s 'set:seta&&set:-setb'
703 Search Track:
705 > geoqo -s track:mytrackfile.gpx -d count:
707 Search/Set Count: 3
708 The track plugin loads track data from a GPX track file (which you can
710 retrieve from you gps using gpsbabel) and then compares the list of
711 caches in you database to this data. It then matches all caches where
712 your speed dropped below a configurable speed (3MPH is the default) and
713 where the distance from the track is less than a configurable amount
714 (defaults to near 500 feet).
715 This is even more useful when combined with the Track modify plugin,
717 which can order caches based on the track and report the times you
718 found them as well.
719 If you know all the caches are in a given set, however, you should
721 probably limit the data it has to search through to a subset of you
722 total database if it runs slowly.
723 To get track data from the gps, use gpsbabel:
725 gpsbabel -t -i garmin -f usb: -o gpx -F track.gpx
727 See the Modify/Track plugin for a detailed example
729 Options:
731 trackfile:
733 A GPX trackfile to load and search by
734 speed:
736 Only look for caches where your speed dropped below this
737 default: 3
739 delta:
741 lat/lon delta to use looking for caches near a stopping point
742 default: 0.002
744 Search Any:
746 The any: search type simply uses all the waypoints in the entire data‐
748 base. It (hopefully) obviously doesn't make sense to use this combined
749 with other types of searches.
750
752 There are advanced things you can do while searching. This section
753 documents those:
754 Accessing a single result from the last search
756 Sumarize just the 12th waypoint from the last search results:
758 > geoqo -s 12 -d list
760 12 GCNK57 James Bond 047
761 Export caches 5-10 from the last search results:
763 > geoqo -s 5-10 -e out.gpx
765 Logical Searches
767 You can use && (AND) and ⎪⎪ (OR) pairs to add powerful searching combi‐
769 nations to your results. In fact, this is actually useful and can
770 increase the speed of your queries if used properly (if you know you
771 only want to search the data from a particular import, use a set:
772 search && with a waypoint: search and the result will likely be
773 returned faster).
774 This example searches for all waypoints owned by "spelunk" that I have
776 found (ie, it exists in the "import:My Finds Pocket Query" imported gpx
777 file).
778 > geoqo -s 'waypoint:owner_name=spelunk&&set:import:My Finds Pocket Query' -d list
780 num GCID Name
781 1 GCJVTR Here's to Your Health Cache
782 2 GCJY4V Sumac Grove Cache
783 3 GCJZ2N Wildlife View Cache
784 4 GCKNZB Misplaced Seed Cache
785 5 GCKQBN Out-N-About Cache
786 6 GCKVFW We Give-A-Hoot Cache
787 7 GCNWM9 BUG JAR
788 8 GCP5YP Greenbelt Hideaway
789 9 GCPZK3 Davis Shopping Spree
790 10 GCQ6Q8 BUG JAR II
791 11 GCQ6TV Great Experience Cache
792 12 GCQ87Z Here's to the Greenbelts
793 13 GCQFYJ Toby & Willie's Friends
794 14 GCQH1M Connect the Dots Cache
795 15 GCTCC5 Canal Cache
796 16 GCTFJH The Micro Equalizer Cache
797 17 GCVVWY Spelunk's 'Fishy' Doings
798 18 GCW26F Mountain or Desert? Cache
799 That is likely faster than doing the next search, but the following is
801 another way to do something similar. In this case, I'm searching for
802 all waypoints owned by spelunk that there is a log entry by me for
803 (note: finder is a mis-nomer as a finder may have logged it as a "did
804 not find"; search on the log "type" as well to limit it to just finds):
805 > geoqo -s 'waypoint:owner_name=spelunk&&log:finder=Yamar' -d list
807 num GCID Name
808 1 GCJVTR Here's to Your Health Cache
809 ... [same result] ...
810 grouping search terms
812 The () arguments can be used to group search terms together as well
814 when you need to mix operations. In the following case we're looking
815 for all waypoints "owned by scoobert AND have the word Ditch in them",
816 and add to that all waypoints logged by me and all waypoints with
817 'ninja' in the title. Silly example, I know.
818 > perl -I. geoqo -s '(waypoint:groundspeak:name=Ditch&&waypoint:owner_name=scoobert)⎪⎪waypoint:groundspeak:name=ninja⎪⎪log:finder=Yamar' -d list
820 1 GCYBDY Whodunit?
821 2 GCP8MT All Day
822 3 GCQJY0 Kate's Watching
823 [...]
824
826 Actually, just about everything is stored in a set. They're a powerful
827 way to "tag" a group of waypoints. The -N flag (or --set-name) flag
828 specifies which name you want to store your current search results into
829 (it's currently required and will always store the results somewhere).
830 Sets can be created from a search
832 > geoqo -N search:47dad47 -s waypoint:owner_name=47dad47 -d list
834 num GCID Name
835 1 GCH5EF Sacramento's Second Webcam Cache
836 [...]
837 14 GCR86K .
838 > geoqo -N search:gary -s waypoint:owner_name=gary -d list
840 num GCID Name
841 1 GCRWXC Fishing in Cache Creek
842 Sets can be listed:
844 > geoqo -d saved
846 Set Name Cache Count
847 -------------------- -----------
848 file:somefile 200
849 search:geoqo 13 <i>(default search name)</i>
850 search:47dad47 14
851 search:gary 1
852 And they can be combined:
854 > geoqo -s set:search:gary,search:47dad47 -d list
856 num GCID Name
857 1 GCRWXC Fishing in Cache Creek
858 2 GCH5EF Sacramento's Second Webcam Cache
859 [...]
860 15 GCR86K .
861
863 You've already seen the effects of the -d list switch, which lists all
864 the waypoints in the resulting set/search. But there are a number of
865 display types to pick from, and 'list' is only one such search output
866 style:
867 Display Help:
869 The help module displays help on a given topic. You can specify help
871 on a given topic.
872 Example 1:
874 geoqo -d help
875 Example 2:
877 geoqo -d help:topicname
878 The help routine displays help for the various geoqo plugins.
880 Options:
882 topic:
884 Specifies the topic to display help on.
885 Display Count:
887 Example:
889 geoqo -s 'set:import:my pocket query' -d count
890 Search/Set Count: 500
891 The Count display simply counts the results in a set. This is very
893 useful for counting the results before you do something with them (like
894 dumping 500 caches to your screen when you were looking for just a
895 few).
896 Options:
898 prefix:
900 The prefix string to print right before the count
901 default: Search/Set Count:
903 Display List:
905 Example 1:
907 geoqo -d list
908 num GCID Name
909 1 GCMR3M The Mystery of Livinrgttoo
910 2 GCPWBT Hidden Cactus Garden
911 Example 2:
913 geoqo -d 'list:format=%{3:count} %{6:ident} terr=%{3:groundspeak_terrain} diff=%{groundspeak_difficulty}'
914 1 GCMR3M terr=1.5 diff=1.5
915 2 GCPWBT terr=2 diff=1.5
916 The List display shows the contents of the search Set one line at a
918 time. By default, the format is (may vary depending on type though):
919 %{3:count} %{8:ident} %{66:urlname}
921 The number prefix is the number of spaces to print it in and it will
923 pad with extra spaces if it doesn't fill that space. If left out,
924 it'll print it straight out in any length it may be. Adding a decimal
925 point will limit it to a maximum of that length. IE:
926 %{20.20:urlname}
928 Will print only the first 20 characetrs of the urlname.
930 Options:
932 format:
934 Specifies the formatting parameters
935 Display Show:
937 Example 1:
939 geoqo -s 1 -d show
940 Show (-d show) the waypoint details for #3 from the last search (which is
941 really #3 from the default set or the set specified via the -N
942 switch):
943 > geoqo -s 3 -d show
945 GCHW9M Multi-cache Location: 38.542933, -121.6998
946 Name: The eyes have it (Yamar's unusual #1)
947 Owner: Yamar (#183928) Created: 2004-03-08
948 Placed By: yamar
949 Rating: 3/1.5
950 URL: http://www.geocaching.com/seek/cache_details.aspx?guid=5f9bd8d4-193a-4e0c-92c4-f107ae6d878b
951 Short Description:
952 A 3 part waypoint: a virtual, an unusual and a regular
953 Long Description:
955 Yamar to Spelunk on 2004-04-06:
956 "If this cache is under that lamp post [again], I'm going to scream."
957 [...]
958 Show the waypoint details and also the logs (-L, but this may change in
960 the future):
961 > geoqo -s 3 -d show -L
963 GCHW9M Multi-cache Location: 38.542933, -121.6998
964 Name: The eyes have it (Yamar's unusual #1)
965 [...]
966 Log #13914681 by Mango101: (Found it)
968 This cache took us way too many tries! Finally we found it! TNLN.
969 Log #14812407 by Mister Grim & Pooka: (Found it)
971 The hint threw us for a loop but we figured it out
972 eventually. Thanks for another great cache!
973 [...]
974 Options:
976 logs:
978 If true, shows the logs in the output.
979 default: 0
981 Display Top10:
983 The top10 dispaly plugin counts the values in a particular field and
985 shows you the top10 results of the counts in that field.
986 Example (defaults to counting the top 10 waypoint owners):
988 > geoqo -s any: -d top10
990 Top 10 'groundspeak_owner_name's
991 Num % Value
992 ----------------------------------------------------------------------
993 22 4 BootyBuddies
994 20 4 sailorscodgers
995 17 3 retiredprof
996 16 3 two bison
997 14 2 Sac D
998 14 2 Oldhippy & Granny
999 13 2 TRAKD
1000 12 2 rivercity
1001 11 2 2Dee2Dee
1002 10 2 jimlips
1003 10 2 Pirate Princesses
1004 Example: counting container types
1006 > geoqo -s any: -d top10:groundspeak_container
1008 Top 10 'groundspeak_container's
1009 Num % Value
1010 ----------------------------------------------------------------------
1011 234 50 Micro
1012 103 22 Regular
1013 92 19 Small
1014 13 2 Not chosen
1015 12 2 Other
1016 10 2 Virtual
1017 4 0 Large
1018 Setting the "doaverage" parameter will also display the average value
1020 associated with a numeric field:
1021 > geoqo -s 'cache:owner_name=Yamar' -d top10:groundspeak_difficulty,doaverage=1
1023 Top 10 'groundspeak_difficulty's
1024 Num % Value
1025 ----------------------------------------------------------------------
1026 14 38 2
1027 9 25 1.5
1028 6 16 1
1029 3 8 2.5
1030 2 5 3
1031 1 2 4
1032 1 2 3.5
1033 Average: 1.90278
1034 Display Sets:
1036 Example:
1038 geoqo -d sets
1039 Count Set Name
1040 ----- ----------------------------------------
1041 450 import:Bethel Island
1042 500 import:Concord
1043 500 import:Copy of SanFrancisco
1044 [...]
1045 Shows the list of existing sets remembered by the geoqo system, and the
1047 number of caches in each one. See the geoqo documentation on "sets"
1048 for further details.
1049 Options:
1051 match:
1053 Only lists set names containing this value
1054 Display Stats:
1056 Example:
1058 > geoqo -d stats
1060 Waypoints: 8754
1061 Geocaches: 8751
1062 Waymarks: 0
1063 Logs: 56659
1064 Sets: 33
1065 The stats display plugin shows statistics about what is contained in
1067 your database.
1068 Display Gui/list:
1070 Example:
1072 geoqo -s cache:urlname=funny -d gui/list
1073 The gui/list module displays a GUI in a graphical window that lets you
1075 examine the caches within a cache set.
1076 This is only very preliminary work and is subject to greater expansion
1078 in the future.
1079 Options:
1081 fields:
1083 default: Ident Type Subtype Groundspeak_Owner_Name URLNAME
1084 plugins:
1086 separator:
1087 default: 0
1088 Display Gui/show:
1090 Example:
1092 geoqo -s cache:urlname=funny -d gui/show
1093 The gui/show module displays a GUI in a graphical window that lets you
1095 examine the caches within a cache set.
1096 This is only very preliminary work and is subject to greater expansion
1098 in the future.
1099 Display Graph/find:
1101 Example:
1103 geoqo -s log:finder=Yamar -d graph/find:finder=Yamar
1104 This shows a graph of finds over time by a given person. Generally,
1106 you'll want to run this after you've incorporated a pocket query of all
1107 of your finds. You can run it against other user names too, but it's
1108 unlikely you have every log record for them unless you've imported
1109 their find pocket query too.
1110 Options:
1112 finder:
1114 Sets the NAME of the finder you're looking for to a particular geo‐
1115 caching name (ie, the name of the user that is logging the finds).
1116 99/100 egoists recommend using your own geocaching name here.
1117 logtype:
1119 Defines the log type to graph.
1120 default: Found it
1122 Display Graph/placed:
1124 Example:
1126 geoqo -s any: -d graph/placed:type=month
1127 Shows a graph displaying which during months, weeks, etc the caches
1129 were placed. Really this just gives an indication of which months are
1130 the most popular months for placing a cache (probably due to weather).
1131 Options:
1133 type:
1135 Examines creation date based on this frequency (X-axis column).
1136 PERIOD may be either month, day, year, weekday or yearday. The
1137 default is month (ie, the graph will be from 1-12 showing the num‐
1138 ber of caches placed during each month in your loaded search set).
1139 default: month
1141 Display Dump:
1143 Example 1:
1145 geoqo -d dump
1146 Example 2:
1148 geoqo -d dump:short=1
1149 Example 3:
1151 geoqo -d dump:format=perl
1152 The Dump display type dumps the contents of a set of waypoints. This
1154 is primarily a debugging mechanism.
1155 Options:
1157 short=1
1159 Makes everything fit on one 80column line per item. This will
1160 truncate field values to something short enough to do this.
1161 format=perl
1163 Uses Data::Dumper to show the output in perl structure form. For
1164 the expert.
1165 Options:
1167 short:
1169 If specified, limits output to 1 line per field
1170 includeall:
1172 If set then all waypoint items will be included, even if the field
1173 itself is blank
1174 default: 0
1176 format:
1178 If set to "perl" will use perl's Data::Dumper to dump the perl
1179 object
1180
1182 There are a number of modification plugins that modify data after it's
1183 been extracted from the database and before it gets either displayed
1184 (-d) or exported (-e). These are most useful for changing data before
1185 it's exported.
1186 Modify Solved:
1188 Example of solving a puzzle and saving it:
1190 > geoqo -s ident:GCABCD -m 'setattr:puzn=N38 42.444,puzw=W121 42.444' --save
1192 Example of exporting it with the replaced coordinates:
1194 > geoqo -s ident:GCABCD -e 'solved:+loc:out.loc'
1196 This plugin replaces the latitude and longitude coordinates of a way‐
1198 point with those in the puzn and puzw attributes. Use the above exam‐
1199 ples as a guide for solving a puzzle and then using the solved: plugin
1200 when exporting your database ready for uploading into a GPS.
1201 Options:
1203 nattr:
1205 The name of the attribute storing the new north coordinate
1206 default: puzn
1208 wattr:
1210 The name of the attribute storing the new west coordinate
1211 default: puzw
1213 dropunparsed:
1215 Drops caches that do not have puzzle answers but are not parseable
1216 default: 1
1218 Modify Gctodiff:
1220 The "gctodiff" plugin (short for "GC to difficulty") replaces the first
1222 two letters in the 6-digit cache identifier with a single digit repre‐
1223 sentation of both the difficulty and terrain ratings.
1224 IE, if you had this cache:
1226 > geoqo -l
1228 num GCID Name
1229 1 GCQEBQ Yamar's Unusual #6: The ORB
1230 It's rated a 1.5 in difficulty and a 2 in terrain. If you ran the
1232 gctodiff modify plugin on this data, it would replace the 'GC' with a 2
1233 and 3:
1234 > geoqo -m gctodiff: -d 'list:format=%{newident} %{desc}'
1236 23QEBQ Yamar's Unusual #6: The ORB
1237 It actually stores the data in the 'newident' field so the old one is
1239 still available. The export modules, however, use the newident field
1240 when writing out the cache identifiers so this is what your GPS, or
1241 what-have-you, will see when you load it into that.
1242 I (Yamar) do this specifically so when I'm looking at my garmin, for
1244 example, I get an immediate feel for how hard a particular cache is
1245 going to be without having to pull up data about it. (I also use the
1246 symbol plugin to change the symbol so I can see the type of cache it is
1247 too). My goal here is to maximize the amount of data I seen on the
1248 screen!
1249 The map from groundspeak/geocaching.com ratings is as follows:
1251 1 => 1
1253 1.5 => 2
1254 2 => 3
1255 2.5 => 4
1256 3 => 5
1257 3.5 => 6
1258 4 => 7
1259 4.5 => 8
1260 5 => 9
1261 Modify Rewrite:
1263 The rewrite modify plugin lets you rewrite fields based on other
1265 fields. For example, I (Yamar) use the following rewrite when putting
1266 stuff to a gpx file I'm going to load into my TomTom so I get as much
1267 information as possible when clicking on the icon in the tomtom map
1268 display:
1269 rewrite:groundspeak_name=%{ident}/%{4:subtype}: %{groundspeak_name}
1271 That way the groundspeak_name which might have been "some cache"
1273 becomes "GCABCD/Trad: some cache" to give me more information about it.
1274 (actually, I use the gctodiff plugin too and use the newident field
1275 instead; see the gctodiff plugin for details).
1276 Modify Setattr:
1278 The "Setattr" plugin (short for 'Set Attributes') allows you to add
1280 your own "attributes" to waypoint(s). You must specify the command
1281 line option "--save" to get them to be saved permenently to the data‐
1282 base though. You can pick any attribute name you want, although some
1283 other modify plugins (like the "solved" plugin) may expect particular
1284 attribute names.
1285 Atttributes can be used for just about anything. For example, you can
1287 use them to store notes, remember hints from other people, collect data
1288 for a complex puzzle cache, etc.
1289 Example of storing a note:
1291 > geoqo -s ident:GCABCD -m 'setattr:notes=I hate this puzzle' --save
1293 Example of something silly:
1295 > geoqo -s ident:GCABCD -m 'setattr:foo=bar' --save
1297 Then you can search for all caches with that name and value later:
1299 > geoqo -s attr:foo=bar -l
1301 Example of solving a puzzle and saving it:
1303 > geoqo -s ident:GCABCD -m 'setattr:puzn=N38 42.444,puzw=W121 42.444' --save
1305 Example of exporting it with the replaced coordinates:
1307 > geoqo -s ident:GCABCD -e 'solved:+loc:out.loc'
1309 The setattr plugin lets you store your own information about a cache
1311 into the database. Some of the other plugins use attributes to manipu‐
1312 late things (see the solved plugin for an example). Sometimes you may
1313 want your own "notes". As an example, I modify Unknown puzzles that
1314 you solve in the field (instead of "in advance" puzzles like cross puz‐
1315 zles) with "setattr:infield=1". (then I can use that attribute with
1316 the modifier: plugin to drop all unknowns that don't have that
1317 attribute set or don't have a 'puzn' coordinate assigned showing I've
1318 solved it.
1319 IMPORTANT NOTE: You must specify --save to the command line to have
1321 geoqo save your attribute changes back to the database. Otherwise
1322 you're only setting attributes temporarily during the one-time call of
1323 geoqo.
1324 Math and Substitution
1326 Math and Substition can be done by prefixing the values with "math:"
1328 and "substitute:" where the contents will be searched for names with
1329 other attribute names in ()s and replaced with the attribute values.
1330 And if the math: was used, it will then be evaluated. Multiple depth
1331 replacements/math will work.
1332 Here's a more complex than needed example (the puzw attribute needs to
1334 be set as well for this to work):
1335 > geoqo -s ident:GCABCD -m 'setattr:puzn=substitute:N38 42.(A)(B)(C)' --save
1337 > geoqo -s ident:GCABCD -m 'setattr:A=4' --save
1338 > geoqo -s ident:GCABCD -m 'setattr:B=math:(A)*2' --save
1339 > geoqo -s ident:GCABCD -m 'setattr:C=math:(B)-(A)' --save
1340 > geoqo -s ident:GCABCD -m solved: -e out.gpx
1341 Note that the actual equation will still be stored as the attribute;
1343 The calculation is done when the attribute is later read (for example,
1344 by the "solved" modify plugin).
1345 Modify Tag:
1347 The "Tag" plugin allows you to add "tag"s to your caches.
1349 Example:
1351 geoqo -s cache:owner_name==Yamar -m 'tag:tags=awesome/cool'
1353 Another to remove tags:
1355 geoqo -s cache:owner_name==Yamar -m 'tag:tags=lame,deletetags=1'
1357 Publishing tags
1359 Your tags may be published to a geoqo tag server, and you may pull
1361 information about how other people have tagged waypoints from the tag
1362 server. To do this you must first create an account on the tag server:
1363 http://tagserver.geoqo.org/
1365 Then put your created username and password into your $HOME/.geoqo/con‐
1367 fig file like:
1368 geoqouser YOURUSERNAME
1370 geoqopass YOURPASSWORD
1371 Then you can publish your tags for a given set using:
1373 geoqo -s SEARCHTERMS -m tag:publish=1
1375 Additionally you can fetch data about other people's tags using:
1377 geoqo -s SEARCHTERMS -m tag:fetch=1
1379 When you use the -S option to show a the data for a waypoint you will
1381 see a list of all your tags as well as a list of other peoples tags
1382 that you have fetched.
1383 Options:
1385 tags:
1387 deletetags:
1388 publish:
1389 publishtags:
1390 ignoretags:
1391 default: lamppost/found
1392 fetch:
1394 geoqouser:
1395 geoqopass:
1396 Modify Rate:
1398 The "Rate" plugin allows you to add "ratings"s to your caches.
1400 Example:
1402 geoqo -s cache:owner_name==Yamar -m 'rate:overall=4'
1404 (at the moment "overall" is the only rating you can provide; more com‐
1406 ing)
1407 Publishing ratings
1409 Your ratings may be published to a geoqo rating server, and you may
1411 pull information about how other people have rated waypoints from the
1412 rating server. To do this you must first create an account on the rat‐
1413 ing server:
1414 http://ratingserver.geoqo.org/
1416 Then put your created username and password into your $HOME/.geoqo/con‐
1418 fig file like:
1419 geoqouser YOURUSERNAME
1421 geoqopass YOURPASSWORD
1422 Then you can publish your ratings for a given set using:
1424 geoqo -s SEARCHTERMS -m rate:publish=1
1426 Additionally you can fetch data about other people's ratings using:
1428 geoqo -s SEARCHTERMS -m rate:fetch=1
1430 When you use the -S option to show a the data for a waypoint you will
1432 see a list of all your ratings as well as a list of other peoples rat‐
1433 ings that you have fetched.
1434 Options:
1436 overall:
1438 ratings:
1439 publish:
1440 publishtags:
1441 ignoreratings:
1442 deleteratings:
1443 fetch:
1444 geoqouser:
1445 geoqopass:
1446 Modify Makepuzzle:
1448 This plugin extracts puzzle coordinates and equations from a cache
1450 description and sets up some attributes for doing the puzzle solving.
1451 If a cache description has text in it like "N38 AB.CDE" then this plug‐
1452 in will create 5 attributes A-E and a "puzn" attribute with the text
1453 "replace:N38 (A)(B).(C)(D)(E)" so that merely by filling in the A-E
1454 attributes will complete the puzzle.
1455 Options:
1457 nattr:
1459 The name of the attribute storing the new north coordinate
1460 default: puzn
1462 wattr:
1464 The name of the attribute storing the new west coordinate
1465 default: puzw
1467 reextract:
1469 Force rextraction of the equation wiping out the existing data
1470 default: 0
1472 Modify Delete:
1474 This command removes the waypoints from the database. Obviously, this
1476 should be used with caution because it can not be undone.
1477 For those that really and truly hate puzzles:
1479 > geoqo -s 'cache:subtype=Unknown' -m delete
1481 This can be useful for temporarily importing a bunch of items you don't
1483 want to keep around in the long run.
1484 Modify Classify:
1486 Modify Symbol:
1488 This plugin replaces symbol identifier (normally "Geocache" for geo‐
1490 caches) with a new symbol based on your set criteria.
1491 As an example, I (Yamar) use the following mem: file definition to
1493 remap all my symbols into things that look (on my garmin) kind like the
1494 cache container:
1495 symbol:
1497 subtype=Multi-cache=Fitness Center,
1498 subtype=Unknown Cache=Information,
1499 subtype=Webcam Cache=Shower,
1500 groundspeak_container=Micro=Cemetery,
1501 groundspeak_container=Small=Tunnel,
1502 groundspeak_container=Large=Geocache Found,
1503 subtype=Virtual Cache=Ultralight Area
1504 Then I can run geoqo to remap stuff before exporting it to a .gpx file:
1506 > geoqo -s some_search_criteria -e 'mem:FILENAME+out.gpx'
1508 That way all multi-caches get remapped to a 'Fitness Center' because
1510 the 'Fitness Center' icon on my garmin looks like a little guy lifting
1511 weights, and thus I know it's going to be a harder cache (or one I'll
1512 likely have to walk more). I like multi's a lot, but I do like to know
1513 when I'm hitting them. Similarily, a Cemetery icon on my etrex is a
1514 small dot, a Tunnel is a bit larger, and a Geocache found icon is very
1515 large so I use them to represent sizes.
1516 If you want to use the symbol plugin, you should pick your own symbols
1518 that seem right on your gps or other software system. Each GPS's sym‐
1519 bols tend to be quite different (and the name chosen should be a symbol
1520 your GPS or software actually matches).
1521 Formatting
1523 The format of the plugin is as follows:
1525 symbol:CACHEDATA=CACHEVALUE=SYMBOLNAME,CACHEDATA2=CACHEVALUE2=SYMBOLNAME2,
1527 They are exact matches only. So the CACHEVALUE must exactly equal the
1529 value found in the CACHEDATA field or it won't be replaced. The symbol
1530 plugin will stop after the first match so the first symbol in the list
1531 that gets matched always wins.
1532 Modify Translate:
1534 By far, this is one of the most powerful modification plugins. It uses
1536 online services (like Google) to translate cache fields from one lan‐
1537 guage to another. As an example, here are some of my caches:
1538 > geoqo -s cache:owner_name==Yamar&&waypoint:ident=GCJ -l
1540 num GCID Name
1541 1 GCJYPW Hoppin' mad about Davis
1542 2 GCJGRQ Beneficial cache
1543 3 GCJKMD Historical water tower
1544 4 GCJ7KT Got Coffee?
1545 5 GCJ66H Gone Fishin' (Yamar's unusual #4)
1546 6 GCJ491 O where art thou (Yamar's unusual #2)
1547 7 GCJ5DV Inverted Cache (Yamar's unusual #3)
1548 And here is what they look like when translated from English to Span‐
1550 ish:
1551 > geoqo -s cache:owner_name==Yamar&&waypoint:ident=GCJ -l -m translate:source=English,destination=Spanish
1553 num GCID Name
1554 1 GCJYPW Hoppin' enojado sobre Davis
1555 2 GCJGRQ Escondrijo beneficioso
1556 3 GCJKMD Torre historica del agua
1557 4 GCJ7KT Cafe Conseguido?
1558 5 GCJ66H Fishin ido ' (4) inusual de Yamar #
1559 6 GCJ491 O donde mil del arte (2) inusual de Yamar #
1560 7 GCJ5DV Escondrijo invertido (3) inusual de Yamar #
1561 Valid languages to pick from:
1563 English
1565 Spanish
1566 French
1567 German
1568 Italian
1569 Korean
1570 Japanese
1571 Portuguese
1572 Requirements
1574 1) you must be connected to the net
1576 2) you must have the WWW::Babelfish perl module installed.
1578 Options:
1580 source:
1582 The source language to translate from.
1583 default: Spanish
1585 destination:
1587 The destination language to translate to.
1588 default: English
1590 fields:
1592 A / separated list of fields to translate.
1593 default: urlname
1595 service:
1597 The name of the translation service to use.
1598 default: Babelfish
1600 Modify Distance:
1602 The distance modify plugin puts distance information from a given lat,
1604 lon coordinate and inserts the data into the "distance" field of the
1605 waypoint. You can then use it in other ways like in rewrite modifica‐
1606 tion engines or in list formatting, etc.
1607 > geoqo -s ident:GCABCD -d 'list:format=%{ident} %{distance}
1609 You can calculate distance from coordinates:
1611 > geoqo -s ident:GCABCD -m 'distance:n=n38 12.123,w=w42 22.333'
1613 or from another waypoint already in the DB:
1615 You can calculate distance from coordinates:
1617 > geoqo -s ident:GCABCD -m 'distance:from=GCABCD'
1619 Options:
1621 from:
1623 The waypoint name distances should be calculated from
1624 n: The North coordiante to calculate distance from
1626 w: The West coordiante to calculate distance from
1628 Modify Sortby:
1630 The sort by function sorts data in a set by a particular field.
1632 > geoqo -s SOMETHING -m sortby:groundspeak_terrain -l
1634 Options:
1636 sortby:
1638 Field to sort by
1639 default: distance
1641 Modify Track:
1643 The track plugin lets you compare a list of waypoints found in a search
1645 against the data in a gpx track file. Specifically, it:
1646 - adds the following attribute fields to the waypoint's attribuets
1648 (not permenantly; use --save to save them):
1649 trkptdate - The date of the track point nearest the cache
1651 trkpttime - The time of the track point nearest the cache
1652 trkptnum - The number of the track point nearest the cache
1653 trkptname - The name of the track the point is in
1654 trkptdist - Distance in feet from the cache to the nearest track point
1656 trkptnum - The Nth track point counter into the track point data
1657 trkptepoch - Seconds since 1970 of the trackpoint closest to the cache
1658 trkptstart - Start time of the search (got closer than config distance)
1659 rtkptend - End time of the search
1660 rtkptnearby - Amount of time spent searching (= end - start)
1661 - optionally sorts the resulting waypoints by time visited if the
1663 sort option is set.
1664 Using this and the track search plugin you can take a track GPX file
1666 downloaded from a GPS and list all the caches you came near in the
1667 order you went to them along with the time stamp when you visited it.
1668 As an example, this is the results of a trip I took one day:
1669 > geoqo -s 'track:track.gpx' -m 'track:track.gpx' -d list:'%{7.7:ident} %{attr:trkpttime} %{urlname}'
1671 GC10J27 10:55:22 This one is Golden
1673 GCPC2R 11:16:53 "THE ISLAND"
1674 GCYCGE 13:02:07 Legacy Trail #1 - River BBQ
1675 GCD8A1 13:10:55 Under Lock & Key
1676 GC5CBC 13:52:32 Let the Games Begin
1677 GCPR6E 14:11:27 YFcache10
1678 GCWR36 14:31:10 Granite Rock
1679 GCK8YR 14:54:07 The Cache in The Middle of The Freeway
1680 GCYYXV 16:02:05 Cisco Grove TB Stop
1681 GC10Q0Q 16:02:41 Hard Rock Exchange #2
1682 GCW1C3 16:27:08 Crack with a View
1683 GCG38E 16:45:33 The Solar System - Pluto
1684 To get track data from the gps, use gpsbabel:
1686 gpsbabel -t -i garmin -f usb: -o gpx -F track.gpx
1688 Options:
1690 trackfile:
1692 Track data to sort by
1693 sort:
1695 field to sort resulting set by (if set)
1696 default: trkptepoch
1698 distance:
1700 Distance away in feet to use for determining how long you were in
1701 the area
1702 default: 528
1704 hroffset:
1706 Offset in hours to use from the datestamp found in the track; use‐
1707 ful if the timezone in the GPS/track does not match the track was
1708 laid
1709 Modify Diff:
1711 Options:
1713 out:
1715 the name of the output file to store the html formated differences
1716 in.
1717 Modify Limit:
1719 This module limits the number of waypoints in a set to a certain number
1721 (starting at an optional certain point in the list of waypoints).
1722 IE, it starts at the offsetth waypoint in the set being modified, and
1724 limits the total number to number, stripping off all of the waypoints
1725 before the offset first and then everything from offset+number next.
1726 If just number is specified (the common case) the firest number way‐
1728 points are kept.
1729 If there are 250 caches in the set:
1731 number = 100, offset = 0
1733 Will get the first 100 caches
1734 number = 100, offset = 100
1736 Will get the next 100.
1737 number = 100, offset = 200
1739 Will get the last 50.
1740 This module is very useful when combined with the distance and sortby
1742 modify pluigns to get the top 10 caches (for example) near something:
1743 geoqo -s 'set:import:mypocketquery' -m distance:from=GCABCD+sortby:+limit:10
1745 Options:
1747 number:
1749 default: 100
1750 offset:
1752 default: 0
1753 Modify Only:
1755 This is most useful when doing really complex exporting. See Yamar's
1757 usage description on the web page for why this is helpful sometimes.
1758 It's mostly useful when you want to only include certain waypoints in a
1759 given export file, and you want to create lots of export files (Tom‐
1760 Tom's require one file per POI you wish to create, and I (Yamar) create
1761 different POIs for each cache type, size, etc.)
1762 The argument formatting is:
1764 only:field=value
1766 where field is the field (or attribute prefixed with 'attr:') name, and
1768 value is the exact value. The valid match types are:
1769 only:field=value
1771 Includes the waypoint only if the value is exactly the same as the
1772 waypoint's field value.
1773 only:field<>value
1775 Matches if the field is not that value
1776 only:field=-
1778 Matchs if the field doesn't exist.
1779 only:field=+
1781 Same as =- but only includes the waypoint if it does exist.
1782 Modify Drop:
1784 This is most useful when doing really complex exporting. See Yamar's
1786 usage description on the web page for why this is helpful sometimes.
1787 The Drop modifier is a compliment to the only modifier. Generally the
1789 "only" modifier will be easier for most people to think about, but
1790 technically you only need one as they can both accomplish the same
1791 tasks with inverse logic.
1792 The argument formatting is:
1794 drop:field=value
1796 where field is the field (or attribute prefixed with 'attr:') name, and
1798 value is the exact value. The valid match types are:
1799 drop:field=value
1801 Matches only if exactly the same.
1802 drop:field<>value
1804 Matches if the field is not that value
1805 drop:field=-
1807 Matchs if the field doesn't exist. I use this like follows:
1808 #
1810 # unknown caches with solved puzzle coords
1811 #
1812 drop:subtype<>Unknown Cache
1813 +drop:attr:puzn=-
1814 +solved:
1815 +gpx:nologs=1:palm-solved.gpx
1816 To drop any unknown cache that a 'puzn' attribute hasn't been added
1818 to it (see the Solved modify plugin for details).
1819 drop:field=+
1821 Same as =- but only drops it if it does exist.
1822 Modify Dropexisting:
1824 This modify function is really only useful during an import before a
1826 data save.
1827 The plugin simply removes all data from the current set that already
1829 exists in the database. This can be used to import data where only the
1830 new data is desired.
1831 Example:
1833 > geoqo -i 'myfile.gpx+dropexisting'
1835 Options:
1837 prefix:
1839 default:
1840 onlyprefixold:
1842 default: 1
1843 Modify Load:
1845 This is only useful when you're going to be doing complex exporting
1847 where you need the caches data loaded early before exporting to multi‐
1848 ple files. Otherwise geoqo may load all the data once per file.
1849 > geoqo -s something -m load -e 'gctodiff+file1.gpx;file2.gpx
1851 See the export documentation for details on why file1.gpx and file2.gpx
1853 may contain separate data.
1854 Basically, since this is a confusing one, is if you're doing complex
1856 exporting (multiple files at once) put this on the -m switch to speed
1857 things up.
1858
1860 None of this is useful if you can't export your results of course.
1861 There are a number of export plugins you can pass to the -e switch to
1862 export the results of your search to a file.
1863 QUICK EXPORT EXAMPLES
1865 Some quick examples:
1867 Exporting all waypoints from two sets:
1869 > geodb -s 'set:search:gary&&set:search:47dad47' -e garyand47.gpx --debug 1
1871 1: writing file: garyand47.gpx
1872 Exporting all waypoints in a set that are of type "Unknown" to a .loc
1874 file:
1875 > geodb -s 'set:import:somefile&&waypoint:type=Unknown' -e partfilebackout.loc
1877 EXPORTING AND MODIFYING
1879 You can also combine modifications and exports in one pass. First list
1881 the modifications specs you want to do (see the documentation on the
1882 modification plugins for details) separated by + signs. Everything
1883 before the last + will call a modification plugin, and after the last +
1884 will be an export plugin.
1885 An example:
1887 > geodb -s 'cache:type=Unknown' -e gctodiff+partfilebackout.loc
1889 OUTPUTING TO MULTIPLE FILES
1891 You can also specify multiple output files separated by ';'s. Modifi‐
1893 cation attributes will only apply to the next file. If you want every
1894 file to contain a modification plugin result, use the -m flag instead.
1895 > geodb -s 'cache:type=Unknown' -e 'gctodiff+partfilebackout.loc;partfilebackout2.gpx
1897 The above applies the gctodiff plugin to only the .loc file; the gpx
1899 file is written out using raw data.
1900 EXPORT PLUGIN TYPES
1902 Export Gpx:
1904 > geoqo -s 'cache:name=cool cache' -e myfile.gpx
1906 The gpx exporter writes out a gpx file containing all the caches in the
1908 search set.
1909 Options are applied between the colon delimiter type specifier (first
1911 part) and the file name (th e last part) like so:
1912 > geoqo -s 'cache:name=cool cache' -e gpx:nologs=1,setname=boo:myfile.gpx
1914 Options:
1916 setname:
1918 Makes the name field in the gpx file set to this value.
1919 default: geoqo-export
1921 nologs:
1923 If set the resulting gpx file does not contain the wayoint logs.
1924 Export Loc:
1926 > geoqo -s 'cache:name=cool cache' -e myfile.loc
1928 The loc exporter writes out a loc file containing all the caches in the
1930 search set.
1931 Export Kml:
1933 > geoqo -s 'set:import:near me' -e fortheearth.kml
1935 The software will also produce a density plot as well, which shows the
1937 density of caches in particular areas color-coded by relief colors
1938 (rainbow; red = very few, purple = many). Examples of this can be seen
1939 on Yamar's cache homepage page http://geocaching.sharedlists.com/.
1940 Options:
1942 size=NUM
1944 > geoqo -s 'set:import:near me' -e kml:size=100:fortheearth.kml
1945 Changes the number of squares in the density plot to NUM by NUM.
1947 Defaults to 50.
1948 width=NUM
1950 height=NUM
1951 Changes just the width and height of the squares. The size parame‐
1952 ter can change both at once.
1953 (there are a bunch of options for the density plot, which are currently
1955 undocumented).
1956 Options:
1958 bogus:
1960 dataname:
1961 default: Export from GeoQO
1962 dowaypoints:
1964 default: 1
1965 dodensity:
1967 default: 1
1968 dojail:
1970 default: 0
1971 bogus:
1973 waypointstyle:
1974 default: geoqo
1975 waypointheight:
1977 default: 150
1978 waypointmode:
1980 default: relativeToGround
1981 waypointextrude:
1983 default: 1
1984 includedescriptions:
1986 default: 1
1987 bogus:
1989 squareratio:
1990 default: 1
1991 size:
1993 Creates a plot where there are SIZE by SIZE squares of colored rec‐
1994 tangles
1995 default: 200
1997 width:
1999 Normally equal to the size value but can be set independently. It
2000 specifies the width (in squares) of the density plot.
2001 height:
2003 Normally equal to the size value but can be set independently. It
2004 specifies the height (in squares) of the density plot.
2005 spread:
2007 Sets the spread that determines the number of neighboring squares
2008 that a given cache will effect. EG, a spread of 5 will affect a
2009 circle of density squares in a radius of 5. This generally should
2010 be a low value of probably not more than 5 or so.
2011 default: 5
2013 doempty:
2015 If set to 1, even empty squares will be colored (red). Otherwise
2016 the empty squares are removed from the plot leaving the plane
2017 ground underneath.
2018 default: 0
2020 bogus:
2022 altitude:
2023 The altitude to set the density plot squares at.
2024 default: 1000
2026 densitymode:
2028 default: relativeToGround
2029 extrude:
2031 Whether or not to extrude the density plot squares down to the
2032 ground.
2033 default: 0
2035 opaque:
2037 The opacity of the density squares. Must be between 0 and 100,
2038 with 0 being completely see-through (and thus completely useless).
2039 default: 20
2041 linewidth:
2043 The width of the border lines to draw (0-4). 0 means don't draw
2044 borders on the squares.
2045 default: 0
2047 bagus:
2049 jailaltitude:
2050 default: 100
2051 jailmode:
2053 default: relativeToGround
2054 bogus:
2056 limitdata:
2057 default: 1
2058 nmax:
2060 The maximum north coordinate value to created the grid over. Nor‐
2061 mally this is automatically set by the maximum value found in the
2062 data, but can be overridden
2063 nmin:
2065 The minimum north coordinate value to created the grid over. Nor‐
2066 mally this is automatically set by the minimum value found in the
2067 data, but can be overridden
2068 wmax:
2070 The maximum west coordinate value to created the grid over. Nor‐
2071 mally this is automatically set by the maximum value found in the
2072 data, but can be overridden
2073 wmin:
2075 The minimum west coordinate value to created the grid over. Nor‐
2076 mally this is automatically set by the minimum value found in the
2077 data, but can be overridden
2078 Export System:
2080 There are two ways to use the system export mechanism:
2082 Run a system command for cache:
2084 > geoqo -s 'cache:name=cool cache' -e 'system:cmd=echo %{ident} %{desc}'
2085 That command runs echo for each cache in the set, replacing
2087 %{ident} and %{desc} with the fields from those caches.
2088 Useful things to do for this would be to open firefox (a web
2090 browser) on each cache page:
2091 > geoqo -s 'cache:name=cool cache' -e 'system:cmd=firefox %{url}'
2093 Run a system command
2095 You can also run a command on a file generated by an export module.
2096 As an example, the following command will call gpsbabel to convert
2097 a gpx file to a tomtom compatible file:
2098 > geoqo -s 'cache:name=cool cache' -e 'system:cmd=gpsbabel -i gpx -f %{file:gpx} -o tomtom -F mycaches.ov2'
2100 Options:
2102 cmd:
2104 COMMAND is what gets run. If it contains a %{file:TYPE} string in
2105 it, that will be replaced with a file name of that type and it'll
2106 get run just once. If it doesn't, it'll get run once per cache in
2107 the set being processed and each %{token} specifier will get
2108 replaced by that item from the cache.
2109 sleep:
2111 Between each command executed in the per-cache mode, geoqo will
2112 sleep for NUM seconds before running the next. It defaults to 1,
2113 and can be set to 0 to just fire them off as fast as possible.
2114 dontdelete:
2116 if set to 1, don't delete the temporary files
2117 tmpdir:
2119 The temporary directory to use
2120 default: /users/hardaker/.geoqo/temp
2122 Export Html:
2124 > geoqo -s 'cache:name=cool cache' -e myfile.html
2126 Prints a set of caches to a series of web pages. Each cache will
2128 get it's own file and a top level index file will be created that
2129 links to each cache page.
2130 Very useful for outputting geocaches to plucker.
2132 Options:
2134 subdir:
2136 Puts created HTML files in this sub directory name.
2137 default: caches
2139 title:
2141 The title to put at the top of the page
2142 default: GeoDB HTML Export
2144
2146 Here are some useful plugins that can be used in many command line def‐
2147 initions.
2148 Everywhere mem:
2150 It hard to repeatedly type complex queries, tasks, or what have you so
2152 to facilitate this you can use the Mem plugin for remembering complex
2153 strings (or even simple onse, if you choose).
2154 To do this, take a complex search (or export, or modify) string and
2156 save it in a file in the directory "$HOME/.geoqo/mem/TYPE/FILENAME".
2157 Where TYPE is one of "search", "export", or "modify" and FILENAME is a
2158 file name of your choosing. You can also store file entries directly
2159 in $HOME/.geoqo/mem/FILENAME (note the missing "TYPE" part), which then
2160 makes the definition usable for all types. It is not likely you'll
2161 need to use a definition for both searching and exporting (as an exam‐
2162 ple), however, so I suggest you store them in a type-based subdirectory
2163 instead. Only because it's cleaner. You want to be neat and tidy
2164 right?
2165 All lines read in these file will be merged together and leading and
2167 trailing white-space characters are stripped as well comment lines
2168 (which should start with a #). For example if you had a file like so:
2169 > cat $HOME/.geoqo/mem/search/memtest
2171 # Searches a particular imported set named "near me"
2172 set:import:near me
2173 # but only for items I haven't logged as found
2174 &&cache:finder<>Yamar
2175 # and aren't unknown caches.
2176 &&cache:subtype<>Unknown
2177 You can then run geoqo like so:
2179 > geoqo -s mem:memtest -d count
2181 Search Result Count: 480
2182 Which is really a replacement for:
2184 > geoqo -s set:import:near me&&cache:finder<>Yamar&&cache:subtype<>Unknown -d count
2186 Since you may want to frequently replace parts of your super-long and
2188 complicated definition strings you've built up, you can do this as well
2189 by putting %[NAME,DEFAULT] strings inside your definitions. IE, doing
2190 this:
2191 > cat $HOME/.geoqo/mem/memtest
2193 set:import:%[setname,near me]
2194 &&cache:finder<>Yamar
2195 &&cache:subtype<>Unknown
2196 Makes the import: set default to "near me" so the above example command
2198 will work just like it would before, but if I specify a setname option
2199 on the command line I can override it. Here's the original command
2200 example:
2201 > geoqo -s mem:memtest -d count
2203 Search Result Count: 480
2204 And here's using the same search criteria, but using "fairfield" as the
2206 import set name instead of the default "near me":
2207 > geoqo -s mem:memtest,setname=fairfield -d count
2209 Search Result Count: 182
2210 Final note: you can have mem: definitions that call other mem: defini‐
2212 tions. The only caveat there is that parameters aren't passed down
2213 automatically, so if your second mem: definition being called has a
2214 %[something,xxx] definition then you should call it within the higher
2215 definition as mem:subdef,something=%[something,xxx] as well.
2216
2218 GeoQO can also perform a bunch of tasks at once in a scripted fashion.
2219 IE, if you find yourself repeatedly doing a standard search followed by
2220 an export, you can script things together in a single file and call
2221 geoqo -x FILE.
2222 The script file format contains lines that start with a '%MODE' fol‐
2224 lowed by text for that MODE. MODE should be one of: search, export,
2225 import, modify, display or print. You can break long lines into pieces
2226 just like the mem: plugin discusses above.
2227 Thus the following script (saved in, for example, "myscript.txt") will
2229 display unsolved puzzles in your database ordered by distance:
2230 # searches for all 'Unknown' caches
2232 %search
2233 subtype=Unknown
2234 &&attr:puzn=-
2235 # displays them in list format
2237 %display
2238 list
2239 Then running the script will display the list:
2241 > geoqo -x myscript.txt
2243 ... [list displayed here] ...
2244 Scripts can be stored in $HOME/.geoqo/scripts and if a script is run
2246 and the file doesn't exist in the current working directory, then the
2247 $HOME/.geoqo/scripts directory will be checked to see if it contains
2248 the file.
2249 Scripts can contain %[name,default value] sections just like Everywhere
2251 Mem: definitions can and are acted upon the same way. Thus a script
2252 of:
2253 %search
2255 waypoint:type==%[type,Waymark]
2256 %display
2258 count
2259 Will default to counting all the Waymarks in the database. But if run
2261 as:
2262 > geoqo -x myscript.txt:type=Geocache
2264 It'll count all the geocaches instead.
2266 Special Script Formatting
2268 White Space Wrapping
2270 Normally script lines are merged together, stripping leading and trail‐
2272 ing white space off of a line. EG, Scripts that look like:
2273 %search
2275 waypoint:type=
2276 =
2277 Geo
2278 cache
2279 will actually be translated to a search using just:
2281 wayoint:type==Geocache
2283 If you need to force whitespace into a script line at the begining or
2285 end you can use a triple " in order to forec it. EG:
2286 %search
2288 cache:owner_name=Super
2289 """ Sleuth"
2290 Will keep the space between the """ and the word Sleuth:
2292 cache:owner_name=Super Sleuth
2294 Trailing """s work similarily.
2296 Special Script Keywords
2298 All script pieces begin with a % sign on a new line. The line format
2300 looks like:
2301 %keyword someoption=1 otheroption=yes
2303 These special options may include these global options as well as any
2305 keyword-specific options discussed below:
2306 allowgui=1
2308 This lets the GUI screens be shown for the sub-scripts. Normally
2309 they're hidden as the top script is always expected to pass needed
2310 parameters down.
2311 The special script keywords that mayb be used are:
2313 %print
2315 Prints everything from that section to the screen.
2316 Example:
2318 %print hello world
2320 %script
2322 Runs a subscript based on the text following the %script line.
2323 (may include the script name and potentially arguments following a
2324 ':').
2325 Example:
2327 %script scriptname:arg1=value1
2329 %include [ARGUMENTS] SCRIPT_FILE_NAME
2331 Include another script as part of this script. Unlike the %script
2332 command, the %include command operates on the same search set,
2333 becomes part of the same auto-gui screen, etc.
2334 You can also pass a type=hooks argument to include a bunch of
2336 files. EG:
2337 %include type=hooks specialhooks/*.inc
2339 Will include every file that matches that pattern in each of the
2341 script search paths. The order in which they are included is
2342 determined by alphabetical ordering of the last filename component
2343 (ie, not directory path component).
2344 Finally, you can auto-wrap includes in if statements and use the
2346 resulting titles from the included files in menu to select which
2347 file gets executed. This is primarily intended for building
2348 dynamic menus from found plugins. This is best seen by an example:
2349 In a file called "testincludetop.txt", we put the menu definition:
2351 %ignore
2353 %[mymenu,0
2354 ,labels=(%{VALUELABELS})
2355 ,type=menu,text=top menu:
2356 ,refresh_on_change=1
2357 ]
2358 In two files called testinclude-1.txt and testinclude-2.txt we put:
2360 #scriptname: item number 1
2362 %print
2363 some thing or other to handle choice #1
2364 (And something similar for number 2)
2366 Then finally, in the real top level script you call the whole sha‐
2368 bang with:
2369 %include type=hooks autoif=mymenu hookheader=testincludetop.txt testinclude*.txt
2371 In the end, the whole result gets built as follows:
2373 %ignore
2375 %[mymenu,0
2376 ,labels=(0,item number 1,2,item number 2)
2377 ,type=menu,text=top menu:
2378 ,refresh_on_change=1
2379 ]
2380 %if "%[mymenu]" eq "0"
2381 %title
2382 item number 1
2383 %print
2384 some thing or other to handle choice #1
2385 %endif
2386 %if "%[mymenu]" eq "1"
2387 %title
2388 item number 2
2389 %print
2390 some thing or other to handle choice #2
2391 %endif
2392 If you could follow that, I'll be impressed. But it's really pow‐
2394 erful! See the included "searchbase" script for a much larger
2395 example.
2396 %save
2398 Calls 'save' on the current set saving all the data to the db
2399 (needed if modified in anyway that should result in a save, such as
2400 when the setattr: modify plugin was called).
2401 %saveset name=MYNAME
2403 Remembers the current set as MYNAME.
2404 %webfile
2406 Pulls a file from a URL and saves it to a file. The format is the
2407 file name to save it to, a comma and then the URL. Example:
2408 %webfile
2410 waymarks-train.gif,http://www.waymarking.com/images/cat_icons/train.gif
2411 You can then refer to these files using webfile:waymarks-train.gif
2413 in %copy or %system commands.
2414 %copy
2416 Copy's a file from one place to another. Example format:
2417 %copy
2419 file1.loc,file2.loc
2420 Or refering to a webfile previously pulled from a %webfile direc‐
2422 tive:
2423 %copy
2425 webfile:waymarks-train.gif,/some/path/to/waymarks-train.gif
2426 %system
2428 Run's a system command. webfile: prefixes within the command
2429 string will be replaced by paths to a stored %webfile.
2430 %if CLAUSE
2432 %else
2433 %endif
2434 These sections allow for variablity of what is done based on user
2435 input. CLAUSE is evaluated as perl code (returning a perl true or
2436 false response (eg, 1 or 0)) to determine what to do next. CLAUSE
2437 will be evaluated first in terms of parameteritized input. Thus:
2438 %print
2440 %if %[desire,1,type=checkbox]
2441 hello
2442 %else
2443 world
2444 %endif
2445 Will print "hello" if the user clicks the check box (defaults to
2447 on) or "world" if the user does not. (They may also hand-specify
2448 the 'Desire' parameter as scriptname:desire=1 or equievelent).
2449 Nesting is properly handled.
2451 %foreach VAR value1 value2 ...
2453 %endforeach
2454 Allows repeated script sections with %{VAR} being replaced with a
2455 different value for each section.
2456 %foreach it 1 2 3 a b word
2458 %print
2459 This is it: %{it}
2460 %endforeach
2461 Will output:
2463 This is it: 1
2465 This is it: 2
2466 This is it: 3
2467 This is it: a
2468 This is it: b
2469 This is it: word
2470 %perl
2472 Embeds perl into the script. $self is a reference to the master
2473 GeoDB object. Use this functionality only if you're an expert (and
2474 in desperate need).
2475 %perl leavewhitespace=1
2477 %title
2479 Names the script with a title.
2480 %title
2482 My super title
2483 %introduction
2485 Includes a paragraph in the top of the GUI screen when the script
2486 is run.
2487 %introduction
2489 This is how you use this screen
2490
2492 -i STRING
2493 --import-file=STRING
2494 Import a file. File should be specified as type:file
2495 -n STRING
2497 --name=STRING
2498 Comma separated names to assign to the objects in the file
2499 -m STRING
2501 --modify=STRING
2502 Modify the search set before displaying or exporting
2503 -e STRING
2505 --export-file=STRING
2506 Export a file. File should be specified as type:file
2507 --execute-script=FILENAME
2509 -x FILENAME
2510 Run a script stored in FILENAME
2511 Search Options:
2513 -s STRING
2515 --search=STRING
2516 Search terms for geocaches
2517 --limit=INTEGER
2519 Maximum number of records to return for searches
2520 -N STRING
2522 --set-name=STRING
2523 Set/Search Storage Name ('search:geoqo')
2524 Display Options:
2526 -l
2528 --list-caches
2529 List geocaches found in search
2530 -S
2532 --show-caches
2533 Show details of geocaches found
2534 -L
2536 --show-logs
2537 Show log messages in details output
2538 -d STRING
2540 --display=STRING
2541 Display output thingies
2542 --save
2544 --save-changes
2545 Save changes to the set to the DB
2546 Database Options:
2548 -t STRING
2550 --db-type=STRING
2551 Database Type (sqlite2, sqlite, mysql, postgres)
2552 -H STRING
2554 --db-host=STRING
2555 Database Host (localhost)
2556 -u STRING
2558 --db-user=STRING
2559 Database User (geoqo)
2560 -p STRING
2562 --db-password=STRING
2563 Database Password
2564 --db-name=STRING
2566 Database Name (geoqo)
2567 --db-flush
2569 Delete the existing DB first
2570 --db-port=INTEGER
2572 Port number for the database
2573 --setup-database
2575 Initialize the database table structure
2576 Configuration Options:
2578 -c STRING
2580 --config-file=STRING
2581 Configuration File to read
2582 -C
2584 --no-config
2585 Do not read any configuration file
2586 --debug=INTEGER
2588 Turn on debugging output
2589 Help Options
2591 -h Display a help summary (short flags preferred)
2593 --help
2595 Display a help summary (long flags preferred)
2596 --help-full
2598 Display all help options (both short and long)
2599 --version
2601 Display the script version number.
2602
2604 GeoQO supports a configuration file where multiple types of things can
2605 be specified.
2606 Command Line Options and Default
2608 You can also store "always use this" options in a configuration file
2610 named ~/.geoqo/config. This file should be the option name on the left
2611 (single letter option if available, not longer ones) followed by the
2612 value you want after a space. EG to always use debugging and post‐
2613 gresql and the 'geo' database user:
2614 t postgresql
2616 u geo
2617 debug 5
2618 Any option may be added to this file. Options on the command line will
2620 override options in this file (as you'd expect).
2621 GUI Defaults
2623 When using the auto-gui created screens, you can specify your own
2625 defaults for widgets created by geoqo modules or scripts using the
2626 "default" keyword. EG:
2627 default searchby Power Search
2629 Will set the default search mechanism to the "Power Search" option.
2631 Knowing what keyword to use and what value to use generaly requires
2632 understanding how geoqo works at this point though (or you can ask
2633 Yamar in the #geoqo IRC channel).
2634 Per-Screen GUI Defaults
2636 You can also set defaults or for particular script screens. To set the
2638 default search type in the devices/cachemate script GUI screen:
2639 screen devices/cachemate searchby Power Search
2641
2643 If you really want to see what geodb is doing internally, run with the
2644 --debug switch. In particuluar, "--debug 5" will print lots of inter‐
2645 esting information. Too much. The higher the number the more you get.
2646
2648 The following people (geocachers) helped in useful ways with this pro‐
2649 gram:
2650 BlueNinja
2652 Self proclaimed "test monkey". He tested lots of early verions and
2653 has caught various bugs as well and given me better usage ideas
2654 through his "why can't I do this" set of questions.
2655 He was also the first person to get it working on Windows and has
2657 contributed vastly to the windows documentation.
2658 ClayJar
2660 Who won the renaming contest on IRC after SourceForge told me GeoDB
2661 was an internal reserved name:
2662 [03:38:13 pm] <ClayJar_SSH>Yamar: How about "Geoqo". You'll have
2664 sole Google of that one, I imagine. You can pronounce it "ge-OH-ko",
2665 and "QO" is DB after ROT13.
2666 For those that don't know, ROT13 is the cheap encryption mechanism
2668 that geocaching.com (and other places) use to encrypt their logs.
2669 (ROT13 is used in many, many other ways too, and the first most
2671 popular usage of it was to encrypt potentially offensive material
2672 (ie, jokes) when posting to USENET news groups)
2673 Planet
2675 Planet nicely volunteered to proof-read a copy of this manual and
2676 sent me many wonderful suggestions about improving it.
2677 jslagle
2679 The first person to send me a code patch (implementing a better zip
2680 file import handler)! Yay! He's now a co-developer.
2681 brdad
2683 The first person to wade through what it takes to get the GUI work‐
2684 ing under windows.
2685 lairsdragon
2687 Submitted patches for the build system to make it more PREFIX
2688 friendly.
2689 Zemmy
2691 An early Windows test case for the installer components.
2692
2694 Wes Hardaker <hardaker ATAT users.sourceforge.net>
2695 AKA "Yamar" on Geocaching.com, IRC, and other places
2697perl v5.8.8 2008-04-23 GEOQO(1)
