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
39 tutorials, 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,
108 however, create as many databases using other file names as you want
109 (but 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
124 sections further below for more details on what a "set" is and how
125 useful 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
155 groundspeak sends them out for geocaching.com pocket queries. IE, if
156 you import "111111.zip" it'll try to unzip it and then import the
157 contained 111111.gpx file. It'll also try to import the
158 1111111-wpts.gpx file, 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: /home/hardaker/.geoqo/temp
178 Import Dir:
180 > geoqo -i /path/to/directory/
182 The dir importer allows you to simply specify a directory ("folder") to
184 attempt to read every file from. It will skip any file types it does
185 not understand.
186 Options:
188 setname:
190 Uses setname as the name of geoqo SET to create based on the data.
191 Normally this is extracted from the name field within the gpx file
192 itself and prepended with "import:". IE, if you had a pocket query
193 named "my search" then, when you imported the gpx file into geoqo,
194 you'd get a new set named "import:my search".
195 tmpdir:
197 The zip importer works by copying the zip file to a tmpdir and then
198 unzipping it there. This is normally set to $HOME/.geoqo/tmpdir.
199 This option lets you override that default.
200 default: /home/hardaker/.geoqo/temp
202 Import Loc:
204 > geoqo -i myfile.loc
206 > geoqo -i loc:setname=myname:myfile.loc
208 The loc importer imports loc files taken from the geocaching.com and
210 waymarking.com site (and probably many other sites too, but only
211 geocaching.com and waymarking.com LOC files have been tested so for)
212 and imports the data into your geoqo database.
213 Options:
215 setname:
217 Uses setname as the name of geoqo SET to create based on the data.
218 Normally this is extracted from the name field within the gpx file
219 itself and prepended with "import:". IE, if you had a pocket query
220 named "my search" then, when you imported the gpx file into geoqo,
221 you'd get a new set named "import:my search".
222 Import Base64:
224 > cat message | geoqo -i base64:-
226 The base64 importer allows you to send mail messages with encoded
228 pocket queries directly to geoqo for decoding, unzipping, extracting
229 and importing.
230 Note: using this importer requires you to have MIME::Base64 installed
232 on your system. Most modern perl packages contain this out of the box.
233 Options:
235 setname:
237 Uses setname as the name of geoqo SET to create based on the data.
238 Normally this is extracted from the name field within the gpx file
239 itself and prepended with "import:". IE, if you had a pocket query
240 named "my search" then, when you imported the gpx file into geoqo,
241 you'd get a new set named "import:my search".
242 tmpdir:
244 The zip importer works by copying the zip file to a tmpdir and then
245 unzipping it there. This is normally set to $HOME/.geoqo/tmpdir.
246 This option lets you override that default.
247 default: /home/hardaker/.geoqo/temp
249 Import Wigle:
251 > geoqo -i myfile.wigle
253 > geoqo -i wigle:setname=myname:mywiglefile
255 The wigle importer imports wigle files taken from the geocaching.com
257 and waymarking.com site (and probably many other sites too, but only
258 geocaching.com and waymarking.com WIGLE files have been tested so for)
259 and imports the data into your geoqo database.
260 Options:
262 setname:
264 Uses setname as the name of geoqo SET to create based on the data.
265 Import System:
267 > geoqo -i "system:gpsbabel -i garmin -f /dev/ttyS0 -o gpx -F %{file:gpx}"
269 The system importer allows you to simply specify a command to run which
271 generates a file of a type that geoqo can actually import. For
272 example, the above command runs gpsbabel to import all the waypoints
273 stored in a GPS on a unix system (/dev/ttyS0 is the name of a serial
274 device on a linux machine).
275 Options:
277 cmd:
279 It must contain a %{file:TYPE} string that indicates where the
280 output file will be stored, but the path and the name of that file
281 will be created by geoqo. Example gpsbable arguments would be -o
282 gpx -F %{file:gpx}
283 setname:
285 Uses setname as the name of geoqo SET to create based on the data.
286 Normally this is extracted from the name field within the gpx file
287 itself and prepended with "import:". IE, if you had a pocket query
288 named "my search" then, when you imported the gpx file into geoqo,
289 you'd get a new set named "import:my search". However if your
290 system command doesn't properly name the resulting file, this can
291 be used to override it.
292 tmpdir:
294 The temporary directory to use
295 default: /home/hardaker/.geoqo/temp
297 Import Create:
299 > geoqo -i create:ident=home,lat=N38
301 The create import plugin lets you create new waypoints and inserts them
303 into the database. The list of options is quite long as each type
304 supported by a given supported waypoint system (geocaching, geodining,
305 ...) requires an appropriate set of fields. Running geoqo simply as:
306 > geoqo -i create
308 should bring up a GUI form which will prompt you for the needed
310 information. Leave anything out that isn't appropriate for the
311 waypoint type you're creating.
312 Options:
314 type:
316 default: Waypoint
317 ident:
319 setname:
320 default: created
321 desc:
323 lat:
324 lon:
325 sym:
326 time:
327 subtype:
328 url:
329 urlname:
330 cmt:
331 Import Average:
333 > geoqo -i average:ident=newwaypoint,from1=oldwaypoint1,from2=oldwaypoint2
335 The average import plugin lets you create a new waypoint by averaging
337 the latitude and longitude of a number of other waypoints. Useful to
338 find the center of a number of waypoints, which is required for a
339 number of geocaching puzzle caches.
340 Options:
342 ident:
344 type:
345 default: Waypoint
346 from1:
348 from2:
349 setname:
350 default: created
351 Import Project:
353 XXXXX DO NOT USE THIS PLUGIN; IT IS NOT FINISHED XXXXX
355 > geoqo -i project:ident=newwaypoint,from=oldwaypoint,distance=528,direction=45
357 The project import plugin lets you project a new waypoint which is a
359 distance from an older one.
360 Options:
362 ident:
364 type:
365 from:
366 distance:
367 default: 0
368 direction:
370 default: 0
371 setname:
373 default: created
374
376 The search system in geoqo is highly flexible and extensible. It
377 supports multiple types of searching, which are documented below. The
378 "-s" or "--search". The format of the search field is as follows:
379 type:terms
381 Type is the type of search you want to do. This can be any of the
383 types shown further below, or any types provided by a plugin. For
384 those that want to write search plugins, please run "perldoc
385 GeoDB::Search" to learn how to write search plugins.
386 Note: searching does nothing if you're not going to act on the results.
388 Thus, you should at least provide a -l, -S or -e flag to list, show, or
389 export the results. All the examples below are using the -l flag.
390 Search types are as follows:
392 Search Cache:
394 > geoqo -s cache:name=unusual -d count
396 Search/Set Count: 6
397 Searchs the database for only waypoints that are of type 'Geocache' and
399 conform to the terms given. See the documentation on the waypoint:
400 search type for further details on how to use it because everything
401 else is the same.
402 Possible search columns for geocaches include the following, beyond
404 those listed in the waypoint section:
405 available
407 archived
408 groundspeak_name
409 groundspeak_placed_by
410 groundspeak_owner_id
411 groundspeak_owner_name
412 groundspeak_type
413 groundspeak_container
414 groundspeak_difficulty
415 groundspeak_terrain
416 groundspeak_country
417 groundspeak_state
418 groundspeak_short_description_html
419 groundspeak_short_description
420 groundspeak_long_description_html
421 groundspeak_long_description
422 groundspeak_encoded_hints
423 Search Waymark:
425 > geoqo -s waymark:name=unusual -d count
427 Search/Set Count: 6
428 Searches the database for only waypoints that are of type 'Waymark' and
430 conform to the terms given. See the documentation on the waypoint:
431 search type for further details on how to use it, because everything
432 else is the same.
433 Possible search columns for waymarks include the following beyond those
435 listed in the waypoint section:
436 waymark_owner_name
438 When waymarking.com starts releasing more data in .gpx files, this will
440 get significantly longer, of course.
441 Search Geodining:
443 > geoqo -s geodining:resturant_name=Cafe -d count
445 Search/Set Count: 6
446 Searches the database for only waypoints that are of type 'Geodining'
448 and conform to the terms given. See the documentation on the waypoint:
449 search type for further details on how to use it, because everything
450 else is the same.
451 Possible search columns for geodining waypoints include the following
453 beyond those listed in the waypoint section:
454 geodining_restaurant_name
456 geodining_submitted_by
457 geodining_price
458 geodining_service
459 geodining_continent
460 geodining_country
461 geodining_state
462 geodining_city
463 geodining_zip
464 geodining_address
465 geodining_description
466 geodining_details
467 Search Wigle:
469 > geoqo -s wigle:name=unusual -d count
471 Search/Set Count: 6
472 Searches the database for only waypoints that are of type 'Wigle' and
474 conform to the terms given. See the documentation on the waypoint:
475 search type for further details on how to use it, because everything
476 else is the same.
477 Possible search columns for wigles include the following beyond those
479 listed in the waypoint section:
480 wigle_ssid
482 wigle_netid
483 wigle_discover
484 wigle_channel
485 wigle_type
486 wigle_freenet
487 wigle_firsttime
488 wigle_sep
489 wigle_comment
490 wigle_qos
491 wigle_lastupdt
492 wigle_paynet
493 wigle_userfound
494 Search Waypoint:
496 > geoqo -s waypoint:name=unusual -d count
498 Search/Set Count: 6
499 The waypoint search type is for searching for primary fields in a
501 waypoint record. Possible search terms include anything in the type-
502 specific searches (since waypoint: searches include everything) and the
503 following fields which apply to all waypoints regardless of specific
504 type:
505 desc
507 lat
508 lon
509 sym
510 time
511 type
512 subtype
513 url
514 urlname
515 cmt
516 The following are some examples of how to use the waypoint: search
518 type. Note that cache: and waymark: searches work the exact same way
519 and also do everything below, but limit your search to just waypoints
520 of those types.
521 The format for using the waypoint (or similarily for cache: or
523 waymark:) search terms is:
524 geqo -s waypoint:I<TERMS>
526 where TERMS are a comma separated list of search terms. Normally these
528 would be specified like:
529 waypoint:FIELDNAME=VALUE
531 The FIELDNAME indicates the field name you want to search (see below),
533 and the VALUE is the value you want to search for. The value field is
534 actually surrounded by wildcards, and thus searching for "me" will
535 match any value with "me" somewhere in it including "He and I went to
536 the store" and "sometimes". Using two equals signs turns off the
537 automatic wildcard support (ie, name==me means search for a name that
538 is just "me").
539 An example: find all waypoints with a urlname field containing
541 "unusual":
542 > geoqo -s waypoint:urlname=tubular -d list
544 num GCID Name
545 1 GCDFE0 Hidden Headstones
546 2 GCE29A Celebrated Cemetery
547 3 GCHW9M The eyes have it (Yamar's unusual #1)
548 4 GCJ491 O where art thou (Yamar's unusual #2)
549 5 GCJ5DV Inverted Cache (Yamar's unusual #3)
550 6 GCJ66H Gone Fishin' (Yamar's unusual #4)
551 7 GCQEBQ Yamar's Unusual #6: The ORB
552 8 GCB284 Don't Be A Drip!
553 An example: find all geocaches owned by 'Spelunk':
555 > geoqo -s cache:owner_name=spelunk -d list
557 num GCID Name
558 1 GCJVTR Here's to Your Health Cache
559 2 GCJY4V Sumac Grove Cache
560 3 GCJZ2N Wildlife View Cache
561 4 GCKNZB Misplaced Seed Cache
562 5 GCKQBN Out-N-About Cache
563 6 GCKVFW We Give-A-Hoot Cache
564 7 GCNWM9 BUG JAR
565 8 GCP5YP Greenbelt Hideaway
566 9 GCPZK3 Davis Shopping Spree
567 10 GCQ6Q8 BUG JAR II
568 11 GCQ6TV Great Experience Cache
569 12 GCQ87Z Here's to the Greenbelts
570 13 GCQFYJ Toby & Willie's Friends
571 14 GCQH1M Connect the Dots Cache
572 15 GCTCC5 Canal Cache
573 16 GCTFJH The Micro Equalizer Cache
574 17 GCVVWY Spelunk's 'Fishy' Doings
575 18 GCW26F Mountain or Desert? Cache
576 Note that terms will match anything beyond the underscore ("_"). IE,
578 if you do a search for:
579 waypoint:short=some text
581 It will search the short description for "some text" even though the
583 actual field name it'll search is "groundspeak_short_description".
584 Using an exact fully spelled out field name is the most precise, but
585 you can truncate names for convience.
586 Finally, you can use '*'s to indicate wildcard spots (u*sal would match
588 "unusual" and "unit of sale"). By default geoqo already adds a * to
589 both the front and the back of your search time (ie, name=unusual is
590 actually interpreted as name=*unusual*).
591 You can also use the folling ARGUMENT types when searching for field
593 values in a waypoint:
594 field ARGUMENT value
596 field=value
598 Fuzzy match on value. The value will be surrounding by wildcards,
599 as previously discussed so searching for "desc=blowfish" will
600 actually search the desc field for "*blowfish*".
601 waypoint:desc=blowfish
603 field==value
605 Also as mentioned above, if you don't want to use the automatic
606 wild card searching discussed above, you can use 2 equal signs to
607 indicate this. Thus if you search for "desc=blowfish" it will
608 search the desc fields for an exact match on the word "blowfish"
609 (IE, must not contain any other words).
610 You should use == searches for numeric values too, or else
612 something like "difficult=3" will also match difficult numbers like
613 3.5.
614 waypoint:desc==blowfish
616 field<value and field>value
618 Allows you to search on less than or greater than numeric values.
619 IE:
620 waypoint:lon<42.123
622 or
624 waypoint:terrain>2
626 <> If you use both, it becomes "not equal to". IE:
628 waypoint:type<>unusual
630 Will list all waypoints without the word unusual in their desc
632 field. This is also doing the same automatic wildcard matching
633 like the = sign does, and thus the above search is actually
634 searching for "*unusual*".p
635 <=> This is also "not equal to", but is an exact match and thus:
637 waypoint:desc<=>blowfish
639 will match any type of cache that doesn't have a desc field of
641 "blowfish". It will include, in the search, caches with a desc
642 field of "blowfish dinner" however because it's not an exact match.
643 Search Ident:
645 > geoqo -s ident:gcabcd,gcefgh,gcijkl -d count
647 Search/Set Count: 3
648 > geoqo -s ident:abcd,efgh,ijkl -d count
650 Search/Set Count: 3
651 The ident plugin merely lets you quickly list a bunch of waypoint
653 identifiers you want to select with geodb.
654 The identifiers do have a wild card inserted before them so you can
656 leave off a common prefix, as shown in the second example above, and
657 still match the list (saves typing).
658 Really, the ident: search type is just a faster way to type:
660 > geoqo -s waypoint:ident=abcd||waypoint:ident=efgh||...
662 Options:
664 idents:
666 A comma separated list of identifiers to search for
667 Search Log:
669 The log: search type lets you search waypoint log entries for waypoints
671 matching a criteria. As an example, you can search for all waypoints
672 in you database found by Yamar (me):
673 > geoqo -s 'log:finder=Yamar' -d list
675 num GCID Name
676 1 GCJVTR Here's to Your Health Cache
677 ...
678 Log tokens to search by:
680 id
682 ident
683 date
684 type
685 logger_id
686 logger
687 text_encoded
688 text
689 Special tokens to search by (makes sure a log was made by someone of a
691 particular type):
692 finder
694 noter
695 dnfer
696 WARNING: this may be amazingly slow on a mysql server. I think.
698 Postgresql or sqlite2 (the defualt) database backends are just zippy,
699 however.
700 Search Attribute:
702 Attribute searches groundspeak (geocaching.com) attributes that were
704 loaded into the database when doing an import from a groundspeak .gpx
705 file.
706 > geoqo -s attribute:Dogs -d count
708 Search Result Count: 32
709 NOTE: this does NOT search the user-defined attributes and only
711 searches (geocaching.com) attributes. For searching user attributes
712 you should use the attr: search plugin intstead.
713 Search Attr:
715 Attr searches attributes that you yourself have placed on a cache using
717 the modify setattr module.
718 > geoqo -s ident:gcabcd -m setattr:found=1 --save
720 > geoqo -s attr:found=1 -d count
722 Search Result Count: 1
723 NOTE: this does NOT search groundpseak (geocaching.com) attributes.
725 For this you should use the attribute: search plugin intstead.
726 Search Rating:
728 The rating plugin lets you search ratings that may have been placed on
730 a cache using the modify rate module.
731 > geoqo -s ident:gcabcd -m rate:fun=8
733 > geoqo -s "rating:fun>5" -d count
735 Search Result Count: 1
736 If you have downloaded average ratings from the ratings server, you can
738 search by those as well by prefixing the name with "others:" to search
739 by the average rating given to the cache by others:
740 > geoqo -s "rating:others:fun>5"
742 If you want to search for all caches that you have not rated for a
744 particular category, use:
745 > geoqo -s "rating:fun=-"
747 Search Tag:
749 Tag searches tags that you yourself or others have placed on a cache.
751 You can place them using the Tag Modify plugin:
753 > geoqo -s ident:gcabcd -m tag:cool/awesome
755 > geoqo -s tag:cool -d count:
757 Search Result Count: 1
758 Prefix the tag names with "mine:" if you want to search just you tags,
760 or "others:" if you want to search other people's tags.
761 > geoqo -s tag:mine:cool -d count:
763 Search Result Count: 1
764 > geoqo -s tag:others:cool -d count:
766 Search Result Count: 2
767 Search Set:
769 Sets, which are described further below, are a bunch of waypoints all
771 with an identically named "tag". As an example, if your geocaching.com
772 pocket query was named "my query" and you import it into geoqo using
773 the -i switch the waypoints contained in that gpx file will be assigned
774 to the "import:my query" set. You can use the set:setname search type
775 to load these waypoints.
776 > geoqo -s "set:import:my query" -d count
778 Search Result Count: 500
779 This command would count everything in the database that was in the
781 "import:my query" set name (that was likely imported from a pocket
782 query). See the Advanced Searching section in the geoqo documentation
783 for other examples of combining set: searches and waypoint: (or other)
784 searches so you can search for "all waypoints matching a criteia within
785 a set" for example.
786 If you prefix the name with a minus sign (-) then it will include all
788 caches NOT in that set. For example to find all caches that are in
789 seta but not in setb then the following expression would accomplish
790 that:
791 > geoqo -s 'set:seta&&set:-setb'
793 Search File:
795 > geoqo -s file:foo.gpx -d count
797 Search/Set Count: 3
798 > geoqo -s file:foo.loc -d count
800 Search/Set Count: 3
801 The file plugin loads a file into memory and then searches the normal
803 geoqo database for all the waypoints that match those found in the
804 file.
805 Options:
807 file:
809 A file to load and search for matching waypoints from
810 Search Track:
812 > geoqo -s track:mytrackfile.gpx -d count:
814 Search/Set Count: 3
815 The track plugin loads track data from a GPX track file (which you can
817 retrieve from you gps using gpsbabel) and then compares the list of
818 caches in you database to this data. It then matches all caches where
819 your speed dropped below a configurable speed (3MPH is the default) and
820 where the distance from the track is less than a configurable amount
821 (defaults to near 500 feet).
822 This is even more useful when combined with the Track modify plugin,
824 which can order caches based on the track and report the times you
825 found them as well.
826 If you know all the caches are in a given set, however, you should
828 probably limit the data it has to search through to a subset of you
829 total database if it runs slowly.
830 To get track data from the gps, use gpsbabel:
832 gpsbabel -t -i garmin -f usb: -o gpx -F track.gpx
834 See the Modify/Track plugin for a detailed example
836 Options:
838 trackfile:
840 A GPX trackfile to load and search by
841 speed:
843 Only look for caches where your speed dropped below this
844 default: 3
846 delta:
848 lat/lon delta to use looking for caches near a stopping point
849 default: 0.002
851 laterthan:
853 Only use track points which are beyond a specifed time.
854 Search File:
856 > geoqo -s file:foo.gpx -d count
858 Search/Set Count: 3
859 > geoqo -s file:foo.loc -d count
861 Search/Set Count: 3
862 The file plugin loads a file into memory and then searches the normal
864 geoqo database for all the waypoints that match those found in the
865 file.
866 Options:
868 file:
870 A file to load and search for matching waypoints from
871 Search Returnhome:
873 > geoqo -s gps -d count
875 Search/Set Count: 3
876 This plugin combines the functionality of a number of other ones rolled
878 into one. In particular, it:
879 1. pulls the existing waypoints from the GPS
881 2. pulls the existing track from the GPS
882 3. searches for the waypoints in the geoqo database that match the
883 ones in the GPS using the GeoDB::Search::File plugin
884 4. seaches the results of those for ones that the track came close
885 using the GeoDB::Search::Track plugin.
886 Options:
888 gpstype:
890 Type of GPS
891 default: garmin
893 gpsport:
895 The port to use
896 default: usb:
898 Search Gps:
900 > geoqo -s gps -d count
902 Search/Set Count: 3
903 The gps plugin talks to a gps and finds all the waypoints in the geoqo
905 database that are also in the GPS. This is done by pulling out all the
906 waypoints from the GPS and then using the list to search the database.
907 Options:
909 gpstype:
911 Type of GPS
912 default: garmin
914 gpsport:
916 The port to use
917 default: usb:
919 Search Any:
921 The any: search type simply uses all the waypoints in the entire
923 database. It (hopefully) obviously doesn't make sense to use this
924 combined with other types of searches.
925
927 There are advanced things you can do while searching. This section
928 documents those:
929 Accessing a single result from the last search
931 Sumarize just the 12th waypoint from the last search results:
933 > geoqo -s 12 -d list
935 12 GCNK57 James Bond 047
936 Export caches 5-10 from the last search results:
938 > geoqo -s 5-10 -e out.gpx
940 Logical Searches
942 You can use && (AND) and || (OR) pairs to add powerful searching
944 combinations to your results. In fact, this is actually useful and can
945 increase the speed of your queries if used properly (if you know you
946 only want to search the data from a particular import, use a set:
947 search && with a waypoint: search and the result will likely be
948 returned faster).
949 This example searches for all waypoints owned by "spelunk" that I have
951 found (ie, it exists in the "import:My Finds Pocket Query" imported gpx
952 file).
953 > geoqo -s 'waypoint:owner_name=spelunk&&set:import:My Finds Pocket Query' -d list
955 num GCID Name
956 1 GCJVTR Here's to Your Health Cache
957 2 GCJY4V Sumac Grove Cache
958 3 GCJZ2N Wildlife View Cache
959 4 GCKNZB Misplaced Seed Cache
960 5 GCKQBN Out-N-About Cache
961 6 GCKVFW We Give-A-Hoot Cache
962 7 GCNWM9 BUG JAR
963 8 GCP5YP Greenbelt Hideaway
964 9 GCPZK3 Davis Shopping Spree
965 10 GCQ6Q8 BUG JAR II
966 11 GCQ6TV Great Experience Cache
967 12 GCQ87Z Here's to the Greenbelts
968 13 GCQFYJ Toby & Willie's Friends
969 14 GCQH1M Connect the Dots Cache
970 15 GCTCC5 Canal Cache
971 16 GCTFJH The Micro Equalizer Cache
972 17 GCVVWY Spelunk's 'Fishy' Doings
973 18 GCW26F Mountain or Desert? Cache
974 That is likely faster than doing the next search, but the following is
976 another way to do something similar. In this case, I'm searching for
977 all waypoints owned by spelunk that there is a log entry by me for
978 (note: finder is a mis-nomer as a finder may have logged it as a "did
979 not find"; search on the log "type" as well to limit it to just finds):
980 > geoqo -s 'waypoint:owner_name=spelunk&&log:finder=Yamar' -d list
982 num GCID Name
983 1 GCJVTR Here's to Your Health Cache
984 ... [same result] ...
985 grouping search terms
987 The () arguments can be used to group search terms together as well
989 when you need to mix operations. In the following case we're looking
990 for all waypoints "owned by scoobert AND have the word Ditch in them",
991 and add to that all waypoints logged by me and all waypoints with
992 'ninja' in the title. Silly example, I know.
993 > perl -I. geoqo -s '(waypoint:groundspeak:name=Ditch&&waypoint:owner_name=scoobert)||waypoint:groundspeak:name=ninja||log:finder=Yamar' -d list
995 1 GCYBDY Whodunit?
996 2 GCP8MT All Day
997 3 GCQJY0 Kate's Watching
998 [...]
999
1001 Actually, just about everything is stored in a set. They're a powerful
1002 way to "tag" a group of waypoints. The -N flag (or --set-name) flag
1003 specifies which name you want to store your current search results into
1004 (it's currently required and will always store the results somewhere).
1005 Sets can be created from a search
1007 > geoqo -N search:47dad47 -s waypoint:owner_name=47dad47 -d list
1009 num GCID Name
1010 1 GCH5EF Sacramento's Second Webcam Cache
1011 [...]
1012 14 GCR86K .
1013 > geoqo -N search:gary -s waypoint:owner_name=gary -d list
1015 num GCID Name
1016 1 GCRWXC Fishing in Cache Creek
1017 Sets can be listed:
1019 > geoqo -d saved
1021 Set Name Cache Count
1022 -------------------- -----------
1023 file:somefile 200
1024 search:geoqo 13 <i>(default search name)</i>
1025 search:47dad47 14
1026 search:gary 1
1027 And they can be combined:
1029 > geoqo -s set:search:gary,search:47dad47 -d list
1031 num GCID Name
1032 1 GCRWXC Fishing in Cache Creek
1033 2 GCH5EF Sacramento's Second Webcam Cache
1034 [...]
1035 15 GCR86K .
1036
1038 You've already seen the effects of the -d list switch, which lists all
1039 the waypoints in the resulting set/search. But there are a number of
1040 display types to pick from, and 'list' is only one such search output
1041 style:
1042 Display Help:
1044 The help module displays help on a given topic. You can specify help
1046 on a given topic.
1047 Example 1:
1049 geoqo -d help
1050 Example 2:
1052 geoqo -d help:topicname
1053 The help routine displays help for the various geoqo plugins.
1055 Options:
1057 topic:
1059 Specifies the topic to display help on.
1060 Display Count:
1062 Example:
1064 geoqo -s 'set:import:my pocket query' -d count
1065 Search/Set Count: 500
1066 The Count display simply counts the results in a set. This is very
1068 useful for counting the results before you do something with them (like
1069 dumping 500 caches to your screen when you were looking for just a
1070 few).
1071 Options:
1073 prefix:
1075 The prefix string to print right before the count
1076 default: Search/Set Count:
1078 Display List:
1080 Example 1:
1082 geoqo -d list
1083 num GCID Name
1084 1 GCMR3M The Mystery of Livinrgttoo
1085 2 GCPWBT Hidden Cactus Garden
1086 Example 2:
1088 geoqo -d 'list:format=%{3:count} %{6:ident} terr=%{3:groundspeak_terrain} diff=%{groundspeak_difficulty}'
1089 1 GCMR3M terr=1.5 diff=1.5
1090 2 GCPWBT terr=2 diff=1.5
1091 The List display shows the contents of the search Set one line at a
1093 time. By default, the format is (may vary depending on type though):
1094 %{3:count} %{8:ident} %{66:urlname}
1096 The number prefix is the number of spaces to print it in and it will
1098 pad with extra spaces if it doesn't fill that space. If left out,
1099 it'll print it straight out in any length it may be. Adding a decimal
1100 point will limit it to a maximum of that length. IE:
1101 %{20.20:urlname}
1103 Will print only the first 20 characetrs of the urlname.
1105 Options:
1107 format:
1109 Specifies the formatting parameters
1110 Display Show:
1112 Example 1:
1114 geoqo -s 1 -d show
1115 Show (-d show) the waypoint details for #3 from the last search (which is
1116 really #3 from the default set or the set specified via the -N
1117 switch):
1118 > geoqo -s 3 -d show
1120 GCHW9M Multi-cache Location: 38.542933, -121.6998
1121 Name: The eyes have it (Yamar's unusual #1)
1122 Owner: Yamar (#183928) Created: 2004-03-08
1123 Placed By: yamar
1124 Rating: 3/1.5
1125 URL: http://www.geocaching.com/seek/cache_details.aspx?guid=5f9bd8d4-193a-4e0c-92c4-f107ae6d878b
1126 Short Description:
1127 A 3 part waypoint: a virtual, an unusual and a regular
1128 Long Description:
1130 Yamar to Spelunk on 2004-04-06:
1131 "If this cache is under that lamp post [again], I'm going to scream."
1132 [...]
1133 Show the waypoint details and also the logs (-L, but this may change in
1135 the future):
1136 > geoqo -s 3 -d show -L
1138 GCHW9M Multi-cache Location: 38.542933, -121.6998
1139 Name: The eyes have it (Yamar's unusual #1)
1140 [...]
1141 Log #13914681 by Mango101: (Found it)
1143 This cache took us way too many tries! Finally we found it! TNLN.
1144 Log #14812407 by Mister Grim & Pooka: (Found it)
1146 The hint threw us for a loop but we figured it out
1147 eventually. Thanks for another great cache!
1148 [...]
1149 Options:
1151 logs:
1153 If true, shows the logs in the output.
1154 default: 0
1156 Display Map:
1158 Example 1:
1160 geoqo -s 'set:import:My Pocket Query' -d map
1161 The Map display plugin displays a map of a set of waypoints with little
1163 red dots for each waypoint.
1164 This plugin requires internet access since the map tiles are pulled
1166 from the http://www.openstreetmap.org/ project (which I highly
1167 recommend you contribute to; it's easy and fun to edit/fix the maps!).
1168 (Eventually it should be possible to display with symbols, colors, etc
1170 as well as display the density overlays like the KML export plugin
1171 does)
1172 Options:
1174 style:
1176 default: icons
1177 icondir:
1179 default: dist/tomtom-icons/
1180 iconscale:
1182 Size to scale icon sizes in the map. "auto" scales based on the
1183 number of waypoints to be shown.
1184 default: auto
1186 maptiles:
1188 default: 2
1189 notext:
1191 dodensity:
1192 Display Top10:
1194 The top10 dispaly plugin counts the values in a particular field and
1196 shows you the top10 results of the counts in that field.
1197 Example (defaults to counting the top 10 waypoint owners):
1199 > geoqo -s any: -d top10
1201 Top 10 'groundspeak_owner_name's
1202 Num % Value
1203 ----------------------------------------------------------------------
1204 22 4 BootyBuddies
1205 20 4 sailorscodgers
1206 17 3 retiredprof
1207 16 3 two bison
1208 14 2 Sac D
1209 14 2 Oldhippy & Granny
1210 13 2 TRAKD
1211 12 2 rivercity
1212 11 2 2Dee2Dee
1213 10 2 jimlips
1214 10 2 Pirate Princesses
1215 Example: counting container types
1217 > geoqo -s any: -d top10:groundspeak_container
1219 Top 10 'groundspeak_container's
1220 Num % Value
1221 ----------------------------------------------------------------------
1222 234 50 Micro
1223 103 22 Regular
1224 92 19 Small
1225 13 2 Not chosen
1226 12 2 Other
1227 10 2 Virtual
1228 4 0 Large
1229 Setting the "doaverage" parameter will also display the average value
1231 associated with a numeric field:
1232 > geoqo -s 'cache:owner_name=Yamar' -d top10:groundspeak_difficulty,doaverage=1
1234 Top 10 'groundspeak_difficulty's
1235 Num % Value
1236 ----------------------------------------------------------------------
1237 14 38 2
1238 9 25 1.5
1239 6 16 1
1240 3 8 2.5
1241 2 5 3
1242 1 2 4
1243 1 2 3.5
1244 Average: 1.90278
1245 Options:
1247 field:
1249 default: groundspeak_owner_name
1250 show:
1252 default: 10
1253 doaverage:
1255 averagetext:
1256 default: Average:
1257 script:
1259 noblank:
1260 default: 1
1261 Display Sets:
1263 Example:
1265 geoqo -d sets
1266 Count Set Name
1267 ----- ----------------------------------------
1268 450 import:Bethel Island
1269 500 import:Concord
1270 500 import:Copy of SanFrancisco
1271 [...]
1272 Shows the list of existing sets remembered by the geoqo system, and the
1274 number of caches in each one. See the geoqo documentation on "sets"
1275 for further details.
1276 Options:
1278 match:
1280 Only lists set names containing this value
1281 orderby:
1283 Can be set to order by "modified" (default) or "setname" or "count"
1284 default: modified
1286 Display Attributes:
1288 Example:
1290 geoqo -d attributes
1291 Id Attribute Name
1292 ------ ----------------------------------------
1293 1 Dogs
1294 3 Climbing gear
1295 4 Boat
1296 5 Scuba gear
1297 [...]
1298 Shows the list of known groundspeak/geocaching attributes. This is
1300 useful for knowing which attributes you can search with using the
1301 'attribute' search plugin.
1302 Options:
1304 match:
1306 Only lists attributes names containing this value
1307 orderby:
1309 Can be set to order by "attributename" (default) or "attributeid"
1310 default: attributename
1312 Display Stats:
1314 Example:
1316 > geoqo -d stats
1318 Waypoints: 8754
1319 Geocaches: 8751
1320 Waymarks: 0
1321 Logs: 56659
1322 Sets: 33
1323 The stats display plugin shows statistics about what is contained in
1325 your database.
1326 Display Gui/list:
1328 Example:
1330 geoqo -s cache:urlname=funny -d gui/list
1331 The gui/list module displays a GUI in a graphical window that lets you
1333 examine the caches within a cache set.
1334 This is only very preliminary work and is subject to greater expansion
1336 in the future.
1337 Options:
1339 fields:
1341 default: Ident Type Subtype Groundspeak_Owner_Name URLNAME
1342 plugins:
1344 separator:
1345 default: 0
1346 Display Gui/show:
1348 Example:
1350 geoqo -s cache:urlname=funny -d gui/show
1351 The gui/show module displays a GUI in a graphical window that lets you
1353 examine the caches within a cache set.
1354 This is only very preliminary work and is subject to greater expansion
1356 in the future.
1357 Display Bounds:
1359 Example 1:
1361 geoqo -s set:import:minneapolis -d bounds
1362 min lat: 44.888483
1363 max lat: 45.061767
1364 min lon: -93.391317
1365 max lon: -93.146517
1366 center lat: 44.975125
1367 center lon: -93.268917
1368 The Bounds display shows the maximum and minimum latitude and longitude
1370 found in the set. It also outputs the center of the bounds as well.
1371 Display Graph/find:
1373 Example:
1375 geoqo -s log:finder=Yamar -d graph/find:finder=Yamar
1376 This shows a graph of finds over time by a given person. Generally,
1378 you'll want to run this after you've incorporated a pocket query of all
1379 of your finds. You can run it against other user names too, but it's
1380 unlikely you have every log record for them unless you've imported
1381 their find pocket query too.
1382 Options:
1384 finder:
1386 Sets the NAME of the finder you're looking for to a particular
1387 geocaching name (ie, the name of the user that is logging the
1388 finds). 99/100 egoists recommend using your own geocaching name
1389 here.
1390 logtype:
1392 Defines the log type to graph.
1393 default: Found it
1395 Display Graph/placed:
1397 Example:
1399 geoqo -s any: -d graph/placed:type=month
1400 Shows a graph displaying which during months, weeks, etc the caches
1402 were placed. Really this just gives an indication of which months are
1403 the most popular months for placing a cache (probably due to weather).
1404 Options:
1406 type:
1408 Examines creation date based on this frequency (X-axis column).
1409 PERIOD may be either month, day, year, weekday or yearday. The
1410 default is month (ie, the graph will be from 1-12 showing the
1411 number of caches placed during each month in your loaded search
1412 set).
1413 default: month
1415 Display Dump:
1417 Example 1:
1419 geoqo -d dump
1420 Example 2:
1422 geoqo -d dump:short=1
1423 Example 3:
1425 geoqo -d dump:format=perl
1426 The Dump display type dumps the contents of a set of waypoints. This
1428 is primarily a debugging mechanism.
1429 Options:
1431 short=1
1433 Makes everything fit on one 80column line per item. This will
1434 truncate field values to something short enough to do this.
1435 format=perl
1437 Uses Data::Dumper to show the output in perl structure form. For
1438 the expert.
1439 Options:
1441 short:
1443 If specified, limits output to 1 line per field
1444 includeall:
1446 If set then all waypoint items will be included, even if the field
1447 itself is blank
1448 default: 0
1450 format:
1452 If set to "perl" will use perl's Data::Dumper to dump the perl
1453 object
1454
1456 There are a number of modification plugins that modify data after it's
1457 been extracted from the database and before it gets either displayed
1458 (-d) or exported (-e). These are most useful for changing data before
1459 it's exported.
1460 Modify Solved:
1462 Example of solving a puzzle and saving it:
1464 > geoqo -s ident:GCABCD -m 'setattr:puzn=N38 42.444,puzw=W121 42.444' --save
1466 Example of exporting it with the replaced coordinates:
1468 > geoqo -s ident:GCABCD -e 'solved:+loc:out.loc'
1470 This plugin replaces the latitude and longitude coordinates of a
1472 waypoint with those in the puzn and puzw attributes. Use the above
1473 examples as a guide for solving a puzzle and then using the solved:
1474 plugin when exporting your database ready for uploading into a GPS.
1475 Options:
1477 nattr:
1479 The name of the attribute storing the new north coordinate
1480 default: puzn
1482 wattr:
1484 The name of the attribute storing the new west coordinate
1485 default: puzw
1487 dropunparsed:
1489 Drops caches that do not have puzzle answers but are not parseable
1490 default: 1
1492 Modify Gctodiff:
1494 The "gctodiff" plugin (short for "GC to difficulty") replaces the first
1496 two letters in the 6-digit cache identifier with a single digit
1497 representation of both the difficulty and terrain ratings.
1498 IE, if you had this cache:
1500 > geoqo -l
1502 num GCID Name
1503 1 GCQEBQ Yamar's Unusual #6: The ORB
1504 It's rated a 1.5 in difficulty and a 2 in terrain. If you ran the
1506 gctodiff modify plugin on this data, it would replace the 'GC' with a 2
1507 and 3:
1508 > geoqo -m gctodiff: -d 'list:format=%{newident} %{desc}'
1510 23QEBQ Yamar's Unusual #6: The ORB
1511 It actually stores the data in the 'newident' field so the old one is
1513 still available. The export modules, however, use the newident field
1514 when writing out the cache identifiers so this is what your GPS, or
1515 what-have-you, will see when you load it into that.
1516 I (Yamar) do this specifically so when I'm looking at my garmin, for
1518 example, I get an immediate feel for how hard a particular cache is
1519 going to be without having to pull up data about it. (I also use the
1520 symbol plugin to change the symbol so I can see the type of cache it is
1521 too). My goal here is to maximize the amount of data I seen on the
1522 screen!
1523 The map from groundspeak/geocaching.com ratings is as follows:
1525 1 => 1
1527 1.5 => 2
1528 2 => 3
1529 2.5 => 4
1530 3 => 5
1531 3.5 => 6
1532 4 => 7
1533 4.5 => 8
1534 5 => 9
1535 Modify Rewrite:
1537 The rewrite modify plugin lets you rewrite fields based on other
1539 fields. For example, I (Yamar) use the following rewrite when putting
1540 stuff to a gpx file I'm going to load into my TomTom so I get as much
1541 information as possible when clicking on the icon in the tomtom map
1542 display:
1543 rewrite:groundspeak_name=%{ident}/%{4:subtype}: %{groundspeak_name}
1545 That way the groundspeak_name which might have been "some cache"
1547 becomes "GCABCD/Trad: some cache" to give me more information about it.
1548 (actually, I use the gctodiff plugin too and use the newident field
1549 instead; see the gctodiff plugin for details).
1550 Modify Setattr:
1552 The "Setattr" plugin (short for 'Set Attributes') allows you to add
1554 your own "attributes" to waypoint(s). You must specify the command
1555 line option "--save" to get them to be saved permenently to the
1556 database though. You can pick any attribute name you want, although
1557 some other modify plugins (like the "solved" plugin) may expect
1558 particular attribute names.
1559 Atttributes can be used for just about anything. For example, you can
1561 use them to store notes, remember hints from other people, collect data
1562 for a complex puzzle cache, etc.
1563 Example of storing a note:
1565 > geoqo -s ident:GCABCD -m 'setattr:notes=I hate this puzzle' --save
1567 Example of something silly:
1569 > geoqo -s ident:GCABCD -m 'setattr:foo=bar' --save
1571 Then you can search for all caches with that name and value later:
1573 > geoqo -s attr:foo=bar -l
1575 Example of solving a puzzle and saving it:
1577 > geoqo -s ident:GCABCD -m 'setattr:puzn=N38 42.444,puzw=W121 42.444' --save
1579 Example of exporting it with the replaced coordinates:
1581 > geoqo -s ident:GCABCD -e 'solved:+loc:out.loc'
1583 The setattr plugin lets you store your own information about a cache
1585 into the database. Some of the other plugins use attributes to
1586 manipulate things (see the solved plugin for an example). Sometimes
1587 you may want your own "notes". As an example, I modify Unknown puzzles
1588 that you solve in the field (instead of "in advance" puzzles like cross
1589 puzzles) with "setattr:infield=1". (then I can use that attribute with
1590 the modifier: plugin to drop all unknowns that don't have that
1591 attribute set or don't have a 'puzn' coordinate assigned showing I've
1592 solved it.
1593 IMPORTANT NOTE: You must specify --save to the command line to have
1595 geoqo save your attribute changes back to the database. Otherwise
1596 you're only setting attributes temporarily during the one-time call of
1597 geoqo.
1598 Math and Substitution
1600 Math and Substition can be done by prefixing the values with "math:"
1602 and "substitute:" where the contents will be searched for names with
1603 other attribute names in ()s and replaced with the attribute values.
1604 And if the math: was used, it will then be evaluated. Multiple depth
1605 replacements/math will work.
1606 Here's a more complex than needed example (the puzw attribute needs to
1608 be set as well for this to work):
1609 > geoqo -s ident:GCABCD -m 'setattr:puzn=substitute:N38 42.(A)(B)(C)' --save
1611 > geoqo -s ident:GCABCD -m 'setattr:A=4' --save
1612 > geoqo -s ident:GCABCD -m 'setattr:B=math:(A)*2' --save
1613 > geoqo -s ident:GCABCD -m 'setattr:C=math:(B)-(A)' --save
1614 > geoqo -s ident:GCABCD -m solved: -e out.gpx
1615 Note that the actual equation will still be stored as the attribute;
1617 The calculation is done when the attribute is later read (for example,
1618 by the "solved" modify plugin).
1619 Modify Tag:
1621 The "Tag" plugin allows you to add "tag"s to your caches.
1623 Example:
1625 geoqo -s cache:owner_name==Yamar -m 'tag:tags=awesome/cool'
1627 Another to remove tags:
1629 geoqo -s cache:owner_name==Yamar -m 'tag:tags=lame,deletetags=1'
1631 Publishing tags
1633 Your tags may be published to a geoqo tag server, and you may pull
1635 information about how other people have tagged waypoints from the tag
1636 server. To do this you must first create an account on the tag server:
1637 http://tagserver.geoqo.org/
1639 Then put your created username and password into your
1641 $HOME/.geoqo/config file like:
1642 geoqouser YOURUSERNAME
1644 geoqopass YOURPASSWORD
1645 Then you can publish your tags for a given set using:
1647 geoqo -s SEARCHTERMS -m tag:publish=1
1649 Additionally you can fetch data about other people's tags using:
1651 geoqo -s SEARCHTERMS -m tag:fetch=1
1653 When you use the -S option to show a the data for a waypoint you will
1655 see a list of all your tags as well as a list of other peoples tags
1656 that you have fetched.
1657 Options:
1659 tags:
1661 deletetags:
1662 publish:
1663 publishtags:
1664 ignoretags:
1665 default: lamppost/found
1666 fetch:
1668 geoqouser:
1669 geoqopass:
1670 Modify Rate:
1672 The "Rate" plugin allows you to add "ratings"s to your caches.
1674 Example:
1676 geoqo -s cache:owner_name==Yamar -m 'rate:overall=4'
1678 (at the moment "overall" is the only rating you can provide; more
1680 coming)
1681 Publishing ratings
1683 Your ratings may be published to a geoqo rating server, and you may
1685 pull information about how other people have rated waypoints from the
1686 rating server. To do this you must first create an account on the
1687 rating server:
1688 http://ratingserver.geoqo.org/
1690 Then put your created username and password into your
1692 $HOME/.geoqo/config file like:
1693 geoqouser YOURUSERNAME
1695 geoqopass YOURPASSWORD
1696 Then you can publish your ratings for a given set using:
1698 geoqo -s SEARCHTERMS -m rate:publish=1
1700 Additionally you can fetch data about other people's ratings using:
1702 geoqo -s SEARCHTERMS -m rate:fetch=1
1704 When you use the -S option to show a the data for a waypoint you will
1706 see a list of all your ratings as well as a list of other peoples
1707 ratings that you have fetched.
1708 Options:
1710 overall:
1712 ratings:
1713 publish:
1714 publishtags:
1715 ignoreratings:
1716 deleteratings:
1717 fetch:
1718 geoqouser:
1719 geoqopass:
1720 Modify Makepuzzle:
1722 This plugin extracts puzzle coordinates and equations from a cache
1724 description and sets up some attributes for doing the puzzle solving.
1725 If a cache description has text in it like "N38 AB.CDE" then this
1726 plugin will create 5 attributes A-E and a "puzn" attribute with the
1727 text "replace:N38 (A)(B).(C)(D)(E)" so that merely by filling in the
1728 A-E attributes will complete the puzzle.
1729 Options:
1731 nattr:
1733 The name of the attribute storing the new north coordinate
1734 default: puzn
1736 wattr:
1738 The name of the attribute storing the new west coordinate
1739 default: puzw
1741 reextract:
1743 Force rextraction of the equation wiping out the existing data
1744 default: 0
1746 Modify Delete:
1748 This command removes the waypoints from the database. Obviously, this
1750 should be used with caution because it can not be undone.
1751 For those that really and truly hate puzzles:
1753 > geoqo -s 'cache:subtype=Unknown' -m delete
1755 This can be useful for temporarily importing a bunch of items you don't
1757 want to keep around in the long run.
1758 Modify Classify:
1760 Options:
1762 inputprefix:
1764 default:
1765 outputprefix:
1767 default: predicted:
1768 categories:
1770 default: kids,coolcontainer,goodlocation,fun
1771 LearningType:
1773 default: DecisionTree
1774 stopwordsfile:
1776 default: /usr/share/geoqo/classify-ignore-words
1777 Debugging:
1779 Modify Symbol:
1781 This plugin replaces symbol identifier (normally "Geocache" for
1783 geocaches) with a new symbol based on your set criteria.
1784 As an example, I (Yamar) use the following mem: file definition to
1786 remap all my symbols into things that look (on my garmin) kind like the
1787 cache container:
1788 symbol:
1790 subtype=Multi-cache=Fitness Center,
1791 subtype=Unknown Cache=Information,
1792 subtype=Webcam Cache=Shower,
1793 groundspeak_container=Micro=Cemetery,
1794 groundspeak_container=Small=Tunnel,
1795 groundspeak_container=Large=Geocache Found,
1796 subtype=Virtual Cache=Ultralight Area
1797 Then I can run geoqo to remap stuff before exporting it to a .gpx file:
1799 > geoqo -s some_search_criteria -e 'mem:FILENAME+out.gpx'
1801 That way all multi-caches get remapped to a 'Fitness Center' because
1803 the 'Fitness Center' icon on my garmin looks like a little guy lifting
1804 weights, and thus I know it's going to be a harder cache (or one I'll
1805 likely have to walk more). I like multi's a lot, but I do like to know
1806 when I'm hitting them. Similarily, a Cemetery icon on my etrex is a
1807 small dot, a Tunnel is a bit larger, and a Geocache found icon is very
1808 large so I use them to represent sizes.
1809 If you want to use the symbol plugin, you should pick your own symbols
1811 that seem right on your gps or other software system. Each GPS's
1812 symbols tend to be quite different (and the name chosen should be a
1813 symbol your GPS or software actually matches).
1814 Formatting
1816 The format of the plugin is as follows:
1818 symbol:CACHEDATA=CACHEVALUE=SYMBOLNAME,CACHEDATA2=CACHEVALUE2=SYMBOLNAME2,
1820 They are exact matches only. So the CACHEVALUE must exactly equal the
1822 value found in the CACHEDATA field or it won't be replaced. The symbol
1823 plugin will stop after the first match so the first symbol in the list
1824 that gets matched always wins.
1825 Modify Translate:
1827 By far, this is one of the most powerful modification plugins. It uses
1829 online services (like Google) to translate cache fields from one
1830 language to another. As an example, here are some of my caches:
1831 > geoqo -s cache:owner_name==Yamar&&waypoint:ident=GCJ -l
1833 num GCID Name
1834 1 GCJYPW Hoppin' mad about Davis
1835 2 GCJGRQ Beneficial cache
1836 3 GCJKMD Historical water tower
1837 4 GCJ7KT Got Coffee?
1838 5 GCJ66H Gone Fishin' (Yamar's unusual #4)
1839 6 GCJ491 O where art thou (Yamar's unusual #2)
1840 7 GCJ5DV Inverted Cache (Yamar's unusual #3)
1841 And here is what they look like when translated from English to
1843 Spanish:
1844 > geoqo -s cache:owner_name==Yamar&&waypoint:ident=GCJ -l -m translate:source=English,destination=Spanish
1846 num GCID Name
1847 1 GCJYPW Hoppin' enojado sobre Davis
1848 2 GCJGRQ Escondrijo beneficioso
1849 3 GCJKMD Torre historica del agua
1850 4 GCJ7KT Cafe Conseguido?
1851 5 GCJ66H Fishin ido ' (4) inusual de Yamar #
1852 6 GCJ491 O donde mil del arte (2) inusual de Yamar #
1853 7 GCJ5DV Escondrijo invertido (3) inusual de Yamar #
1854 Valid languages to pick from:
1856 English
1858 Spanish
1859 French
1860 German
1861 Italian
1862 Korean
1863 Japanese
1864 Portuguese
1865 Requirements
1867 1) you must be connected to the net
1869 2) you must have the WWW::Babelfish perl module installed.
1871 Options:
1873 source:
1875 The source language to translate from.
1876 default: Spanish
1878 destination:
1880 The destination language to translate to.
1881 default: English
1883 fields:
1885 A / separated list of fields to translate.
1886 default: urlname
1888 service:
1890 The name of the translation service to use.
1891 default: Babelfish
1893 Modify Distance:
1895 The distance modify plugin puts distance information from a given lat,
1897 lon coordinate and inserts the data into the "distance" field of the
1898 waypoint. You can then use it in other ways like in rewrite
1899 modification engines or in list formatting, etc.
1900 > geoqo -s ident:GCABCD -d 'list:format=%{ident} %{distance}
1902 You can calculate distance from coordinates:
1904 > geoqo -s ident:GCABCD -m 'distance:n=n38 12.123,w=w42 22.333'
1906 or from another waypoint already in the DB:
1908 You can calculate distance from coordinates:
1910 > geoqo -s ident:GCABCD -m 'distance:from=GCABCD'
1912 Options:
1914 from:
1916 The waypoint name distances should be calculated from
1917 n: The North coordiante to calculate distance from
1919 w: The West coordiante to calculate distance from
1921 Modify Sortby:
1923 The sort by function sorts data in a set by a particular field.
1925 > geoqo -s SOMETHING -m sortby:groundspeak_terrain -l
1927 Options:
1929 sortby:
1931 Field to sort by
1932 default: distance
1934 Modify Track:
1936 The track plugin lets you compare a list of waypoints found in a search
1938 against the data in a gpx track file. Specifically, it:
1939 - adds the following attribute fields to the waypoint's attribuets
1941 (not permenantly; use --save to save them):
1942 trkptdate - The date of the track point nearest the cache
1944 trkpttime - The time of the track point nearest the cache
1945 trkptnum - The number of the track point nearest the cache
1946 trkptname - The name of the track the point is in
1947 trkptdist - Distance in feet from the cache to the nearest track point
1949 trkptnum - The Nth track point counter into the track point data
1950 trkptepoch - Seconds since 1970 of the trackpoint closest to the cache
1951 trkptstart - Start time of the search (got closer than config distance)
1952 rtkptend - End time of the search
1953 rtkptnearby - Amount of time spent searching (= end - start)
1954 - optionally sorts the resulting waypoints by time visited if the
1956 sort option is set.
1957 Using this and the track search plugin you can take a track GPX file
1959 downloaded from a GPS and list all the caches you came near in the
1960 order you went to them along with the time stamp when you visited it.
1961 As an example, this is the results of a trip I took one day:
1962 > geoqo -s 'track:track.gpx' -m 'track:track.gpx' -d list:'%{7.7:ident} %{attr:trkpttime} %{urlname}'
1964 GC10J27 10:55:22 This one is Golden
1966 GCPC2R 11:16:53 "THE ISLAND"
1967 GCYCGE 13:02:07 Legacy Trail #1 - River BBQ
1968 GCD8A1 13:10:55 Under Lock & Key
1969 GC5CBC 13:52:32 Let the Games Begin
1970 GCPR6E 14:11:27 YFcache10
1971 GCWR36 14:31:10 Granite Rock
1972 GCK8YR 14:54:07 The Cache in The Middle of The Freeway
1973 GCYYXV 16:02:05 Cisco Grove TB Stop
1974 GC10Q0Q 16:02:41 Hard Rock Exchange #2
1975 GCW1C3 16:27:08 Crack with a View
1976 GCG38E 16:45:33 The Solar System - Pluto
1977 To get track data from the gps, use gpsbabel:
1979 gpsbabel -t -i garmin -f usb: -o gpx -F track.gpx
1981 Options:
1983 trackfile:
1985 Track data to sort by
1986 sort:
1988 field to sort resulting set by (if set)
1989 default: trkptepoch
1991 distance:
1993 Distance away in feet to use for determining how long you were in
1994 the area
1995 default: 528
1997 hroffset:
1999 Offset in hours to use from the datestamp found in the track;
2000 useful if the timezone in the GPS/track does not match the track
2001 was laid
2002 Modify Diff:
2004 Options:
2006 out:
2008 the name of the output file to store the html formated differences
2009 in.
2010 Modify Limit:
2012 This module limits the number of waypoints in a set to a certain number
2014 (starting at an optional certain point in the list of waypoints).
2015 IE, it starts at the offsetth waypoint in the set being modified, and
2017 limits the total number to number, stripping off all of the waypoints
2018 before the offset first and then everything from offset+number next.
2019 If just number is specified (the common case) the firest number
2021 waypoints are kept.
2022 If there are 250 caches in the set:
2024 number = 100, offset = 0
2026 Will get the first 100 caches
2027 number = 100, offset = 100
2029 Will get the next 100.
2030 number = 100, offset = 200
2032 Will get the last 50.
2033 This module is very useful when combined with the distance and sortby
2035 modify pluigns to get the top 10 caches (for example) near something:
2036 geoqo -s 'set:import:mypocketquery' -m distance:from=GCABCD+sortby:+limit:10
2038 Options:
2040 number:
2042 default: 100
2043 offset:
2045 default: 0
2046 Modify Only:
2048 This is most useful when doing really complex exporting. See Yamar's
2050 usage description on the web page for why this is helpful sometimes.
2051 It's mostly useful when you want to only include certain waypoints in a
2052 given export file, and you want to create lots of export files
2053 (TomTom's require one file per POI you wish to create, and I (Yamar)
2054 create different POIs for each cache type, size, etc.)
2055 The argument formatting is:
2057 only:field=value
2059 where field is the field (or attribute prefixed with 'attr:') name, and
2061 value is the exact value. The valid match types are:
2062 only:field=value
2064 Includes the waypoint only if the value is exactly the same as the
2065 waypoint's field value.
2066 only:field<>value
2068 Matches if the field is not that value
2069 only:field=-
2071 Matchs if the field doesn't exist.
2072 only:field=+
2074 Same as =- but only includes the waypoint if it does exist.
2075 Modify Drop:
2077 This is most useful when doing really complex exporting. See Yamar's
2079 usage description on the web page for why this is helpful sometimes.
2080 The Drop modifier is a compliment to the only modifier. Generally the
2082 "only" modifier will be easier for most people to think about, but
2083 technically you only need one as they can both accomplish the same
2084 tasks with inverse logic.
2085 The argument formatting is:
2087 drop:field=value
2089 where field is the field (or attribute prefixed with 'attr:') name, and
2091 value is the exact value. The valid match types are:
2092 drop:field=value
2094 Matches only if exactly the same.
2095 drop:field<>value
2097 Matches if the field is not that value
2098 drop:field=-
2100 Matchs if the field doesn't exist. I use this like follows:
2101 #
2103 # unknown caches with solved puzzle coords
2104 #
2105 drop:subtype<>Unknown Cache
2106 +drop:attr:puzn=-
2107 +solved:
2108 +gpx:nologs=1:palm-solved.gpx
2109 To drop any unknown cache that a 'puzn' attribute hasn't been added
2111 to it (see the Solved modify plugin for details).
2112 drop:field=+
2114 Same as =- but only drops it if it does exist.
2115 Modify Dropexisting:
2117 This modify function is really only useful during an import before a
2119 data save.
2120 The plugin simply removes all data from the current set that already
2122 exists in the database. This can be used to import data where only the
2123 new data is desired.
2124 Example:
2126 > geoqo -i 'myfile.gpx+dropexisting'
2128 Options:
2130 prefix:
2132 default:
2133 onlyprefixold:
2135 default: 1
2136 Modify Load:
2138 This is only useful when you're going to be doing complex exporting
2140 where you need the caches data loaded early before exporting to
2141 multiple files. Otherwise geoqo may load all the data once per file.
2142 > geoqo -s something -m load -e 'gctodiff+file1.gpx;file2.gpx
2144 See the export documentation for details on why file1.gpx and file2.gpx
2146 may contain separate data.
2147 Basically, since this is a confusing one, is if you're doing complex
2149 exporting (multiple files at once) put this on the -m switch to speed
2150 things up.
2151
2153 None of this is useful if you can't export your results of course.
2154 There are a number of export plugins you can pass to the -e switch to
2155 export the results of your search to a file.
2156 QUICK EXPORT EXAMPLES
2158 Some quick examples:
2160 Exporting all waypoints from two sets:
2162 > geodb -s 'set:search:gary&&set:search:47dad47' -e garyand47.gpx --debug 1
2164 1: writing file: garyand47.gpx
2165 Exporting all waypoints in a set that are of type "Unknown" to a .loc
2167 file:
2168 > geodb -s 'set:import:somefile&&waypoint:type=Unknown' -e partfilebackout.loc
2170 EXPORTING AND MODIFYING
2172 You can also combine modifications and exports in one pass. First list
2174 the modifications specs you want to do (see the documentation on the
2175 modification plugins for details) separated by + signs. Everything
2176 before the last + will call a modification plugin, and after the last +
2177 will be an export plugin.
2178 An example:
2180 > geodb -s 'cache:type=Unknown' -e gctodiff+partfilebackout.loc
2182 OUTPUTING TO MULTIPLE FILES
2184 You can also specify multiple output files separated by ';'s.
2186 Modification attributes will only apply to the next file. If you want
2187 every file to contain a modification plugin result, use the -m flag
2188 instead.
2189 > geodb -s 'cache:type=Unknown' -e 'gctodiff+partfilebackout.loc;partfilebackout2.gpx
2191 The above applies the gctodiff plugin to only the .loc file; the gpx
2193 file is written out using raw data.
2194 EXPORT PLUGIN TYPES
2196 Export Gpx:
2198 > geoqo -s 'cache:name=cool cache' -e myfile.gpx
2200 The gpx exporter writes out a gpx file containing all the caches in the
2202 search set.
2203 Options are applied between the colon delimiter type specifier (first
2205 part) and the file name (th e last part) like so:
2206 > geoqo -s 'cache:name=cool cache' -e gpx:nologs=1,setname=boo:myfile.gpx
2208 Options:
2210 setname:
2212 Makes the name field in the gpx file set to this value.
2213 default: geoqo-export
2215 nologs:
2217 If set the resulting gpx file does not contain the wayoint logs.
2218 nogcattributes:
2220 If set the resulting gpx file does not contain the groundspeak
2221 attributes.
2222 Export Loc:
2224 > geoqo -s 'cache:name=cool cache' -e myfile.loc
2226 The loc exporter writes out a loc file containing all the caches in the
2228 search set.
2229 Export Map:
2231 Example:
2233 geoqo -s set:import:myPQ -e map:output.png
2234 The map will show red dots whereever there is a cache (Yes virginia,
2236 there will eventually be symbols and names). The output (currently)
2237 must be a PNG file.
2238 Options:
2240 style:
2242 default: icons
2243 icondir:
2245 default: dist/tomtom-icons/
2246 iconscale:
2248 Size to scale icon sizes in the map. "auto" scales based on the
2249 number of waypoints to be shown.
2250 default: auto
2252 maptiles:
2254 default: 2
2255 notext:
2257 dodensity:
2258 Export Html:
2260 > geoqo -s 'cache:name=cool cache' -e myfile.html
2262 Prints a set of caches to a series of web pages. Each cache will
2264 get it's own file and a top level index file will be created that
2265 links to each cache page.
2266 Very useful for outputting geocaches to plucker.
2268 Options:
2270 subdir:
2272 Puts created HTML files in this sub directory name.
2273 default: caches
2275 title:
2277 The title to put at the top of the page
2278 default: GeoDB HTML Export
2280 Export Kml:
2282 > geoqo -s 'set:import:near me' -e fortheearth.kml
2284 The software will also produce a density plot as well, which shows the
2286 density of caches in particular areas color-coded by relief colors
2287 (rainbow; red = very few, purple = many). Examples of this can be seen
2288 on Yamar's cache homepage page http://geocaching.sharedlists.com/.
2289 Options:
2291 size=NUM
2293 > geoqo -s 'set:import:near me' -e kml:size=100:fortheearth.kml
2294 Changes the number of squares in the density plot to NUM by NUM.
2296 Defaults to 50.
2297 width=NUM
2299 height=NUM
2300 Changes just the width and height of the squares. The size
2301 parameter can change both at once.
2302 (there are a bunch of options for the density plot, which are currently
2304 undocumented).
2305 Options:
2307 bogus:
2309 dataname:
2310 default: Export from GeoQO
2311 dowaypoints:
2313 default: 1
2314 dodensity:
2316 default: 1
2317 dojail:
2319 default: 0
2320 bogus:
2322 waypointstyle:
2323 default: geoqo
2324 waypointheight:
2326 default: 150
2327 waypointmode:
2329 default: relativeToGround
2330 waypointextrude:
2332 default: 1
2333 includedescriptions:
2335 default: 1
2336 bogus:
2338 squareratio:
2339 default: 1
2340 size:
2342 Creates a plot where there are SIZE by SIZE squares of colored
2343 rectangles
2344 default: 200
2346 width:
2348 Normally equal to the size value but can be set independently. It
2349 specifies the width (in squares) of the density plot.
2350 height:
2352 Normally equal to the size value but can be set independently. It
2353 specifies the height (in squares) of the density plot.
2354 spread:
2356 Sets the spread that determines the number of neighboring squares
2357 that a given cache will effect. EG, a spread of 5 will affect a
2358 circle of density squares in a radius of 5. This generally should
2359 be a low value of probably not more than 5 or so.
2360 default: 5
2362 doempty:
2364 If set to 1, even empty squares will be colored (red). Otherwise
2365 the empty squares are removed from the plot leaving the plane
2366 ground underneath.
2367 default: 0
2369 bogus:
2371 altitude:
2372 The altitude to set the density plot squares at.
2373 default: 1000
2375 densitymode:
2377 default: relativeToGround
2378 extrude:
2380 Whether or not to extrude the density plot squares down to the
2381 ground.
2382 default: 0
2384 opaque:
2386 The opacity of the density squares. Must be between 0 and 100,
2387 with 0 being completely see-through (and thus completely useless).
2388 default: 20
2390 linewidth:
2392 The width of the border lines to draw (0-4). 0 means don't draw
2393 borders on the squares.
2394 default: 0
2396 bagus:
2398 jailaltitude:
2399 default: 100
2400 jailmode:
2402 default: relativeToGround
2403 bogus:
2405 limitdata:
2406 default: 1
2407 nmax:
2409 The maximum north coordinate value to created the grid over.
2410 Normally this is automatically set by the maximum value found in
2411 the data, but can be overridden
2412 nmin:
2414 The minimum north coordinate value to created the grid over.
2415 Normally this is automatically set by the minimum value found in
2416 the data, but can be overridden
2417 wmax:
2419 The maximum west coordinate value to created the grid over.
2420 Normally this is automatically set by the maximum value found in
2421 the data, but can be overridden
2422 wmin:
2424 The minimum west coordinate value to created the grid over.
2425 Normally this is automatically set by the minimum value found in
2426 the data, but can be overridden
2427 Export System:
2429 There are two ways to use the system export mechanism:
2431 Run a system command for cache:
2433 > geoqo -s 'cache:name=cool cache' -e 'system:cmd=echo %{ident} %{desc}'
2434 That command runs echo for each cache in the set, replacing
2436 %{ident} and %{desc} with the fields from those caches.
2437 Useful things to do for this would be to open firefox (a web
2439 browser) on each cache page:
2440 > geoqo -s 'cache:name=cool cache' -e 'system:cmd=firefox %{url}'
2442 Run a system command
2444 You can also run a command on a file generated by an export module.
2445 As an example, the following command will call gpsbabel to convert
2446 a gpx file to a tomtom compatible file:
2447 > geoqo -s 'cache:name=cool cache' -e 'system:cmd=gpsbabel -i gpx -f %{file:gpx} -o tomtom -F mycaches.ov2'
2449 Options:
2451 cmd:
2453 COMMAND is what gets run. If it contains a %{file:TYPE} string in
2454 it, that will be replaced with a file name of that type and it'll
2455 get run just once. If it doesn't, it'll get run once per cache in
2456 the set being processed and each %{token} specifier will get
2457 replaced by that item from the cache.
2458 sleep:
2460 Between each command executed in the per-cache mode, geoqo will
2461 sleep for NUM seconds before running the next. It defaults to 1,
2462 and can be set to 0 to just fire them off as fast as possible.
2463 dontdelete:
2465 if set to 1, don't delete the temporary files
2466 tmpdir:
2468 The temporary directory to use
2469 default: /home/hardaker/.geoqo/temp
2471
2473 Here are some useful plugins that can be used in many command line
2474 definitions.
2475 Everywhere mem:
2477 It hard to repeatedly type complex queries, tasks, or what have you so
2479 to facilitate this you can use the Mem plugin for remembering complex
2480 strings (or even simple onse, if you choose).
2481 To do this, take a complex search (or export, or modify) string and
2483 save it in a file in the directory "$HOME/.geoqo/mem/TYPE/FILENAME".
2484 Where TYPE is one of "search", "export", or "modify" and FILENAME is a
2485 file name of your choosing. You can also store file entries directly
2486 in $HOME/.geoqo/mem/FILENAME (note the missing "TYPE" part), which then
2487 makes the definition usable for all types. It is not likely you'll
2488 need to use a definition for both searching and exporting (as an
2489 example), however, so I suggest you store them in a type-based
2490 subdirectory instead. Only because it's cleaner. You want to be neat
2491 and tidy right?
2492 All lines read in these file will be merged together and leading and
2494 trailing white-space characters are stripped as well comment lines
2495 (which should start with a #). For example if you had a file like so:
2496 > cat $HOME/.geoqo/mem/search/memtest
2498 # Searches a particular imported set named "near me"
2499 set:import:near me
2500 # but only for items I haven't logged as found
2501 &&cache:finder<>Yamar
2502 # and aren't unknown caches.
2503 &&cache:subtype<>Unknown
2504 You can then run geoqo like so:
2506 > geoqo -s mem:memtest -d count
2508 Search Result Count: 480
2509 Which is really a replacement for:
2511 > geoqo -s set:import:near me&&cache:finder<>Yamar&&cache:subtype<>Unknown -d count
2513 Since you may want to frequently replace parts of your super-long and
2515 complicated definition strings you've built up, you can do this as well
2516 by putting %[NAME,DEFAULT] strings inside your definitions. IE, doing
2517 this:
2518 > cat $HOME/.geoqo/mem/memtest
2520 set:import:%[setname,near me]
2521 &&cache:finder<>Yamar
2522 &&cache:subtype<>Unknown
2523 Makes the import: set default to "near me" so the above example command
2525 will work just like it would before, but if I specify a setname option
2526 on the command line I can override it. Here's the original command
2527 example:
2528 > geoqo -s mem:memtest -d count
2530 Search Result Count: 480
2531 And here's using the same search criteria, but using "fairfield" as the
2533 import set name instead of the default "near me":
2534 > geoqo -s mem:memtest,setname=fairfield -d count
2536 Search Result Count: 182
2537 Final note: you can have mem: definitions that call other mem:
2539 definitions. The only caveat there is that parameters aren't passed
2540 down automatically, so if your second mem: definition being called has
2541 a %[something,xxx] definition then you should call it within the higher
2542 definition as mem:subdef,something=%[something,xxx] as well.
2543
2545 GeoQO can also perform a bunch of tasks at once in a scripted fashion.
2546 IE, if you find yourself repeatedly doing a standard search followed by
2547 an export, you can script things together in a single file and call
2548 geoqo -x FILE.
2549 The script file format contains lines that start with a '%MODE'
2551 followed by text for that MODE. MODE should be one of: search, export,
2552 import, modify, display or print. You can break long lines into pieces
2553 just like the mem: plugin discusses above.
2554 Thus the following script (saved in, for example, "myscript.txt") will
2556 display unsolved puzzles in your database ordered by distance:
2557 # searches for all 'Unknown' caches
2559 %search
2560 subtype=Unknown
2561 &&attr:puzn=-
2562 # displays them in list format
2564 %display
2565 list
2566 Then running the script will display the list:
2568 > geoqo -x myscript.txt
2570 ... [list displayed here] ...
2571 Scripts can be stored in $HOME/.geoqo/scripts and if a script is run
2573 and the file doesn't exist in the current working directory, then the
2574 $HOME/.geoqo/scripts directory will be checked to see if it contains
2575 the file.
2576 Scripts can contain %[name,default value] sections just like Everywhere
2578 Mem: definitions can and are acted upon the same way. Thus a script
2579 of:
2580 %search
2582 waypoint:type==%[type,Waymark]
2583 %display
2585 count
2586 Will default to counting all the Waymarks in the database. But if run
2588 as:
2589 > geoqo -x myscript.txt:type=Geocache
2591 It'll count all the geocaches instead.
2593 Special Script Formatting
2595 White Space Wrapping
2597 Normally script lines are merged together, stripping leading and
2599 trailing white space off of a line. EG, Scripts that look like:
2600 %search
2602 waypoint:type=
2603 =
2604 Geo
2605 cache
2606 will actually be translated to a search using just:
2608 wayoint:type==Geocache
2610 If you need to force whitespace into a script line at the begining or
2612 end you can use a triple " in order to forec it. EG:
2613 %search
2615 cache:owner_name=Super
2616 """ Sleuth"
2617 Will keep the space between the """ and the word Sleuth:
2619 cache:owner_name=Super Sleuth
2621 Trailing """s work similarily.
2623 Special Script Keywords
2625 All script pieces begin with a % sign on a new line. The line format
2627 looks like:
2628 %keyword someoption=1 otheroption=yes
2630 These special options may include these global options as well as any
2632 keyword-specific options discussed below:
2633 allowgui=1
2635 This lets the GUI screens be shown for the sub-scripts. Normally
2636 they're hidden as the top script is always expected to pass needed
2637 parameters down.
2638 The special script keywords that mayb be used are:
2640 %print
2642 Prints everything from that section to the screen.
2643 Example:
2645 %print hello world
2647 %script
2649 Runs a subscript based on the text following the %script line.
2650 (may include the script name and potentially arguments following a
2651 ':').
2652 Example:
2654 %script scriptname:arg1=value1
2656 %include [ARGUMENTS] SCRIPT_FILE_NAME
2658 Include another script as part of this script. Unlike the %script
2659 command, the %include command operates on the same search set,
2660 becomes part of the same auto-gui screen, etc.
2661 You can also pass a type=hooks argument to include a bunch of
2663 files. EG:
2664 %include type=hooks specialhooks/*.inc
2666 Will include every file that matches that pattern in each of the
2668 script search paths. The order in which they are included is
2669 determined by alphabetical ordering of the last filename component
2670 (ie, not directory path component).
2671 Finally, you can auto-wrap includes in if statements and use the
2673 resulting titles from the included files in menu to select which
2674 file gets executed. This is primarily intended for building
2675 dynamic menus from found plugins. This is best seen by an example:
2676 In a file called "testincludetop.txt", we put the menu definition:
2678 %ignore
2680 %[mymenu,0
2681 ,labels=(%{VALUELABELS})
2682 ,type=menu,text=top menu:
2683 ,refresh_on_change=1
2684 ]
2685 In two files called testinclude-1.txt and testinclude-2.txt we put:
2687 #scriptname: item number 1
2689 %print
2690 some thing or other to handle choice #1
2691 (And something similar for number 2)
2693 Then finally, in the real top level script you call the whole
2695 shabang with:
2696 %include type=hooks autoif=mymenu hookheader=testincludetop.txt testinclude*.txt
2698 In the end, the whole result gets built as follows:
2700 %ignore
2702 %[mymenu,0
2703 ,labels=(0,item number 1,2,item number 2)
2704 ,type=menu,text=top menu:
2705 ,refresh_on_change=1
2706 ]
2707 %if "%[mymenu]" eq "0"
2708 %title
2709 item number 1
2710 %print
2711 some thing or other to handle choice #1
2712 %endif
2713 %if "%[mymenu]" eq "1"
2714 %title
2715 item number 2
2716 %print
2717 some thing or other to handle choice #2
2718 %endif
2719 If you could follow that, I'll be impressed. But it's really
2721 powerful! See the included "searchbase" script for a much larger
2722 example.
2723 %save
2725 Calls 'save' on the current set saving all the data to the db
2726 (needed if modified in anyway that should result in a save, such as
2727 when the setattr: modify plugin was called).
2728 %saveset name=MYNAME
2730 Remembers the current set as MYNAME.
2731 %webfile
2733 Pulls a file from a URL and saves it to a file. The format is the
2734 file name to save it to, a comma and then the URL. Example:
2735 %webfile
2737 waymarks-train.gif,http://www.waymarking.com/images/cat_icons/train.gif
2738 You can then refer to these files using webfile:waymarks-train.gif
2740 in %copy or %system commands.
2741 %copy
2743 Copy's a file from one place to another. Example format:
2744 %copy
2746 file1.loc,file2.loc
2747 Or refering to a webfile previously pulled from a %webfile
2749 directive:
2750 %copy
2752 webfile:waymarks-train.gif,/some/path/to/waymarks-train.gif
2753 %system
2755 Run's a system command. webfile: prefixes within the command
2756 string will be replaced by paths to a stored %webfile.
2757 %if CLAUSE
2759 %else
2760 %endif
2761 These sections allow for variablity of what is done based on user
2762 input. CLAUSE is evaluated as perl code (returning a perl true or
2763 false response (eg, 1 or 0)) to determine what to do next. CLAUSE
2764 will be evaluated first in terms of parameteritized input. Thus:
2765 %print
2767 %if %[desire,1,type=checkbox]
2768 hello
2769 %else
2770 world
2771 %endif
2772 Will print "hello" if the user clicks the check box (defaults to
2774 on) or "world" if the user does not. (They may also hand-specify
2775 the 'Desire' parameter as scriptname:desire=1 or equievelent).
2776 Nesting is properly handled.
2778 %foreach VAR value1 value2 ...
2780 %endforeach
2781 Allows repeated script sections with %{VAR} being replaced with a
2782 different value for each section.
2783 %foreach it 1 2 3 a b word
2785 %print
2786 This is it: %{it}
2787 %endforeach
2788 Will output:
2790 This is it: 1
2792 This is it: 2
2793 This is it: 3
2794 This is it: a
2795 This is it: b
2796 This is it: word
2797 %perl
2799 Embeds perl into the script. $self is a reference to the master
2800 GeoDB object. Use this functionality only if you're an expert (and
2801 in desperate need).
2802 %perl leavewhitespace=1
2804 %title
2806 Names the script with a title.
2807 %title
2809 My super title
2810 %introduction
2812 Includes a paragraph in the top of the GUI screen when the script
2813 is run.
2814 %introduction
2816 This is how you use this screen
2817
2819 -i STRING
2820 --import-file=STRING
2821 Import a file. File should be specified as type:file
2822 -n STRING
2824 --name=STRING
2825 Comma separated names to assign to the objects in the file
2826 -m STRING
2828 --modify=STRING
2829 Modify the search set before displaying or exporting
2830 -e STRING
2832 --export-file=STRING
2833 Export a file. File should be specified as type:file
2834 --execute-script=FILENAME
2836 -x FILENAME
2837 Run a script stored in FILENAME
2838 Search Options:
2840 -s STRING
2842 --search=STRING
2843 Search terms for geocaches
2844 --limit=INTEGER
2846 Maximum number of records to return for searches
2847 -N STRING
2849 --set-name=STRING
2850 Set/Search Storage Name ('search:geoqo')
2851 Display Options:
2853 -l
2855 --list-caches
2856 List geocaches found in search
2857 -S
2859 --show-caches
2860 Show details of geocaches found
2861 -L
2863 --show-logs
2864 Show log messages in details output
2865 -d STRING
2867 --display=STRING
2868 Display output thingies
2869 --save
2871 --save-changes
2872 Save changes to the set to the DB
2873 Database Options:
2875 -t STRING
2877 --db-type=STRING
2878 Database Type (sqlite2, sqlite, mysql, postgres)
2879 -H STRING
2881 --db-host=STRING
2882 Database Host (localhost)
2883 -u STRING
2885 --db-user=STRING
2886 Database User (geoqo)
2887 -p STRING
2889 --db-password=STRING
2890 Database Password
2891 --db-name=STRING
2893 Database Name (geoqo)
2894 --db-flush
2896 Delete the existing DB first
2897 --db-port=INTEGER
2899 Port number for the database
2900 --setup-database
2902 Initialize the database table structure
2903 Configuration Options:
2905 -c STRING
2907 --config-file=STRING
2908 Configuration File to read
2909 -C
2911 --no-config
2912 Do not read any configuration file
2913 --debug=INTEGER
2915 Turn on debugging output
2916 --test
2918 Prints a bunch of test output that Yamar (or someone else) may ask
2919 you for if you have problems.
2920 Help Options
2922 -h Display a help summary (short flags preferred)
2924 --help
2926 Display a help summary (long flags preferred)
2927 --help-full
2929 Display all help options (both short and long)
2930 --version
2932 Display the script version number.
2933
2935 GeoQO supports a configuration file where multiple types of things can
2936 be specified.
2937 Command Line Options and Default
2939 You can also store "always use this" options in a configuration file
2941 named ~/.geoqo/config. This file should be the option name on the left
2942 (single letter option if available, not longer ones) followed by the
2943 value you want after a space. EG to always use debugging and
2944 postgresql and the 'geo' database user:
2945 t postgresql
2947 u geo
2948 debug 5
2949 Any option may be added to this file. Options on the command line will
2951 override options in this file (as you'd expect).
2952 GUI Defaults
2954 When using the auto-gui created screens, you can specify your own
2956 defaults for widgets created by geoqo modules or scripts using the
2957 "default" keyword. EG:
2958 default searchby Power Search
2960 Will set the default search mechanism to the "Power Search" option.
2962 Knowing what keyword to use and what value to use generaly requires
2963 understanding how geoqo works at this point though (or you can ask
2964 Yamar in the #geoqo IRC channel).
2965 Per-Screen GUI Defaults
2967 You can also set defaults or for particular script screens. To set the
2969 default search type in the devices/cachemate script GUI screen:
2970 screen devices/cachemate searchby Power Search
2972
2974 If you really want to see what geodb is doing internally, run with the
2975 --debug switch. In particuluar, "--debug 5" will print lots of
2976 interesting information. Too much. The higher the number the more you
2977 get.
2978
2980 The following people (geocachers) helped in useful ways with this
2981 program:
2982 BlueNinja
2984 Self proclaimed "test monkey". He tested lots of early verions and
2985 has caught various bugs as well and given me better usage ideas
2986 through his "why can't I do this" set of questions.
2987 He was also the first person to get it working on Windows and has
2989 contributed vastly to the windows documentation.
2990 ClayJar
2992 Who won the renaming contest on IRC after SourceForge told me GeoDB
2993 was an internal reserved name:
2994 [03:38:13 pm] <ClayJar_SSH>Yamar: How about "Geoqo". You'll have
2996 sole Google of that one, I imagine. You can pronounce it "ge-OH-ko",
2997 and "QO" is DB after ROT13.
2998 For those that don't know, ROT13 is the cheap encryption mechanism
3000 that geocaching.com (and other places) use to encrypt their logs.
3001 (ROT13 is used in many, many other ways too, and the first most
3003 popular usage of it was to encrypt potentially offensive material
3004 (ie, jokes) when posting to USENET news groups)
3005 Planet
3007 Planet nicely volunteered to proof-read a copy of this manual and
3008 sent me many wonderful suggestions about improving it.
3009 jslagle
3011 The first person to send me a code patch (implementing a better zip
3012 file import handler)! Yay! He's now a co-developer.
3013 brdad
3015 The first person to wade through what it takes to get the GUI
3016 working under windows.
3017 lairsdragon
3019 Submitted patches for the build system to make it more PREFIX
3020 friendly.
3021 Zemmy
3023 An early Windows test case for the installer components.
3024
3026 Wes Hardaker <hardaker ATAT users.sourceforge.net>
3027 AKA "Yamar" on Geocaching.com, IRC, and other places
3029perl v5.10.0 2009-11-10 GEOQO(1)
