extra/spotlight/spotlight-docs.factor

   1 ! Copyright (C) 2013 Charles Alston, John Benediktsson
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax io.pathnames sequences strings ;
   4 IN: spotlight
   5
   6 HELP: mdfind
   7 { $values { "query" string } { "results" sequence } }
   8 { $description
   9     "Finds files matching a given query."
  10     $nl
  11     { $snippet "mdfind [-live] [-count] [-onlyin directory] [-name fileName] query" }
  12     $nl
  13     "The mdfind command consults the central metadata store and returns a list of files that match the given metadata query. The query can be a string or a query expression."
  14     $nl
  15     { $subheading "Spotlight Keywords" }
  16     "These can be included in the query expression to limit the type of documents returned:"
  17     { $table
  18         { "Applications"  "kind:application, kind:applications, kind:app" }
  19         { "Audio/Music"   "kind:audio, kind:music" }
  20         { "Bookmarks"     "kind:bookmark, kind:bookmarks" }
  21         { "Contacts"      "kind:contact, kind:contacts" }
  22         { "Email"         "kind:email, kind:emails, kind:mail message, kind:mail messages" }
  23         { "Folders"       "kind:folder, kind:folders" }
  24         { "Fonts"         "kind:font, kind:fonts" }
  25         { "iCal Events"   "kind:event, kind:events" }
  26         { "iCal To Dos"   "kind:todo, kind:todos, kind:to do, kind:to dos" }
  27         { "Images"        "kind:image, kind:images" }
  28         { "Movies"        "kind:movie, kind:movies" }
  29         { "PDF"           "kind:pdf, kind:pdfs" }
  30         { "Preferences"   "kind:system preferences, kind:preferences" }
  31         { "Presentations" "kind:presentations, kind:presentation" }
  32     }
  33     { $subheading "Date Keywords" }
  34     "These can be included in the query expression to limit the age of documents returned:"
  35     { $table
  36         { "date:today"       "$time.today()" }
  37         { "date:yesterday"   "$time.yesterday()" }
  38         { "date:this week"   "$time.this_week()" }
  39         { "date:this month"  "$time.this_month()" }
  40         { "date:this year"   "$time.this_year()" }
  41         { "date:tomorrow"    "$time.tomorrow()" }
  42         { "date:next month"  "$time.next_month()" }
  43         { "date:next week"   "$time.next_week()" }
  44         { "date:next year"   "$time.next_year()" }
  45     }
  46     { $subheading "Boolean Operators" }
  47     "By default mdfind will AND together elements of the query string."
  48     { $table
  49         { "| (OR)"    { "to return items that match either word, use the pipe character: " { $snippet "stringA|stringB" } } }
  50         { "- (NOT)"   { "to exclude documents that match a string: " { $snippet "-string" } } }
  51         { "=="        "equal" }
  52         { "!="        "not equal" }
  53         { "< and >"   "\"less\" or \"more than\"" }
  54         { "<= and >=" "\"less than or equal\" or \"more than or equal\"" }
  55     }
  56 }
  57 { $examples
  58     "Return all files that have been modified today"
  59     { $code "\"date:today\" mdfind" }
  60     "Return all files that have been modified in the last 3 days"
  61     { $code "\"kMDItemFSContentChangeDate >= $time.today (-3)\" mdfind" }
  62     "Returns files with particular attributes"
  63     { $code "\"com.microsoft.word.doc\" \"kMDItemContentType\" attr== mdfind" }
  64     "Look for files with a particular file name"
  65     { $code "\"Finding Joy in Combinators.pdf\" \"kMDItemFSName\" attr== mdfind" }
  66     "Look for terms in documents"
  67     { $code "\"Document cocoa.messages selector\" mdfind" }
  68     "Return all files in the users home folder that have been modified in the last 3 days"
  69     { $code "\"~\" [ \"kMDItemFSContentChangeDate >= $time.today (-3)\" mdfind ] with-directory" }
  70 }
  71 { $notes "This word uses the " { $link current-directory } " to restrict the search, choosing to search from the root ('" { $snippet "/" } "') if not set." } ;
  72
  73 HELP: mdfind.
  74 { $values { "query" string } }
  75 { $description "Similar to " { $link mdfind } ", but prints out the results as a list of " { $link pathname } " objects, allowing you to right-click and \"Open File\" if used with the " { $snippet "webbrowser" } " vocabulary." } ;
  76
  77 HELP: mdls
  78 { $values { "path" "string or pathname" } }
  79 { $description
  80     "Lists the metadata attributes for the specified file."
  81     $nl
  82     { $snippet "mdls [-name attributeName] [-raw [-nullMarker markerString]] file ..." }
  83     $nl
  84     "The mdls command prints the values of all the metadata attributes associated with the files provided as an argument."
  85 } ;
  86
  87 HELP: mdutil
  88 { $values { "flags" string } { "on|off" string } { "volume" string } { "seq" sequence } }
  89 { $description
  90     "Manage the metadata stores used by Spotlight."
  91     $nl
  92     { $snippet "mdutil [-pEsav] [-i on | off] mountPoint ..." }
  93     $nl
  94     "The mdutil command is useful for managing the metadata stores for mounted volumes."
  95 } ;
  96
  97 HELP: mdimport
  98 { $values { "path" string } { "seq" sequence } }
  99 { $description
 100     "Import file hierarchies into the metadata datastore."
 101     $nl
 102     { $snippet "mdimport [-VXLArgn] [-d level | category] [-w delay] file | directory" }
 103     $nl
 104     "mdimport is used to test Spotlight plug-ins, list the installed plug-ins and schema, and re-index files handled by a plug-in when a new plug-in is installed."
 105 } ;
 106
 107 HELP: kMDItems
 108 { $values { "seq" sequence } }
 109 { $description "Retrieves all the available kMDItemAttributes." } ;
 110
 111 HELP: kMDItems.
 112 { $description "Prints a table of all the available kMDItemAttributes." } ;