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. |
Notes |
|
Source | extensions/spotlight/libspotlight.m line 877 |
Signature | hs.spotlight.definedSearchScopes[] |
---|---|
Type | Constant |
Description | A table of key-value pairs describing predefined search scopes for Spotlight queries |
Notes |
|
Source | extensions/spotlight/libspotlight.m line 847 |
Signature | hs.spotlight.new() -> spotlightObject |
---|---|
Type | Constructor |
Description | Creates a new spotlightObject to use for Spotlight searches. |
Parameters |
|
Returns |
|
Source | extensions/spotlight/libspotlight.m line 96 |
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 |
|
Source | extensions/spotlight/libspotlight.m line 112 |
Signature | hs.spotlight:callbackMessages([messages]) -> table | spotlightObject |
---|---|
Type | Method |
Description | Get or specify the specific messages that should generate a callback. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spotlight/spotlight.lua line 81 |
Signature | hs.spotlight:count() -> integer |
---|---|
Type | Method |
Description | Returns the number of results for the spotlightObject's query |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spotlight/libspotlight.m line 581 |
Signature | hs.spotlight:groupedResults() -> table |
---|---|
Type | Method |
Description | Returns the grouped results for a Spotlight query. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spotlight/libspotlight.m line 663 |
Signature | hs.spotlight:groupingAttributes([attributes]) -> table | spotlightObject |
---|---|
Type | Method |
Description | Get or set the grouping attributes for the Spotlight query. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spotlight/spotlight.lua line 106 |
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 |
|
Source | extensions/spotlight/libspotlight.m line 508 |
Signature | hs.spotlight:isRunning() -> boolean |
---|---|
Type | Method |
Description | Returns a boolean specifying if the query is active or inactive. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spotlight/libspotlight.m line 487 |
Signature | hs.spotlight:queryString(query) -> spotlightObject |
---|---|
Type | Method |
Description | Specify the query string for the spotlightObject |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spotlight/libspotlight.m line 529 |
Signature | hs.spotlight:resultAtIndex(index) -> spotlightItemObject |
---|---|
Type | Method |
Description | Returns the spotlightItemObject at the specified index of the spotlightObject |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spotlight/libspotlight.m line 605 |
Signature | hs.spotlight:searchScopes([scope]) -> table | spotlightObject |
---|---|
Type | Method |
Description | Get or set the search scopes allowed for the Spotlight query. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spotlight/spotlight.lua line 51 |
Signature | hs.spotlight:setCallback(fn) -> spotlightObject |
---|---|
Type | Method |
Description | Set or remove the callback function for the Spotlight search object. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spotlight/libspotlight.m line 198 |
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 |
|
Source | extensions/spotlight/spotlight.lua line 164 |
Signature | hs.spotlight:start() -> spotlightObject |
---|---|
Type | Method |
Description | Begin the gathering phase of a Spotlight query. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spotlight/libspotlight.m line 424 |
Signature | hs.spotlight:stop() -> spotlightObject |
---|---|
Type | Method |
Description | Stop the Spotlight query. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spotlight/libspotlight.m line 461 |
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 |
|
Source | extensions/spotlight/libspotlight.m line 291 |
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 |
|
Source | extensions/spotlight/spotlight.lua line 135 |
Signature | hs.spotlight:valueLists() -> table |
---|---|
Type | Method |
Description | Returns the value list summaries for the Spotlight query |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spotlight/libspotlight.m line 639 |