hs.spotlight.md

docs » hs.spotlight

---

This module allows Hammerspoon to preform Spotlight metadata queries.

This module will only be able to perform queries on volumes and folders which are not blocked by the Privacy settings in the System Preferences Spotlight panel.

A Spotlight query consists of two phases: an initial gathering phase where information currently in the Spotlight database is collected and returned, and a live-update phase which occurs after the gathering phase and consists of changes made to the Spotlight database, such as new entries being added, information in existing entries changing, or entities being removed.

The syntax for Spotlight Queries is beyond the scope of this module's documentation. It is a subset of the syntax supported by the Objective-C NSPredicate class. Some references for this syntax can be found at:

• https://developer.apple.com/library/content/documentation/Carbon/Conceptual/SpotlightQuery/Concepts/QueryFormat.html
• https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/Predicates/Articles/pSyntax.html

Depending upon the callback messages enabled with the hs.spotlight:callbackMessages method, your callback assigned with the hs.spotlight:setCallback method, you can determine the query phase by noting which messages you have received. During the initial gathering phase, the following callback messages may be observed: "didStart", "inProgress", and "didFinish". Once the initial gathering phase has completed, you will only observe "didUpdate" messages until the query is stopped with the hs.spotlight:stop method.

You can also check to see if the initial gathering phase is in progress with the hs.spotlight:isGathering method.

You can access the individual results of the query with the hs.spotlight:resultAtIndex method. For convenience, metamethods have been added to the spotlightObject which make accessing individual results easier: an individual spotlightItemObject may be accessed from a spotlightObject by treating the spotlightObject like an array; e.g. spotlightObject[n] will access the n'th spotlightItemObject in the current results.

Submodules

• hs.spotlight.group
• hs.spotlight.item

API Overview

• Constants - Useful values which cannot be changed
• commonAttributeKeys
• definedSearchScopes
• Constructors - API calls which return an object, typically one that offers API methods
• new
• newWithin
• Methods - API calls which can only be made on an object returned by a constructor
• callbackMessages
• count
• groupedResults
• groupingAttributes
• isGathering
• isRunning
• queryString
• resultAtIndex
• searchScopes
• setCallback
• sortDescriptors
• start
• stop
• updateInterval
• valueListAttributes
• valueLists

API Documentation

Constants

commonAttributeKeys

Signature	hs.spotlight.commonAttributeKeys[]
Type	Constant
Description	A list of defined attribute keys as discovered in the macOS 10.12 SDK framework headers.
Notes	This list was generated by searching the Framework header files for string constants which matched one of the following regular expressions: "kMDItem.+", "NSMetadataItem.+", and "NSMetadataUbiquitousItem.+"

definedSearchScopes

Signature	hs.spotlight.definedSearchScopes[]
Type	Constant
Description	A table of key-value pairs describing predefined search scopes for Spotlight queries
Notes	It is uncertain at this time if the iCloud* search scopes are actually useful within Hammerspoon as Hammerspoon is not a sandboxed application that uses the iCloud API fo document storage. Further information on your experiences with these scopes, if you use them, is welcome in the Hammerspoon Google Group or at the Hammerspoon Github web site.

Constructors

new

Signature	hs.spotlight.new() -> spotlightObject
Type	Constructor
Description	Creates a new spotlightObject to use for Spotlight searches.
Parameters	None
Returns	a new spotlightObject

newWithin

Signature	hs.spotlight.newWithin(spotlightObject) -> spotlightObject
Type	Constructor
Description	Creates a new spotlightObject that limits its searches to the current results of another spotlightObject.
Parameters	spotlightObject - the object whose current results are to be used to limit the scope of the new Spotlight search.
Returns	a new spotlightObject

Methods

callbackMessages

| Signature | hs.spotlight:callbackMessages([messages]) -> table | spotlightObject | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or specify the specific messages that should generate a callback. | | Parameters |

• messages - an optional table or list of items specifying the specific callback messages that will generate a callback. Defaults to { "didFinish" }.

| | Returns |

• if an argument is provided, returns the spotlightObject; otherwise returns the current values

| | Notes |

• Valid messages for the table are: "didFinish", "didStart", "didUpdate", and "inProgress". See hs.spotlight:setCallback for more details about the messages.

|

count

Signature	hs.spotlight:count() -> integer
Type	Method
Description	Returns the number of results for the spotlightObject's query
Parameters	None
Returns	if the query has collected results, returns the number of results that match the query; if the query has not been started, this value will be 0.
Notes	Just because the result of this method is 0 does not mean that the query has not been started; the query itself may not match any entries in the Spotlight database. A query which ran in the past but has been subsequently stopped will retain its queries unless the parameters have been changed. The result of this method will indicate the number of results still attached to the query, even if it has been previously stopped.

groupedResults

Signature	hs.spotlight:groupedResults() -> table
Type	Method
Description	Returns the grouped results for a Spotlight query.
Parameters	None
Returns	an array table containing the grouped results for the Spotlight query as specified by the hs.spotlight:groupingAttributes method. Each member of the array will be a spotlightGroupObject which is detailed in the hs.spotlight.group module documentation.
Notes	The spotlightItemObjects available with the hs.spotlight.group:resultAtIndex method are the subset of the full results of the spotlightObject that match the attribute and value of the spotlightGroupObject. The same item is available through the spotlightObject and the spotlightGroupObject, though likely at different indicies.

groupingAttributes

| Signature | hs.spotlight:groupingAttributes([attributes]) -> table | spotlightObject | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the grouping attributes for the Spotlight query. | | Parameters |

• attributes - an optional table or list of items specifying the grouping attributes for the Spotlight query. Defaults to an empty array.

| | Returns |

• if an argument is provided, returns the spotlightObject; otherwise returns the current values

| | Notes |

• Setting this property while a query is running stops the query and discards the current results. The receiver immediately starts a new query.
• Setting this property will increase CPU and memory usage while performing the Spotlight query.

|

isGathering

Signature	hs.spotlight:isGathering() -> boolean
Type	Method
Description	Returns a boolean specifying whether or not the query is in the active gathering phase.
Parameters	None
Returns	a boolean value of true if the query is in the active gathering phase or false if it is not.
Notes	An inactive query will also return false for this method since an inactive query is neither gathering nor waiting for updates. To determine if a query is active or inactive, use the hs.spotlight:isRunning method.

isRunning

Signature	hs.spotlight:isRunning() -> boolean
Type	Method
Description	Returns a boolean specifying if the query is active or inactive.
Parameters	None
Returns	a boolean value of true if the query is active or false if it is inactive.
Notes	An active query may be gathering query results (in the initial gathering phase) or listening for changes which should cause a "didUpdate" message (after the initial gathering phase). To determine which state the query may be in, use the hs.spotlight:isGathering method.

queryString

Signature	hs.spotlight:queryString(query) -> spotlightObject
Type	Method
Description	Specify the query string for the spotlightObject
Parameters	a string containing the query for the spotlightObject
Returns	the spotlightObject
Notes	Setting this property while a query is running stops the query and discards the current results. The receiver immediately starts a new query.

resultAtIndex

Signature	hs.spotlight:resultAtIndex(index) -> spotlightItemObject
Type	Method
Description	Returns the spotlightItemObject at the specified index of the spotlightObject
Parameters	index - an integer specifying the index of the result to return.
Returns	the spotlightItemObject at the specified index or an error if the index is out of bounds.
Notes	For convenience, metamethods have been added to the spotlightObject which allow you to use spotlightObject[index] as a shortcut for spotlightObject:resultAtIndex(index).

searchScopes

| Signature | hs.spotlight:searchScopes([scope]) -> table | spotlightObject | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the search scopes allowed for the Spotlight query. | | Parameters |

• scope - an optional table or list of items specifying the search scope for the Spotlight query. Defaults to an empty array, specifying that the search is not limited in scope.

| | Returns |

• if an argument is provided for scope, returns the spotlightObject; otherwise returns a table containing the current search scopes.

| | Notes |

• Setting this property while a query is running stops the query and discards the current results. The receiver immediately starts a new query.

|

setCallback

| Signature | hs.spotlight:setCallback(fn | nil) -> spotlightObject | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Set or remove the callback function for the Spotlight search object. | | Parameters |

• fn - the function to replace the current callback function. If this argument is an explicit nil, removes the current callback function and does not replace it. The function should expect 2 or 3 arguments and should return none.

| | Returns |

• the spotlightObject

| | Notes |

• Depending upon the messages set with the hs.spotlight:callbackMessages method, the following callbacks may occur:

|

sortDescriptors

| Signature | hs.spotlight:sortDescriptors([attributes]) -> table | spotlightObject | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the sorting preferences for the results of a Spotlight query. | | Parameters |

• attributes - an optional table or list of items specifying sort descriptors which affect the sorting order of results for a Spotlight query. Defaults to an empty array.

| | Returns |

• if an argument is provided, returns the spotlightObject; otherwise returns the current values

| | Notes |

• Setting this property while a query is running stops the query and discards the current results. The receiver immediately starts a new query.

|

start

Signature	hs.spotlight:start() -> spotlightObject
Type	Method
Description	Begin the gathering phase of a Spotlight query.
Parameters	None
Returns	the spotlightObject
Notes	If the query string set with hs.spotlight:queryString is invalid, an error message will be logged to the Hammerspoon console and the query will not start. You can test to see if the query is actually running with the hs.spotlight:isRunning method.

stop

Signature	hs.spotlight:stop() -> spotlightObject
Type	Method
Description	Stop the Spotlight query.
Parameters	None
Returns	the spotlightObject
Notes	This method will prevent further gathering of items either during the initial gathering phase or from updates which may occur after the gathering phase; however it will not discard the results already discovered.

updateInterval

| Signature | hs.spotlight:updateInterval([interval]) -> number | spotlightObject | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the time interval at which the spotlightObject will send "didUpdate" messages during the initial gathering phase. | | Parameters |

• interval - an optional number, default 1.0, specifying how often in seconds the "didUpdate" message should be generated during the initial gathering phase of a Spotlight query.

| | Returns |

• if an argument is provided, returns the spotlightObject object; otherwise returns the current value.

|

valueListAttributes

| Signature | hs.spotlight:valueListAttributes([attributes]) -> table | spotlightObject | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the attributes for which value list summaries are produced for the Spotlight query. | | Parameters |

• attributes - an optional table or list of items specifying the attributes for which value list summaries are produced for the Spotlight query. Defaults to an empty array.

| | Returns |

• if an argument is provided, returns the spotlightObject; otherwise returns the current values

| | Notes |

• Setting this property while a query is running stops the query and discards the current results. The receiver immediately starts a new query.
• Setting this property will increase CPU and memory usage while performing the Spotlight query.

|

valueLists

Signature	hs.spotlight:valueLists() -> table
Type	Method
Description	Returns the value list summaries for the Spotlight query
Parameters	None
Returns	an array table of the value list summaries for the Spotlight query as specified by the hs.spotlight:valueListAttributes method. Each member of the array will be a table with the following keys: attribute - the attribute for the summary value - the value of the attribute for the summary count - the number of Spotlight items in the spotlightObject results for which this attribute has this value
Notes	Value list summaries are a quick way to gather statistics about the number of results which match certain criteria - they do not allow you easy access to the matching members, just information about their numbers.