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:
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.
Signature | hs.spotlight.commonAttributeKeys[] |
---|---|
Type | Constant |
Description | A list of defined attribute keys as discovered in the macOS 10.12 SDK framework headers. This table contains a list of attribute strings that may be available for spotlightSearch result items. This list is by no means complete, and not every result will contain all or even most of these keys. Notes:
|
Signature | hs.spotlight.definedSearchScopes[] |
---|---|
Type | Constant |
Description | A table of key-value pairs describing predefined search scopes for Spotlight queries The keys for this table are as follows:
Notes:
|
Signature | hs.spotlight.new() -> spotlightObject |
---|---|
Type | Constructor |
Description | Creates a new spotlightObject to use for Spotlight searches. Parameters:
Returns:
|
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:
Returns:
|
Signature | hs.spotlight:callbackMessages([messages]) -> table | spotlightObject |
---|---|
Type | Method |
Description | Get or specify the specific messages that should generate a callback. Parameters:
Returns:
Notes:
|
Signature | hs.spotlight:count() -> integer |
---|---|
Type | Method |
Description | Returns the number of results for the spotlightObject's query Parameters:
Returns:
Notes:
|
Signature | hs.spotlight:groupedResults() -> table |
---|---|
Type | Method |
Description | Returns the grouped results for a Spotlight query. Parameters:
Returns:
Notes:
|
Signature | hs.spotlight:groupingAttributes([attributes]) -> table | spotlightObject |
---|---|
Type | Method |
Description | Get or set the grouping attributes for the Spotlight query. Parameters:
Returns:
Notes:
|
Signature | hs.spotlight:isGathering() -> boolean |
---|---|
Type | Method |
Description | Returns a boolean specifying whether or not the query is in the active gathering phase. Parameters:
Returns:
Notes:
|
Signature | hs.spotlight:isRunning() -> boolean |
---|---|
Type | Method |
Description | Returns a boolean specifying if the query is active or inactive. Parameters:
Returns:
Notes:
|
Signature | hs.spotlight:queryString(query) -> spotlightObject |
---|---|
Type | Method |
Description | Specify the query string for the spotlightObject Parameters:
Returns:
Notes:
|
Signature | hs.spotlight:resultAtIndex(index) -> spotlightItemObject |
---|---|
Type | Method |
Description | Returns the spotlightItemObject at the specified index of the spotlightObject Parameters:
Returns:
Notes:
|
Signature | hs.spotlight:searchScopes([scope]) -> table | spotlightObject |
---|---|
Type | Method |
Description | Get or set the search scopes allowed for the Spotlight query. Parameters:
Returns:
Notes:
|
Signature | hs.spotlight:setCallback(fn | nil) -> spotlightObject |
---|---|
Type | Method |
Description | Set or remove the callback function for the Spotlight search object. Parameters:
Returns:
Notes:
|
Signature | hs.spotlight:sortDescriptors([attributes]) -> table | spotlightObject |
---|---|
Type | Method |
Description | Get or set the sorting preferences for the results of a Spotlight query. Parameters:
Returns:
Notes:
|
Signature | hs.spotlight:start() -> spotlightObject |
---|---|
Type | Method |
Description | Begin the gathering phase of a Spotlight query. Parameters:
Returns:
Notes:
|
Signature | hs.spotlight:stop() -> spotlightObject |
---|---|
Type | Method |
Description | Stop the Spotlight query. Parameters:
Returns:
Notes:
|
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:
Returns:
|
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:
Returns:
Notes:
|
Signature | hs.spotlight:valueLists() -> table |
---|---|
Type | Method |
Description | Returns the value list summaries for the Spotlight query Parameters:
Returns:
Notes:
|