docs.json

[
  {
    "Constant" : [

    ],
    "submodules" : [

    ],
    "Function" : [
      {
        "doc" : "Callback for when the curl command finishes downloading the image.\n\nThis function is used internally by the RandomBackground Spoon.\nIt's intended to be used as a callback function for the 'hs.task' that downloads an image using the curl command.\n\nParameters:\n * exitCode - A number containing the exit code of the task.\n * stdOut - A string containing the standard output of the task.\n * stdErr - A string containing the standard error of the task.\n\nReturns:\n * None.\n\nNotes:\n * If the task finishes successfully (exitCode == 0), this function sets the downloaded image as the desktop background on the main screen and logs a success message.\n * If the task does not finish successfully, this function logs an error message along with the standard output and standard error of the task.",
        "desc" : "Callback for when the curl command finishes downloading the image.",
        "parameters" : [
          " * exitCode - A number containing the exit code of the task.",
          " * stdOut - A string containing the standard output of the task.",
          " * stdErr - A string containing the standard error of the task.",
          ""
        ],
        "stripped_doc" : [
          "Callback for when the curl command finishes downloading the image.",
          "",
          "This function is used internally by the RandomBackground Spoon.",
          "It's intended to be used as a callback function for the 'hs.task' that downloads an image using the curl command.",
          ""
        ],
        "notes" : [
          " * If the task finishes successfully (exitCode == 0), this function sets the downloaded image as the desktop background on the main screen and logs a success message.",
          " * If the task does not finish successfully, this function logs an error message along with the standard output and standard error of the task."
        ],
        "signature" : "RandomBackground.curl_download_callback(exitCode, stdOut, stdErr) -> nil",
        "type" : "Function",
        "returns" : [
          " * None.",
          ""
        ],
        "def" : "RandomBackground.curl_download_callback(exitCode, stdOut, stdErr) -> nil",
        "name" : "curl_download_callback"
      },
      {
        "doc" : "Extracts and returns the download link from a response body.\n\nThis function is used internally by the RandomBackground Spoon.\nIt's intended to be used to parse the response body from an Unsplash API call and extract the image download link.\n\nParameters:\n * response_body - A string containing the response body, expected to be in JSON format.\n\nReturns:\n * If successful, a string containing the download link.\n * If unsuccessful (due to the response body not being valid JSON or not containing a `links.download` field), it returns `nil`.\n\nNotes:\n * This function uses the protected call (`pcall`) function in Lua to handle potential errors when decoding the JSON response body.\n * If the decoding fails (due to invalid JSON, for example), it will return `nil`.",
        "desc" : "Extracts and returns the download link from a response body.",
        "parameters" : [
          " * response_body - A string containing the response body, expected to be in JSON format.",
          ""
        ],
        "stripped_doc" : [
          "Extracts and returns the download link from a response body.",
          "",
          "This function is used internally by the RandomBackground Spoon.",
          "It's intended to be used to parse the response body from an Unsplash API call and extract the image download link.",
          ""
        ],
        "notes" : [
          " * This function uses the protected call (`pcall`) function in Lua to handle potential errors when decoding the JSON response body.",
          " * If the decoding fails (due to invalid JSON, for example), it will return `nil`."
        ],
        "signature" : "RandomBackground.get_download_link(response_body)",
        "type" : "Function",
        "returns" : [
          " * If successful, a string containing the download link.",
          " * If unsuccessful (due to the response body not being valid JSON or not containing a `links.download` field), it returns `nil`.",
          ""
        ],
        "def" : "RandomBackground.get_download_link(response_body)",
        "name" : "get_download_link"
      },
      {
        "doc" : "Downloads an image from a given URL and stores it in the system's Trash folder.\n\nThis function is intended to be used internally by the RandomBackground Spoon.\nIt is called by the `set_new_background` function once a suitable image URL has been fetched from the Unsplash API.\nPrior to the download, it cancels any previous download task.\nIt then sets the download path to the system's Trash folder and initiates the download task using `hs.task.new`.\n\nParameters:\n * image_url - A string containing the URL of the image to be downloaded.\n\nReturns:\n * None\n\nNotes:\n * This function will log information about its progress, including the URL of the image being downloaded.\n * The downloaded image file is saved with a hashed name to prevent naming conflicts.\n * The image is saved in the Trash folder as it is intended to be a temp file used only for setting the wallpaper.",
        "desc" : "Downloads an image from a given URL and stores it in the system's Trash folder.",
        "parameters" : [
          " * image_url - A string containing the URL of the image to be downloaded.",
          ""
        ],
        "stripped_doc" : [
          "Downloads an image from a given URL and stores it in the system's Trash folder.",
          "",
          "This function is intended to be used internally by the RandomBackground Spoon.",
          "It is called by the `set_new_background` function once a suitable image URL has been fetched from the Unsplash API.",
          "Prior to the download, it cancels any previous download task.",
          "It then sets the download path to the system's Trash folder and initiates the download task using `hs.task.new`.",
          ""
        ],
        "notes" : [
          " * This function will log information about its progress, including the URL of the image being downloaded.",
          " * The downloaded image file is saved with a hashed name to prevent naming conflicts.",
          " * The image is saved in the Trash folder as it is intended to be a temp file used only for setting the wallpaper."
        ],
        "signature" : "RandomBackground.download_img_request(image_url)",
        "type" : "Function",
        "returns" : [
          " * None",
          ""
        ],
        "def" : "RandomBackground.download_img_request(image_url)",
        "name" : "download_img_request"
      },
      {
        "doc" : "Sets a new background for the system using a randomly fetched image from Unsplash.\n\nThis function is intended to be used internally by the RandomBackground Spoon.\nIt is triggered by a timer started in the `start()` method.\nIt sends an asynchronous GET request to the Unsplash API to fetch a random landscape image.\nIf the request is successful, it proceeds to download and set the image as the background.\n\nParameters:\n * None\n\nReturns:\n * None\n\nNotes:\n * This function will log information about its progress, including whether the API request and image parsing were successful,\n and the remaining rate limit for the Unsplash API.",
        "desc" : "Sets a new background for the system using a randomly fetched image from Unsplash.",
        "parameters" : [
          " * None",
          ""
        ],
        "stripped_doc" : [
          "Sets a new background for the system using a randomly fetched image from Unsplash.",
          "",
          "This function is intended to be used internally by the RandomBackground Spoon.",
          "It is triggered by a timer started in the `start()` method.",
          "It sends an asynchronous GET request to the Unsplash API to fetch a random landscape image.",
          "If the request is successful, it proceeds to download and set the image as the background.",
          ""
        ],
        "notes" : [
          " * This function will log information about its progress, including whether the API request and image parsing were successful,",
          " and the remaining rate limit for the Unsplash API."
        ],
        "signature" : "RandomBackground.set_new_background()",
        "type" : "Function",
        "returns" : [
          " * None",
          ""
        ],
        "def" : "RandomBackground.set_new_background()",
        "name" : "set_new_background"
      }
    ],
    "Variable" : [

    ],
    "stripped_doc" : [

    ],
    "Deprecated" : [

    ],
    "type" : "Module",
    "desc" : "Use Unsplash API to set a random background image for your desktop",
    "Constructor" : [

    ],
    "doc" : "Use Unsplash API to set a random background image for your desktop\n\nDownload: [https:\/\/github.com\/roeeyn\/RandomBackground.spoon\/releases\/download\/v1.1.0\/RandomBackground.spoon.zip](https:\/\/github.com\/roeeyn\/RandomBackground.spoon\/releases\/download\/v1.1.0\/RandomBackground.spoon.zip)",
    "items" : [
      {
        "doc" : "Callback for when the curl command finishes downloading the image.\n\nThis function is used internally by the RandomBackground Spoon.\nIt's intended to be used as a callback function for the 'hs.task' that downloads an image using the curl command.\n\nParameters:\n * exitCode - A number containing the exit code of the task.\n * stdOut - A string containing the standard output of the task.\n * stdErr - A string containing the standard error of the task.\n\nReturns:\n * None.\n\nNotes:\n * If the task finishes successfully (exitCode == 0), this function sets the downloaded image as the desktop background on the main screen and logs a success message.\n * If the task does not finish successfully, this function logs an error message along with the standard output and standard error of the task.",
        "desc" : "Callback for when the curl command finishes downloading the image.",
        "parameters" : [
          " * exitCode - A number containing the exit code of the task.",
          " * stdOut - A string containing the standard output of the task.",
          " * stdErr - A string containing the standard error of the task.",
          ""
        ],
        "stripped_doc" : [
          "Callback for when the curl command finishes downloading the image.",
          "",
          "This function is used internally by the RandomBackground Spoon.",
          "It's intended to be used as a callback function for the 'hs.task' that downloads an image using the curl command.",
          ""
        ],
        "notes" : [
          " * If the task finishes successfully (exitCode == 0), this function sets the downloaded image as the desktop background on the main screen and logs a success message.",
          " * If the task does not finish successfully, this function logs an error message along with the standard output and standard error of the task."
        ],
        "signature" : "RandomBackground.curl_download_callback(exitCode, stdOut, stdErr) -> nil",
        "type" : "Function",
        "returns" : [
          " * None.",
          ""
        ],
        "def" : "RandomBackground.curl_download_callback(exitCode, stdOut, stdErr) -> nil",
        "name" : "curl_download_callback"
      },
      {
        "doc" : "Downloads an image from a given URL and stores it in the system's Trash folder.\n\nThis function is intended to be used internally by the RandomBackground Spoon.\nIt is called by the `set_new_background` function once a suitable image URL has been fetched from the Unsplash API.\nPrior to the download, it cancels any previous download task.\nIt then sets the download path to the system's Trash folder and initiates the download task using `hs.task.new`.\n\nParameters:\n * image_url - A string containing the URL of the image to be downloaded.\n\nReturns:\n * None\n\nNotes:\n * This function will log information about its progress, including the URL of the image being downloaded.\n * The downloaded image file is saved with a hashed name to prevent naming conflicts.\n * The image is saved in the Trash folder as it is intended to be a temp file used only for setting the wallpaper.",
        "desc" : "Downloads an image from a given URL and stores it in the system's Trash folder.",
        "parameters" : [
          " * image_url - A string containing the URL of the image to be downloaded.",
          ""
        ],
        "stripped_doc" : [
          "Downloads an image from a given URL and stores it in the system's Trash folder.",
          "",
          "This function is intended to be used internally by the RandomBackground Spoon.",
          "It is called by the `set_new_background` function once a suitable image URL has been fetched from the Unsplash API.",
          "Prior to the download, it cancels any previous download task.",
          "It then sets the download path to the system's Trash folder and initiates the download task using `hs.task.new`.",
          ""
        ],
        "notes" : [
          " * This function will log information about its progress, including the URL of the image being downloaded.",
          " * The downloaded image file is saved with a hashed name to prevent naming conflicts.",
          " * The image is saved in the Trash folder as it is intended to be a temp file used only for setting the wallpaper."
        ],
        "signature" : "RandomBackground.download_img_request(image_url)",
        "type" : "Function",
        "returns" : [
          " * None",
          ""
        ],
        "def" : "RandomBackground.download_img_request(image_url)",
        "name" : "download_img_request"
      },
      {
        "doc" : "Extracts and returns the download link from a response body.\n\nThis function is used internally by the RandomBackground Spoon.\nIt's intended to be used to parse the response body from an Unsplash API call and extract the image download link.\n\nParameters:\n * response_body - A string containing the response body, expected to be in JSON format.\n\nReturns:\n * If successful, a string containing the download link.\n * If unsuccessful (due to the response body not being valid JSON or not containing a `links.download` field), it returns `nil`.\n\nNotes:\n * This function uses the protected call (`pcall`) function in Lua to handle potential errors when decoding the JSON response body.\n * If the decoding fails (due to invalid JSON, for example), it will return `nil`.",
        "desc" : "Extracts and returns the download link from a response body.",
        "parameters" : [
          " * response_body - A string containing the response body, expected to be in JSON format.",
          ""
        ],
        "stripped_doc" : [
          "Extracts and returns the download link from a response body.",
          "",
          "This function is used internally by the RandomBackground Spoon.",
          "It's intended to be used to parse the response body from an Unsplash API call and extract the image download link.",
          ""
        ],
        "notes" : [
          " * This function uses the protected call (`pcall`) function in Lua to handle potential errors when decoding the JSON response body.",
          " * If the decoding fails (due to invalid JSON, for example), it will return `nil`."
        ],
        "signature" : "RandomBackground.get_download_link(response_body)",
        "type" : "Function",
        "returns" : [
          " * If successful, a string containing the download link.",
          " * If unsuccessful (due to the response body not being valid JSON or not containing a `links.download` field), it returns `nil`.",
          ""
        ],
        "def" : "RandomBackground.get_download_link(response_body)",
        "name" : "get_download_link"
      },
      {
        "doc" : "Sets a new background for the system using a randomly fetched image from Unsplash.\n\nThis function is intended to be used internally by the RandomBackground Spoon.\nIt is triggered by a timer started in the `start()` method.\nIt sends an asynchronous GET request to the Unsplash API to fetch a random landscape image.\nIf the request is successful, it proceeds to download and set the image as the background.\n\nParameters:\n * None\n\nReturns:\n * None\n\nNotes:\n * This function will log information about its progress, including whether the API request and image parsing were successful,\n and the remaining rate limit for the Unsplash API.",
        "desc" : "Sets a new background for the system using a randomly fetched image from Unsplash.",
        "parameters" : [
          " * None",
          ""
        ],
        "stripped_doc" : [
          "Sets a new background for the system using a randomly fetched image from Unsplash.",
          "",
          "This function is intended to be used internally by the RandomBackground Spoon.",
          "It is triggered by a timer started in the `start()` method.",
          "It sends an asynchronous GET request to the Unsplash API to fetch a random landscape image.",
          "If the request is successful, it proceeds to download and set the image as the background.",
          ""
        ],
        "notes" : [
          " * This function will log information about its progress, including whether the API request and image parsing were successful,",
          " and the remaining rate limit for the Unsplash API."
        ],
        "signature" : "RandomBackground.set_new_background()",
        "type" : "Function",
        "returns" : [
          " * None",
          ""
        ],
        "def" : "RandomBackground.set_new_background()",
        "name" : "set_new_background"
      },
      {
        "doc" : "Initializes the RandomBackground Spoon.\n\nThis function is called automatically by Hammerspoon during the creation of the Spoon object.\nThe initialization involves preparing resources that would be needed by the Spoon for later use.\nNote: It is not recommended to start timers, watchers, or map hotkeys in this method.\n\nThe init method does not start the functionality of the RandomBackground spoon,\nas the necessary API key from the config table is not accessible until the setup is completed (i.e., the start method is called).\n\nExample usage:\nspoon.RandomBackground:init()\n\nReturns:\n * None\n\nNotes:\n * The Hammerspoon user has the option to override the automatic calling of this method.\n * For more details, see: https:\/\/github.com\/Hammerspoon\/hammerspoon\/blob\/master\/SPOONS.md#how-do-i-create-a-spoon",
        "desc" : "Initializes the RandomBackground Spoon.",
        "parameters" : [

        ],
        "stripped_doc" : [
          "Initializes the RandomBackground Spoon.",
          "",
          "This function is called automatically by Hammerspoon during the creation of the Spoon object.",
          "The initialization involves preparing resources that would be needed by the Spoon for later use.",
          "Note: It is not recommended to start timers, watchers, or map hotkeys in this method.",
          "",
          "The init method does not start the functionality of the RandomBackground spoon,",
          "as the necessary API key from the config table is not accessible until the setup is completed (i.e., the start method is called).",
          "",
          "Example usage:",
          "spoon.RandomBackground:init()",
          ""
        ],
        "notes" : [
          " * The Hammerspoon user has the option to override the automatic calling of this method.",
          " * For more details, see: https:\/\/github.com\/Hammerspoon\/hammerspoon\/blob\/master\/SPOONS.md#how-do-i-create-a-spoon"
        ],
        "signature" : "RandomBackground:init()",
        "type" : "Method",
        "returns" : [
          " * None",
          ""
        ],
        "def" : "RandomBackground:init()",
        "name" : "init"
      },
      {
        "doc" : "This method starts the RandomBackground spoon. It sets the URL for the Unsplash API with the provided API key.\nand initiates the timer to change the desktop background.\n\nParameters:\n * None\n\nReturns:\n * `false` if the Unsplash API key is not provided or is an empty string.\n In this case, the method also logs an error message and stops the execution of the spoon.\n * No explicit return (i.e., `nil`) in case of successful operation.\n\nNotes:\n * The Unsplash API key must be provided for this method to start the spoon successfully.\n * If the key is not provided, the method will not start the spoon and will return `false`.\n * If there's no existing timer, it creates a new one that triggers the `set_new_background` method\n every `UPDATE_INTERVAL_SECONDS` seconds.\n * The first trigger happens after a 5-second delay.\n * If a timer already exists, it simply restarts it.\n\nExample usage:\nspoon.RandomBackground:start()",
        "desc" : "",
        "parameters" : [
          " * None",
          ""
        ],
        "stripped_doc" : [
          "This method starts the RandomBackground spoon. It sets the URL for the Unsplash API with the provided API key.",
          "and initiates the timer to change the desktop background.",
          ""
        ],
        "notes" : [
          " * The Unsplash API key must be provided for this method to start the spoon successfully.",
          " * If the key is not provided, the method will not start the spoon and will return `false`.",
          " * If there's no existing timer, it creates a new one that triggers the `set_new_background` method",
          " every `UPDATE_INTERVAL_SECONDS` seconds.",
          " * The first trigger happens after a 5-second delay.",
          " * If a timer already exists, it simply restarts it.",
          "",
          "Example usage:",
          "spoon.RandomBackground:start()"
        ],
        "signature" : "RandomBackground:start()",
        "type" : "Method",
        "returns" : [
          " * `false` if the Unsplash API key is not provided or is an empty string.",
          " In this case, the method also logs an error message and stops the execution of the spoon.",
          " * No explicit return (i.e., `nil`) in case of successful operation.",
          ""
        ],
        "def" : "RandomBackground:start()",
        "name" : "start"
      },
      {
        "doc" : "Stops the RandomBackground Spoon.\n\nThis function is used to stop the functionality of the RandomBackground Spoon.\nIf a timer has been started by the Spoon, it is stopped when this method is called.\n\nExample usage:\nspoon.RandomBackground:stop()\n\nParameters:\n * None\n\nReturns:\n * None\n\nNotes:\n * This method stops the RandomBackground Spoon and any associated timers.",
        "desc" : "Stops the RandomBackground Spoon.",
        "parameters" : [
          " * None",
          ""
        ],
        "stripped_doc" : [
          "Stops the RandomBackground Spoon.",
          "",
          "This function is used to stop the functionality of the RandomBackground Spoon.",
          "If a timer has been started by the Spoon, it is stopped when this method is called.",
          "",
          "Example usage:",
          "spoon.RandomBackground:stop()",
          ""
        ],
        "notes" : [
          " * This method stops the RandomBackground Spoon and any associated timers."
        ],
        "signature" : "RandomBackground:stop()",
        "type" : "Method",
        "returns" : [
          " * None",
          ""
        ],
        "def" : "RandomBackground:stop()",
        "name" : "stop"
      }
    ],
    "Command" : [

    ],
    "Field" : [

    ],
    "Method" : [
      {
        "doc" : "This method starts the RandomBackground spoon. It sets the URL for the Unsplash API with the provided API key.\nand initiates the timer to change the desktop background.\n\nParameters:\n * None\n\nReturns:\n * `false` if the Unsplash API key is not provided or is an empty string.\n In this case, the method also logs an error message and stops the execution of the spoon.\n * No explicit return (i.e., `nil`) in case of successful operation.\n\nNotes:\n * The Unsplash API key must be provided for this method to start the spoon successfully.\n * If the key is not provided, the method will not start the spoon and will return `false`.\n * If there's no existing timer, it creates a new one that triggers the `set_new_background` method\n every `UPDATE_INTERVAL_SECONDS` seconds.\n * The first trigger happens after a 5-second delay.\n * If a timer already exists, it simply restarts it.\n\nExample usage:\nspoon.RandomBackground:start()",
        "desc" : "",
        "parameters" : [
          " * None",
          ""
        ],
        "stripped_doc" : [
          "This method starts the RandomBackground spoon. It sets the URL for the Unsplash API with the provided API key.",
          "and initiates the timer to change the desktop background.",
          ""
        ],
        "notes" : [
          " * The Unsplash API key must be provided for this method to start the spoon successfully.",
          " * If the key is not provided, the method will not start the spoon and will return `false`.",
          " * If there's no existing timer, it creates a new one that triggers the `set_new_background` method",
          " every `UPDATE_INTERVAL_SECONDS` seconds.",
          " * The first trigger happens after a 5-second delay.",
          " * If a timer already exists, it simply restarts it.",
          "",
          "Example usage:",
          "spoon.RandomBackground:start()"
        ],
        "signature" : "RandomBackground:start()",
        "type" : "Method",
        "returns" : [
          " * `false` if the Unsplash API key is not provided or is an empty string.",
          " In this case, the method also logs an error message and stops the execution of the spoon.",
          " * No explicit return (i.e., `nil`) in case of successful operation.",
          ""
        ],
        "def" : "RandomBackground:start()",
        "name" : "start"
      },
      {
        "doc" : "Stops the RandomBackground Spoon.\n\nThis function is used to stop the functionality of the RandomBackground Spoon.\nIf a timer has been started by the Spoon, it is stopped when this method is called.\n\nExample usage:\nspoon.RandomBackground:stop()\n\nParameters:\n * None\n\nReturns:\n * None\n\nNotes:\n * This method stops the RandomBackground Spoon and any associated timers.",
        "desc" : "Stops the RandomBackground Spoon.",
        "parameters" : [
          " * None",
          ""
        ],
        "stripped_doc" : [
          "Stops the RandomBackground Spoon.",
          "",
          "This function is used to stop the functionality of the RandomBackground Spoon.",
          "If a timer has been started by the Spoon, it is stopped when this method is called.",
          "",
          "Example usage:",
          "spoon.RandomBackground:stop()",
          ""
        ],
        "notes" : [
          " * This method stops the RandomBackground Spoon and any associated timers."
        ],
        "signature" : "RandomBackground:stop()",
        "type" : "Method",
        "returns" : [
          " * None",
          ""
        ],
        "def" : "RandomBackground:stop()",
        "name" : "stop"
      },
      {
        "doc" : "Initializes the RandomBackground Spoon.\n\nThis function is called automatically by Hammerspoon during the creation of the Spoon object.\nThe initialization involves preparing resources that would be needed by the Spoon for later use.\nNote: It is not recommended to start timers, watchers, or map hotkeys in this method.\n\nThe init method does not start the functionality of the RandomBackground spoon,\nas the necessary API key from the config table is not accessible until the setup is completed (i.e., the start method is called).\n\nExample usage:\nspoon.RandomBackground:init()\n\nReturns:\n * None\n\nNotes:\n * The Hammerspoon user has the option to override the automatic calling of this method.\n * For more details, see: https:\/\/github.com\/Hammerspoon\/hammerspoon\/blob\/master\/SPOONS.md#how-do-i-create-a-spoon",
        "desc" : "Initializes the RandomBackground Spoon.",
        "parameters" : [

        ],
        "stripped_doc" : [
          "Initializes the RandomBackground Spoon.",
          "",
          "This function is called automatically by Hammerspoon during the creation of the Spoon object.",
          "The initialization involves preparing resources that would be needed by the Spoon for later use.",
          "Note: It is not recommended to start timers, watchers, or map hotkeys in this method.",
          "",
          "The init method does not start the functionality of the RandomBackground spoon,",
          "as the necessary API key from the config table is not accessible until the setup is completed (i.e., the start method is called).",
          "",
          "Example usage:",
          "spoon.RandomBackground:init()",
          ""
        ],
        "notes" : [
          " * The Hammerspoon user has the option to override the automatic calling of this method.",
          " * For more details, see: https:\/\/github.com\/Hammerspoon\/hammerspoon\/blob\/master\/SPOONS.md#how-do-i-create-a-spoon"
        ],
        "signature" : "RandomBackground:init()",
        "type" : "Method",
        "returns" : [
          " * None",
          ""
        ],
        "def" : "RandomBackground:init()",
        "name" : "init"
      }
    ],
    "name" : "RandomBackground"
  }
]