diff --git a/.gitignore b/.gitignore index 25a4781..426979f 100644 --- a/.gitignore +++ b/.gitignore @@ -55,3 +55,4 @@ config/zed/settings.json *.tmp.* config/op/plugins/gh.json config/fish/fish_variables.* +config/karabiner/automatic_backups diff --git a/base/hammerspoon/.luacheckrc b/base/hammerspoon/.luacheckrc new file mode 100644 index 0000000..6a19a97 --- /dev/null +++ b/base/hammerspoon/.luacheckrc @@ -0,0 +1,15 @@ +-- +-- These globals can be set and accessed: +-- +globals = { + "rawrequire", +} + +-- +-- These globals can only be accessed: +-- +read_globals = { + "hs", + "ls", + "spoon", +} diff --git a/base/hammerspoon/generate-hammerspoon-types.py b/base/hammerspoon/generate-hammerspoon-types.py new file mode 100755 index 0000000..b32f3f8 --- /dev/null +++ b/base/hammerspoon/generate-hammerspoon-types.py @@ -0,0 +1,1010 @@ +#!/usr/bin/env python3 +""" +Generate Hammerspoon EmmyLua type definitions from official documentation. + +This script fetches all API documentation pages from hammerspoon.org, +parses the HTML structure, and generates comprehensive EmmyLua annotations. + +Requirements: Python 3.11+ (no external dependencies) +Output: hammerspoon.types.lua +""" + +import re +import urllib.request +from html.parser import HTMLParser +from typing import Optional +from collections import defaultdict + + +class HammerspoonDocParser(HTMLParser): + """Parse Hammerspoon HTML documentation to extract API definitions.""" + + def __init__(self): + super().__init__() + self.modules = [] + self.in_module_list = False + self.current_tag = None + self.current_attrs = {} + + def handle_starttag(self, tag, attrs): + self.current_tag = tag + self.current_attrs = dict(attrs) + + # Find module links in the documentation index + if tag == "a" and self.current_attrs.get("href", "").endswith(".html"): + href = self.current_attrs["href"] + # Filter out non-module links (index, tutorials, etc.) + if not any( + x in href for x in ["index.html", "getting_started", "tutorials"] + ): + self.modules.append(href) + + +class ModuleAPIParser(HTMLParser): + """Parse individual module documentation to extract API items.""" + + def __init__(self, module_name): + super().__init__() + self.module_name = module_name + self.api_items = [] + self.current_item = {} + self.in_h5 = False + self.in_td = False + self.in_th = False + self.current_th = None + self.current_td_content = [] + self.in_api_section = False + self.current_tag_stack = [] + self.in_li = False + self.current_li_content = [] + self.current_section = None # Track current section (API Overview, etc.) + self.in_h3 = False # For section headers + self.deprecation_info = {} # Store deprecation notices + + def handle_starttag(self, tag, attrs): + self.current_tag_stack.append(tag) + attrs_dict = dict(attrs) + + if tag == "h3": + self.in_h3 = True + + elif tag == "h5": + self.in_h5 = True + self.current_item = {"module": self.module_name} + + elif tag == "th": + self.in_th = True + self.current_th = None + + elif tag == "td": + self.in_td = True + self.current_td_content = [] + + elif tag == "li" and self.in_td: + self.in_li = True + self.current_li_content = [] + + def handle_endtag(self, tag): + if self.current_tag_stack: + self.current_tag_stack.pop() + + if tag == "h3": + self.in_h3 = False + + elif tag == "h5": + self.in_h5 = False + + elif tag == "th": + self.in_th = False + + elif tag == "li" and self.in_li: + self.in_li = False + # Store list item content + li_text = " ".join(self.current_li_content).strip() + if li_text: + self.current_td_content.append(li_text) + self.current_li_content = [] + + elif tag == "td": + self.in_td = False + if self.current_th and self.current_item: + content = "\n".join(self.current_td_content).strip() + self.current_item[self.current_th.lower()] = content + self.current_td_content = [] + + elif tag == "table": + # End of current API item's table + if self.current_item and "name" in self.current_item: + # Store current section context + if self.current_section: + self.current_item["section"] = self.current_section + self.api_items.append(self.current_item.copy()) + self.current_item = {} + + def handle_data(self, data): + data = data.strip() + if not data: + return + + if self.in_h3: + # Track section headers (e.g., "API Overview", "Fields") + self.current_section = data + + elif self.in_h5: + self.current_item["name"] = data + + elif self.in_th: + self.current_th = data + + elif self.in_li: + self.current_li_content.append(data) + + elif self.in_td and not self.in_li: + # Only capture non-list text (descriptions, etc.) + self.current_td_content.append(data) + + +def fetch_url(url: str) -> str: + """Fetch content from URL with error handling.""" + try: + with urllib.request.urlopen(url, timeout=10) as response: + return response.read().decode("utf-8") + except Exception as e: + print(f"Error fetching {url}: {e}") + return "" + + +def get_all_modules(base_url: str) -> list[str]: + """Fetch the main index and extract all module URLs.""" + print("Fetching module list from documentation index...") + index_url = f"{base_url}/docs/index.html" + html = fetch_url(index_url) + + parser = HammerspoonDocParser() + parser.feed(html) + + # Remove duplicates and sort + modules = sorted(set(parser.modules)) + print(f"Found {len(modules)} modules") + return modules + + +def parse_module_documentation(base_url: str, module_path: str) -> list[dict]: + """Parse a single module's documentation page.""" + module_name = module_path.replace(".html", "") + url = f"{base_url}/docs/{module_path}" + + print(f" Parsing {module_name}...") + html = fetch_url(url) + if not html: + return [] + + parser = ModuleAPIParser(module_name) + parser.feed(html) + + return parser.api_items + + +def make_union_type(types: list[str]) -> str: + """Create a clean union type string, removing duplicates while preserving order.""" + # Remove duplicates while preserving order + seen = set() + unique_types = [] + for t in types: + t = t.strip() + if t and t not in seen: + seen.add(t) + unique_types.append(t) + + if not unique_types: + return "any" + elif len(unique_types) == 1: + return unique_types[0] + else: + return "|".join(unique_types) + + +def extract_type_from_description(description: str) -> str: + """ + Extract type information from natural language description. + Handles unions, hs.* types, callbacks, and table structures. + """ + desc_lower = description.lower() + + # Check for explicit "or nil" pattern + has_nil = " or nil" in desc_lower or "optional" in desc_lower or "may be nil" in desc_lower + + # Check if description explicitly starts with basic type indicators + # These take precedence over module names mentioned later + starts_with_table = re.match(r"^\s*(?:this |a |an |the )?table\b", desc_lower) + starts_with_string = re.match(r"^\s*(?:this |a |an |the )?string\b", desc_lower) + starts_with_number = re.match(r"^\s*(?:this |a |an |the )?number\b", desc_lower) + starts_with_boolean = re.match(r"^\s*(?:this |a |an |the )?boolean\b", desc_lower) + starts_with_function = re.match(r"^\s*(?:this |a |an |the )?function\b", desc_lower) + + # Extract all hs.* types (remove duplicates) + # Match hs.module.submodule but not trailing dots + hs_types = re.findall(r"\bhs\.[a-zA-Z0-9_]+(?:\.[a-zA-Z0-9_]+)*(?:\s+object)?", description) + # Deduplicate while preserving order + hs_types_unique = [] + seen = set() + for ht in hs_types: + # Clean up " object" suffix + ht = re.sub(r"\s+object$", "", ht) + # Remove trailing dots (in case any slipped through) + ht = ht.rstrip(".") + if ht and ht not in seen: + seen.add(ht) + hs_types_unique.append(ht) + hs_types = hs_types_unique + + # Look for union patterns like "string, number, or table" + union_match = re.search(r"(?:a |an )?(\w+)(?:,\s+(\w+))*(?:,?\s+or\s+(\w+))", desc_lower) + + # Look for callback signatures + # Patterns: "function that receives", "callback with", "function(param1, param2)" + is_callback = any(keyword in desc_lower for keyword in [ + "function that", "callback", "function which", "called with", + "receives a function", "function to" + ]) + + # Look for table structure hints + # Patterns: "table containing", "table with keys", "table of", "list of", "array of" + is_table = "table" in desc_lower + table_of_match = re.search(r"table of (\w+)s?", desc_lower) + + # Check for array/list patterns + list_match = re.search(r"(?:list|array) of (\w+)", desc_lower) + # Pattern: "returns X devices/objects/items" + returns_list_match = re.search(r"returns? (?:a list of |an array of |)?(\w+) (?:devices|objects|items)", desc_lower) + + # Determine the base type + base_type = "any" + + # Prioritize explicit type indicators at start of description + if starts_with_table: + base_type = "table" + elif starts_with_string: + base_type = "string" + elif starts_with_number: + base_type = "number" + elif starts_with_boolean: + base_type = "boolean" + elif starts_with_function: + base_type = "function" + elif hs_types: + # Create union from unique hs types (only if not explicitly typed above) + base_type = make_union_type(hs_types) + elif is_callback: + base_type = "function" + elif list_match or returns_list_match: + # Array pattern: "list of X" or "returns X devices" + match = list_match or returns_list_match + item_type = match.group(1) + + # Map common type names + type_map = { + "audiodevice": "hs.audiodevice", + "device": "hs.audiodevice", + "window": "hs.window", + "screen": "hs.screen", + "application": "hs.application", + "string": "string", + "number": "number", + "boolean": "boolean", + "table": "table", + } + + lua_type = type_map.get(item_type.lower(), item_type) + base_type = f"{lua_type}[]" + elif table_of_match: + # Array-like table: table of strings -> string[] + item_type = table_of_match.group(1) + if item_type in ["string", "number", "boolean", "table"]: + base_type = f"{item_type}[]" + else: + base_type = "table" + elif union_match: + # Handle union types from description + types_found = [t for t in union_match.groups() if t] + # Map common words to Lua types + type_map = { + "string": "string", "number": "number", "integer": "number", + "boolean": "boolean", "bool": "boolean", "table": "table", + "function": "function", "userdata": "any" + } + lua_types = [type_map.get(t, t) for t in types_found if t in type_map] + base_type = make_union_type(lua_types) + elif is_table: + base_type = "table" + else: + # Fall back to keyword detection + if "boolean" in desc_lower or "true or false" in desc_lower: + base_type = "boolean" + elif "string" in desc_lower: + base_type = "string" + elif "number" in desc_lower or "integer" in desc_lower: + base_type = "number" + elif "function" in desc_lower: + base_type = "function" + + # Add nil if optional + if has_nil and base_type != "any" and "|nil" not in base_type: + base_type = f"{base_type}|nil" + + return base_type + + +def infer_type_from_param_name(param_name: str) -> str: + """ + Infer parameter type from naming conventions. + Returns "any" if no convention matches. + """ + name_lower = param_name.lower() + + # String indicators + if (name_lower.endswith("id") or name_lower.endswith("uuid") or + name_lower.endswith("uid") or name_lower.endswith("name") or + name_lower.endswith("path") or name_lower.endswith("text") or + name_lower.endswith("string") or name_lower.endswith("pattern") or + name_lower.endswith("title") or name_lower.endswith("message") or + name_lower.endswith("url") or name_lower.endswith("uri") or + name_lower.endswith("key") or name_lower.endswith("command")): + return "string" + + # Boolean indicators (common prefixes and specific names) + if (name_lower.startswith("with") or name_lower.startswith("is") or + name_lower.startswith("has") or name_lower.startswith("should") or + name_lower.startswith("can") or name_lower.startswith("will") or + name_lower.startswith("enable") or name_lower.startswith("disable") or + name_lower.startswith("show") or name_lower.startswith("hide") or + name_lower.startswith("allow") or name_lower.startswith("bring") or + name_lower == "state" or name_lower == "append" or + name_lower == "bringtofront" or "tofront" in name_lower): + return "boolean" + + # Table/Array indicators + if (name_lower in ["array", "list", "items", "elements", "args", "arguments"] or + name_lower.endswith("array") or name_lower.endswith("list")): + return "table" + + # Function indicators + if (param_name in ["fn", "func", "callback", "handler", "listener", + "predicate", "filter", "mapper", "reducer"]): + return "function" + + # Number indicators + if (name_lower.endswith("count") or name_lower.endswith("index") or + name_lower.endswith("size") or name_lower.endswith("width") or + name_lower.endswith("height") or name_lower.endswith("length") or + name_lower.endswith("duration") or name_lower.endswith("delay") or + name_lower.endswith("timeout") or name_lower.endswith("interval") or + name_lower.endswith("x") or name_lower.endswith("y") or + name_lower.endswith("position") or name_lower.endswith("offset")): + return "number" + + return "any" + + +def parse_parameter_descriptions(param_text: str) -> dict[str, str]: + """ + Parse parameter descriptions to extract types. + Supports unions, callbacks, hs.* types, and table structures. + Falls back to naming conventions if description parsing fails. + + Format: "paramName - description with type information" + Returns: {param_name: type} + """ + param_types = {} + + if not param_text or param_text == "None": + return param_types + + # Split by lines (each parameter is on its own line) + for line in param_text.split("\n"): + line = line.strip() + if not line or line.lower() == "none": + continue + + # Extract parameter name (everything before first dash or colon) + match = re.match(r"^([a-zA-Z0-9_]+)\s*[-:]", line) + if not match: + continue + + param_name = match.group(1) + + # Extract description (everything after the dash/colon) + desc_match = re.search(r"[-:]\s*(.+)$", line) + description = desc_match.group(1) if desc_match else line + + # Use enhanced type extraction + param_type = extract_type_from_description(description) + + # If type extraction failed (returned "any"), try naming conventions + if param_type == "any": + param_type = infer_type_from_param_name(param_name) + + param_types[param_name] = param_type + + return param_types + + +def parse_signature(signature: str) -> tuple[str, list[tuple[str, str]], list[str]]: + """ + Parse function signature to extract name, parameters, and return types. + + Hammerspoon uses format: func(req1, req2[, opt1[, opt2]]) -> return1[, return2] + where nested brackets indicate optional parameters. + + Returns: (function_name, [(param_name, param_type)], [return_types]) + """ + signature = signature.strip() + + # Extract function name (everything before opening parenthesis) + paren_pos = signature.find("(") + if paren_pos == -1: + return "", [], "any" + + func_name = signature[:paren_pos].strip() + + # Extract parameters from parentheses - find matching closing paren + paren_count = 0 + param_start = paren_pos + 1 + param_end = param_start + + for i in range(paren_pos + 1, len(signature)): + if signature[i] == "(": + paren_count += 1 + elif signature[i] == ")": + if paren_count == 0: + param_end = i + break + paren_count -= 1 + + param_str = signature[param_start:param_end] if param_end > param_start else "" + + # Parse parameters + params = [] + if param_str and param_str.strip(): + # Remove all square brackets to get clean parameter list + # Then track which ones were optional based on bracket positions + + # First, find where optional params start (first occurrence of [,) + optional_start = -1 + for i in range(len(param_str)): + if i > 0 and param_str[i-1:i+1] == "[,": + optional_start = i + break + + # Remove all brackets to get clean param string + clean_str = param_str.replace("[", "").replace("]", "") + + # Split by comma to get individual parameters + param_parts = [p.strip() for p in clean_str.split(",") if p.strip()] + + # Determine which params are optional + # Count how many commas appear before the optional marker + required_count = 0 + if optional_start > 0: + required_count = param_str[:optional_start].count(",") + 1 + else: + required_count = len(param_parts) + + for idx, param_name in enumerate(param_parts): + is_optional = idx >= required_count + param_type = "any" + + # Mark optional params with ? + if is_optional and not param_name.endswith("?"): + param_name += "?" + + params.append((param_name, param_type)) + + # Extract return types (can be multiple, separated by commas) + return_types = [] + return_match = re.search(r"->\s*(.+?)$", signature) + if return_match: + return_str = return_match.group(1).strip() + # Handle multiple return values separated by commas + # But be careful not to split inside type expressions like "table" + # For simplicity, split by comma and trim + parts = [p.strip() for p in return_str.split(",")] + return_types = [p for p in parts if p and p not in ["or", "and"]] + + # If no return type specified, assume "any" + if not return_types: + return_types = ["any"] + + return func_name, params, return_types + + +def convert_type_to_lua(type_str: str) -> str: + """Convert Hammerspoon type notation to EmmyLua type notation.""" + if not type_str or type_str == "None": + return "nil" + + # Clean up malformed brackets and parentheses that don't belong in type annotations + # Simple approach: remove all parens and square brackets that aren't part of array notation [] + # Keep [] for arrays, remove everything else + type_str = re.sub(r"\(.*?\)", "", type_str) # Remove content in parentheses + type_str = re.sub(r"[()]", "", type_str) # Remove stray parens + type_str = re.sub(r"\[(?!\])", "", type_str) # Remove [ not followed by ] + type_str = re.sub(r"(? "hs.window") + type_str = re.sub(r"\s+object\b", "", type_str) + + # Remove common description words that shouldn't be in types + # These are placeholders/descriptions from the API docs + description_words = [ + "current value", "currentValue", "binary data", + "errString", "value", "item", "result" + ] + for word in description_words: + type_str = re.sub(rf"\b{re.escape(word)}\b", "", type_str, flags=re.IGNORECASE) + + # Map common *Object patterns to proper hs.* types + object_type_map = { + "axuielementObject": "hs.axuielement", + "axTextMarkerObject": "hs.axuielement.axtextmarker", + "axTextMarkerRangeObject": "hs.axuielement.axtextmarker", + "observerObject": "hs.axuielement.observer", + "browserObject": "hs.bonjour", + "serviceObject": "hs.bonjour.service", + "drawingObject": "hs.drawing", + "canvasObject": "hs.canvas", + "menubarObject": "hs.menubar", + "menubaritem": "hs.menubar", + "timerObject": "hs.timer", + "watchableObject": "hs.watchable", + } + + # Apply object type mappings + for old_type, new_type in object_type_map.items(): + type_str = re.sub(rf"\b{re.escape(old_type)}\b", new_type, type_str, flags=re.IGNORECASE) + + # Clean up extra whitespace and pipes + type_str = re.sub(r"\s+", " ", type_str).strip() + type_str = re.sub(r"\|\s*\|", "|", type_str) # Remove double pipes + type_str = re.sub(r"^\|+", "", type_str) # Remove leading pipes + type_str = re.sub(r"\|+$", "", type_str) # Remove trailing pipes + + # Remove trailing dots from type names (e.g., "hs.drawing.color." -> "hs.drawing.color") + type_str = re.sub(r"\.(?=\||$)", "", type_str) # Remove dots before pipe or end of string + + # Handle common type mappings (preserve unions by not replacing inside |) + type_map = { + "boolean": "boolean", + "number": "number", + "integer": "number", + "string": "string", + "table": "table", + "function": "function", + "userdata": "any", + "nil": "nil", + "bool": "boolean", + "true": "boolean", + "false": "boolean", + } + + # For union types, process each component separately + if "|" in type_str: + parts = type_str.split("|") + converted_parts = [] + for part in parts: + part = part.strip() + # Skip if empty or invalid + if not part: + continue + # Map known types + mapped = False + for old, new in type_map.items(): + if part == old: + part = new + mapped = True + break + # Add if valid + if part and not part.lower() in ["or", "and", "the", "a", "an"]: + converted_parts.append(part) + + # Deduplicate union components + return make_union_type(converted_parts) if converted_parts else "any" + else: + # Single type - direct mapping + type_str = type_str.strip() + for old, new in type_map.items(): + if type_str == old: + return new + + # Return cleaned type or "any" if empty or invalid + if not type_str or type_str.lower() in ["or", "and", "the", "a", "an"]: + return "any" + + return type_str + + +def format_description(desc: str, indent: str = "--- ") -> list[str]: + """Format description text for EmmyLua comments.""" + if not desc: + return [] + + lines = [] + # Split by newlines and wrap long lines + for line in desc.split("\n"): + line = line.strip() + if not line: + continue + + # Wrap at 120 characters (more reasonable for modern editors) + max_len = 116 # Account for "--- " prefix (4 chars) + + while len(line) > max_len: + # Find last space before max_len chars + wrap_pos = line[:max_len].rfind(" ") + if wrap_pos == -1 or wrap_pos < max_len * 0.6: + # If no good break point, don't wrap this line + break + + lines.append(f"{indent}{line[:wrap_pos]}") + line = line[wrap_pos:].strip() + + if line: + lines.append(f"{indent}{line}") + + return lines + + +def generate_api_item_annotation(item: dict) -> list[str]: + """Generate EmmyLua annotation for a single API item.""" + lines = [] + + # Parse signature + signature = item.get("signature", "") + if not signature: + return lines + + item_type = item.get("type", "").lower() + desc = item.get("description", "").strip() + + # Check for deprecation + is_deprecated = "deprecat" in desc.lower() or "deprecat" in item.get("notes", "").lower() + + # Handle Fields (return as field definitions, not standalone) + if item_type == "field": + # Fields will be handled in generate_type_definitions as @field annotations + # Return field info in a special format + field_name = signature.replace("`", "").strip() + field_type = extract_type_from_description(desc) if desc else "any" + + # Store as metadata for later use in class definitions + return [] # Fields are added to classes, not as standalone items + + # Handle Constants and Variables + if item_type in ["constant", "variable"]: + lines.append("") + + # Add description + if desc: + desc_lines = format_description(desc) + if desc_lines: + lines.extend(desc_lines) + + # Add deprecation notice + if is_deprecated: + lines.append("---@deprecated") + + # Use enhanced type extraction + var_type = extract_type_from_description(desc) if desc else "any" + + # Extract variable name from signature (remove backticks) + var_name = signature.replace("`", "").strip() + + lines.append(f"---@type {var_type}") + lines.append(f"{var_name} = nil") + + return lines + + # Handle Functions, Methods, Constructors + func_name, params, return_types = parse_signature(signature) + if not func_name: + return lines + + # Add separator + lines.append("") + + # Determine if it's a method (contains :) or function (contains .) + is_method = ":" in func_name + is_constructor = item_type == "constructor" + + # Add description (only if not empty) + if desc: + desc_lines = format_description(desc) + if desc_lines: + lines.extend(desc_lines) + + # Add notes if present (only if not empty) + notes = item.get("notes", "").strip() + if notes: + lines.append("---") + lines.extend(format_description(f"Note: {notes}")) + + # Add deprecation notice + if is_deprecated: + lines.append("---@deprecated") + + # Parse parameter descriptions to get types + param_desc = item.get("parameters", "") + param_type_map = parse_parameter_descriptions(param_desc) + + # Add parameters with types from descriptions + if params: + for param_name, param_type in params: + # Use type from parameter description if available + clean_name = param_name.rstrip("?") + if clean_name in param_type_map: + param_type = param_type_map[clean_name] + + # If still "any", try naming convention inference + if param_type == "any": + param_type = infer_type_from_param_name(clean_name) + + lua_type = convert_type_to_lua(param_type) + lines.append(f"---@param {param_name} {lua_type}") + + # Add return types (can be multiple) + # Parse return description to enhance types ONLY if signature didn't provide specific types + return_desc = item.get("returns", "") + if return_desc and return_desc.lower() != "none": + # Only use description if signature returned generic "any" or is empty + if not return_types or (len(return_types) == 1 and return_types[0] in ["any", "None"]): + # Try to extract type info from return description + enhanced_return_type = extract_type_from_description(return_desc) + if enhanced_return_type != "any": + return_types = [enhanced_return_type] + + # Generate return annotations + if return_types and not (len(return_types) == 1 and return_types[0] == "None"): + for ret_type in return_types: + lua_return_type = convert_type_to_lua(ret_type) + lines.append(f"---@return {lua_return_type}") + + # Generate function signature + param_names = ", ".join(p[0].rstrip("?") for p in params) + + # Format function declaration + if is_method: + # Method: remove module prefix and : + method_name = func_name.split(":")[-1] + module_name = func_name.split(":")[0] + # Use lowercase version of last component as object name + obj_name = module_name.split(".")[-1].lower() + lines.append(f"function {obj_name}:{method_name}({param_names}) end") + else: + # Function or constructor + lines.append(f"function {func_name}({param_names}) end") + + return lines + + +def truncate_field_description(desc: str, max_length: int = 120) -> str: + """ + Truncate field description intelligently at word boundaries. + Ensures no orphaned text or corrupted formatting. + Preserves module names like hs.geometry that contain periods. + """ + if not desc: + return "" + + # Remove newlines and extra whitespace first + desc = " ".join(desc.split()) + + # Get first sentence - split on ". " (period + space) not just "." + # This preserves module names like "hs.geometry" within descriptions + sentence_end = desc.find(". ") + if sentence_end > 0: + short_desc = desc[:sentence_end].strip() + else: + # No sentence ending found, use whole description + short_desc = desc.strip() + + # If already short enough, return as-is + if len(short_desc) <= max_length: + return short_desc + + # Truncate at word boundary, but avoid breaking module references + # Find last space before max_length + truncate_pos = short_desc[:max_length].rfind(" ") + + # Check if we're in the middle of an hs.* module reference + # If so, try to find a better break point + if truncate_pos > 0: + # Check if there's an hs.* pattern near the truncation point + check_range = short_desc[max(0, truncate_pos - 20):min(len(short_desc), truncate_pos + 20)] + if "hs." in check_range: + # Try to find a break point before the module reference + better_pos = short_desc[:truncate_pos].rfind(" ", 0, truncate_pos - 15) + if better_pos > max_length * 0.6: + truncate_pos = better_pos + + if truncate_pos > max_length * 0.6: # Only truncate if we found a good break point (more lenient) + short_desc = short_desc[:truncate_pos].strip() + "..." + else: + # No good break point, just cut at max_length + short_desc = short_desc[:max_length - 3].strip() + "..." + + return short_desc + + +def generate_type_definitions(all_api_items: list[dict]) -> str: + """Generate complete EmmyLua type definition file.""" + output = [] + + # Header + output.append("---@meta") + output.append("--- Hammerspoon EmmyLua Type Definitions") + output.append("--- Auto-generated from official documentation") + output.append("--- https://www.hammerspoon.org/docs/") + output.append("") + + # Group items by module + modules = defaultdict(list) + for item in all_api_items: + module = item.get("module", "unknown") + modules[module].append(item) + + # Generate definitions for each module + for module in sorted(modules.keys()): + items = modules[module] + + output.append("") + output.append(f"-- {'-' * 60}") + output.append(f"-- {module}") + output.append(f"-- {'-' * 60}") + + # Separate fields from other items + fields = [item for item in items if item.get("type", "").lower() == "field"] + non_field_items = [item for item in items if item.get("type", "").lower() != "field"] + + # Create module class with fields + output.append("") + output.append(f"---@class {module}") + + # Add field annotations to class + for field_item in fields: + signature = field_item.get("signature", "") + desc = field_item.get("description", "").strip() + full_field_name = signature.replace("`", "").strip() + # Extract just the field name (last component after last dot) + field_name = full_field_name.split(".")[-1] if "." in full_field_name else full_field_name + field_type = extract_type_from_description(desc) if desc else "any" + field_type_lua = convert_type_to_lua(field_type) + + # Add field description as comment if available + if desc: + short_desc = truncate_field_description(desc) + output.append(f"---@field {field_name} {field_type_lua} {short_desc}") + else: + output.append(f"---@field {field_name} {field_type_lua}") + + output.append(f"{module} = {{}}") + + # Create object class for methods (if any methods exist) + has_methods = any(":" in item.get("signature", "") for item in non_field_items) + if has_methods: + obj_name = module.split(".")[-1] + + # Check if any fields reference this object type + obj_fields = [f for f in fields if obj_name in str(f.get("description", ""))] + + output.append("") + output.append(f"---@class {obj_name}") + + # Add fields to object class too if relevant + for field_item in obj_fields: + signature = field_item.get("signature", "") + desc = field_item.get("description", "").strip() + full_field_name = signature.replace("`", "").strip() + # Extract just the field name (last component after last dot) + field_name = full_field_name.split(".")[-1] if "." in full_field_name else full_field_name + field_type = extract_type_from_description(desc) if desc else "any" + field_type_lua = convert_type_to_lua(field_type) + + if desc: + short_desc = truncate_field_description(desc) + output.append(f"---@field {field_name} {field_type_lua} {short_desc}") + else: + output.append(f"---@field {field_name} {field_type_lua}") + + output.append(f"local {obj_name} = {{}}") + + # Check for enum-like constant groups + constants = [item for item in non_field_items if item.get("type", "").lower() == "constant"] + if len(constants) > 3: # If module has several constants, treat as enum + # Check if they're all in a table (common pattern) + const_tables = {} + for const in constants: + sig = const.get("signature", "") + if "." in sig: + # Extract table name (e.g., "hs.eventtap.event.types.keyDown" -> "types") + parts = sig.split(".") + if len(parts) > 2: + table_name = parts[-2] + if table_name not in const_tables: + const_tables[table_name] = [] + const_tables[table_name].append(const) + + # Generate enum annotations for constant tables + for table_name, table_constants in const_tables.items(): + if len(table_constants) > 2: # Only for groups with multiple constants + output.append("") + output.append(f"---@class {module}.{table_name}") + for const in table_constants[:5]: # Show first few as examples + const_name = const.get("signature", "").split(".")[-1] + const_desc = const.get("description", "") + if const_desc: + short_desc = truncate_field_description(const_desc) + output.append(f"---@field {const_name} any {short_desc}") + + # Generate each non-field API item + for item in non_field_items: + annotation = generate_api_item_annotation(item) + output.extend(annotation) + + return "\n".join(output) + + +def main(): + """Main execution function.""" + print("=" * 70) + print("Hammerspoon Type Definition Generator") + print("=" * 70) + + base_url = "https://www.hammerspoon.org" + output_file = "hammerspoon.types.lua" + + # Step 1: Get all module URLs + modules = get_all_modules(base_url) + + if not modules: + print("Error: No modules found!") + return 1 + + # Step 2: Parse each module's documentation + print(f"\nParsing {len(modules)} modules...") + all_api_items = [] + + for module_path in modules: + items = parse_module_documentation(base_url, module_path) + all_api_items.extend(items) + + print(f"\nExtracted {len(all_api_items)} API items") + + # Step 3: Generate type definitions + print("\nGenerating type definitions...") + type_defs = generate_type_definitions(all_api_items) + + # Step 4: Write to file + print(f"Writing to {output_file}...") + with open(output_file, "w", encoding="utf-8") as f: + f.write(type_defs) + + print(f"\n✓ Successfully generated {output_file}") + print(f" Total lines: {len(type_defs.splitlines())}") + print(f" Total API items: {len(all_api_items)}") + + # Show statistics + modules_count = len(set(item.get("module", "") for item in all_api_items)) + print(f" Modules documented: {modules_count}") + + print("\n" + "=" * 70) + return 0 + + +if __name__ == "__main__": + exit(main()) diff --git a/base/hammerspoon/hammerspoon.types.lua b/base/hammerspoon/hammerspoon.types.lua new file mode 100644 index 0000000..ed2f4c8 --- /dev/null +++ b/base/hammerspoon/hammerspoon.types.lua @@ -0,0 +1,17863 @@ +---@meta +--- Hammerspoon EmmyLua Type Definitions +--- Auto-generated from official documentation +--- https://www.hammerspoon.org/docs/ + + +-- ------------------------------------------------------------ +-- hs +-- ------------------------------------------------------------ + +---@class hs +hs = {} + +--- A string containing Hammerspoon's configuration directory. Typically +--- ~/.hammerspoon/ +---@type string +hs.configdir = nil + +--- A string containing the full path to the +--- docs.json +--- file inside Hammerspoon's app bundle. This contains the full Hammerspoon API documentation and can be accessed in +--- the Console using +--- help("someAPI") +--- . It can also be loaded and processed by the +--- hs.doc +--- extension +---@type string +hs.docstrings_json_file = nil + +--- A table containing read-only information about the Hammerspoon application instance currently running. +---@type table +hs.processInfo = nil + +--- An optional function that will be called when the Accessibility State is changed. +---@type function|nil +hs.accessibilityStateCallback = nil + +--- Gathers tab completion options for the Console window +---@type any +hs.completionsForInputString(completionWord) -> table of strings = nil + +--- An optional function that will be called when the Hammerspoon Dock Icon is clicked while the app is running +---@type function|nil +hs.dockIconClickCallback = nil + +--- An optional function that will be called when a files are dragged to the Hammerspoon Dock Icon or sent via the +--- Services menu +---@type function|nil +hs.fileDroppedToDockIconCallback = nil + +--- An optional function that will be called when the Lua environment is being destroyed (either because Hammerspoon is +--- exiting or reloading its config) +---@type function|nil +hs.shutdownCallback = nil + +--- An optional function that will be called when text is dragged to the Hammerspoon Dock Icon or sent via the Services +--- menu +---@type function|nil +hs.textDroppedToDockIconCallback = nil + +--- Checks the Accessibility Permissions for Hammerspoon, and optionally allows you to prompt for permissions. +--- +--- Note: Since this check is done automatically when Hammerspoon loads, it is probably of limited use except for +--- skipping things that are known to fail when Accessibility is not enabled. Evettaps which try to capture keyUp and +--- keyDown events, for example, will fail until Accessibility is enabled and the Hammerspoon application is relaunched. +---@param shouldPrompt boolean|nil +---@return isEnabled +function hs.accessibilityState(shouldPrompt) end + +--- Set or display whether or not external Hammerspoon AppleScript commands are allowed. +--- +--- Note: AppleScript access is disallowed by default. +--- However due to the way AppleScript support works, Hammerspoon will always allow AppleScript commands that are part +--- of the "Standard Suite", such as name , quit , version , etc. However, Hammerspoon will only allow commands from +--- the "Hammerspoon Suite" if hs.allowAppleScript() is set to true . +--- Open /Applications/Utilities/Script Editor.app +--- Click File > Open Dictionary... +--- Select Hammerspoon from the list of Applications +--- This will now open a Dictionary containing all of the available Hammerspoon AppleScript commands. +--- Note that strings within the Lua code you pass from AppleScript can be delimited by [[ and ]] rather than normal +--- quotes +--- Example: tell application "Hammerspoon" execute lua code "hs.alert([[Hello from AppleScript]])" end tell ``` +---@param state boolean +---@return boolean +function hs.allowAppleScript(state) end + +--- Set or display the "Launch on Login" status for Hammerspoon. +---@param state boolean +---@return boolean +function hs.autoLaunch(state) end + +--- Gets and optionally sets the Hammerspoon option to automatically check for updates. +--- +--- Note: If you are running a non-release or locally compiled version of Hammerspoon then the results of this function +--- are unspecified. +---@param setting boolean|nil +---@return boolean +function hs.automaticallyCheckForUpdates(setting) end + +--- Checks the Camera Permissions for Hammerspoon, and optionally allows you to prompt for permissions. +--- +--- Note: Will always return true on macOS 10.13 or earlier. +---@param shouldPrompt boolean|nil +---@return boolean +function hs.cameraState(shouldPrompt) end + +--- Returns a boolean indicating whether or not the Sparkle framework is available to check for Hammerspoon updates. +--- +--- Note: The Sparkle framework is included in all regular releases of Hammerspoon but not included if you are running +--- a non-release or locally compiled version of Hammerspoon, so this function can be used as a simple test to +--- determine whether or not you are running a formal release Hammerspoon or not. +---@return boolean +function hs.canCheckForUpdates() end + +--- Check for an update now, and if one is available, prompt the user to continue the update process. +--- +--- Note: If you are running a non-release or locally compiled version of Hammerspoon then the results of this function +--- are unspecified. +---@param silent boolean|nil +---@return none +function hs.checkForUpdates(silent) end + +--- Returns a copy of the incoming string that can be displayed in the Hammerspoon console. Invalid UTF8 sequences are +--- converted to the Unicode Replacement Character and NULL (0x00) is converted to the Unicode Empty Set character. +--- +--- Note: This function is applied automatically to all output which appears in the Hammerspoon console, but not to the +--- output provided by the hs command line tool. +--- This function does not modify the original string - to actually replace it, assign the result of this function to +--- the original string. +--- This function is a more specifically targeted version of the hs.utf8.fixUTF8(...) function. +---@param inString string +---@return outString +function hs.cleanUTF8forConsole(inString) end + +--- Closes the Hammerspoon Console window +---@return any +function hs.closeConsole() end + +--- Closes the Hammerspoon Preferences window +---@return any +function hs.closePreferences() end + +--- Set or display whether or not the Hammerspoon console is always on top when visible. +---@param state boolean +---@return boolean +function hs.consoleOnTop(state) end + +--- Yield coroutine to allow the Hammerspoon application to process other scheduled events and schedule a resume in the +--- event application queue. +--- +--- Note: this function will return an error if invoked outside of a coroutine. +--- unlike coroutine.yield , this function does not allow the passing of (new) information to or from the coroutine +--- while it is running; this function is to allow long running tasks to yield time to the Hammerspoon application so +--- other timers and scheduled events can occur without requiring the programmer to add code for an explicit resume. +--- this function is added to the lua coroutine library as coroutine.applicationYield as an alternative name. +---@param delay hs.math.minFloat|nil +---@return any +function hs.coroutineApplicationYield(delay) end + +--- Set or display whether or not the Hammerspoon dock icon is visible. +--- +--- Note: This function is a wrapper to functions found in the hs.dockicon module, but is provided here to provide an +--- interface consistent with other selectable preference items. +---@param state boolean +---@return boolean +function hs.dockIcon(state) end + +--- Runs a shell command, optionally loading the users shell environment first, and returns stdout as a string, +--- followed by the same result codes as +--- os.execute +--- would return. +--- +--- Note: Setting with_user_env to true does incur noticeable overhead, so it should only be used if necessary (to set +--- the path or other environment variables). +--- Because this function returns the stdout as it's first return value, it is not quite a drop-in replacement for +--- os.execute . In most cases, it is probable that stdout will be the empty string when status is nil, but this is +--- not guaranteed, so this trade off of shifting os.execute's results was deemed acceptable. +--- This particular function is most useful when you're more interested in the command's output then a simple check for +--- completion and result codes. If you only require the result codes or verification of command completion, then +--- os.execute will be slightly more efficient. +--- If you need to execute commands that have spaces in their paths, use a form like: hs.execute [["/Some/Path +--- To/An/Executable" "--first-arg" "second-arg"]] +---@param command string +---@param with_user_env? boolean|nil +---@return output +---@return status +---@return type +---@return rc +function hs.execute(command, with_user_env) end + +--- Makes Hammerspoon the foreground app. +---@return any +function hs.focus() end + +--- Fetches the Lua metatable for objects produced by an extension +---@param name string +---@return table|nil +function hs.getObjectMetatable(name) end + +--- Prints the documentation for some part of Hammerspoon's API and Lua 5.3. This function is actually sourced from +--- hs.doc.help. +--- +--- Note: This function is mainly for runtime API help while using Hammerspoon's Console +--- help("identifier") -- quotes are required, e.g. help("hs.reload") +--- help.identifier.path -- no quotes are required, e.g. help.hs.reload +--- the identifier lua._man provides the table of contents for the Lua 5.3 manual. You can pull up a specific section +--- of the lua manual by including the chapter (and subsection) like this: lua._man._3_4_8 . +--- the identifier lua._C will provide information specifically about the Lua C API for use when developing modules +--- which require external libraries. +---@param identifier string +---@return any +function hs.help(identifier) end + +--- Display's Hammerspoon API documentation in a webview browser. +--- +--- Note: hs.hsdocs.identifier.path -- no quotes are required, e.g. hs.hsdocs.hs.reload +--- See hs.doc.hsdocs for more information about the available settings for the documentation browser. +--- This function provides documentation for Hammerspoon modules, functions, and methods similar to the Hammerspoon +--- Dash docset, but does not require any additional software. +--- This currently only provides documentation for the built in Hammerspoon modules, functions, and methods. The Lua +--- documentation and third-party modules are not presently supported, but may be added in a future release. +---@param identifier hs.reload|nil +---@return any +function hs.hsdocs(identifier) end + +--- Loads a Spoon +--- +--- Note: Spoons are a way of distributing self-contained units of Lua functionality, for Hammerspoon. For more +--- information, see https://github.com/Hammerspoon/hammerspoon/blob/master/SPOONS.md +--- This function will load the Spoon and call its :init() method if it has one. If you do not wish this to happen, or +--- wish to use a Spoon that somehow doesn't fit with the behaviours of this function, you can also simply +--- require('name') to load the Spoon +--- If the Spoon has a :start() method you are responsible for calling it before using the functionality of the Spoon. +--- If the Spoon provides documentation, it will be loaded by made available in hs.docs +--- To learn how to distribute your own code as a Spoon, see https://github.com/Hammerspoon/hammerspoon/blob/master/SPOONS.md +---@param name string +---@param global? boolean|nil +---@return Spoon +function hs.loadSpoon(name, global) end + +--- Set or display whether or not the Hammerspoon menu icon is visible. +---@param state boolean +---@return boolean +function hs.menuIcon(state) end + +--- Checks the Microphone Permissions for Hammerspoon, and optionally allows you to prompt for permissions. +--- +--- Note: Will always return true on macOS 10.13 or earlier. +---@param shouldPrompt boolean|nil +---@return boolean +function hs.microphoneState(shouldPrompt) end + +--- Opens a file as if it were opened with /usr/bin/open +---@param filePath string +---@return boolean +function hs.open(filePath) end + +--- Displays the OS X About panel for Hammerspoon; implicitly focuses Hammerspoon. +---@return any +function hs.openAbout() end + +--- Opens the Hammerspoon Console window and optionally focuses it. +---@param bringToFront boolean +---@return any +function hs.openConsole(bringToFront) end + +--- Set or display whether or not the Console window will open when the Hammerspoon dock icon is clicked +--- +--- Note: This only refers to dock icon clicks while Hammerspoon is already running. The console window is not opened +--- by launching the app +---@param state boolean|nil +---@return boolean +function hs.openConsoleOnDockClick(state) end + +--- Displays the Hammerspoon Preferences panel; implicitly focuses Hammerspoon. +---@return any +function hs.openPreferences() end + +--- Set or display whether or not the Preferences panel should display in dark mode. +---@param state boolean +---@return boolean +function hs.preferencesDarkMode(state) end + +--- Prints formatted strings to the Console +--- +--- Note: This is a simple wrapper around the Lua code print(string.format(...)) . +---@param format string +---@param ... any +---@return any +function hs.printf(format, ...) end + +--- The original Lua print() function +--- +--- Note: Hammerspoon overrides Lua's print() function, but this is a reference we retain to is, should you need it for +--- any reason +---@param aString string +---@return any +function hs.rawprint(aString) end + +--- Quits and relaunches Hammerspoon. +---@return any +function hs.relaunch() end + +--- Reloads your init-file in a fresh Lua environment. +---@return any +function hs.reload() end + +--- Checks the Screen Recording Permissions for Hammerspoon, and optionally allows you to prompt for permissions. +--- +--- Note: If you trigger the prompt and the user denies it, you cannot bring up the prompt again - the user must +--- manually enable it in System Preferences. +---@param shouldPrompt boolean|nil +---@return isEnabled +function hs.screenRecordingState(shouldPrompt) end + +--- Shows an error to the user, using Hammerspoon's Console +--- +--- Note: This function is called whenever an (uncaught) error occurs or is thrown (via error() ) +--- The default implementation shows a notification, opens the Console, and prints the error message and stacktrace +--- You can override this function if you wish to route errors differently (e.g. for remote systems) +---@param err string +---@return any +function hs.showError(err) end + +--- Toggles the visibility of the console +--- +--- Note: If the console is not currently open, it will be opened. If it is open and not the focused window, it will be +--- brought forward and focused. +--- If the console is focused, it will be closed. +---@return any +function hs.toggleConsole() end + +--- Gets the version & build number of an available update +--- +--- Note: This is not a live check, it is a cached result of whatever the previous update check found. By default +--- Hammerspoon checks for updates every few hours, but you can also add your own timer to check for updates more +--- frequently with hs.checkForUpdates() +---@return string|boolean +---@return string +function hs.updateAvailable() end + +--- Get or set the "Upload Crash Data" preference for Hammerspoon +--- +--- Note: If at all possible, please do allow Hammerspoon to upload crash reports to us, it helps a great deal in +--- keeping Hammerspoon stable +--- Our Privacy Policy can be found here: https://www.hammerspoon.org/privacy.html +---@param state boolean|nil +---@return boolean +function hs.uploadCrashData(state) end + +-- ------------------------------------------------------------ +-- hs.alert +-- ------------------------------------------------------------ + +---@class hs.alert +hs.alert = {} + +--- A table defining the default visual style for the alerts generated by this module. +---@type table +hs.alert.defaultStyle[] = nil + +--- Closes all alerts currently open on the screen +---@param seconds hs.alert.defaultStyle|nil +---@return any +function hs.alert.closeAll(seconds) end + +--- Closes the alert with the specified identifier +--- +--- Note: Use this function to close an alert which is indefinite or close an alert with a long duration early. +---@param uuid string +---@param seconds hs.alert.defaultStyle|nil +---@return any +function hs.alert.closeSpecific(uuid, seconds) end + +--- Shows a message in large words briefly in the middle of the screen; does tostring() on its argument for convenience. +--- +--- Note: For convenience, you can call this function as hs.alert(...) +--- This function effectively calls hs.alert.showWithImage(msg, nil, ...) . As such, all the same rules apply regarding +--- argument processing +---@param str string +---@param style hs.alert.defaultStyle|hs.styledtext|nil +---@param screen hs.screen|hs.screen.mainScreen|nil +---@param seconds number +---@return uuid +function hs.alert.show(str, style, screen, seconds) end + +--- Shows an image and a message in large words briefly in the middle of the screen; does tostring() on its argument +--- for convenience. +--- +--- Note: if the argument is a table and style has not previously been set, then the table is assigned to style +--- if the argument is a userdata and screen has not previously been set, then the userdata is assigned to screen +--- if duration has not been set, then it is assigned the value of the argument +--- if all of these conditions fail for a given argument, then an error is returned +--- The reason for this logic is to support the creation of persistent alerts as was previously handled by the module: +--- If you specify a non-number value for seconds you will need to store the string identifier returned by this +--- function so that you can close it manually with hs.alert.closeSpecific when the alert should be removed. +--- Any style element which is not specified in the style argument table will use the value currently defined in the +--- hs.alert.defaultStyle table. +---@param str string +---@param image any +---@param style hs.alert.defaultStyle|hs.styledtext|nil +---@param screen hs.screen|hs.window|hs.screen.mainScreen|nil +---@param seconds number +---@return uuid +function hs.alert.showWithImage(str, image, style, screen, seconds) end + +-- ------------------------------------------------------------ +-- hs.appfinder +-- ------------------------------------------------------------ + +---@class hs.appfinder +hs.appfinder = {} + +--- Finds an application by its name (e.g. "Safari") +---@param name string +---@return app|nil +function hs.appfinder.appFromName(name) end + +--- Finds an application by its window title (e.g. "Activity Monitor (All Processes)") +---@param title string +---@return app|nil +function hs.appfinder.appFromWindowTitle(title) end + +--- Finds an application by Lua pattern in its window title (e.g."Inbox %(%d+ messages.*)") +--- +--- Note: For more about Lua patterns, see http://lua-users.org/wiki/PatternsTutorial and +--- http://www.lua.org/manual/5.2/manual.html#6.4.1 +---@param pattern string +---@return app|nil +function hs.appfinder.appFromWindowTitlePattern(pattern) end + +--- Finds a window by its title (e.g. "Activity Monitor (All Processes)") +---@param title string +---@return win|nil +function hs.appfinder.windowFromWindowTitle(title) end + +--- Finds a window by Lua pattern in its title (e.g."Inbox %(%d+ messages.*)") +--- +--- Note: For more about Lua patterns, see http://lua-users.org/wiki/PatternsTutorial and +--- http://www.lua.org/manual/5.2/manual.html#6.4.1 +---@param pattern string +---@return app|nil +function hs.appfinder.windowFromWindowTitlePattern(pattern) end + +-- ------------------------------------------------------------ +-- hs.application +-- ------------------------------------------------------------ + +---@class hs.application +hs.application = {} + +---@class application +local application = {} + +--- A table containing UTF8 representations of the defined key glyphs used in Menus for keyboard shortcuts which are +--- presented pictorially rather than as text (arrow keys, return key, etc.) +---@type table +hs.application.menuGlyphs = nil + +--- Returns the running app for the given pid, if it exists. +---@param pid number +---@return hs.application|nil +function hs.application.applicationForPID(pid) end + +--- Returns any running apps that have the given bundleID. +---@param bundleID string +---@return list of hs.application objects +function hs.application.applicationsForBundleID(bundleID) end + +--- Returns the bundle ID of the default application for a given UTI +---@param uti string +---@return string|nil +function hs.application.defaultAppForUTI(uti) end + +--- Get or set whether Spotlight should be used to find alternate names for applications. +--- +--- Note: This setting is persistent across reloading and restarting Hammerspoon. +--- If this was set to true and you set it to true again, it will purge the alternate name map and rebuild it from +--- scratch. +--- You can disable Spotlight alternate name mapping by setting this value to false or nil. If you set this to false, +--- then the notifications indicating that more results might be possible if Spotlight is enabled will be suppressed. +---@param state hs.application.find|nil +---@return boolean +function hs.application.enableSpotlightForNameSearches(state) end + +--- Returns the application object for the frontmost (active) application. This is the application which currently +--- receives input events. +---@return hs.application +function hs.application.frontmostApplication() end + +--- Gets the metadata of an application from its bundle identifier +---@param bundleID string +---@return table|nil +function hs.application.infoForBundleID(bundleID) end + +--- Gets the metadata of an application from its path on disk +---@param bundlePath string +---@return table|nil +function hs.application.infoForBundlePath(bundlePath) end + +--- Launches the app with the given name, or activates it if it's already running +--- +--- Note: The name parameter should match the name of the application on disk, e.g. "IntelliJ IDEA", rather than +--- "IntelliJ" +---@param name string +---@return boolean +function hs.application.launchOrFocus(name) end + +--- Launches the app with the given bundle ID, or activates it if it's already running +--- +--- Note: Bundle identifiers typically take the form of com.company.ApplicationName +---@param bundleID string +---@return boolean +function hs.application.launchOrFocusByBundleID(bundleID) end + +--- Gets a list of all the localizations contained in the bundle. +---@param bundleID string +---@return table|nil +function hs.application.localizationsForBundleID(bundleID) end + +--- Gets a list of all the localizations contained in the bundle. +---@param bundlePath string +---@return table|nil +function hs.application.localizationsForBundlePath(bundlePath) end + +--- Gets the name of an application from its bundle identifier +---@param bundleID string +---@return string|nil +function hs.application.nameForBundleID(bundleID) end + +--- Gets the filesystem path of an application from its bundle identifier +---@param bundleID string +---@return string|nil +function hs.application.pathForBundleID(bundleID) end + +--- Gets an ordered list of preferred localizations contained in a bundle +---@param bundleID string +---@return table|nil +function hs.application.preferredLocalizationsForBundleID(bundleID) end + +--- Gets an ordered list of preferred localizations contained in a bundle +---@param bundlePath string +---@return table|nil +function hs.application.preferredLocalizationsForBundlePath(bundlePath) end + +--- Returns all running apps. +---@return list of hs.application objects +function hs.application.runningApplications() end + +--- Finds running applications +--- +--- Note: If multiple results are found, this function will return multiple values. See +--- https://www.lua.org/pil/5.1.html for more information on how to work with this +--- for convenience you can call this as hs.application(hint) +--- use this function when you don't know the exact name of an application you're interested in, i.e. +--- from the console: hs.application'term' --> hs.application: iTerm2 (0x61000025fb88) hs.application: Terminal +--- (0x618000447588) . +--- But be careful when using it in your init.lua : terminal=hs.application'term' will assign either "Terminal" or +--- "iTerm2" arbitrarily (or even, +--- if neither are running, any other app with a window that happens to have "term" in its title); to make sure you get +--- the right app in your scripts, +--- use hs.application.get with the exact name: terminal=hs.application.get'Terminal' --> "Terminal" app, or nil if +--- it's not running +--- Usage: +--- -- by pid +--- hs.application(42):name() --> Finder +--- -- by bundle id +--- hs.application'com.apple.Safari':name() --> Safari +--- -- by name +--- hs.application'chrome':name() --> Google Chrome +--- -- by window title +--- hs.application'bash':name() --> Terminal +---@param hint hs.application|hs.window +---@param exact boolean +---@param stringLiteral boolean +---@return hs.application +function hs.application.find(hint, exact, stringLiteral) end + +--- Gets a running application +--- +--- Note: see also hs.application.find +---@param hint hs.application +---@return hs.application +function hs.application.get(hint) end + +--- Launches an application, or activates it if it's already running +--- +--- Note: the wait parameter will block all Hammerspoon activity in order to return the application object +--- "synchronously"; only use it if you +--- a) have no time-critical event processing happening elsewhere in your init.lua and b) need to act on the +--- application object, or on +--- its window(s), right away +--- when launching a "windowless" app (background daemon, menulet, etc.) make sure to omit waitForFirstWindow +---@param app string +---@param wait? number|nil +---@param waitForFirstWindow? any +---@return hs.application +function hs.application.open(app, wait, waitForFirstWindow) end + +--- Tries to activate the app (make its key window focused) and returns whether it succeeded; if allWindows is true, +--- all windows of the application are brought forward as well. +---@param allWindows any +---@return boolean +function application:activate(allWindows) end + +--- Returns all open windows owned by the given app. +--- +--- Note: if Displays have separate Spaces is on (in System Preferences>Mission Control) the current Space is defined +--- as the union of all currently visible Spaces +--- minimized windows and hidden windows (i.e. belonging to hidden apps, e.g. via cmd-h) are always considered +--- to be in the current Space +---@return list of hs.window objects +function application:allWindows() end + +--- Returns the bundle identifier of the app. +---@return string +function application:bundleID() end + +--- Searches the application for a menu item +--- +--- Note: This can only search for menu items that don't have children - i.e. you can't search for the name of a submenu +---@param menuItem table +---@param isRegex? boolean|nil +---@return table|nil +function application:findMenuItem(menuItem, isRegex) end + +--- Finds windows from this application +---@param titlePattern string +---@return hs.window +function application:findWindow(titlePattern) end + +--- Returns the currently focused window of the application, or nil +---@return hs.window|nil +function application:focusedWindow() end + +--- Gets the menu structure of the application +--- +--- Note: In some applications, this can take a little while to complete, because quite a large number of round trips +--- are required to the source application, to get the information. When this method is invoked without a callback +--- function, Hammerspoon will block while creating the menu structure table. When invoked with a callback function, +--- the menu structure is built in a background thread. +--- The table is nested with the same structure as the menus of the application. Each item has several keys containing +--- information about the menu item. Not all keys will appear for all items. The possible keys are: +--- AXTitle - A string containing the text of the menu item (entries which have no title are menu separators) +--- AXEnabled - A boolean, 1 if the menu item is clickable, 0 if not +--- AXRole - A string containing the role of the menu item - this will be either AXMenuBarItem for a top level menu, or +--- AXMenuItem for an item in a menu +--- AXMenuItemMarkChar - A string containing the "mark" character for a menu item. This is for toggleable menu items +--- and will usually be an empty string or a Unicode tick character (✓) +--- AXMenuItemCmdModifiers - A table containing string representations of the keyboard modifiers for the menu item's +--- keyboard shortcut, or nil if no modifiers are present +--- AXMenuItemCmdChar - A string containing the key for the menu item's keyboard shortcut, or an empty string if no +--- shortcut is present +--- AXMenuItemCmdGlyph - An integer, corresponding to one of the defined glyphs in hs.application.menuGlyphs if the +--- keyboard shortcut is a special character usually represented by a pictorial representation (think arrow keys, +--- return, etc), or an empty string if no glyph is used in presenting the keyboard shortcut. +--- Using hs.inspect() on these tables, while useful for exploration, can be extremely slow, taking several minutes to +--- correctly render very complex menus +---@param fn function|nil +---@return table|nil|hs.application +function application:getMenuItems(fn) end + +--- Gets a specific window from this application +---@param title hs.window +---@return hs.window +function application:getWindow(title) end + +--- Hides the app (and all its windows). +---@return boolean +function application:hide() end + +--- Returns whether the app is the frontmost (i.e. is the currently active application) +---@return boolean +function application:isFrontmost() end + +--- Returns whether the app is currently hidden. +---@return boolean +function application:isHidden() end + +--- Checks if the application is still running +--- +--- Note: If an application is terminated and re-launched, this method will still return false, as hs.application +--- objects are tied to a specific instance of an application (i.e. its PID) +---@return boolean +function application:isRunning() end + +--- Tries to terminate the app gracefully. +---@return any +function application:kill() end + +--- Tries to terminate the app forcefully. +---@return any +function application:kill9() end + +--- Identify the application's GUI state +---@return number +function application:kind() end + +--- Returns the main window of the given app, or nil. +---@return hs.window|nil +function application:mainWindow() end + +--- Alias for +--- hs.application:title() +---@return any +function application:name() end + +--- Returns the filesystem path of the app. +---@return string +function application:path() end + +--- Returns the app's process identifier. +---@return number +function application:pid() end + +--- Selects a menu item (i.e. simulates clicking on the menu item) +--- +--- Note: Depending on the type of menu item involved, this will either activate or tick/untick the menu item +---@param menuitem hs.application +---@param isRegex? boolean|nil +---@return boolean|nil +function application:selectMenuItem(menuitem, isRegex) end + +--- Sets the app to the frontmost (i.e. currently active) application +---@param allWindows boolean|nil +---@return boolean +function application:setFrontmost(allWindows) end + +--- Returns the localized name of the app (in UTF8). +---@return string +function application:title() end + +--- Unhides the app (and all its windows) if it's hidden. +---@return boolean +function application:unhide() end + +--- Returns only the app's windows that are visible. +---@return win[] +function application:visibleWindows() end + +-- ------------------------------------------------------------ +-- hs.application.watcher +-- ------------------------------------------------------------ + +---@class hs.application.watcher +hs.application.watcher = {} + +---@class watcher +local watcher = {} + +---@class hs.application.watcher.watcher +---@field activated any An application has been activated (i.e +---@field deactivated any An application has been deactivated (i.e +---@field hidden any An application has been hidden +---@field launched any An application has been launched +---@field launching any An application is in the process of being launched + +--- An application has been activated (i.e. given keyboard/mouse focus) +---@type any +hs.application.watcher.activated = nil + +--- An application has been deactivated (i.e. lost keyboard/mouse focus) +---@type any +hs.application.watcher.deactivated = nil + +--- An application has been hidden +---@type any +hs.application.watcher.hidden = nil + +--- An application has been launched +---@type any +hs.application.watcher.launched = nil + +--- An application is in the process of being launched +---@type any +hs.application.watcher.launching = nil + +--- An application has been terminated +---@type any +hs.application.watcher.terminated = nil + +--- An application has been unhidden +---@type any +hs.application.watcher.unhidden = nil + +--- Creates an application event watcher +--- +--- Note: If the function is called with an event type of hs.application.watcher.terminated then the application name +--- parameter will be nil and the hs.application parameter, will only be useful for getting the UNIX process ID (i.e. +--- the PID) of the application +---@param fn function +---@return watcher +function hs.application.watcher.new(fn) end + +--- Starts the application watcher +---@return hs.application.watcher +function watcher:start() end + +--- Stops the application watcher +---@return hs.application.watcher +function watcher:stop() end + +-- ------------------------------------------------------------ +-- hs.audiodevice +-- ------------------------------------------------------------ + +---@class hs.audiodevice +hs.audiodevice = {} + +---@class audiodevice +local audiodevice = {} + +--- Returns a list of all connected devices +---@return hs.audiodevice[] +function hs.audiodevice.allDevices() end + +--- Returns a list of all connected input devices. +---@return audio[] +function hs.audiodevice.allInputDevices() end + +--- Returns a list of all connected output devices +---@return hs.audiodevice[] +function hs.audiodevice.allOutputDevices() end + +--- Fetch various metadata about the current default audio devices +---@param input any +---@return table +function hs.audiodevice.current(input) end + +--- Get the currently selected sound effect device +---@return audio|nil +function hs.audiodevice.defaultEffectDevice() end + +--- Get the currently selected audio input device +---@return audio|nil +function hs.audiodevice.defaultInputDevice() end + +--- Get the currently selected audio output device +---@return audio|nil +function hs.audiodevice.defaultOutputDevice() end + +--- Find an audio device by name +---@param name string +---@return device|nil +function hs.audiodevice.findDeviceByName(name) end + +--- Find an audio device by UID +---@param uid string +---@return device|nil +function hs.audiodevice.findDeviceByUID(uid) end + +--- Find an audio input device by name +---@param name string +---@return device|nil +function hs.audiodevice.findInputByName(name) end + +--- Find an audio input device by UID +---@param uid string +---@return device|nil +function hs.audiodevice.findInputByUID(uid) end + +--- Find an audio output device by name +---@param name string +---@return device|nil +function hs.audiodevice.findOutputByName(name) end + +--- Find an audio output device by UID +---@param uid string +---@return device|nil +function hs.audiodevice.findOutputByUID(uid) end + +--- Gets all of the input data sources of an audio device +---@return hs.audiodevice.dataSource[]|nil +function audiodevice:allInputDataSources() end + +--- Gets all of the output data sources of an audio device +---@return hs.audiodevice.dataSource[]|nil +function audiodevice:allOutputDataSources() end + +--- Get the current left/right balance of this audio device +--- +--- Note: The return value will be a floating point number +--- This method will inspect the device to determine if it is an input or output device, and return the appropriate +--- volume. For devices that are both input and output devices, see :inputVolume() and :outputVolume() +---@return number|nil +function audiodevice:balance() end + +--- Gets the current input data source of an audio device +--- +--- Note: Before calling this method, you should check the result of hs.audiodevice:supportsInputDataSources() +---@return hs.audiodevice.dataSource|nil +function audiodevice:currentInputDataSource() end + +--- Gets the current output data source of an audio device +--- +--- Note: Before calling this method, you should check the result of hs.audiodevice:supportsOutputDataSources() +---@return hs.audiodevice.dataSource|nil +function audiodevice:currentOutputDataSource() end + +--- Get the Input mutedness state of the audio device +---@return boolean|nil +function audiodevice:inputMuted() end + +--- Get the current input volume of this audio device +--- +--- Note: The return value will be a floating point number +---@return number|nil +function audiodevice:inputVolume() end + +--- Check if the audio device is in use +---@return boolean|nil +function audiodevice:inUse() end + +--- Determines if an audio device is an input device +---@return boolean +function audiodevice:isInputDevice() end + +--- Determines if an audio device is an output device +---@return boolean +function audiodevice:isOutputDevice() end + +--- Determines whether an audio jack (e.g. headphones) is connected to an audio device +---@return boolean|nil +function audiodevice:jackConnected() end + +--- Get the mutedness state of the audio device +--- +--- Note: If a device is capable of both input and output, this method will prefer the output. See :inputMuted() and +--- :outputMuted() for specific variants. +---@return boolean|nil +function audiodevice:muted() end + +--- Get the name of the audio device +---@return string|nil +function audiodevice:name() end + +--- Get the Output mutedness state of the audio device +---@return boolean|nil +function audiodevice:outputMuted() end + +--- Get the current output volume of this audio device +--- +--- Note: The return value will be a floating point number +---@return number|nil +function audiodevice:outputVolume() end + +--- Set the balance of this audio device +--- +--- Note: This method will inspect the device to determine if it is an input or output device, and set the appropriate +--- volume. For devices that are both input and output devices, see :setInputVolume() and :setOutputVolume() +---@param level number +---@return boolean +function audiodevice:setBalance(level) end + +--- Selects this device as the audio output device for system sound effects +---@return boolean +function audiodevice:setDefaultEffectDevice() end + +--- Selects this device as the system's audio input device +---@return boolean +function audiodevice:setDefaultInputDevice() end + +--- Selects this device as the system's audio output device +---@return boolean +function audiodevice:setDefaultOutputDevice() end + +--- Set the mutedness state of the Input of the audio device +---@param state boolean +---@return boolean +function audiodevice:setInputMuted(state) end + +--- Set the input volume of this audio device +--- +--- Note: The volume level is a floating point number. Depending on your audio hardware, it may not be possible to +--- increase volume in single digit increments +---@param level number +---@return boolean +function audiodevice:setInputVolume(level) end + +--- Set the mutedness state of the audio device +--- +--- Note: If a device is capable of both input and output, this method will prefer the output. See :setInputMuted() and +--- :setOutputMuted() for specific variants. +---@param state boolean +---@return boolean +function audiodevice:setMuted(state) end + +--- Set the mutedness state of the Output of the audio device +---@param state boolean +---@return boolean +function audiodevice:setOutputMuted(state) end + +--- Set the output volume of this audio device +--- +--- Note: The volume level is a floating point number. Depending on your audio hardware, it may not be possible to +--- increase volume in single digit increments +---@param level number +---@return boolean +function audiodevice:setOutputVolume(level) end + +--- Set the volume of this audio device +--- +--- Note: The volume level is a floating point number. Depending on your audio hardware, it may not be possible to +--- increase volume in single digit increments. +--- This method will inspect the device to determine if it is an input or output device, and set the appropriate +--- volume. For devices that are both input and output devices, see :setInputVolume() and :setOutputVolume() +---@param level number +---@return boolean +function audiodevice:setVolume(level) end + +--- Determines whether an audio device supports input data sources +---@return boolean +function audiodevice:supportsInputDataSources() end + +--- Determines whether an audio device supports output data sources +---@return boolean +function audiodevice:supportsOutputDataSources() end + +--- Gets the hardware transport type of an audio device +---@return string +function audiodevice:transportType() end + +--- Get the unique identifier of the audio device +---@return string|nil +function audiodevice:uid() end + +--- Get the current volume of this audio device +--- +--- Note: The return value will be a floating point number +--- This method will inspect the device to determine if it is an input or output device, and return the appropriate +--- volume. For devices that are both input and output devices, see :inputVolume() and :outputVolume() +---@return number|nil +function audiodevice:volume() end + +--- Sets or removes a callback function for an audio device watcher +--- +--- Note: You will receive many events to your callback, so filtering on the name/scope/element arguments is vital. For +--- example, on a stereo device, it is not uncommon to receive a volm event for each audio channel when the volume +--- changes, or multiple mute events for channels. Dragging a volume slider in the system Sound preferences will +--- produce a large number of volm events. Plugging/unplugging headphones may trigger volm events in addition to jack +--- ones, etc. +--- If you need to use the hs.audiodevice object in your callback, use hs.audiodevice.findDeviceByUID() to obtain it +--- fro the first callback argument +---@param fn function +---@return hs.audiodevice +function audiodevice:watcherCallback(fn) end + +--- Gets the status of the +--- hs.audiodevice +--- object watcher +---@return boolean +function audiodevice:watcherIsRunning() end + +--- Starts the watcher on an +--- hs.audiodevice +--- object +---@return hs.audiodevice|nil +function audiodevice:watcherStart() end + +--- Stops the watcher on an +--- hs.audiodevice +--- object +---@return hs.audiodevice +function audiodevice:watcherStop() end + +-- ------------------------------------------------------------ +-- hs.audiodevice.datasource +-- ------------------------------------------------------------ + +---@class hs.audiodevice.datasource +hs.audiodevice.datasource = {} + +---@class datasource +local datasource = {} + +--- Gets the name of an audio device datasource +---@return string +function datasource:name() end + +--- Sets the audio device datasource as the default +---@return hs.audiodevice.datasource +function datasource:setDefault() end + +-- ------------------------------------------------------------ +-- hs.audiodevice.watcher +-- ------------------------------------------------------------ + +---@class hs.audiodevice.watcher +hs.audiodevice.watcher = {} + +--- Gets the status of the audio device watcher +---@return boolean +function hs.audiodevice.watcher.isRunning() end + +--- Sets the callback function for the audio device watcher +--- +--- Note: This watcher will call the callback when various audio device related events occur (e.g. an audio device +--- appears/disappears, a system default audio device setting changes, etc) +--- To watch for changes within an audio device, see hs.audiodevice:newWatcher() +--- The callback function argument is a string which may be one of the following strings, but might also be a different +--- string entirely: +--- dIn - Default audio input device setting changed (Note that there is a space character after dIn , because these +--- values always have to be four characters long) +--- dOut - Default audio output device setting changed +--- sOut - Default system audio output setting changed (i.e. the device that system sound effects use. This may also be +--- triggered by dOut, depending on the user's settings) +--- dev# - An audio device appeared or disappeared +--- The callback will be called for each individual audio device event received from the OS, so you may receive +--- multiple events for a single physical action (e.g. unplugging the default audio device will cause dOut and dev# +--- events, and possibly sOut too) +--- Passing nil will cause the watcher to stop if it is already running +---@param fn function|nil +---@return any +function hs.audiodevice.watcher.setCallback(fn) end + +--- Starts the audio device watcher +---@return any +function hs.audiodevice.watcher.start() end + +--- Stops the audio device watcher +---@return hs.audiodevice.watcher +function hs.audiodevice.watcher.stop() end + +-- ------------------------------------------------------------ +-- hs.axuielement +-- ------------------------------------------------------------ + +---@class hs.axuielement +hs.axuielement = {} + +---@class axuielement +local axuielement = {} + +---@class hs.axuielement.axuielement +---@field actions[] any A table of common accessibility object action names, provided for reference. +---@field attributes[] any A table of common accessibility object attribute names which may be used with... +---@field orientations[] any A table of orientation types which may be used with hs.axuielement:elementSearch or hs.axuielement:matchesCriteria as... +---@field parameterizedAttributes[] any A table of common accessibility object parameterized attribute names, provided for reference. +---@field roles[] any A table of common accessibility object roles which may be used with hs.axuielement:elementSearch or... + +--- A table of common accessibility object action names, provided for reference. +---@type table +hs.axuielement.actions[] = nil + +--- A table of common accessibility object attribute names which may be used with +--- hs.axuielement:elementSearch +--- or +--- hs.axuielement:matchesCriteria +--- as keys in the match criteria argument. +---@type table +hs.axuielement.attributes[] = nil + +--- A table of orientation types which may be used with +--- hs.axuielement:elementSearch +--- or +--- hs.axuielement:matchesCriteria +--- as attribute values for "AXOrientation" in the match criteria argument. +---@type table +hs.axuielement.orientations[] = nil + +--- A table of common accessibility object parameterized attribute names, provided for reference. +---@type table +hs.axuielement.parameterizedAttributes[] = nil + +--- A table of common accessibility object roles which may be used with +--- hs.axuielement:elementSearch +--- or +--- hs.axuielement:matchesCriteria +--- as attribute values for "AXRole" in the match criteria argument. +---@type table +hs.axuielement.roles[] = nil + +--- A table of ruler marker types which may be used with +--- hs.axuielement:elementSearch +--- or +--- hs.axuielement:matchesCriteria +--- as attribute values for "AXMarkerType" in the match criteria argument. +---@type table +hs.axuielement.rulerMarkers[] = nil + +--- A table of sort direction types which may be used with +--- hs.axuielement:elementSearch +--- or +--- hs.axuielement:matchesCriteria +--- as attribute values for "AXSortDirection" in the match criteria argument. +---@type table +hs.axuielement.sortDirections[] = nil + +--- A table of common accessibility object subroles which may be used with +--- hs.axuielement:elementSearch +--- or +--- hs.axuielement:matchesCriteria +--- as attribute values for "AXSubrole" in the match criteria argument. +---@type table +hs.axuielement.subroles[] = nil + +--- A table of measurement unit types which may be used with +--- hs.axuielement:elementSearch +--- or +--- hs.axuielement:matchesCriteria +--- as attribute values for attributes which specify measurement unit types (e.g. "AXUnits", "AXHorizontalUnits", and +--- "AXVerticalUnits") in the match criteria argument. +---@type table +hs.axuielement.units[] = nil + +--- Returns a function for use with +--- hs.axuielement:elementSearch +--- that uses +--- hs.axuielement:matchesCriteria +--- with the specified criteria. +---@param criteria hs.axuielement +---@return function +function hs.axuielement.searchCriteriaFunction(criteria) end + +--- Returns the top-level accessibility object for the application specified by the +--- hs.application +--- object. +--- +--- Note: if applicationObject is a string or number, only the first item found with hs.application.find will be used +--- by this function to create an axuielementObject. +---@param applicationObject hs.application|hs.application.find +---@return hs.axuielement +function hs.axuielement.applicationElement(applicationObject) end + +--- Returns the top-level accessibility object for the application with the specified process ID. +---@param pid string +---@return hs.axuielement +function hs.axuielement.applicationElementForPID(pid) end + +--- Returns the accessibility object at the specified position on the screen. The top-left corner of the primary screen +--- is 0, 0. +--- +--- Note: See also hs.axuielement:elementAtPosition -- this function is a shortcut for +--- hs.axuielement.systemWideElement():elementAtPosition(...) . +--- This function does hit-testing based on window z-order (that is, layering). If one window is on top of another +--- window, the returned accessibility object comes from whichever window is topmost at the specified location. +---@param x table +---@param y | pointTable any +---@return hs.axuielement +function hs.axuielement.systemElementAtPosition(x, y | pointTable) end + +--- Returns an accessibility object that provides access to system attributes. +---@return hs.axuielement +function hs.axuielement.systemWideElement() end + +--- Returns the accessibility object for the window specified by the +--- hs.window +--- object. +--- +--- Note: if windowObject is a string or number, only the first item found with hs.window.find will be used by this +--- function to create an axuielementObject. +---@param windowObject hs.window|hs.window.find +---@return hs.axuielement +function hs.axuielement.windowElement(windowObject) end + +--- Returns a localized description of the specified accessibility object's action. +--- +--- Note: The action descriptions are provided by the target application; as such their accuracy and usefulness rely on +--- the target application's developers. +---@param action hs.axuielement +---@return string|nil +---@return any +function axuielement:actionDescription(action) end + +--- Returns a list of all the actions the specified accessibility object can perform. +--- +--- Note: Common action names can be found in the hs.axuielement.actions table; however, this method will list only +--- those names which are supported by this object, and is not limited to just those in the referenced table. +---@return table|nil +---@return any +function axuielement:actionNames() end + +--- Returns a table containing key-value pairs for all attributes of the accessibility object. +--- +--- Note: if includeErrors is not specified or is false, then attributes which exist for the element, but currently +--- have no value assigned, will not appear in the table. This is because Lua treats a nil value for a table's +--- key-value pair as an instruction to remove the key from the table, if it currently exists. +--- _code = -25212 +--- error = "Requested value does not exist" +---@param includeErrors boolean|nil +---@return table|nil +---@return any +function axuielement:allAttributeValues(includeErrors) end + +--- Query the accessibility object for all child accessibility objects and their descendants +--- +--- Note: This method is syntactic sugar for hs.axuielement:elementSearch(callback, { [includeParents = withParents] }) +--- . Please refer to hs.axuielement:elementSearch for details about the returned object and callback arguments. +---@param callback function +---@param withParents boolean|nil +---@return elementSearchObject +function axuielement:allDescendantElements(callback, withParents) end + +--- If the element refers to an application, return an +--- hs.application +--- object for the element. +--- +--- Note: An element is considered an application by this method if it has an AXRole of AXApplication and has a process +--- identifier (pid). +---@return hs.application|nil +function axuielement:asHSApplication() end + +--- If the element refers to a window, return an +--- hs.window +--- object for the element. +--- +--- Note: An element is considered a window by this method if it has an AXRole of AXWindow. +---@return hs.window|nil +function axuielement:asHSWindow() end + +--- Returns a list of all the attributes supported by the specified accessibility object. +--- +--- Note: Common attribute names can be found in the hs.axuielement.attributes tables; however, this method will list +--- only those names which are supported by this object, and is not limited to just those in the referenced table. +---@return table|nil +---@return any +function axuielement:attributeNames() end + +--- Returns the value of an accessibility object's attribute. +---@param attribute hs.axuielement +---@return nil +---@return any +function axuielement:attributeValue(attribute) end + +--- Returns the count of the array of an accessibility object's attribute value. +---@param attribute hs.axuielement +---@return number|nil +---@return any +function axuielement:attributeValueCount(attribute) end + +--- Captures all of the available information for the accessibility object and its descendants and returns it in a +--- table for inspection. +--- +--- Note: The format of the results table passed to the callback for this method is primarily for debugging and +--- exploratory purposes and may not be arranged for easy programatic evaluation. +--- This method is syntactic sugar for hs.axuielement:elementSearch(callback, { objectOnly = false, asTree = true, +--- [depth = depth], [includeParents = withParents] }) . Please refer to hs.axuielement:elementSearch for details about +--- the returned object and callback arguments. +---@param callback function +---@param depth number|nil +---@param withParents boolean +---@return elementSearchObject +function axuielement:buildTree(callback, depth, withParents) end + +--- Returns a table containing only those immediate children of the element that perform the specified role. +--- +--- Note: only the immediate children of the object are searched. +---@param role string +---@return table +function axuielement:childrenWithRole(role) end + +--- Return a duplicate userdata reference to the Accessibility object. +---@return hs.axuielement +function axuielement:copy() end + +--- Returns the accessibility object at the specified position on the screen. The top-left corner of the primary screen +--- is 0, 0. +--- +--- Note: This method can only be called on an axuielementObject that represents an application or the system-wide +--- element (see hs.axuielement.systemWideElement ). +--- This function does hit-testing based on window z-order (that is, layering). If one window is on top of another +--- window, the returned accessibility object comes from whichever window is topmost at the specified location. +--- If this method is called on an axuielementObject representing an application, the search is restricted to the +--- application. +--- If this method is called on an axuielementObject representing the system-wide element, the search is not restricted +--- to any particular application. See hs.axuielement.systemElementAtPosition . +---@param x table +---@param y | pointTable any +---@return hs.axuielement|nil +---@return any +function axuielement:elementAtPosition(x, y | pointTable) end + +--- Search for and generate a table of the accessibility elements for the attributes and descendants of this object +--- based on the specified criteria. +--- +--- Note: This method utilizes coroutines to keep Hammerspoon responsive, but may be slow to complete if includeParents +--- is true, if you do not specify depth , or if you start from an element that has a lot of descendants (e.g. the +--- application element for a web browser). This is dependent entirely upon how many active accessibility elements the +--- target application defines and where you begin your search and cannot reliably be determined up front, so you may +--- need to experiment to find the best balance for your specific requirements. +--- The search performed is a breadth-first search, so in general earlier elements in the results table will be +--- "closer" in the Accessibility hierarchy to the starting point than later elements. +--- The exception to this is when asTree is true and objectsOnly is false and the search criteria is nil -- see +--- hs.axuielement:buildTree . In this case, the results passed to the callback will be equal to elementSearchObject[1] +--- . +--- If objectsOnly is specified as false, it may take some time after cancel is invoked for the mapping of element +--- attribute tables to the descendant elements in the results set -- this is a by product of the need to iterate +--- through the results to match up all of the instances of each element to it's attribute table. +--- hs.axuielement:allDescendantElements is syntactic sugar for hs.axuielement:elementSearch(callback, { +--- [includeParents = withParents] }) +--- hs.axuielement:buildTree is syntactic sugar for hs.axuielement:elementSearch(callback, { objectOnly = false, asTree +--- = true, [depth = depth], [includeParents = withParents] }) +---@param callback function +---@param criteria hs.axuielement.searchCriteriaFunction|hs.axuielement|nil +---@param namedModifiers any +---@return elementSearchObject +function axuielement:elementSearch(callback, criteria, namedModifiers) end + +--- Returns whether the specified accessibility object's attribute can be modified. +---@param attribute hs.axuielement +---@return boolean|nil +---@return any +function axuielement:isAttributeSettable(attribute) end + +--- Returns whether the specified accessibility object is still valid. +--- +--- Note: an accessibilityObject can become invalid for a variety of reasons, including but not limited to the element +--- referred to no longer being available (e.g. an element referring to a window or one of its descendants that has +--- been closed) or the application terminating. +---@return boolean|nil +---@return any +function axuielement:isValid() end + +--- Returns true if the axuielementObject matches the specified criteria or false if it does not. +--- +--- Note: a single string, specifying the value the element's AXRole attribute must equal for a positive match +--- an array table of strings specifying a list of possible values the element's AXRole attribute can equal for a +--- positive match +--- attribute -- a string, or table of strings, specifying attributes that the element must support. +--- action -- a string, or table of strings, specifying actions that the element must be able to perform. +--- parameterizedAttribute -- a string, or table of strings, specifying parametrized attributes that the element must +--- support. +--- only those keys which are specified within the value are checked for equality (or pattern matching). Values which +--- are present in the attribute's value but are not specified in the comparison value are ignored (i.e. the previous +--- example of y = 22 would only check the y component of an AXFrame attribute -- the x , h , and w values would be +--- ignored). +--- For value components which are numeric, e.g. 22 in the previous example, the default comparison is equality. You +--- may change this with the comparison key described below in the optional keys. +--- For possible keys when trying to match a color, see the documentation for hs.drawing.color . +--- For possible keys when trying to match a URL, use url = and/or filePath = . The string for the +--- specified table key will be compared in accordance with the pattern optional key described below. +--- Order of the elements provided in the comparison value does not matter -- this only tests for existence within the +--- attributes value. +--- The test is for inclusion only -- the attribute's value may contain other elements as well, but must contain those +--- specified within the comparison value. +--- nilValue -- a boolean, specifying that the attributes must not have an assigned value (true) or may be assigned any +--- value except nil (false). If the value key is specified, this key is ignored. Note that this applies to all of the +--- attributes specified with the attribute key. +--- pattern -- a boolean, default false, specifying whether string matches for attribute values should be evaluated +--- with string.match (true) or as exact matches (false). See the Lua manual, section 6.4.1 ( help.lua._man._6_4_1 in +--- the Hammerspoon console). If the value key is not set, than this key is ignored. +--- invert -- a boolean, default false, specifying inverted logic for the criteria result --- if this is true and the +--- criteria matches, evaluate criteria as false; otherwise evaluate as true. +--- comparison -- a string, default "==", specifying the comparison to be used when comparing numeric values. Possible +--- comparison strings are: "==" for equality, "<" for less than, "<=" for less than or equal to, ">" for greater than, +--- ">=" for greater than or equal to, or "~=" for not equal to. +--- an array table of one or more key-value tables as described immediately above; the element must be a positive match +--- for all of the individual criteria tables specified (logical AND). +--- This method is used by hs.axuielement.searchCriteriaFunction to create criteria functions compatible with +--- hs.axuielement:elementSearch . +---@param criteria any +---@return boolean +function axuielement:matchesCriteria(criteria) end + +--- Returns a list of all the parameterized attributes supported by the specified accessibility object. +---@return table|nil +---@return any +function axuielement:parameterizedAttributeNames() end + +--- Returns the value of an accessibility object's parameterized attribute. +--- +--- Note: The specific parameter required for a each parameterized attribute is different and is often application +--- specific thus requiring some experimentation. Notes regarding identified parameter types and thoughts on some still +--- being investigated will be provided in the Hammerspoon Wiki, hopefully shortly after this module becomes part of a +--- Hammerspoon release. +---@param attribute hs.axuielement +---@param parameter any +---@return nil +---@return any +function axuielement:parameterizedAttributeValue(attribute, parameter) end + +--- Returns a table of axuielements tracing this object through its parent objects to the root for this element, most +--- likely an application object or the system wide object. +--- +--- Note: this object will always exist as the last element in the table (e.g. at table[#table] ) with its most +--- immediate parent at #table - 1 , etc. until the rootmost object for this element is reached at index position 1. +--- an axuielement object representing an application or the system wide object is its own rootmost object and will +--- return a table containing only itself (i.e. #table will equal 1) +---@return table +function axuielement:path() end + +--- Requests that the specified accessibility object perform the specified action. +--- +--- Note: The return value only suggests success or failure, but is not a guarantee. The receiving application may +--- have internal logic which prevents the action from occurring at this time for some reason, even though this method +--- returns success (the axuielementObject). Contrawise, the requested action may trigger a requirement for a response +--- from the user and thus appear to time out, causing this method to return false or nil. +---@param action hs.axuielement +---@return axuielement|boolean|nil +---@return any +function axuielement:performAction(action) end + +--- Returns the process ID associated with the specified accessibility object. +---@return number|nil +---@return any +function axuielement:pid() end + +--- Sets the accessibility object's attribute to the specified value. +---@param attribute hs.axuielement +---@param value any +---@return hs.axuielement|nil +---@return any +function axuielement:setAttributeValue(attribute, value) end + +--- Sets the timeout value used accessibility queries performed from this element. +--- +--- Note: To change the global timeout affecting all queries on elements which do not have a specific timeout set, use +--- this method on the systemwide element (see hs.axuielement.systemWideElement . +--- Changing the timeout value for an axuielement object only changes the value for that specific element -- other +--- axuieleement objects that may refer to the identical accessibility item are not affected. +--- Setting the value to 0.0 resets the timeout -- if applied to the systemWideElement , the global default will be +--- reset to its default value; if applied to another axuielement object, the timeout will be reset to the current +--- global value as applied to the systemWideElement. +---@param value number +---@return hs.axuielement|nil +---@return any +function axuielement:setTimeout(value) end + +-- ------------------------------------------------------------ +-- hs.axuielement.axtextmarker +-- ------------------------------------------------------------ + +---@class hs.axuielement.axtextmarker +hs.axuielement.axtextmarker = {} + +---@class axtextmarker +local axtextmarker = {} + +--- Returns a table of the AXTextMarker and AXTextMarkerRange functions that have been discovered and are used within +--- this module. +--- +--- Note: the functions are defined within the HIServices framework which is part of the ApplicationServices framework, +--- so it is expected that the necessary functions will always be available; however, if you ever receive an error +--- message from a function or method within this submodule of the form "CF function AX... undefined", please see the +--- submodule heading documentation for a description of the information, including that which this function provides, +--- that should be included in any error report you submit. +--- This is for debugging purposes and is not expected to be used often. +---@return table +function hs.axuielement.axtextmarker._functionCheck() end + +--- Returns a string containing the opaque binary data contained within the axTextMarkerObject +--- +--- Note: the string will likely contain invalid UTF8 code sequences or unprintable ascii values; to see the data in +--- decimal or hexadecimal form you can use: +--- string.byte(hs.axuielement.axtextmarker:bytes(), 1, hs.axuielement.axtextmarker:length()) +--- -- or +--- hs.utf8.hexDump(hs.axuielement.axtextmarker:bytes()) +--- As the data is application specific, it is unlikely that you will use this method often; it is included primarily +--- for testing and debugging purposes. +---@return string|nil +---@return errorString +function axtextmarker:bytes() end + +--- Returns the ending marker for an axTextMarkerRangeObject +---@return hs.axuielement.axtextmarker|nil +---@return errorString +function axtextmarker:endMarker() end + +--- Returns an integer specifying the number of bytes in the data portion of the axTextMarkerObject. +--- +--- Note: As the data is application specific, it is unlikely that you will use this method often; it is included +--- primarily for testing and debugging purposes. +---@return number|nil +---@return errorString +function axtextmarker:length() end + +--- Returns the starting marker for an axTextMarkerRangeObject +---@return hs.axuielement.axtextmarker|nil +---@return errorString +function axtextmarker:startMarker() end + +--- Creates a new AXTextMarker object from the string of binary data provided +--- +--- Note: This function is included primarily for testing and debugging purposes -- in general you will probably never +--- use this constructor; AXTextMarker objects appear to be mostly application dependant and have no meaning external +--- to the application from which it was created. +---@param string string +---@return hs.axuielement.axtextmarker|nil +---@return errorString +function hs.axuielement.axtextmarker.newMarker(string) end + +--- Creates a new AXTextMarkerRange object from the start and end markers provided +--- +--- Note: this constructor can be used to create a range from axTextMarkerObjects obtained from an application to +--- specify a new range for a parameterized attribute. As a simple example (it is hoped that more will be added to the +--- Hammerspoon wiki shortly): s = hs . axuielement . applicationElement ( hs . application ( "Safari" )) -- for a +--- window displaying the DuckDuckGo main search page, this gets the -- primary display area. Other pages may vary and +--- you should build your -- object as necessary for your target. c = s ( "AXMainWindow" )( "AXSections" )[ 1 ]. +--- SectionObject [ 1 ][ 1 ] start = c ( "AXStartTextMarker" ) -- get the text marker for the start of this element +--- ending = c ( "AXNextLineEndTextMarkerForTextMarker" , start ) -- get the next end of line marker print ( c ( +--- "AXStringForTextMarkerRange" , hs . axuielement . axtextmarker . newRange ( start , ending ))) -- outputs "Privacy, +--- simplified." to the Hammerspoon console``` +--- The specific attributes and parameterized attributes supported by a given application differ and can be discovered +--- with the hs.axuielement:getAttributeNames and hs.axuielement:getParameterizedAttributeNames methods. +---@param startMarker any +---@param endMarker any +---@return hs.axuielement.axtextmarker|nil +---@return errorString +function hs.axuielement.axtextmarker.newRange(startMarker, endMarker) end + +-- ------------------------------------------------------------ +-- hs.axuielement.observer +-- ------------------------------------------------------------ + +---@class hs.axuielement.observer +hs.axuielement.observer = {} + +---@class observer +local observer = {} + +--- A table of common accessibility object notification names, provided for reference. +---@type table +hs.axuielement.observer.notifications[] = nil + +--- Creates a new observer object for the application with the specified process ID. +--- +--- Note: If you already have the hs.application object for an application, you can get its process ID with +--- hs.application:pid() +--- If you already have an hs.axuielement from the application you wish to observe (it doesn't have to be the +--- application axuielement object, just one belonging to the application), you can get the process ID with +--- hs.axuielement:pid() . +---@param pid string +---@return hs.axuielement.observer +function hs.axuielement.observer.new(pid) end + +--- Registers the specified notification for the specified accessibility element with the observer. +--- +--- Note: multiple notifications for the same accessibility element can be registered by invoking this method multiple +--- times with the same element but different notification strings. +--- if the specified element and notification string are already registered, this method does nothing. +--- the notification string is application dependent and can be any string that the application developers choose; some +--- common ones are found in hs.axuielement.observer.notifications , but the list is not exhaustive nor is an +--- application or element required to provide them. +---@param element hs.axuielement +---@param notification string +---@return hs.axuielement.observer +function observer:addWatcher(element, notification) end + +--- Get or set the callback for the observer. +--- +--- Note: the observerObject itself +--- the hs.axuielement object for the accessibility element which generated the notification +--- a string specifying the specific notification which was received +--- a table containing key-value pairs with more information about the notification, if the element and notification +--- type provide it. Commonly this will be an empty table indicating that no additional detail was provided. +---@param fn function +---@return hs.axuielement.observer|fn|nil +function observer:callback(fn) end + +--- Returns true or false indicating whether the observer is currently watching for notifications and generating +--- callbacks. +---@return boolean +function observer:isRunning() end + +--- Unregisters the specified notification for the specified accessibility element from the observer. +--- +--- Note: if the specified element and notification string are not currently registered with the observer, this method +--- does nothing. +---@param element hs.axuielement +---@param notification string +---@return hs.axuielement.observer +function observer:removeWatcher(element, notification) end + +--- Start observing the application and trigger callbacks for the elements and notifications assigned. +--- +--- Note: This method does nothing if the observer is already running +---@return hs.axuielement.observer +function observer:start() end + +--- Stop observing the application; no further callbacks will be generated. +--- +--- Note: This method does nothing if the observer is not currently running +---@return hs.axuielement.observer +function observer:stop() end + +--- Returns a table of the notifications currently registered with the observer. +--- +--- Note: If an element is specified, then the table returned will contain a list of strings specifying the specific +--- notifications that the observer is watching that element for. +--- If no argument is specified, then the table will contain key-value pairs in which each key will be an +--- hs.axuielement that is being observed and the corresponding value will be a table containing a list of strings +--- specifying the specific notifications that the observer is watching for from that element. +---@param element hs.axuielement|nil +---@return table +function observer:watching(element) end + +-- ------------------------------------------------------------ +-- hs.base64 +-- ------------------------------------------------------------ + +---@class hs.base64 +hs.base64 = {} + +--- Decodes a given base64 string +---@param str string +---@return val +function hs.base64.decode(str) end + +--- Encodes a given string to base64 +---@param val string +---@param width? number +---@return str +function hs.base64.encode(val, width) end + +-- ------------------------------------------------------------ +-- hs.battery +-- ------------------------------------------------------------ + +---@class hs.battery +hs.battery = {} + +--- Returns a table containing all of the details concerning the Mac's powersource(s). +--- +--- Note: hs.battery._adapterDetails() +--- hs.battery._powerSources() +--- hs.battery._appleSmartBattery() +--- hs.battery._iopmBatteryInfo() +--- You can view this report by typing hs.inspect(hs.battery._report()) (or a subset of it by using one of the above +--- listed functions instead) -- it will primarily be of interest when debugging or extending this module and generally +--- not necessary to use. +---@return table +function hs.battery._report() end + +--- Returns the serial number of the attached power supply, if present +---@return number|string +function hs.battery.adapterSerialNumber() end + +--- Returns the amount of current flowing through the battery, in mAh +---@return number +function hs.battery.amperage() end + +--- Returns the serial number of the battery, if present +---@return string +function hs.battery.batterySerialNumber() end + +--- Returns the type of battery present, or nil if there is no battery +---@return string +function hs.battery.batteryType() end + +--- Returns the current capacity of the battery in mAh +--- +--- Note: This is the measure of how charged the battery is, vs the value of hs.battery.maxCapacity() +---@return number +function hs.battery.capacity() end + +--- Returns the number of discharge cycles of the battery +--- +--- Note: One cycle is a full discharge of the battery, followed by a full charge. This may also be an aggregate of +--- many smaller discharge-then-charge cycles (e.g. 10 iterations of discharging the battery from 100% to 90% and then +--- charging back to 100% each time, is considered to be one cycle) +---@return number +function hs.battery.cycles() end + +--- Returns the design capacity of the battery in mAh. +---@return number +function hs.battery.designCapacity() end + +--- Get all available battery information +--- +--- Note: If you require multiple pieces of information about a battery, this function may be more efficient than +--- calling several other functions separately +---@return table +function hs.battery.getAll() end + +--- Returns the health status of the battery. +---@return string +function hs.battery.health() end + +--- Returns the health condition status of the battery. +---@return string|nil +function hs.battery.healthCondition() end + +--- Returns the charged state of the battery +---@return boolean +function hs.battery.isCharged() end + +--- Returns the charging state of the battery +---@return boolean +function hs.battery.isCharging() end + +--- Returns true if battery is finishing its charge +---@return boolean|string +function hs.battery.isFinishingCharge() end + +--- Returns the maximum capacity of the battery in mAh +--- +--- Note: This may exceed the value of hs.battery.designCapacity() due to small variations in the production chemistry +--- vs the design +---@return number +function hs.battery.maxCapacity() end + +--- Returns the name of the battery +---@return string +function hs.battery.name() end + +--- Returns information about non-PSU batteries (e.g. Bluetooth accessories) +---@return table +function hs.battery.otherBatteryInfo() end + +--- Returns the current percentage of battery charge +---@return number +function hs.battery.percentage() end + +--- Returns the current source providing power +---@return string +function hs.battery.powerSource() end + +--- Returns current power source type +---@return string +function hs.battery.powerSourceType() end + +--- Returns information about Bluetooth devices using Apple Private APIs +--- +--- Note: This function uses private Apple APIs - that means it can break without notice on any macOS version update. +--- Please report breakage to us! +--- This function will return information for all connected Bluetooth devices, but much of it will be meaningless for +--- most devices +--- vendorID - Numerical identifier for the vendor of the device (Apple's ID is 76) +--- productID - Numerical identifier for the device +--- address - The Bluetooth address of the device +--- isApple - A string containing "YES" or "NO", depending on whether or not this is an Apple/Beats product, or a third +--- party product +--- name - A human readable string containing the name of the device +--- batteryPercentSingle - For some devices this will contain the percentage of the battery (e.g. Beats headphones) +--- batteryPercentCombined - We do not currently understand what this field represents, please report if you find a +--- non-zero value here +--- batteryPercentCase - Battery percentage of AirPods cases (note that this will often read 0 - the AirPod case sleeps +--- aggressively) +--- batteryPercentLeft - Battery percentage of the left AirPod if it is out of the case +--- batteryPercentRight - Battery percentage of the right AirPod if it is out of the case +--- buttonMode - We do not currently understand what this field represents, please report if you find a value other +--- than 1 +--- micMode - For AirPods this corresponds to the microphone option in the device's Bluetooth options +--- leftDoubleTap - For AirPods this corresponds to the left double tap action in the device's Bluetooth options +--- rightDoubleTap - For AirPods this corresponds to the right double tap action in the device's Bluetooth options +--- primaryBud - For AirPods this is either "left" or "right" depending on which bud is currently considered the +--- primary device +--- primaryInEar - For AirPods this is "YES" or "NO" depending on whether or not the primary bud is currently in an ear +--- secondaryInEar - For AirPods this is "YES" or "NO" depending on whether or not the secondary bud is currently in an +--- ear +--- isInEarDetectionSupported - Whether or not this device can detect when it is currently in an ear +--- isEnhancedDoubleTapSupported - Whether or not this device supports double tapping +--- isANCSupported - We believe this likely indicates whether or not this device supports Active Noise Cancelling (e.g. +--- Beats Solo) +--- Please report any crashes from this function - it's likely that there are Bluetooth devices we haven't tested which +--- may return weird data +--- Many/Most/All non-Apple party products will likely return zeros for all of the battery related fields here, as will +--- Apple HID devices. It seems that these private APIs mostly exist to support Apple/Beats headphones. +---@return table +function hs.battery.privateBluetoothBatteryInfo() end + +--- Returns the battery life remaining, in minutes +---@return number +function hs.battery.timeRemaining() end + +--- Returns the time remaining for the battery to be fully charged, in minutes +---@return number +function hs.battery.timeToFullCharge() end + +--- Returns the current voltage of the battery in mV +---@return number +function hs.battery.voltage() end + +--- Returns a string specifying the current battery warning state. +--- +--- Note: "none" - indicates that the system is not in a low battery situation, or is currently attached to an AC power +--- source. +--- "low" - the system is in a low battery situation and can provide no more than 20 minutes of runtime. Note that +--- this is a guess only; 20 minutes cannot be guaranteed and will be greatly influenced by what the computer is doing +--- at the time, how many applications are running, screen brightness, etc. +--- "critical" - the system is in a very low battery situation and can provide no more than 10 minutes of runtime. Note +--- that this is a guess only; 10 minutes cannot be guaranteed and will be greatly influenced by what the computer is +--- doing at the time, how many applications are running, screen brightness, etc. +---@return string +function hs.battery.warningLevel() end + +--- Returns the power entering or leaving the battery, in W +---@return number +function hs.battery.watts() end + +-- ------------------------------------------------------------ +-- hs.battery.watcher +-- ------------------------------------------------------------ + +---@class hs.battery.watcher +hs.battery.watcher = {} + +---@class watcher +local watcher = {} + +--- Creates a battery watcher +--- +--- Note: Because the callback function accepts no arguments, tracking of state of changing battery attributes is the +--- responsibility of the user (see https://github.com/Hammerspoon/hammerspoon/issues/166 for discussion) +---@param fn function +---@return watcher +function hs.battery.watcher.new(fn) end + +--- Starts the battery watcher +---@return self +function watcher:start() end + +--- Stops the battery watcher +---@return self +function watcher:stop() end + +-- ------------------------------------------------------------ +-- hs.bonjour +-- ------------------------------------------------------------ + +---@class hs.bonjour +hs.bonjour = {} + +---@class bonjour +local bonjour = {} + +--- Polls a host for the service types it is advertising via multicast DNS. +--- +--- Note: this function may not work for all clients implementing multicast DNS; it has been successfully tested with +--- macOS and Linux targets running the Avahi Daemon service, but has generally returned an error when used with +--- minimalist implementations found in common IOT devices and embedded electronics. +---@param target string +---@param callback function +---@return none +function hs.bonjour.machineServices(target, callback) end + +--- Returns a list of service types being advertised on your local network. +--- +--- Note: This function is a convenience wrapper to hs.bonjour:findServices which collects the results from multiple +--- callbacks made to findServices and returns them all at once to the callback function provided as an argument to +--- this function. +--- This is a best guess made by the macOS which may not always be accurate if your local network is particularly slow +--- or if there are machines on your network which are slow to respond. +--- See hs.bonjour:findServices for more details if you need to create your own query which can persist for longer +--- periods of time or require termination logic that ignores the macOS's best guess. +---@param callback function +---@param timeout function|nil +---@return none +function hs.bonjour.networkServices(callback, timeout) end + +--- Creates a new network service browser that finds published services on a network using multicast DNS. +---@return hs.bonjour +function hs.bonjour.new() end + +--- Return a list of zero-conf and bonjour domains visible to the users computer. +--- +--- Note: This method returns domains which are visible to your machine; however, your machine may or may not be able +--- to access or publish records within the returned domains. See hs.bonjour:findRegistrationDomains +--- For most non-corporate network users, it is likely that the callback will only be invoked once for the local +--- domain. This is normal. Corporate networks or networks including Linux machines using additional domains defined +--- with Avahi may see additional domains as well, though most Avahi installations now use only 'local' by default +--- unless specifically configured to do otherwise. +--- Generally macOS is fairly accurate in this regard concerning domain searches, so to reduce the impact on system +--- resources, it is recommended that you use hs.bonjour:stop when this parameter is false +---@param callback function +---@return hs.bonjour +function bonjour:findBrowsableDomains(callback) end + +--- Return a list of zero-conf and bonjour domains this computer can register services in. +--- +--- Note: This is the preferred method for accessing domains as it guarantees that the host machine can connect to +--- services in the returned domains. Access to domains outside this list may be more limited. See also +--- hs.bonjour:findBrowsableDomains +--- For most non-corporate network users, it is likely that the callback will only be invoked once for the local +--- domain. This is normal. Corporate networks or networks including Linux machines using additional domains defined +--- with Avahi may see additional domains as well, though most Avahi installations now use only 'local' by default +--- unless specifically configured to do otherwise. +--- Generally macOS is fairly accurate in this regard concerning domain searches, so to reduce the impact on system +--- resources, it is recommended that you use hs.bonjour:stop when this parameter is false +---@param callback function +---@return hs.bonjour +function bonjour:findRegistrationDomains(callback) end + +--- Find advertised services of the type specified. +--- +--- Note: macOS will indicate when it believes there are no more advertisements of the type specified by type in domain +--- by marking the last argument to your callback function as false. This is a best guess and may not always be +--- accurate if your network is slow or some servers on your network are particularly slow to respond. +--- In addition, if you leave the browser running this method, you will get future updates when services are removed +--- because of server shutdowns or added because of new servers being booted up. +--- Leaving the browser running does consume some system resources though, so you will have to determine, based upon +--- your specific requirements, if this is a concern for your specific task or not. To terminate the browser when you +--- have retrieved all of the information you require, you can use the hs.bonjour:stop method. +--- this special type is used by the shortcut function hs.bonjour.networkServices for this specific purpose. +--- In theory, with additional software, you may be able to publish services on your machine for Wide-Area Service +--- discovery using this domain with hs.bonjour.service.new but the local dns server requirements and security +--- implications of doing so are beyond the scope of this documentation. You should refer to http://www.dns-sd.org and +--- your local DNS Server administrator or provider for more details. +---@param type string +---@param domain string|nil +---@param callback function +---@return hs.bonjour +function bonjour:findServices(type, domain, callback) end + +--- Get or set whether to also browse over peer-to-peer Bluetooth and Wi-Fi, if available. +--- +--- Note: This property must be set before initiating a search to have an effect. +---@param value boolean|nil +---@return hs.bonjour +function bonjour:includesPeerToPeer(value) end + +--- Stops a currently running search or resolution for the browser object +--- +--- Note: This method should be invoked when you have identified the services or hosts you require to reduce the +--- consumption of system resources. +--- Invoking this method on an already idle browser will do nothing +--- In general, when your callback function for hs.bonjour:findBrowsableDomains , hs.bonjour:findRegistrationDomains , +--- or hs.bonjour:findServices receives false for the moreExpected parameter, you should invoke this method on the +--- browserObject unless there are specific reasons not to. Possible reasons you might want to extend the life of the +--- browserObject are documented within each method. +---@return hs.bonjour +function bonjour:stop() end + +-- ------------------------------------------------------------ +-- hs.bonjour.service +-- ------------------------------------------------------------ + +---@class hs.bonjour.service +hs.bonjour.service = {} + +---@class service +local service = {} + +--- A list of common service types which can used for discovery through this module. +---@type common[] +hs.bonjour.serviceTypes = nil + +--- Returns a new serviceObject for advertising a service provided by your computer. +--- +--- Note: If the name specified is not unique on the network for the service type specified, then a number will be +--- appended to the end of the name. This behavior cannot be overridden and can only be detected by checking +--- hs.bonjour.service:name after hs.bonjour.service:publish is invoked to see if the name has been changed from what +--- you originally assigned. +--- The service will not be advertised until hs.bonjour.service:publish is invoked on the serviceObject returned. +--- If you do not specify the domain parameter, your default domain, usually "local" will be used. +---@param name string +---@param service string +---@param port any +---@param domain string|nil +---@return hs.bonjour.service +function hs.bonjour.service.new(name, service, port, domain) end + +--- Returns a new serviceObject for a remote machine (i.e. not the users computer) on your network offering the +--- specified service. +--- +--- Note: In general you should not need to use this constructor, as they will be created automatically for you in the +--- callbacks to hs.bonjour:findServices . +--- This method can be used, however, when you already know that a specific service should exist on the network and you +--- wish to resolve its current IP addresses or text records. +--- Resolution of the service ip address, hostname, port, and current text records will not occur until +--- hs.bonjour.service:publish is invoked on the serviceObject returned. +--- The macOS API specifies that an empty domain string (i.e. specifying the domain parameter as "" or leaving it off +--- completely) should result in using the default domain for the computer; in my experience this results in an error +--- when attempting to resolve the serviceObject's ip addresses if I don't specify "local" explicitly. In general this +--- shouldn't be an issue if you limit your use of remote serviceObjects to those returned by hs.bonjour:findServices +--- as the domain of discovery will be included in the object for you automatically. If you do try to create these +--- objects independently yourself, be aware that attempting to use the "default domain" rather than specifying it +--- explicitly will probably not work as expected. +---@param name string +---@param service string +---@param domain string|nil +---@return hs.bonjour.service +function hs.bonjour.service.remote(name, service, domain) end + +--- Returns a table listing the addresses for the service represented by the serviceObject +--- +--- Note: for remote serviceObjects, the table will be empty if this method is invoked before +--- hs.bonjour.service:resolve . +--- for local (published) serviceObjects, this table will always be empty. +---@return table +function service:addresses() end + +--- Returns the domain the service represented by the serviceObject belongs to. +--- +--- Note: for remote serviceObjects, this domain will be the domain the service was discovered in. +--- for local (published) serviceObjects, this domain will be the domain the service is published in; if you did not +--- specify a domain with hs.bonjour.service.new then this will be an empty string until hs.bonjour.service:publish is +--- invoked. +---@return string +function service:domain() end + +--- Returns the hostname of the machine the service represented by the serviceObject belongs to. +--- +--- Note: for remote serviceObjects, this will be nil if this method is invoked before hs.bonjour.service:resolve . +--- for local (published) serviceObjects, this method will always return nil. +---@return string +function service:hostname() end + +--- Get or set whether the service represented by the service object should be published or resolved over peer-to-peer +--- Bluetooth and Wi-Fi, if available. +--- +--- Note: if you are changing the value of this property, you must call this method before invoking +--- [hs.bonjour.service:publish](#publish] or hs.bonjour.service:resolve , or after stopping publishing or resolving +--- with hs.bonjour.service:stop . +--- for remote serviceObjects, this flag determines if resolution and text record monitoring should occur over +--- peer-to-peer network interfaces. +--- for local (published) serviceObjects, this flag determines if advertising should occur over peer-to-peer network +--- interfaces. +---@param value boolean|nil +---@return boolean|hs.bonjour.service +function service:includesPeerToPeer(value) end + +--- Monitor the service for changes to its associated text records. +--- +--- Note: When monitoring is active, hs.bonjour.service:txtRecord will return the most recent text records observed. If +--- this is the only method by which you check the text records, but you wish to ensure you have the most recent +--- values, you should invoke this method without specifying a callback. +--- When hs.bonjour.service:resolve is invoked, the text records at the time of resolution are captured for retrieval +--- with hs.bonjour.service:txtRecord . Subsequent changes to the text records will not be reflected by +--- hs.bonjour.service:txtRecord unless this method has been invoked (with or without a callback function) and is +--- currently active. +--- You can monitor for text changes on local serviceObjects that were created by hs.bonjour.service.new and that you +--- are publishing. This can be used to invoke a callback when one portion of your code makes changes to the text +--- records you are publishing and you need another portion of your code to be aware of this change. +---@param callback function +---@return hs.bonjour.service +function service:monitor(callback) end + +--- Returns the name of the service represented by the serviceObject. +---@return string +function service:name() end + +--- Returns the port the service represented by the serviceObject is available on. +--- +--- Note: for remote serviceObjects, this will be -1 if this method is invoked before hs.bonjour.service:resolve . +--- for local (published) serviceObjects, this method will always return the number specified when the serviceObject +--- was created with the hs.bonjour.service.new constructor. +---@return number +function service:port() end + +--- Begin advertising the specified local service. +--- +--- Note: this method should only be called on serviceObjects which were created with hs.bonjour.service.new . +---@param allowRename boolean|nil +---@param callback function +---@return hs.bonjour.service +function service:publish(allowRename, callback) end + +--- Resolve the address and details for a discovered service. +--- +--- Note: this method should only be called on serviceObjects which were returned by an hs.bonjour browserObject or +--- created with hs.bonjour.service.remote . +--- For a remote service, this method must be called in order to retrieve the addresses , the port , the hostname , and +--- any the associated text records for the service. +--- To reduce the usage of system resources, you should generally specify a timeout value or make sure to invoke +--- hs.bonjour.service:stop after you have verified that you have received the details you require. +---@param timeout number|nil +---@param callback function +---@return hs.bonjour.service +function service:resolve(timeout, callback) end + +--- Stop advertising or resolving the service specified by the serviceObject +--- +--- Note: this method will stop the advertising of a service which has been published with hs.bonjour.service:publish +--- or is being resolved with hs.bonjour.service:resolve . +--- To reduce the usage of system resources, you should make sure to use this method when resolving a remote service if +--- you did not specify a timeout for hs.bonjour.service:resolve or specified a timeout of 0.0 once you have verified +--- that you have the details you need. +---@return hs.bonjour.service +function service:stop() end + +--- Stop monitoring a service for changes to its text records. +--- +--- Note: This method will stop updating hs.bonjour.service:txtRecord and invoking the callback, if any, assigned with +--- hs.bonjour.service:monitor . +---@return hs.bonjour.service +function service:stopMonitoring() end + +--- Get or set the text records associated with the serviceObject. +--- +--- Note: for remote serviceObjects, this method will return nil if invoked before hs.bonjour.service:resolve +--- setting the text record for a service replaces the existing records for the serviceObject. If the serviceObject is +--- remote, this change is only visible on the local machine. For a service you are advertising, this change will be +--- advertised to other machines. +--- Text records are usually used to provide additional information concerning the service and their purpose and +--- meanings are service dependant; for example, when advertising an _http._tcp. service, you can specify a specific +--- path on the server by specifying a table of text records containing the "path" key. +---@param records table|nil +---@return table|hs.bonjour.service|boolean +function service:txtRecord(records) end + +--- Returns the type of service represented by the serviceObject. +---@return string +function service:type() end + +-- ------------------------------------------------------------ +-- hs.brightness +-- ------------------------------------------------------------ + +---@class hs.brightness +hs.brightness = {} + +--- Gets the current ambient brightness +--- +--- Note: Even though external Apple displays include an ambient light sensor, their data is typically not available, +--- so this function will likely only be useful to MacBook users +--- On Silicon based macs, this function uses a method similar to that used by corebrightnessdiag to retrieve the +--- aggregate lux as reported to sysdiagnose . +--- On Intel based macs, the raw sensor data is converted to lux via an algorithm used by Mozilla Firefox and is not +--- guaranteed to give an accurate lux value. +---@return number +function hs.brightness.ambient() end + +--- Returns the current brightness of the display +---@return number +function hs.brightness.get() end + +--- Sets the display brightness +---@param brightness number +---@return boolean +function hs.brightness.set(brightness) end + +-- ------------------------------------------------------------ +-- hs.caffeinate +-- ------------------------------------------------------------ + +---@class hs.caffeinate +hs.caffeinate = {} + +--- Fetches information about processes which are currently asserting display/power sleep restrictions +---@return table +function hs.caffeinate.currentAssertions() end + +--- Informs the OS that the user performed some activity +--- +--- Note: This is intended to simulate user activity, for example to prevent displays from sleeping, or to wake them up +--- It is not mandatory to re-use assertion IDs if you are calling this function multiple times, but it is recommended +--- that you do so if the calls are related +---@param id number +---@return number +function hs.caffeinate.declareUserActivity(id) end + +--- Show the Fast User Switch screen (ie a login screen without logging out first) +---@return any +function hs.caffeinate.fastUserSwitch() end + +--- Queries whether a particular sleep type is being prevented +---@param sleepType string +---@return boolean|nil +function hs.caffeinate.get(sleepType) end + +--- Locks the displays +--- +--- Note: This function uses private Apple APIs and could therefore stop working in any given release of macOS without +--- warning. +---@return any +function hs.caffeinate.lockScreen() end + +--- Request the system log out the current user +---@return any +function hs.caffeinate.logOut() end + +--- Request the system reboot +---@return any +function hs.caffeinate.restartSystem() end + +--- Fetches information from the display server about the current session +--- +--- Note: The keys in this dictionary will vary based on the current state of the system (e.g. local vs VNC login, +--- screen locked vs unlocked). +---@return table|nil +function hs.caffeinate.sessionProperties() end + +--- Configures the sleep prevention settings +--- +--- Note: These calls are not guaranteed to prevent the system sleep behaviours described above. The OS may override +--- them if it feels it must (e.g. if your CPU temperature becomes dangerously high). +--- The acAndBattery argument only applies to the system sleep type. +--- You can toggle the acAndBattery state by calling hs.caffeinate.set() again and altering the acAndBattery value. +--- The acAndBattery option does not appear to work anymore - it is based on private API that is not allowed in macOS +--- 10.15 when running with the Hardened Runtime (which Hammerspoon now uses). +---@param sleepType any +---@param aValue boolean +---@param acAndBattery boolean +---@return any +function hs.caffeinate.set(sleepType, aValue, acAndBattery) end + +--- Request the system log out and power down +---@return any +function hs.caffeinate.shutdownSystem() end + +--- Request the system start the screensaver (which may lock the screen if the OS is configured to do so) +---@return any +function hs.caffeinate.startScreensaver() end + +--- Requests the system to sleep immediately +---@return any +function hs.caffeinate.systemSleep() end + +--- Toggles the current state of the specified type of sleep +--- +--- Note: If systemIdle is toggled to on, it will apply to AC only +---@param sleepType string +---@return boolean|nil +function hs.caffeinate.toggle(sleepType) end + +-- ------------------------------------------------------------ +-- hs.caffeinate.watcher +-- ------------------------------------------------------------ + +---@class hs.caffeinate.watcher +hs.caffeinate.watcher = {} + +---@class watcher +local watcher = {} + +---@class hs.caffeinate.watcher.watcher +---@field screensaverDidStart any The screensaver started +---@field screensaverDidStop any The screensaver stopped +---@field screensaverWillStop any The screensaver is about to stop +---@field screensDidLock any The screen was locked +---@field screensDidSleep any The displays have gone to sleep + +--- The screensaver started +---@type any +hs.caffeinate.watcher.screensaverDidStart = nil + +--- The screensaver stopped +---@type any +hs.caffeinate.watcher.screensaverDidStop = nil + +--- The screensaver is about to stop +---@type any +hs.caffeinate.watcher.screensaverWillStop = nil + +--- The screen was locked +---@type any +hs.caffeinate.watcher.screensDidLock = nil + +--- The displays have gone to sleep +---@type any +hs.caffeinate.watcher.screensDidSleep = nil + +--- The screen was unlocked +---@type any +hs.caffeinate.watcher.screensDidUnlock = nil + +--- The displays have woken from sleep +---@type any +hs.caffeinate.watcher.screensDidWake = nil + +--- The session became active, due to fast user switching +---@type any +hs.caffeinate.watcher.sessionDidBecomeActive = nil + +--- The session is no longer active, due to fast user switching +---@type any +hs.caffeinate.watcher.sessionDidResignActive = nil + +--- The system woke from sleep +---@type any +hs.caffeinate.watcher.systemDidWake = nil + +--- The user requested a logout or shutdown +---@type any +hs.caffeinate.watcher.systemWillPowerOff = nil + +--- The system is preparing to sleep +---@type any +hs.caffeinate.watcher.systemWillSleep = nil + +--- Creates a watcher object for system and display sleep/wake/power events +---@param fn function +---@return watcher +function hs.caffeinate.watcher.new(fn) end + +--- Starts the sleep/wake watcher +---@return hs.caffeinate.watcher +function watcher:start() end + +--- Stops the sleep/wake watcher +---@return hs.caffeinate.watcher +function watcher:stop() end + +-- ------------------------------------------------------------ +-- hs.camera +-- ------------------------------------------------------------ + +---@class hs.camera +hs.camera = {} + +---@class camera +local camera = {} + +--- Get all the cameras known to the system +---@return table +function hs.camera.allCameras() end + +--- Checks if the camera devices watcher is running +---@return Boolean +function hs.camera.isWatcherRunning() end + +--- Sets/clears the callback function for the camera devices watcher +--- +--- Note: The callback will be called when a camera is added or removed from the system +--- To watch for changes within a single camera device, see hs.camera:newWatcher() +--- The callback function arguments are: +--- An hs.camera device object for the affected device +--- A string, either "Added" or "Removed" depending on whether the device was added or removed from the system +--- For "Removed" events, most methods on the hs.camera device object will not function correctly anymore and the +--- device object passed to the callback is likely to be useless. It is recommended you re-check hs.camera.allCameras() +--- and keep records of the cameras you care about +--- Passing nil will cause the watcher to stop if it is running +---@param fn function|nil +---@return any +function hs.camera.setWatcherCallback(fn) end + +--- Starts the camera devices watcher +---@return any +function hs.camera.startWatcher() end + +--- Stops the camera devices watcher +---@return any +function hs.camera.stopWatcher() end + +--- Get the raw connection ID of the camera +---@return String +function camera:connectionID() end + +--- Get the usage status of the camera +---@return Boolean +function camera:isInUse() end + +--- Checks if the property watcher on a camera object is running +---@return boolean +function camera:isPropertyWatcherRunning() end + +--- Get the name of the camera +---@return String +function camera:name() end + +--- Sets or clears a callback for when the properties of an hs.camera object change +---@param fn function +---@return hs.camera +function camera:setPropertyWatcherCallback(fn) end + +--- Starts the property watcher on a camera +---@return hs.camera +function camera:startPropertyWatcher() end + +--- Stops the property watcher on a camera +---@return hs.camera +function camera:stopPropertyWatcher() end + +--- Get the UID of the camera +--- +--- Note: The UID is not guaranteed to be stable across reboots +---@return String +function camera:uid() end + +-- ------------------------------------------------------------ +-- hs.canvas +-- ------------------------------------------------------------ + +---@class hs.canvas +---@field attributes any Canvas Element Attributes +---@field object[index] any An array-like method for accessing the attributes for the canvas element at the specified index +---@field percentages any Canvas attributes which specify the location and size of canvas elements can be specified with an absolute position or... +hs.canvas = {} + +---@class canvas +---@field object[index] any An array-like method for accessing the attributes for the canvas element at the specified index +---@field percentages any Canvas attributes which specify the location and size of canvas elements can be specified with an absolute position or... +local canvas = {} + +--- A table containing the possible compositing rules for elements within the canvas. +---@type table +hs.canvas.compositeTypes[] = nil + +--- Array of window behavior labels for determining how a canvas or drawing object is handled in Spaces and Exposé +---@type hs.window[] +hs.canvas.windowBehaviors[] = nil + +--- A table of predefined window levels usable with +--- hs.canvas:level +---@type table +hs.canvas.windowLevels = nil + +--- Returns a table containing the default font, size, color, and paragraphStyle used by +--- hs.canvas +--- for text drawing objects. +--- +--- Note: This method is intended to be used in conjunction with hs.styledtext to create styledtext objects that are +--- based on, or a slight variation of, the defaults used by hs.canvas . +---@return table +function hs.canvas.defaultTextStyle() end + +--- Returns the list of attributes and their specifications that are recognized for canvas elements by this module. +--- +--- Note: This is primarily for debugging purposes and may be removed in the future. +---@return table +function hs.canvas.elementSpec() end + +--- Provides specification information for the recognized attributes, or the specific attribute specified. +---@param attribute string|nil +---@return string +function hs.canvas.help(attribute) end + +--- Get or set whether or not canvas objects use a custom accessibility subrole for the containing system window. +--- +--- Note: Under some conditions, it has been observed that Hammerspoon's hs.window.filter module will misidentify +--- Canvas and Drawing objects as windows of the Hammerspoon application that it should consider when evaluating its +--- filters. To eliminate this, hs.canvas objects (and previously hs.drawing objects, which are now deprecated and pass +--- through to hs.canvas ) were given a nonstandard accessibility subrole to prevent them from being included. This has +--- caused some issues with third party tools, like Yabai, which also use the accessibility subroles for determining +--- what actions it may take with Hammerspoon windows. +--- By passing false to this function, all canvas objects will revert to specifying the standard subrole for the +--- containing windows by default and should work as expected with third party tools. Note that this may cause issues +--- or slowdowns if you are also using hs.window.filter ; a more permanent solution is being considered. +--- If you need to control the subrole of canvas objects more specifically, or only for some canvas objects, see +--- hs.canvas:_accessibilitySubrole . +---@deprecated +---@param state boolean +---@return boolean +function hs.canvas.useCustomAccessibilitySubrole(state) end + +--- Create a new canvas object at the specified coordinates +--- +--- Note: The size of the canvas defines the visible area of the canvas -- any portion of a canvas element which +--- extends past the canvas's edges will be clipped. +--- a rect-table is a table with key-value pairs specifying the top-left coordinate on the screen for the canvas (keys +--- x and y ) and the size (keys h and w ) of the canvas. The table may be crafted by any method which includes these +--- keys, including the use of an hs.geometry object. +---@param rect table +---@return hs.canvas +function hs.canvas.new(rect) end + +--- Get or set the accessibility subrole returned by +--- hs.canvas +--- objects. +--- +--- Note: Most people will probably not need to use this method; See hs.canvas.useCustomAccessibilitySubrole for a +--- discussion as to why this method may be of use when Hammerspoon is being controlled through the accessibility +--- framework by other applications. +--- If a non empty string is specified as the argument to this method, the string will be returned whenever the canvas +--- object's containing window is queried for its accessibility subrole. +--- If an explicit nil (the default) is specified for this method, the string returned when the canvas object's +--- accessibility is queried will be the default macOS subrole for the canvas's window with the string ".Hammerspoon` +--- appended to it. +--- If the empty string is specified (e.g. "" ), then the default macOS subrole for the canvas's window will be +--- returned. +--- If an explicit nil (the default) is specified for this method, then the default macOS subrole for the canvas's +--- window will be returned. +--- If the empty string is specified (e.g. "" ), the string returned when the canvas object's accessibility is queried +--- will be the default macOS subrole for the canvas's window with the string ".Hammerspoon` appended to it. +---@param subrole string|nil +---@return hs.canvas +function canvas:_accessibilitySubrole(subrole) end + +--- Get or set the alpha level of the window containing the canvasObject. +---@param alpha number|nil +---@return hs.canvas +function canvas:alpha(alpha) end + +--- Appends the elements specified to the canvas. +--- +--- Note: You can also specify multiple elements in a table as an array, where each index in the table contains an +--- element table, and use the array as a single argument to this method if this style works better in your code. +---@param element... any +---@return hs.canvas +function canvas:appendElements(element...) end + +--- Assigns a new element to the canvas at the specified index. +--- +--- Note: When the index specified is the canvas element count + 1, the behavior of this method is the same as +--- hs.canvas:insertElement ; i.e. it adds the new element to the end of the currently defined element list. +---@param elementTable table +---@param index number|nil +---@return hs.canvas +function canvas:assignElement(elementTable, index) end + +--- Get or set the window behavior settings for the canvas object using labels defined in +--- hs.canvas.windowBehaviors +--- . +---@param behavior any +---@return hs.canvas +function canvas:behavior(behavior) end + +--- Get or set the window behavior settings for the canvas object using labels defined in +--- hs.canvas.windowBehaviors +--- . +---@param behaviorTable table|nil +---@return hs.canvas +function canvas:behaviorAsLabels(behaviorTable) end + +--- Places the canvas object on top of normal windows +--- +--- Note: As of macOS Sierra and later, if you want a hs.canvas object to appear above full-screen windows you must +--- hide the Hammerspoon Dock icon first using: hs.dockicon.hide() +---@param aboveEverything any +---@return hs.canvas +function canvas:bringToFront(aboveEverything) end + +--- Get or set the element default specified by keyName. +--- +--- Note: Not all keys will apply to all element types. +--- Currently set and built-in defaults may be retrieved in a table with hs.canvas:canvasDefaults . +---@param keyName string +---@param newValue any +---@return hs.canvas +function canvas:canvasDefaultFor(keyName, newValue) end + +--- Returns a list of the key names for the attributes set for the canvas defaults. +---@param module boolean|nil +---@return table +function canvas:canvasDefaultKeys(module) end + +--- Get a table of the default key-value pairs which apply to the canvas. +--- +--- Note: Not all keys will apply to all element types. +--- To change the defaults for the canvas, use hs.canvas:canvasDefaultFor . +---@param module table|nil +---@return table +function canvas:canvasDefaults(module) end + +--- Returns an array containing the elements defined for this canvas. Each array entry will be a table containing the +--- key-value pairs which have been set for that canvas element. +---@return table +function canvas:canvasElements() end + +--- Get or set whether or not regions of the canvas which are not otherwise covered by an element with mouse tracking +--- enabled should generate a callback for mouse events. +--- +--- Note: Each value that you wish to set must be provided in the order given above, but you may specify a position as +--- nil to indicate that whatever it's current state, no change should be applied. For example, to activate a callback +--- for entering and exiting the canvas without changing the current callback status for up or down button clicks, you +--- could use: hs.canvas:canvasMouseTracking(nil, nil, true) . +--- Use hs.canvas:mouseCallback to set the callback function. The identifier field in the callback's argument list +--- will be " canvas ", but otherwise identical to those specified in hs.canvas:mouseCallback . +---@param down function|nil +---@param up function|nil +---@param enterExit function|nil +---@param move function|nil +---@return hs.canvas|current values +function canvas:canvasMouseEvents(down, up, enterExit, move) end + +--- Get or set whether or not clicking on a canvas with a click callback defined should bring all of Hammerspoon's open +--- windows to the front. +--- +--- Note: Setting this to false changes a canvas object's AXsubrole value and may affect the results of filters used +--- with hs.window.filter , depending upon how they are defined. +---@param flag function|nil +---@return hs.canvas +function canvas:clickActivating(flag) end + +--- Creates a copy of the canvas. +--- +--- Note: The new canvas will not have a callback function assigned, even if the original canvas does. +--- The new canvas will not initially be visible, even if the original is. +--- The new canvas is an independent entity -- any subsequent changes to either canvas will not be reflected in the +--- other canvas. +--- This method allows you to display a canvas in multiple places or use it as a canvas element multiple times. +---@return hs.canvas +function canvas:copy() end + +--- Destroys the canvas object, optionally fading it out first (if currently visible). +--- +--- Note: This method is automatically called during garbage collection, notably during a Hammerspoon termination or +--- reload, with a fade time of 0. +---@param fadeOutTime number|nil +---@return none +function canvas:delete(fadeOutTime) end + +--- Sets or remove a callback for accepting dragging and dropping items onto the canvas. +--- +--- Note: pasteboard - the name of the pasteboard that contains the items being dragged +--- sequence - an integer that uniquely identifies the dragging session. +--- mouse - a point table containing the location of the mouse pointer within the canvas corresponding to when the +--- callback occurred. +--- operation - a table containing string descriptions of the type of dragging the source application supports. +--- Potentially useful for determining if your callback function should accept the dragged item or not. +--- "enter" - the user has dragged an item into the canvas. When your callback receives this message, you can +--- optionally return false to indicate that you do not wish to accept the item being dragged. +--- "exit" - the user has moved the item out of the canvas; if the previous "enter" callback returned false, this +--- message will also occur when the user finally releases the items being dragged. +--- "receive" - indicates that the user has released the dragged object while it is still within the canvas frame. +--- When your callback receives this message, you can optionally return false to indicate to the sending application +--- that you do not want to accept the dragged item -- this may affect the animations provided by the sending +--- application. +--- You can use the sequence number in the details table to match up an "enter" with an "exit" or "receive" message. +--- You should capture the details you require from the drag-and-drop operation during the callback for "receive" by +--- using the pasteboard field of the details table and the hs.pasteboard module. Because of the nature of "promised +--- items", it is not guaranteed that the items will still be on the pasteboard after your callback completes handling +--- this message. +--- A canvas object can only accept drag-and-drop items when its window level is at hs.canvas.windowLevels.dragging or +--- lower. +--- a canvas object can only accept drag-and-drop items when it accepts mouse events. You must define a +--- hs.canvas:mouseCallback function, even if it is only a placeholder, e.g. hs.canvas:mouseCallback(function() end) +---@param fn function +---@return hs.canvas +function canvas:draggingCallback(fn) end + +--- Get or set the attribute +--- key +--- for the canvas element at the specified index. +---@param index number +---@param key string +---@param value any +---@return hs.canvas +function canvas:elementAttribute(index, key, value) end + +--- Returns the smallest rectangle which can fully contain the canvas element at the specified index. +--- +--- Note: For many elements, this will be the same as the element frame. For items without a frame (e.g. segments , +--- circle , etc.) this will be the smallest rectangle which can fully contain the canvas element as specified by it's +--- attributes. +---@param index number +---@return rectTable +function canvas:elementBounds(index) end + +--- Returns the number of elements currently defined for the canvas object. +---@return number +function canvas:elementCount() end + +--- Returns a list of the key names for the attributes set for the canvas element at the specified index. +--- +--- Note: Any attribute which has been explicitly set for the element will be included in the key list (even if it is +--- ignored for the element type). If the optional flag is set to true, the additional attribute names added to the +--- list will only include those which are relevant to the element type. +---@param index number +---@param optional boolean|nil +---@return table +function canvas:elementKeys(index, optional) end + +--- Get or set the frame of the canvasObject. +--- +--- Note: a rect-table is a table with key-value pairs specifying the new top-left coordinate on the screen of the +--- canvas (keys x and y ) and the new size (keys h and w ). The table may be crafted by any method which includes +--- these keys, including the use of an hs.geometry object. +--- elements in the canvas that have the absolutePosition attribute set to false will be moved so that their relative +--- position within the canvas remains the same with respect to the new size. +--- elements in the canvas that have the absoluteSize attribute set to false will be resized so that their relative +--- size with respect to the canvas remains the same with respect to the new size. +---@param rect table|nil +---@return hs.canvas +function canvas:frame(rect) end + +--- Hides the canvas object +---@param fadeOutTime number|nil +---@return hs.canvas +function canvas:hide(fadeOutTime) end + +--- Returns an image of the canvas contents as an +--- hs.image +--- object. +--- +--- Note: The canvas does not have to be visible in order for an image to be generated from it. +---@return hs.image +function canvas:imageFromCanvas() end + +--- Insert a new element into the canvas at the specified index. +--- +--- Note: see also hs.canvas:assignElement . +---@param elementTable table +---@param index number|nil +---@return hs.canvas +function canvas:insertElement(elementTable, index) end + +--- Returns whether or not the canvas is currently occluded (hidden by other windows, off screen, etc). +--- +--- Note: If any part of the canvas is visible (even if that portion of the canvas does not contain any canvas +--- elements), then the canvas is not considered occluded. +--- a canvas which is completely covered by one or more opaque windows is considered occluded; however, if the windows +--- covering the canvas are not opaque, then the canvas is not occluded. +--- a canvas that is currently hidden or with a height of 0 or a width of 0 is considered occluded. +--- See also hs.canvas:isShowing . +---@return boolean +function canvas:isOccluded() end + +--- Returns whether or not the canvas is currently being shown. +--- +--- Note: This method only determines whether or not the canvas is being shown or is hidden -- it does not indicate +--- whether or not the canvas is currently off screen or is occluded by other objects. +--- See also hs.canvas:isOccluded . +---@return boolean +function canvas:isShowing() end + +--- Returns whether or not the canvas is currently showing and is (at least partially) visible on screen. +--- +--- Note: This is syntactic sugar for not hs.canvas:isOccluded() . +--- See hs.canvas:isOccluded for more details. +---@return boolean +function canvas:isVisible() end + +--- Sets the window level more precisely than sendToBack and bringToFront. +---@param level hs.canvas.windowLevels|nil +---@return hs.canvas +function canvas:level(level) end + +--- Returns a table specifying the size of the rectangle which can fully render the text with the specified style so +--- that is will be completely visible. +--- +--- Note: Multi-line text (separated by a newline or return) is supported. The height will be for the multiple lines +--- and the width returned will be for the longest line. +---@param index hs.styledtext|nil +---@param text string +---@return table +function canvas:minimumTextSize(index, text) end + +--- Sets a callback for mouse events with respect to the canvas +--- +--- Note: The callback function should expect 5 arguments: the canvas object itself, a message specifying the type of +--- mouse event, the canvas element id (or index position in the canvas if the id attribute is not set for the +--- element), the x position of the mouse when the event was triggered within the rendered portion of the canvas +--- element, and the y position of the mouse when the event was triggered within the rendered portion of the canvas +--- element. +--- See also hs.canvas:canvasMouseEvents for tracking mouse events in regions of the canvas not covered by an element +--- with mouse tracking enabled. +--- trackMouseDown - indicates that a callback should be invoked when a mouse button is clicked down on the canvas +--- element. The message will be "mouseDown". +--- trackMouseUp - indicates that a callback should be invoked when a mouse button has been released over the canvas +--- element. The message will be "mouseUp". +--- trackMouseEnterExit - indicates that a callback should be invoked when the mouse pointer enters or exits the +--- canvas element. The message will be "mouseEnter" or "mouseExit". +--- trackMouseMove - indicates that a callback should be invoked when the mouse pointer moves within the canvas +--- element. The message will be "mouseMove". +--- The callback mechanism uses reverse z-indexing to determine which element will receive the callback -- the topmost +--- element of the canvas which has enabled callbacks for the specified message will be invoked. +--- No distinction is made between the left, right, or other mouse buttons. If you need to determine which specific +--- button was pressed, use hs.eventtap.checkMouseButtons() within your callback to check. +--- The hit point detection occurs by comparing the mouse pointer location to the rendered content of each individual +--- canvas object... if an object which obscures a lower object does not have mouse tracking enabled, the lower object +--- will still receive the event if it does have tracking enabled. +--- Clipping regions which remove content from the visible area of a rendered object are ignored for the purposes of +--- element hit-detection. +---@param mouseCallbackFn function +---@return hs.canvas +function canvas:mouseCallback(mouseCallbackFn) end + +--- Moves canvas object above canvas2, or all canvas objects in the same presentation level, if canvas2 is not given. +--- +--- Note: If the canvas object and canvas2 are not at the same presentation level, this method will move the canvas +--- object as close to the desired relationship as possible without changing the canvas object's presentation level. +--- See hs.canvas.level . +---@param canvas2 boolean +---@return hs.canvas +function canvas:orderAbove(canvas2) end + +--- Moves canvas object below canvas2, or all canvas objects in the same presentation level, if canvas2 is not given. +--- +--- Note: If the canvas object and canvas2 are not at the same presentation level, this method will move the canvas +--- object as close to the desired relationship as possible without changing the canvas object's presentation level. +--- See hs.canvas.level . +---@param canvas2 boolean +---@return hs.canvas +function canvas:orderBelow(canvas2) end + +--- Insert a new element into the canvas at the specified index. +---@param index number|nil +---@return hs.canvas +function canvas:removeElement(index) end + +--- Replaces all of the elements in the canvas with the elements specified. Shortens or lengthens the canvas element +--- count if necessary to accomodate the new canvas elements. +--- +--- Note: You can also specify multiple elements in a table as an array, where each index in the table contains an +--- element table, and use the array as a single argument to this method if this style works better in your code. +---@param element... any +---@return hs.canvas +function canvas:replaceElements(element...) end + +--- Rotates an element about the point specified, or the elements center if no point is specified. +--- +--- Note: a point-table is a table with key-value pairs specifying a coordinate in the canvas (keys x and y ). The +--- table may be crafted by any method which includes these keys, including the use of an hs.geometry object. +--- The center of the object is determined by getting the element's bounds with hs.canvas:elementBounds . +--- If the third argument is a boolean value, the point argument is assumed to be the element's center and the boolean +--- value is used as the append argument. +--- This method uses hs.canvas.matrix to generate the rotation transformation and provides a wrapper for +--- hs.canvas.matrix.translate(x, y):rotate(angle):translate(-x, -y) which is then assigned or appended to the +--- element's existing transformation attribute. +---@param index number +---@param angle any +---@param point table|nil +---@param append boolean +---@return hs.canvas +function canvas:rotateElement(index, angle, point, append) end + +--- Places the canvas object behind normal windows, between the desktop wallpaper and desktop icons +---@return hs.canvas +function canvas:sendToBack() end + +--- Displays the canvas object +--- +--- Note: if the canvas is in use as an element in another canvas, this method will result in an error. +---@param fadeInTime number|nil +---@return hs.canvas +function canvas:show(fadeInTime) end + +--- Get or set the size of a canvas object +--- +--- Note: a size-table is a table with key-value pairs specifying the size (keys h and w ) the canvas should be resized +--- to. The table may be crafted by any method which includes these keys, including the use of an hs.geometry object. +--- elements in the canvas that have the absolutePosition attribute set to false will be moved so that their relative +--- position within the canvas remains the same with respect to the new size. +--- elements in the canvas that have the absoluteSize attribute set to false will be resized so that their relative +--- size with respect to the canvas remains the same with respect to the new size. +---@param size table|nil +---@return hs.canvas +function canvas:size(size) end + +--- Get or set the top-left coordinate of the canvas object +--- +--- Note: a point-table is a table with key-value pairs specifying the new top-left coordinate on the screen of the +--- canvas (keys x and y ). The table may be crafted by any method which includes these keys, including the use of an +--- hs.geometry object. +---@param point table|nil +---@return hs.canvas +function canvas:topLeft(point) end + +--- Get or set the matrix transformation which is applied to every element in the canvas before being individually +--- processed and added to the canvas. +--- +--- Note: An example use for this method would be to change the canvas's origin point { x = 0, y = 0 } from the lower +--- left corner of the canvas to somewhere else, like the middle of the canvas. +---@param matrix hs.canvas.matrix|nil +---@return hs.canvas +function canvas:transformation(matrix) end + +--- Get or set whether or not the canvas object should be rendered by the view or by Core Animation. +--- +--- Note: This method can help smooth the display of small text objects on non-Retina monitors. +---@param flag boolean|nil +---@return hs.canvas +function canvas:wantsLayer(flag) end + +-- ------------------------------------------------------------ +-- hs.canvas.matrix +-- ------------------------------------------------------------ + +---@class hs.canvas.matrix +hs.canvas.matrix = {} + +---@class matrix +local matrix = {} + +--- Specifies the identity matrix. Resets all existing transformations when applied as a method to an existing +--- matrixObject. +--- +--- Note: The identity matrix can be thought of as "apply no transformations at all" or "render as specified". +--- Mathematically this is represented as: +--- [ 1, 0, 0 ] +--- [ 0, 1, 0 ] +--- [ 0, 0, 1 ] +---@return matrixObject +function hs.canvas.matrix.identity() end + +--- Appends the specified matrix transformations to the matrix and returns the new matrix. This method cannot be used +--- as a constructor. +--- +--- Note: Mathematically this method multiples the original matrix by the new one and returns the result of the +--- multiplication. +--- You can use this method to "stack" additional transformations on top of existing transformations, without having to +--- know what the existing transformations in effect for the canvas element are. +---@param matrix table +---@return matrixObject +function matrix:append(matrix) end + +--- Generates the mathematical inverse of the matrix. This method cannot be used as a constructor. +--- +--- Note: Inverting a matrix which represents a series of transformations has the effect of reversing or undoing the +--- original transformations. +--- This is useful when used with hs.canvas.matrix.append to undo a previously applied transformation without actually +--- replacing all of the transformations which may have been applied to a canvas element. +---@return matrixObject +function matrix:invert() end + +--- Prepends the specified matrix transformations to the matrix and returns the new matrix. This method cannot be used +--- as a constructor. +--- +--- Note: Mathematically this method multiples the new matrix by the original one and returns the result of the +--- multiplication. +--- You can use this method to apply a transformation before the currently applied transformations, without having to +--- know what the existing transformations in effect for the canvas element are. +---@param matrix table +---@return matrixObject +function matrix:prepend(matrix) end + +--- Applies a rotation of the specified number of degrees to the transformation matrix. This method can be used as a +--- constructor or a method. +--- +--- Note: e.g. hs.canvas.matrix.translate(x, y):rotate(angle):translate(-x, -y) +---@param angle number +---@return matrixObject +function matrix:rotate(angle) end + +--- Applies a scaling transformation to the matrix. This method can be used as a constructor or a method. +---@param xFactor any +---@param yFactor any +---@return matrixObject +function matrix:scale(xFactor, yFactor) end + +--- Applies a shearing transformation to the matrix. This method can be used as a constructor or a method. +---@param xFactor any +---@param yFactor any +---@return matrixObject +function matrix:shear(xFactor, yFactor) end + +--- Applies a translation transformation to the matrix. This method can be used as a constructor or a method. +---@param x number +---@param y number +---@return matrixObject +function matrix:translate(x, y) end + +-- ------------------------------------------------------------ +-- hs.chooser +-- ------------------------------------------------------------ + +---@class hs.chooser +hs.chooser = {} + +---@class chooser +local chooser = {} + +--- A global callback function used for various hs.chooser events +---@type hs.chooser +hs.chooser.globalCallback = nil + +--- Creates a new chooser object +--- +--- Note: As of macOS Sierra and later, if you want a hs.chooser object to appear above full-screen windows you must +--- hide the Hammerspoon Dock icon first using: hs.dockicon.hide() +---@param completionFn function +---@return hs.chooser +function hs.chooser.new(completionFn) end + +--- Get or attach/detach a toolbar to/from the chooser. +--- +--- Note: this method is a convenience wrapper for the hs.webview.toolbar.attachToolbar function. +--- If the toolbarObject is currently attached to another window when this method is called, it will be detached from +--- the original window and attached to the chooser. If you wish to attach the same toolbar to multiple chooser +--- objects, see hs.webview.toolbar:copy . +---@param toolbar hs.webview.toolbar +---@return hs.chooser +function chooser:attachedToolbar(toolbar) end + +--- Sets the background of the chooser between light and dark +--- +--- Note: The text colors will not automatically change when you toggle the darkness of the chooser window, you should +--- also set appropriate colors with hs.chooser:fgColor() and hs.chooser:subTextColor() +---@param beDark boolean|nil +---@return hs.chooser|boolean +function chooser:bgDark(beDark) end + +--- Cancels the chooser +---@return hs.chooser +function chooser:cancel() end + +--- Sets the choices for a chooser +--- +--- Note: The table of choices (be it provided statically, or returned by the callback) must contain at least the +--- following keys for each choice: +--- text - A string or hs.styledtext object that will be shown as the main text of the choice +--- Each choice may also optionally contain the following keys: +--- subText - A string or hs.styledtext object that will be shown underneath the main text of the choice +--- image - An hs.image image object that will be displayed next to the choice +--- valid - A boolean that defaults to true , if set to false selecting the choice will invoke the invalidCallback +--- method instead of dismissing the chooser +--- Any other keys/values in each choice table will be retained by the chooser and returned to the completion callback +--- when a choice is made. This is useful for storing UUIDs or other non-user-facing information, however, it is +--- important to note that you should not store userdata objects in the table - it is run through internal conversion +--- functions, so only basic Lua types should be stored. +--- If a function is given, it will be called once, when the chooser window is displayed. The results are then cached +--- until this method is called again, or hs.chooser:refreshChoicesCallback() is called. +--- If you're using a hs.styledtext object for text or subText choices, make sure you specify a color, otherwise your +--- text could appear transparent depending on the bgDark setting. +--- Example: +--- local +--- choices +--- = +--- { +--- { +--- [ +--- "text" +--- ] +--- = +--- "First Choice" +--- , +--- [ +--- "subText" +--- ] +--- = +--- "This is the subtext of the first choice" +--- , +--- [ +--- "uuid" +--- ] +--- = +--- "0001" +--- }, +--- { +--- [ +--- "text" +--- ] +--- = +--- "Second Option" +--- , +--- [ +--- "subText" +--- ] +--- = +--- "I wonder what I should type here?" +--- , +--- [ +--- "uuid" +--- ] +--- = +--- "Bbbb" +--- }, +--- { +--- [ +--- "text" +--- ] +--- = +--- hs +--- . +--- styledtext +--- . +--- new +--- ( +--- "Third Possibility" +--- , +--- { +--- font +--- = +--- { +--- size +--- = +--- 18 +--- }, +--- color +--- = +--- hs +--- . +--- drawing +--- . +--- color +--- . +--- definedCollections +--- . +--- hammerspoon +--- . +--- green +--- }), +--- [ +--- "subText" +--- ] +--- = +--- "What a lot of choosing there is going on here!" +--- , +--- [ +--- "uuid" +--- ] +--- = +--- "III3" +--- }, +--- } +--- ``` +---@param choices function|nil +---@return hs.chooser +function chooser:choices(choices) end + +--- Deletes a chooser +---@return any +function chooser:delete() end + +--- Gets/Sets whether the chooser should run the callback on a query when it does not match any on the list +--- +--- Note: This should be used before a chooser has been displayed +---@return hs.chooser|boolean +function chooser:enableDefaultForQuery() end + +--- Sets the foreground color of the chooser +---@param color hs.drawing.color|nil +---@return hs.chooser +function chooser:fgColor(color) end + +--- Hides the chooser +---@return hs.chooser +function chooser:hide() end + +--- Sets/clears a callback for when the chooser window is hidden +--- +--- Note: This callback is called after the chooser is hidden. +--- This callback is called after hs.chooser.globalCallback. +---@param fn function|nil +---@return hs.chooser +function chooser:hideCallback(fn) end + +--- Sets/clears a callback for invalid choices +--- +--- Note: The callback may accept one argument, it will be a table containing whatever information you supplied for the +--- item the user chose. +--- To display a context menu, see hs.menubar , specifically the :popupMenu() method +---@param fn function|nil +---@return hs.chooser +function chooser:invalidCallback(fn) end + +--- Checks if the chooser is currently displayed +---@return boolean +function chooser:isVisible() end + +--- Sets/gets placeholder text that is shown in the query text field when no other text is present +---@param placeholderText string|nil +---@return hs.chooser|string +function chooser:placeholderText(placeholderText) end + +--- Sets/gets the search string +--- +--- Note: You can provide an explicit nil or empty string to clear the current query string. +---@param queryString string +---@return hs.chooser|string +function chooser:query(queryString) end + +--- Sets/clears a callback for when the search query changes +--- +--- Note: As the user is typing, the callback function will be called for every keypress. You may wish to do filtering +--- on each call, or you may wish to use a delayed hs.timer object to only react when they have finished typing. +--- The callback function should accept a single argument: +--- A string containing the new search query +---@param fn function|nil +---@return hs.chooser +function chooser:queryChangedCallback(fn) end + +--- Refreshes the choices data from a callback +--- +--- Note: This method will do nothing if you have not set a function with hs.chooser:choices() +---@param reload string|nil +---@return hs.chooser +function chooser:refreshChoicesCallback(reload) end + +--- Sets/clears a callback for right clicking on choices +--- +--- Note: The callback may accept one argument, the row the right click occurred in or 0 if there is currently no +--- selectable row where the right click occurred. To determine the location of the mouse pointer at the right click, +--- see hs.mouse . +--- To display a context menu, see hs.menubar , specifically the :popupMenu() method +---@param fn function|nil +---@return hs.chooser +function chooser:rightClickCallback(fn) end + +--- Gets/Sets the number of rows that will be shown +---@param numRows number|nil +---@return hs.chooser|number +function chooser:rows(numRows) end + +--- Gets/Sets whether the chooser should search in the sub-text of each item +--- +--- Note: This should be used before a chooser has been displayed +---@param searchSubText boolean|nil +---@return hs.chooser|boolean +function chooser:searchSubText(searchSubText) end + +--- Closes the chooser by selecting the specified row, or the currently selected row if not given +---@param row number|nil +---@return hs.chooser +function chooser:select(row) end + +--- Get or set the currently selected row +---@param row number|nil +---@return number +function chooser:selectedRow(row) end + +--- Returns the contents of the currently selected or specified row +---@param row number|nil +---@return table +function chooser:selectedRowContents(row) end + +--- Displays the chooser +---@param topLeftPoint any +---@return hs.chooser +function chooser:show(topLeftPoint) end + +--- Sets/clears a callback for when the chooser window is shown +--- +--- Note: This callback is called after the chooser is shown. To execute code just before it's shown (and/or after it's +--- removed) see hs.chooser.globalCallback +---@param fn function|nil +---@return hs.chooser +function chooser:showCallback(fn) end + +--- Sets the sub-text color of the chooser +---@param color hs.drawing.color|nil +---@return hs.chooser|hs.color +function chooser:subTextColor(color) end + +--- Gets/Sets the width of the chooser +--- +--- Note: This should be used before a chooser has been displayed +---@param percent number|nil +---@return hs.chooser|number +function chooser:width(percent) end + +-- ------------------------------------------------------------ +-- hs.console +-- ------------------------------------------------------------ + +---@class hs.console +hs.console = {} + +--- Because use of this function can easily lead to a crash, useful methods from +--- hs.drawing +--- have been added to the +--- hs.console +--- module itself. If you believe that a useful method has been overlooked, please submit an issue. +---@return hs.drawing +function hs.console.asHSDrawing() end + +--- Returns an hs.window object for the console so that you can use hs.window methods on it. +---@return hs.window +function hs.console.asHSWindow() end + +--- Default toolbar for the Console window +---@type any +hs.console.defaultToolbar = nil + +--- Get or set the alpha level of the console window. +---@param alpha number|nil +---@return any +function hs.console.alpha(alpha) end + +--- Get or set the window behavior settings for the console using labels defined in +--- hs.drawing.windowBehaviors +--- . +--- +--- Note: Window behaviors determine how the console is handled by Spaces and Exposé. See hs.drawing.windowBehaviors +--- for more information. +---@param behaviorTable table|nil +---@return any +function hs.console.behaviorAsLabels(behaviorTable) end + +--- Clear the Hammerspoon console output window. +--- +--- Note: This is equivalent to hs.console.setConsole() +---@return nil +function hs.console.clearConsole() end + +--- Get or set the color that commands displayed in the Hammerspoon console are displayed with. +--- +--- Note: See the hs.drawing.color entry in the Dash documentation, or type help.hs.drawing.color in the Hammerspoon +--- console to get more information on how to specify a color. +--- Note this only affects future output -- anything already in the console will remain its current color. +---@param color hs.drawing.color|nil +---@return color +function hs.console.consoleCommandColor(color) end + +--- Get or set the font used in the Hammerspoon console. +--- +--- Note: See the hs.drawing.color entry in the Dash documentation, or type help.hs.drawing.color in the Hammerspoon +--- console to get more information on how to specify a color. +--- Note this only affects future output -- anything already in the console will remain its current font. +---@param font string|table|nil +---@return fontTable +function hs.console.consoleFont(font) end + +--- Get or set the color that regular output displayed in the Hammerspoon console is displayed with. +--- +--- Note: See the hs.drawing.color entry in the Dash documentation, or type help.hs.drawing.color in the Hammerspoon +--- console to get more information on how to specify a color. +--- Note this only affects future output -- anything already in the console will remain its current color. +---@param color hs.drawing.color|nil +---@return color +function hs.console.consolePrintColor(color) end + +--- Get or set the color that function results displayed in the Hammerspoon console are displayed with. +--- +--- Note: See the hs.drawing.color entry in the Dash documentation, or type help.hs.drawing.color in the Hammerspoon +--- console to get more information on how to specify a color. +--- Note this only affects future output -- anything already in the console will remain its current color. +---@param color hs.drawing.color|nil +---@return color +function hs.console.consoleResultColor(color) end + +--- Set or display whether or not the Console window should display in dark mode. +--- +--- Note: Enabling Dark Mode for the Console only affects the window background, and doesn't automatically change the +--- Console's Background Color, so you will need to add something similar to: if hs . console . darkMode () then hs . +--- console . outputBackgroundColor { white = 0 } hs . console . consoleCommandColor { white = 1 } hs . console . alpha +--- ( .8 ) end +--- . ``` +---@param state boolean +---@return boolean +function hs.console.darkMode(state) end + +--- Get the text of the Hammerspoon console output window. +--- +--- Note: If the text of the console is retrieved as a string, no color or style information in the console output is +--- retrieved - only the raw text. +---@param styled string|nil +---@return text|styledText +function hs.console.getConsole(styled) end + +--- Get the Hammerspoon console command history as an array. +---@return array +function hs.console.getHistory() end + +--- Get an hs.window object which represents the Hammerspoon console window +---@return hs.window +function hs.console.hswindow() end + +--- Get or set the color for the background of the Hammerspoon Console's input field. +--- +--- Note: See the hs.drawing.color entry in the Dash documentation, or type help.hs.drawing.color in the Hammerspoon +--- console to get more information on how to specify a color. +---@param color hs.drawing.color|nil +---@return color +function hs.console.inputBackgroundColor(color) end + +--- Get or set the console window level +--- +--- Note: see the notes for hs.drawing.windowLevels +---@param theLevel hs.drawing.windowLevels|nil +---@return any +function hs.console.level(theLevel) end + +--- Get or set the max length of the Hammerspoon console's scrollback history. +--- +--- Note: A length value of zero will allow the history to grow infinitely +--- The default console history is 100,000 characters +---@param length number|nil +---@return number +function hs.console.maxOutputHistory(length) end + +--- Get or set the color for the background of the Hammerspoon Console's output view. +--- +--- Note: See the hs.drawing.color entry in the Dash documentation, or type help.hs.drawing.color in the Hammerspoon +--- console to get more information on how to specify a color. +---@param color hs.drawing.color|nil +---@return color +function hs.console.outputBackgroundColor(color) end + +--- A print function which recognizes +--- hs.styledtext +--- objects and renders them as such in the Hammerspoon console. +--- +--- Note: This has been made as close to the Lua print command as possible. You can replace the existing print command +--- with this by adding the following to your init.lua file: +--- print = function(...) +--- hs.rawprint(...) +--- hs.console.printStyledtext(...) +--- end +---@param ... any +---@return none +function hs.console.printStyledtext(...) end + +--- Clear the Hammerspoon console output window. +--- +--- Note: You can specify the console content as a string or as an hs.styledtext object in either userdata or table +--- format. +---@param styledText hs.styledtext|nil +---@return none +function hs.console.setConsole(styledText) end + +--- Set the Hammerspoon console command history to the items specified in the given array. +--- +--- Note: You can clear the console history by using an empty array (e.g. hs.console.setHistory({}) +---@param array commands[] +---@return nil +function hs.console.setHistory(array) end + +--- Determine whether or not objects copied from the console window insert or delete space around selected words to +--- preserve proper spacing and punctuation. +--- +--- Note: this only applies to future copy operations from the Hammerspoon console -- anything already in the clipboard +--- is not affected. +---@param flag any +---@return boolean +function hs.console.smartInsertDeleteEnabled(flag) end + +--- Get or set whether or not the "Hammerspoon Console" text appears in the Hammerspoon console titlebar. +--- +--- Note: When a toolbar is attached to the Hammerspoon console (see the hs.webview.toolbar module documentation), this +--- function can be used to specify whether the Toolbar appears underneath the console window's title ("visible") or in +--- the window's title bar itself, as seen in applications like Safari ("hidden"). When the title is hidden, the +--- toolbar will only display the toolbar items as icons without labels, and ignores changes made with +--- hs.webview.toolbar:displayMode . +--- If a toolbar is attached to the console, you can achieve the same effect as this function with +--- hs.console.toolbar():inTitleBar(boolean) +---@param state boolean +---@return any +function hs.console.titleVisibility(state) end + +--- Get or set the color for the background of the Hammerspoon Console's window. +--- +--- Note: See the hs.drawing.color entry in the Dash documentation, or type help.hs.drawing.color in the Hammerspoon +--- console to get more information on how to specify a color. +---@param color hs.drawing.color|nil +---@return color +function hs.console.windowBackgroundColor(color) end + +--- Get or set the window behavior settings for the console. +--- +--- Note: Window behaviors determine how the webview object is handled by Spaces and Exposé. See +--- hs.drawing.windowBehaviors for more information. +---@param behavior number|nil +---@return any +function hs.console.behavior(behavior) end + +--- Get or attach/detach a toolbar to/from the Hammerspoon console. +--- +--- Note: this method is a convenience wrapper for the hs.webview.toolbar.attachToolbar function. +--- If the toolbar is currently attached to another window when this function is called, it will be detached from the +--- original window and attached to the console. +---@param toolbar hs.webview.toolbar +---@return toolbarObject +function hs.console.toolbar(toolbar) end + +-- ------------------------------------------------------------ +-- hs.crash +-- ------------------------------------------------------------ + +---@class hs.crash +hs.crash = {} + +--- Attempts to reduce RAM usage of Hammerspoon +--- +--- Note: This function will print some memory usage numbers (in bytes) to the Hammerspoon Console before and after +--- forcing Lua's garbage collector +---@return any +function hs.crash.attemptMemoryRelease() end + +--- Causes Hammerspoon to immediately crash +--- +--- Note: This is for testing purposes only, you are extremely unlikely to need this in normal Hammerspoon usage +---@return any +function hs.crash.crash() end + +--- Sets a key/value pair in any Sentry crash dump generated by this Hammerspoon session +---@param key string +---@param value string +---@return any +function hs.crash.crashKV(key, value) end + +--- Leaves a breadcrumb log message in any Sentry crash dump generated by this Hammerspoon session +--- +--- Note: This is probably only useful to extension developers. If you are trying to track down a confusing crash, and +--- you have access to the Sentry project for Hammerspoon (or access to someone who has access!), this can be a useful +--- way to leave breadcrumbs from Lua in the crash dump +---@param logMessage string +---@return any +function hs.crash.crashLog(logMessage) end + +--- Dumps the contents of Lua's CLIBS registry +--- +--- Note: This is probably only useful to extension developers as a useful way of ensuring that you are loading C +--- libraries from the places you expect. +---@return table +function hs.crash.dumpCLIBS() end + +--- Gets the resident size of the Hammerspoon process +---@return number|nil +function hs.crash.residentSize() end + +--- Causes Hammerspoon to generate an Objective C exception +--- +--- Note: Outside of a context of a Lua pcall() (or a C lua_pcall()), this will cause Hammerspoon to exit. We follow +--- the safe behaviour of terminating the app on any unhandled Objective C exception. +---@param name string +---@param message string +---@return any +function hs.crash.throwObjCException(name, message) end + +-- ------------------------------------------------------------ +-- hs.deezer +-- ------------------------------------------------------------ + +---@class hs.deezer +hs.deezer = {} + +--- Returned by +--- hs.deezer.getPlaybackState() +--- to indicates deezer is paused +---@type hs.deezer.getPlaybackState +hs.deezer.state_paused = nil + +--- Returned by +--- hs.deezer.getPlaybackState() +--- to indicates deezer is playing +---@type hs.deezer.getPlaybackState +hs.deezer.state_playing = nil + +--- Returned by +--- hs.deezer.getPlaybackState() +--- to indicates deezer is stopped +---@type hs.deezer.getPlaybackState +hs.deezer.state_stopped = nil + +--- Displays information for current track on screen +---@return any +function hs.deezer.displayCurrentTrack() end + +--- Skips the playback position forwards by 5 seconds +---@return any +function hs.deezer.ff() end + +--- Gets the name of the album of the current track +---@return string|nil +function hs.deezer.getCurrentAlbum() end + +--- Gets the name of the artist of the current track +---@return string|nil +function hs.deezer.getCurrentArtist() end + +--- Gets the name of the current track +---@return string|nil +function hs.deezer.getCurrentTrack() end + +--- Gets the current playback state of deezer +---@return hs.deezer.state_stopped|hs.deezer.state_paused|hs.deezer.state_playing +function hs.deezer.getPlaybackState() end + +--- Gets the playback position (in seconds) in the current song +---@return number +function hs.deezer.getPosition() end + +--- Gets the deezer volume setting +---@return number +function hs.deezer.getVolume() end + +--- Returns whether deezer is currently playing +---@return boolean|nil +function hs.deezer.isPlaying() end + +--- Returns whether deezer is currently open. Most other functions in hs.deezer will automatically start the +--- application, so this function can be used to guard against that. +---@return boolean +function hs.deezer.isRunning() end + +--- Skips to the next deezer track +---@return any +function hs.deezer.next() end + +--- Pauses the current deezer track +---@return any +function hs.deezer.pause() end + +--- Plays the current deezer track +---@return any +function hs.deezer.play() end + +--- Toggles play/pause of current deezer track +---@return any +function hs.deezer.playpause() end + +--- Skips to previous deezer track +---@return any +function hs.deezer.previous() end + +--- Skips the playback position backwards by 5 seconds +---@return any +function hs.deezer.rw() end + +--- Sets the playback position in the current song +---@param pos number +---@return any +function hs.deezer.setPosition(pos) end + +--- Sets the deezer volume setting +---@param vol number +---@return any +function hs.deezer.setVolume(vol) end + +--- Reduces the volume by 5 +---@return any +function hs.deezer.volumeDown() end + +--- Increases the volume by 5 +---@return any +function hs.deezer.volumeUp() end + +-- ------------------------------------------------------------ +-- hs.dialog +-- ------------------------------------------------------------ + +---@class hs.dialog +hs.dialog = {} + +--- Displays a simple non-blocking dialog box using +--- NSAlert +--- and a hidden +--- hs.webview +--- that's automatically destroyed when the alert is closed. +--- +--- Note: The optional values must be entered in order (i.e. you can't supply style without also supplying buttonOne +--- and buttonTwo ). +--- [style] can be "warning", "informational" or "critical". If something other than these string values is given, it +--- will use "informational". +--- Example: testCallbackFn = function ( result ) print ( "Callback Result: " .. result ) end hs . dialog . alert ( 100 +--- , 100 , testCallbackFn , "Message" , "Informative Text" , "Button One" , "Button Two" , "NSCriticalAlertStyle" ) hs +--- . dialog . alert ( 200 , 200 , testCallbackFn , "Message" , "Informative Text" , "Single Button" ) ``` +---@param x number +---@param y number +---@param callbackFn function +---@param message string +---@param informativeText string +---@param buttonOne any +---@param buttonTwo any +---@param style any +---@return string +function hs.dialog.alert(x, y, callbackFn, message, informativeText, buttonOne, buttonTwo, style) end + +--- Displays a simple dialog box using +--- NSAlert +--- that will halt Lua code processing until the alert is closed. +--- +--- Note: The optional values must be entered in order (i.e. you can't supply style without also supplying buttonOne +--- and buttonTwo ). +--- [style] can be "warning", "informational" or "critical". If something other than these string values is given, it +--- will use "warning". +--- Example: hs.dialog.blockAlert("Message", "Informative Text", "Button One", "Button Two", "critical") +---@param message string +---@param informativeText string +---@param buttonOne any +---@param buttonTwo any +---@param style any +---@return string +function hs.dialog.blockAlert(message, informativeText, buttonOne, buttonTwo, style) end + +--- Displays a file and/or folder selection dialog box using NSOpenPanel. +--- +--- Note: The optional values must be entered in order (i.e. you can't supply allowsMultipleSelection without also +--- supplying canChooseFiles and canChooseDirectories ). +--- Example: hs.inspect(hs.dialog.chooseFileOrFolder("Please select a file:", "~/Desktop", true, false, true, {"jpeg", +--- "pdf"}, true)) +---@param message string +---@param defaultPath string +---@param canChooseFiles boolean +---@param canChooseDirectories boolean +---@param allowsMultipleSelection boolean +---@param allowedFileTypes boolean +---@param resolvesAliases any +---@return string +function hs.dialog.chooseFileOrFolder(message, defaultPath, canChooseFiles, canChooseDirectories, allowsMultipleSelection, allowedFileTypes, resolvesAliases) end + +--- Displays a simple text input dialog box. +--- +--- Note: buttonOne defaults to "OK" if no value is supplied. +--- buttonOne will also be triggered by pressing ENTER , whereas buttonTwo will be triggered by pressing ESC . +--- Examples: hs.dialog.textPrompt("Main message.", "Please enter something:") hs.dialog.textPrompt("Main message.", +--- "Please enter something:", "Default Value", "OK") hs.dialog.textPrompt("Main message.", "Please enter something:", +--- "Default Value", "OK", "Cancel") hs.dialog.textPrompt("Main message.", "Please enter something:", "", "OK", +--- "Cancel", true) +---@param message string +---@param informativeText string +---@param defaultText string +---@param buttonOne any +---@param buttonTwo any +---@param secureField any +---@return string +---@return string +function hs.dialog.textPrompt(message, informativeText, defaultText, buttonOne, buttonTwo, secureField) end + +--- Displays a simple dialog box using +--- NSAlert +--- in a +--- hs.webview +--- . +--- +--- Note: This alert is will prevent the user from interacting with the hs.webview until a button is pressed on the +--- alert. +--- The optional values must be entered in order (i.e. you can't supply style without also supplying buttonOne and +--- buttonTwo ). +--- [style] can be "warning", "informational" or "critical". If something other than these string values is given, it +--- will use "informational". +--- Example: testCallbackFn = function ( result ) print ( "Callback Result: " .. result ) end testWebviewA = hs . +--- webview . newBrowser ( hs . geometry . rect ( 250 , 250 , 250 , 250 )): show () testWebviewB = hs . webview . +--- newBrowser ( hs . geometry . rect ( 450 , 450 , 450 , 450 )): show () hs . dialog . webviewAlert ( testWebviewA , +--- testCallbackFn , "Message" , "Informative Text" , "Button One" , "Button Two" , "warning" ) hs . dialog . +--- webviewAlert ( testWebviewB , testCallbackFn , "Message" , "Informative Text" , "Single Button" ) ``` +---@param webview hs.webview +---@param callbackFn function +---@param message string +---@param informativeText string +---@param buttonOne any +---@param buttonTwo any +---@param style any +---@return string +function hs.dialog.webviewAlert(webview, callbackFn, message, informativeText, buttonOne, buttonTwo, style) end + +-- ------------------------------------------------------------ +-- hs.dialog.color +-- ------------------------------------------------------------ + +---@class hs.dialog.color +hs.dialog.color = {} + +--- Set or display the selected opacity. +--- +--- Note: Example: hs.dialog.color.alpha(0.5) +---@param value any +---@return number +function hs.dialog.color.alpha(value) end + +--- Sets or removes the callback function for the color panel. +--- +--- Note: Example: hs.dialog.color.callback(function(a,b) print("COLOR CALLBACK:\nSelected Color: " .. hs.inspect(a) .. +--- "\nPanel Closed: " .. hs.inspect(b)) end) +---@param callbackFn any +---@return function|nil +function hs.dialog.color.callback(callbackFn) end + +--- Set or display the currently selected color in a color wheel. +--- +--- Note: Example: hs.dialog.color.color(hs.drawing.color.blue) +---@param value any +---@return table +function hs.dialog.color.color(value) end + +--- Set or display whether or not the callback should be continuously updated when a user drags a color slider or +--- control. +--- +--- Note: Example: hs.dialog.color.continuous(true) +---@param value any +---@return boolean +function hs.dialog.color.continuous(value) end + +--- Hides the Color Panel. +--- +--- Note: Example: hs.dialog.color.hide() +---@return none +function hs.dialog.color.hide() end + +--- Set or display the currently selected color panel mode. +--- +--- Note: Example: hs.dialog.color.mode("RGB") +---@param value any +---@return table +function hs.dialog.color.mode(value) end + +--- Shows the Color Panel. +--- +--- Note: Example: hs.dialog.color.show() +---@return none +function hs.dialog.color.show() end + +--- Set or display whether or not the color panel should display an opacity slider. +--- +--- Note: Example: hs.dialog.color.showsAlpha(true) +---@param value any +---@return boolean +function hs.dialog.color.showsAlpha(value) end + +-- ------------------------------------------------------------ +-- hs.distributednotifications +-- ------------------------------------------------------------ + +---@class hs.distributednotifications +hs.distributednotifications = {} + +---@class distributednotifications +local distributednotifications = {} + +--- Sends a distributed notification +---@param name string +---@param sender? string|nil +---@param userInfo? table|nil +---@return any +function hs.distributednotifications.post(name, sender, userInfo) end + +--- Creates a new NSDistributedNotificationCenter watcher +--- +--- Note: On Catalina and above, it is no longer possible to observe all notifications - the name parameter is +--- effectively now required. See https://mjtsai.com/blog/2019/10/04/nsdistributednotificationcenter-no-longer-supports-nil-names +---@param callback function +---@param name? string|nil +---@param object? string|nil +---@return object +function hs.distributednotifications.new(callback, name, object) end + +--- Starts a NSDistributedNotificationCenter watcher +---@return object +function distributednotifications:start() end + +--- Stops a NSDistributedNotificationCenter watcher +---@return object +function distributednotifications:stop() end + +-- ------------------------------------------------------------ +-- hs.doc +-- ------------------------------------------------------------ + +---@class hs.doc +hs.doc = {} + +--- Prints the documentation for some part of Hammerspoon's API and Lua 5.3. This function has also been aliased as +--- hs.help +--- and +--- help +--- as a shorthand for use within the Hammerspoon console. +--- +--- Note: This function is mainly for runtime API help while using Hammerspoon's Console +--- Documentation files registered with hs.doc.registerJSONFile or hs.doc.preloadSpoonDocs that have not yet been +--- actually loaded will be loaded when this command is invoked in any of the forms described below. +--- help("prefix.path") -- quotes are required, e.g. help("hs.reload") +--- hs - provides documentation for Hammerspoon's builtin commands and modules +--- spoon - provides documentation for the Spoons installed on your system +--- lua._man - provides the table of contents for the Lua 5.3 manual. You can pull up a specific section of the lua +--- manual by including the chapter (and subsection) like this: lua._man._3_4_8 . +--- lua._C - provides documentation specifically about the Lua C API for use when developing modules which require +--- external libraries. +--- path is one or more components, separated by a period specifying the module, submodule, function, or method you +--- wish to view documentation for. +---@param identifier string +---@return any +function hs.doc.help(identifier) end + +--- Locates the JSON file corresponding to the specified third-party module or Spoon by searching package.path and +--- package.cpath. +--- +--- Note: The JSON should be named 'docs.json' and located in the same directory as the lua or so file which is used +--- when the module is loaded via require . +--- The documentation for core modules is stored in the JSON file specified by the hs.docstrings_json_file variable; +--- this function is intended for use in locating the documentation file for third party modules and Spoons. +---@param module any +---@return path|boolean +---@return message +function hs.doc.locateJSONFile(module) end + +--- Locates all installed Spoon documentation files and marks them for loading the next time the +--- hs.doc.help +--- function is invoked. +---@return any +function hs.doc.preloadSpoonDocs() end + +--- Returns the list of registered JSON files. +--- +--- Note: The table returned by this function has a metatable including a __tostring method which allows you to see the +--- list of registered files by simply typing hs.doc.registeredFiles() in the Hammerspoon Console. +--- By default, the internal core documentation and portions of the Lua 5.3 manual, located at +--- http://www.lua.org/manual/5.3/manual.html, are already registered for inclusion within this documentation object. +--- hs.doc.unregisterJSONFile(hs.docstrings_json_file) -- to unregister the Hammerspoon API docs +--- hs.doc.unregisterJSONFile((hs.docstrings_json_file:gsub("/docs.json$","/lua.json"))) -- to unregister the Lua 5.3 +--- Documentation. +---@return table +function hs.doc.registeredFiles() end + +--- Register a JSON file for inclusion when Hammerspoon generates internal documentation. +--- +--- Note: this function just registers the documentation file; it won't actually be loaded and parsed until hs.doc.help +--- is invoked. +---@param jsonfile string +---@param isSpoon boolean|nil +---@return status +---@return message +function hs.doc.registerJSONFile(jsonfile, isSpoon) end + +--- Remove a JSON file from the list of registered files. +--- +--- Note: This function requires the rebuilding of the entire documentation tree for all remaining registered files, so +--- the next time help is queried with hs.doc.help , there may be a slight one-time delay. +---@param jsonfile string +---@return status +---@return message +function hs.doc.unregisterJSONFile(jsonfile) end + +-- ------------------------------------------------------------ +-- hs.doc.builder +-- ------------------------------------------------------------ + +---@class hs.doc.builder +hs.doc.builder = {} + +--- Generates a documentation table for Hammerspoon modules or Spoon bundles from the source files located in the +--- path(s) provided. +--- +--- Note: Because Hammerspoon and all known currently available modules are coded in Objective-C and/or Lua, only files +--- with the .m or .lua extension are examined in the provided path(s). Please submit an issue (or pull request, if +--- you modify this submodule yourself) at https://github.com/Hammerspoon if you need this to be changed for your +--- addition. +---@param path string +---@param recurse any +---@return table +function hs.doc.builder.genComments(path, recurse) end + +--- Generates a JSON string representation of the documentation source specified. This is the format expected by +--- hs.doc +--- and +--- hs.doc.hsdoc +--- and is used to provide the built in documentation for Hammerspoon. +--- +--- Note: If you have installed the hs command line tool (see hs.ipc ), you can use the following to generate the +--- docs.json file that is used to provide documentation for Hammerspoon Spoon bundles: hs -c +--- "hs.doc.builder.genJSON(\"$(pwd)\")" > docs.json +--- You can also use this to generate documentation for any third-party-modules you build, but you will have to +--- register the documentation with hs.doc.registerJSONFile yourself -- it is not automatically loaded for you like it +--- is for Spoons. +---@param source hs.doc.builder.genComments +---@return string +function hs.doc.builder.genJSON(source) end + +--- Generates the SQL commands required for creating the search index when creating a docset of the documentation. +---@param source hs.doc.builder.genComments +---@return string +function hs.doc.builder.genSQL(source) end + +-- ------------------------------------------------------------ +-- hs.doc.hsdocs +-- ------------------------------------------------------------ + +---@class hs.doc.hsdocs +hs.doc.hsdocs = {} + +--- Get or set whether or not the Hammerspoon browser renders output in Dark mode. +--- +--- Note: Inversion is applied through the use of CSS filtering, so while numeric values other than 0 (false) and 100 +--- (true) are allowed, the result is generally not what is desired. +--- Changes made with this function are saved with hs.settings with the label "_documentationServer.invertDocs" and +--- will persist through a reload or restart of Hammerspoon. +---@param value any +---@return any +function hs.doc.hsdocs.browserDarkMode(value) end + +--- Get or set the currently saved initial frame location for the documentation browser. +--- +--- Note: If hs.doc.hsdocs.trackBrowserFrame is false or nil (the default), then you can use this function to specify +--- the initial position of the documentation browser. +--- If hs.doc.hsdocs.trackBrowserFrame is true, then this any value set with this function will be overwritten whenever +--- the browser window is moved or resized. +--- Changes made with this function are saved with hs.settings with the label "_documentationServer.browserFrame" and +--- will persist through a reload or restart of Hammerspoon. +---@param frameTable table +---@return any +function hs.doc.hsdocs.browserFrame(frameTable) end + +--- Get or set whether or not +--- hs.doc.hsdocs.help +--- uses an external browser. +--- +--- Note: If this value is set to true, help requests invoked by hs.doc.hsdocs.help will be invoked by your system's +--- default handler for the http scheme. +--- If this value is set to a string, the string specifies the bundle ID of an application which will be used to handle +--- the url request for the documentation. The string should match one of the items returned by +--- hs.urlevent.getAllHandlersForScheme("http") . +--- This behavior is triggered automatically, regardless of this setting, if you are running with a version of OS X +--- prior to 10.10, since hs.webview requires OS X 10.10 or later. +--- Changes made with this function are saved with hs.settings with the label +--- "_documentationServer.forceExternalBrowser" and will persist through a reload or restart of Hammerspoon. +---@param value hs.webview|nil +---@return any +function hs.doc.hsdocs.forceExternalBrowser(value) end + +--- Display the documentation for the specified Hammerspoon function, or the Table of Contents for the Hammerspoon +--- documentation in a built-in mini browser. +---@param identifier any +---@return nil +function hs.doc.hsdocs.help(identifier) end + +--- Get or set the network interface that the Hammerspoon documentation web server will be served on +--- +--- Note: See hs.httpserver.setInterface for a description of valid values that can be specified as the interface +--- argument to this function. +--- A change to the interface can only occur when the documentation server is not running. If the server is currently +--- active when you call this function with an argument, the server will be temporarily stopped and then restarted +--- after the interface has been changed. +--- Changes made with this function are saved with hs.settings with the label "_documentationServer.interface" and will +--- persist through a reload or restart of Hammerspoon. +---@param interface string|nil +---@return any +function hs.doc.hsdocs.interface(interface) end + +--- Get or set whether or not a module's entity list is displayed as a column on the left of the rendered page. +--- +--- Note: This is experimental and is disabled by default. It was inspired by a Userscript written by krasnovpro. The +--- original can be found at https://openuserjs.org/scripts/krasnovpro/hammerspoon.org_Documentation/source. +--- Changes made with this function are saved with hs.settings with the label "_documentationServer.entitiesInSidebar" +--- and will persist through a reload or restart of Hammerspoon. +---@param value any +---@return any +function hs.doc.hsdocs.moduleEntitiesInSidebar(value) end + +--- Get or set the Hammerspoon documentation server HTTP port. +--- +--- Note: The default port number is 12345. +--- Changes made with this function are saved with hs.settings with the label "_documentationServer.serverPort" and +--- will persist through a reload or restart of Hammerspoon. +---@param value number|nil +---@return any +function hs.doc.hsdocs.port(value) end + +--- Start the Hammerspoon internal documentation web server. +--- +--- Note: This function is automatically called, if necessary, when hs.doc.hsdocs.help is invoked. +--- The documentation web server can be viewed from a web browser by visiting "http://localhost:port" where port is the +--- port the server is running on, 12345 by default -- see hs.doc.hsdocs.port . +---@return hs.doc.hsdocs +function hs.doc.hsdocs.start() end + +--- Stop the Hammerspoon internal documentation web server. +---@return hs.doc.hsdocs +function hs.doc.hsdocs.stop() end + +--- Get or set whether or not changes in the documentation browsers location and size persist through launches of +--- Hammerspoon. +--- +--- Note: Changes made with this function are saved with hs.settings with the label +--- "_documentationServer.trackBrowserFrameChanges" and will persist through a reload or restart of Hammerspoon. +---@param value any +---@return any +function hs.doc.hsdocs.trackBrowserFrame(value) end + +-- ------------------------------------------------------------ +-- hs.doc.markdown +-- ------------------------------------------------------------ + +---@class hs.doc.markdown +hs.doc.markdown = {} + +--- Converts markdown encoded text to html or plaintext. +--- +--- Note: NO_INTRA_EMPHASIS - disallow emphasis inside of words +--- LAX_SPACING - supports spacing like in Markdown 1.0.0 (i.e. do not require an empty line between two +--- different blocks in a paragraph) +--- STRIKETHROUGH - support strikethrough with double tildes (~) +--- TABLES - support Markdown tables +--- FENCED_CODE - supports fenced code blocks surround by three back-ticks (`) or three tildes (~) +--- AUTOLINK - HTTP URL's are treated as links, even if they aren't marked as such with Markdown tags +--- The "gfm" type also includes the following extensions: +--- HARD_WRAP - line breaks are replaced with
entities +--- SPACE_HEADERS - require a space between the # and the name of a header (prevents collisions with the Issues filter) +---@param markdown string +---@param type any +---@return output +function hs.doc.markdown.convert(markdown, type) end + +-- ------------------------------------------------------------ +-- hs.dockicon +-- ------------------------------------------------------------ + +---@class hs.dockicon +hs.dockicon = {} + +--- Bounce Hammerspoon's dock icon +---@param indefinitely boolean +---@return any +function hs.dockicon.bounce(indefinitely) end + +--- Hide Hammerspoon's dock icon +---@return any +function hs.dockicon.hide() end + +--- Set Hammerspoon's dock icon badge +---@param badge string +---@return any +function hs.dockicon.setBadge(badge) end + +--- Make Hammerspoon's dock icon visible +---@return any +function hs.dockicon.show() end + +--- Get or set a canvas object to be displayed as the Hammerspoon dock icon +--- +--- Note: If you update the canvas object by changing any of its components, it will not be reflected in the dock icon +--- until you invoke hs.dockicon.tileUpdate . +---@param canvas hs.canvas|nil +---@return hs.canvas|nil +function hs.dockicon.tileCanvas(canvas) end + +--- Returns a table containing the size of the tile representing the dock icon. +--- +--- Note: the size returned specifies the display size of the dock icon tile. If your canvas item is larger than this, +--- then only the top left portion corresponding to the size returned will be displayed. +---@return size table +function hs.dockicon.tileSize() end + +--- Force an update of the dock icon. +--- +--- Note: Changes made to a canvas object are not reflected automatically like they are when a canvas is being +--- displayed on the screen; you must invoke this method after making changes to the canvas for the updates to be +--- reflected in the dock icon. +---@return none +function hs.dockicon.tileUpdate() end + +--- Determine whether Hammerspoon's dock icon is visible +---@return boolean +function hs.dockicon.visible() end + +-- ------------------------------------------------------------ +-- hs.drawing +-- ------------------------------------------------------------ + +---@class hs.drawing +hs.drawing = {} + +---@class drawing +local drawing = {} + +--- Array of window behavior labels for determining how an hs.drawing object is handled in Spaces and Exposé +---@type hs.drawing +hs.drawing.windowBehaviors[] = nil + +--- A table of predefined window levels usable with +--- hs.drawing:setLevel(...) +---@type table +hs.drawing.windowLevels = nil + +--- Returns a table containing the default font, size, color, and paragraphStyle used by +--- hs.drawing +--- for text drawing objects. +--- +--- Note: This method returns the default font, size, color, and paragraphStyle used by hs.drawing for text objects. +--- If you modify a drawing object's defaults with hs.drawing:setColor , hs.drawing:setTextFont , or +--- hs.drawing:setTextSize , the changes will not be reflected by this function. +---@return table +function hs.drawing.defaultTextStyle() end + +--- Tells the OS X window server to pause updating the physical displays for a short while. +--- +--- Note: This method can be used to allow multiple changes which are being made to the users display appear as if they +--- all occur simultaneously by holding off on updating the screen on the regular schedule. +--- This method should always be balanced with a call to hs.drawing.enableScreenUpdates when your updates have been +--- completed. Failure to do so will be logged in the system logs. +--- The window server will only allow you to pause updates for up to 1 second. This prevents a rogue or hung process +--- from locking the systems display completely. Updates will be resumed when hs.drawing.enableScreenUpdates is +--- encountered or after 1 second, whichever comes first. +--- The underlying OS function for disabling screen updates is deprecated. +---@deprecated +function hs.drawing.disableScreenUpdates() end + +--- Tells the OS X window server to resume updating the physical displays after a previous pause. +--- +--- Note: In conjunction with hs.drawing.disableScreenUpdates , this method can be used to allow multiple changes which +--- are being made to the users display appear as if they all occur simultaneously by holding off on updating the +--- screen on the regular schedule. +--- The window server will only allow you to pause updates for up to 1 second. This prevents a rogue or hung process +--- from locking the systems display completely. Updates will be resumed when this function is encountered or after 1 +--- second, whichever comes first. +--- The underlying OS function for enabling screen updates is deprecated. +---@deprecated +function hs.drawing.enableScreenUpdates() end + +--- Get the size of the rectangle necessary to fully render the text with the specified style so that is will be +--- completely visible. +--- +--- Note: This function assumes the default values specified for any key which is not included in the provided +--- textStyle. +--- The size returned is an approximation and may return a width that is off by about 4 points. Use the returned size +--- as a minimum starting point. Sometimes using the "clip" or "truncateMiddle" lineBreak modes or "justified" +--- alignment will fit, but its safest to add in your own buffer if you have the space in your layout. +--- Multi-line text (separated by a newline or return) is supported. The height will be for the multiple lines and the +--- width returned will be for the longest line. +--- The following simplified style format is supported for use with hs.drawing:setText and hs.drawing.setTextStyle . +--- theText - the text which is to be displayed. +--- font - the name of the font to use (default: the system font) +--- size - the font point size to use (default: 27.0) +--- color - ignored, but accepted for compatibility with hs.drawing:setTextStyle() +--- "left" - the text is visually left aligned. +--- "right" - the text is visually right aligned. +--- "center" - the text is visually center aligned. +--- "justified" - the text is justified +--- "natural" - (default) the natural alignment of the text’s script +--- "wordWrap" - (default) wrap at word boundaries, unless the word itself doesn’t fit on a single line +--- "charWrap" - wrap before the first character that doesn’t fit +--- "clip" - do not draw past the edge of the drawing object frame +--- "truncateHead" - the line is displayed so that the end fits in the frame and the missing text at the beginning of +--- the line is indicated by an ellipsis +--- "truncateTail" - the line is displayed so that the beginning fits in the frame and the missing text at the end of +--- the line is indicated by an ellipsis +--- "truncateMiddle" - the line is displayed so that the beginning and end fit in the frame and the missing text in the +--- middle is indicated by an ellipsis +---@param styledTextObject or theText string +---@param textStyle hs.drawing|nil +---@return sizeTable|nil +function hs.drawing.getTextDrawingSize(styledTextObject or theText, textStyle) end + +--- Creates a new image object with the icon of a given app +---@param sizeRect table +---@param bundleID string +---@return hs.drawing|nil +function hs.drawing.appImage(sizeRect, bundleID) end + +--- Creates a new arc object +--- +--- Note: This constructor is actually a wrapper for the hs.drawing.ellipticalArc constructor. +---@param centerPoint table +---@param radius any +---@param startAngle any +---@param endAngle any +---@return hs.drawing|nil +function hs.drawing.arc(centerPoint, radius, startAngle, endAngle) end + +--- Creates a new circle object +---@param sizeRect table +---@return hs.drawing|nil +function hs.drawing.circle(sizeRect) end + +--- Creates a new elliptical arc object +---@param sizeRect table +---@param startAngle any +---@param endAngle any +---@return hs.drawing|nil +function hs.drawing.ellipticalArc(sizeRect, startAngle, endAngle) end + +--- Creates a new image object +--- +--- Note: To use the ASCII diagram image support, see http://cocoamine.net/blog/2015/03/20/replacing-photoshop-with-nsstring/ and be sure to preface your ASCII diagram with the special string ASCII: +---@param sizeRect table +---@param imageData any +---@return hs.drawing|nil +function hs.drawing.image(sizeRect, imageData) end + +--- Creates a new line object +---@param originPoint table +---@param endPoint table +---@return hs.drawing|nil +function hs.drawing.line(originPoint, endPoint) end + +--- Creates a new rectangle object +---@param sizeRect table +---@return hs.drawing|nil +function hs.drawing.rectangle(sizeRect) end + +--- Creates a new text object +---@param sizeRect table +---@param message string +---@return hs.drawing|nil +function hs.drawing.text(sizeRect, message) end + +--- Get the alpha level of the window containing the hs.drawing object. +---@return number +function drawing:alpha() end + +--- Returns the current behavior of the hs.drawing object with respect to Spaces and Exposé for the object. +---@return number +function drawing:behavior() end + +--- Returns a table of the labels for the current behaviors of the object. +---@return table +function drawing:behaviorAsLabels() end + +--- Places the drawing object on top of normal windows +--- +--- Note: As of macOS Sierra and later, if you want a hs.drawing object to appear above full-screen windows you must +--- hide the Hammerspoon Dock icon first using: hs.dockicon.hide() +---@param aboveEverything boolean|nil +---@return hs.drawing +function drawing:bringToFront(aboveEverything) end + +--- Get or set whether or not clicking on a drawing with a click callback defined should bring all of Hammerspoon's +--- open windows to the front. +--- +--- Note: Setting this to false changes a drawing object's AXsubrole value and may affect the results of filters +--- defined for hs.window.filter, depending upon how they are defined. +---@param false any +---@return hs.drawing +function drawing:clickCallbackActivating(false) end + +--- Set the screen area in which the drawing contents are visible. +--- +--- Note: This method can be used to specify the area of the display where this drawing should be visible. If any +--- portion of the drawing extends beyond this rectangle, the image is clipped so that only the portion within this +--- rectangle is visible. +--- The rectangle defined by this method is independent of the drawing's actual frame -- if you move the drawing with +--- hs.drawing:setFrame or hs.drawing:setTopLeft , this rectangle retains its current value. +--- This method does not work for image objects at present. +---@param rect any +---@return hs.drawing +function drawing:clippingRectangle(rect) end + +--- Destroys the drawing object +--- +--- Note: This method immediately destroys the drawing object. If you want it to fade out, use :hide() first, with some +--- suitable time, and hs.timer.doAfter() to schedule the :delete() call +---@return any +function drawing:delete() end + +--- Gets the frame of a drawingObject in absolute coordinates +---@return hs.geometry +function drawing:frame() end + +--- Gets the text of a drawing object as an +--- hs.styledtext +--- object +--- +--- Note: This method should only be used on text drawing objects +---@return hs.styledtext +function drawing:getStyledText() end + +--- Hides the drawing object +---@param fadeOutTime any +---@return hs.drawing +function drawing:hide(fadeOutTime) end + +--- Get or set the alignment of an image that doesn't fully fill the drawing objects frame. +---@param type any +---@return hs.drawing +function drawing:imageAlignment(type) end + +--- Get or set whether or not an animated GIF image should cycle through its animation. +---@param flag any +---@return hs.drawing +function drawing:imageAnimates(flag) end + +--- Get or set what type of frame should be around the drawing frame of the image. +--- +--- Note: Apple considers the photo, groove, and button style frames "stylistically obsolete" and if a frame is +--- required, recommend that you use the bezel style or draw your own to more closely match the OS look and feel. +---@param type any +---@return hs.drawing +function drawing:imageFrame(type) end + +--- Get or set how an image is scaled within the frame of a drawing object containing an image. +---@param type any +---@return hs.drawing +function drawing:imageScaling(type) end + +--- Moves drawing object above drawing object2, or all drawing objects in the same presentation level, if object2 is +--- not provided. +---@param object2 any +---@return object +function drawing:orderAbove(object2) end + +--- Moves drawing object below drawing object2, or all drawing objects in the same presentation level, if object2 is +--- not provided. +---@param object2 any +---@return object1 +function drawing:orderBelow(object2) end + +--- Rotates an image clockwise around its center +--- +--- Note: This method works by rotating the image view within its drawing window. This means that an image which +--- completely fills its viewing area will most likely be cropped in some places. Best results are achieved with +--- images that have clear space around their edges or with hs.drawing.imageScaling set to "none". +---@param angle any +---@return hs.drawing +function drawing:rotateImage(angle) end + +--- Places the drawing object behind normal windows, between the desktop wallpaper and desktop icons +---@return hs.drawing +function drawing:sendToBack() end + +--- Sets the alpha level of the window containing the hs.drawing object. +---@param level any +---@return object +function drawing:setAlpha(level) end + +--- Changes the starting and ending angles for an arc drawing object +--- +--- Note: This method should only be used on arc drawing objects +---@param startAngle any +---@param endAngle any +---@return hs.drawing +function drawing:setArcAngles(startAngle, endAngle) end + +--- Sets the window behaviors represented by the number provided for the window containing the hs.drawing object. +---@param behavior any +---@return object +function drawing:setBehavior(behavior) end + +--- Sets the window behaviors based upon the labels specified in the table provided. +---@param table any +---@return object +function drawing:setBehaviorByLabels(table) end + +--- Sets a callback for mouseUp and mouseDown click events +--- +--- Note: No distinction is made between the left, right, or other mouse buttons -- they all invoke the same up or down +--- function. If you need to determine which specific button was pressed, use hs.eventtap.checkMouseButtons() within +--- your callback to check. +---@param mouseUpFn function +---@param mouseDownFn function +---@return hs.drawing +function drawing:setClickCallback(mouseUpFn, mouseDownFn) end + +--- Sets whether or not to fill a drawing object +--- +--- Note: This method should only be used on line, rectangle, circle, or arc drawing objects +---@param doFill boolean +---@return hs.drawing +function drawing:setFill(doFill) end + +--- Sets the fill color of a drawing object +--- +--- Note: This method should only be used on rectangle, circle, or arc drawing objects +--- Calling this method will remove any gradient fill colors previously set with hs.drawing:setFillGradient() +---@param color hs.drawing.color +---@return hs.drawing +function drawing:setFillColor(color) end + +--- Sets the fill gradient of a drawing object +--- +--- Note: This method should only be used on rectangle, circle, or arc drawing objects +--- Calling this method will remove any fill color previously set with hs.drawing:setFillColor() +---@param startColor any +---@param endColor any +---@param angle number +---@return hs.drawing +function drawing:setFillGradient(startColor, endColor, angle) end + +--- Sets the frame of the drawingObject in absolute coordinates +---@param rect table +---@return hs.drawing +function drawing:setFrame(rect) end + +--- Sets the image of a drawing object +---@param image hs.image +---@return hs.drawing +function drawing:setImage(image) end + +--- Sets the image of a drawing object from an ASCII representation +--- +--- Note: To use the ASCII diagram image support, see http://cocoamine.net/blog/2015/03/20/replacing-photoshop-with-nsstring +---@param ascii string +---@return hs.drawing +function drawing:setImageASCII(ascii) end + +--- Sets the image path of a drawing object +--- +--- Note: This method should only be used on an image drawing object +--- Paths relative to the PWD of Hammerspoon (typically ~/.hammerspoon/) will work, but paths relative to the UNIX +--- homedir character, ~ will not +--- Animated GIFs are supported. They're not super friendly on your CPU, but they work +---@param imagePath string +---@return hs.drawing +function drawing:setImageFromPath(imagePath) end + +--- Sets the window level more precisely than sendToBack and bringToFront. +--- +--- Note: see the notes for hs.drawing.windowLevels +--- These levels may be unable to explicitly place drawing objects around full-screen macOS windows +---@param theLevel hs.drawing.windowLevels +---@return hs.drawing +function drawing:setLevel(theLevel) end + +--- Sets the radii of the corners of a rectangle drawing object +--- +--- Note: This method should only be used on rectangle drawing objects +--- If either radius value is greater than half the width/height (as appropriate) of the rectangle, the value will be +--- clamped at half the width/height +--- If either (or both) radius values are 0, the rectangle will be drawn without rounded corners +---@param xradius number +---@param yradius number +---@return hs.drawing +function drawing:setRoundedRectRadii(xradius, yradius) end + +--- Resizes a drawing object +--- +--- Note: If this is called on an hs.drawing.text object, only its window will be resized. If you also want to change +--- the font size, use :setTextSize() +---@param size table +---@return hs.drawing +function drawing:setSize(size) end + +--- Sets whether or not to stroke a drawing object +--- +--- Note: This method should only be used on line, rectangle, circle, or arc drawing objects +---@param doStroke boolean +---@return hs.drawing +function drawing:setStroke(doStroke) end + +--- Sets the stroke color of a drawing object +--- +--- Note: This method should only be used on line, rectangle, circle, or arc drawing objects +---@param color hs.drawing.color +---@return hs.drawing +function drawing:setStrokeColor(color) end + +--- Sets the stroke width of a drawing object +--- +--- Note: This method should only be used on line, rectangle, circle, or arc drawing objects +---@param width number +---@return hs.drawing +function drawing:setStrokeWidth(width) end + +--- Sets the text of a drawing object from an +--- hs.styledtext +--- object +--- +--- Note: This method should only be used on text drawing objects +---@param message hs.styledtext +---@return hs.drawing +function drawing:setStyledText(message) end + +--- Sets the text of a drawing object +--- +--- Note: This method should only be used on text drawing objects +--- If the text of the drawing object is emptied (i.e. "") then style changes may be lost. Use a placeholder such as a +--- space (" ") or hide the object if style changes need to be saved but the text should disappear for a while. +---@param message string +---@return hs.drawing +function drawing:setText(message) end + +--- Sets the default text color for a drawing object +--- +--- Note: This method should only be called on text drawing objects +--- This method changes the font color for portions of an hs.drawing text object which do not have a specific font set +--- in their attributes list (see hs.styledtext for more details). +---@param color hs.drawing.color +---@return hs.drawing +function drawing:setTextColor(color) end + +--- Sets the default font for a drawing object +--- +--- Note: This method should only be used on text drawing objects +--- This method changes the font for portions of an hs.drawing text object which do not have a specific font set in +--- their attributes list (see hs.styledtext for more details). +---@param fontname string +---@return hs.drawing +function drawing:setTextFont(fontname) end + +--- Sets the default text size for a drawing object +--- +--- Note: This method should only be used on text drawing objects +--- This method changes the font size for portions of an hs.drawing text object which do not have a specific font set +--- in their attributes list (see hs.styledtext for more details). +---@param size number +---@return hs.drawing +function drawing:setTextSize(size) end + +--- Sets some simple style parameters for the entire text of a drawing object. For more control over style including +--- having multiple styles within a single text object, use +--- hs.styledtext +--- and +--- hs.drawing:setStyledText +--- instead. +--- +--- Note: This method should only be used on text drawing objects +--- If the text of the drawing object is currently empty (i.e. "") then style changes may be lost. Use a placeholder +--- such as a space (" ") or hide the object if style changes need to be saved but the text should disappear for a +--- while. +--- Only the keys specified are changed. To reset an object to all of its defaults, call this method with an explicit +--- nil as its only parameter (e.g. hs.drawing:setTextStyle(nil) +--- The font, font size, and font color can also be set by their individual specific methods as well; this method is +--- provided so that style components can be stored and applied collectively, as well as used by +--- hs.drawing.getTextDrawingSize() to determine the proper rectangle size for a textual drawing object. +---@param textStyle any +---@return hs.drawing +function drawing:setTextStyle(textStyle) end + +--- Moves the drawingObject to a given point +---@param point table +---@return hs.drawing +function drawing:setTopLeft(point) end + +--- Displays the drawing object +---@param fadeInTime number|nil +---@return hs.drawing +function drawing:show(fadeInTime) end + +-- ------------------------------------------------------------ +-- hs.drawing.color +-- ------------------------------------------------------------ + +---@class hs.drawing.color +hs.drawing.color = {} + +--- This table contains this list of defined color collections provided by the +--- hs.drawing.color +--- module. Collections differ from the system color lists in that you can modify the color values their members +--- contain by modifying the table at +--- hs.drawing.color.. +--- and future references to that color will reflect the new changes, thus allowing you to customize the palettes for +--- your installation. +---@type table +hs.drawing.color.definedCollections = nil + +--- A collection of colors representing the ANSI Terminal color sequences. The color definitions are based upon code +--- found at https://github.com/balthamos/geektool-3 in the /NerdTool/classes/ANSIEscapeHelper.m file. +---@type any +hs.drawing.color.ansiTerminalColors = nil + +--- This table contains a collection of various useful pre-defined colors: +---@type table +hs.drawing.color.hammerspoon = nil + +--- A collection of colors representing the X11 color names as defined at +--- https://en.wikipedia.org/wiki/Web_colors#X11_color_names (names in lowercase) +---@type any +hs.drawing.color.x11 = nil + +--- Returns a table containing the HSB representation of the specified color. +--- +--- Note: See also hs.drawing.color.asRGB +---@param color table +---@return table|string +function hs.drawing.color.asHSB(color) end + +--- Returns a table containing the RGB representation of the specified color. +--- +--- Note: See also hs.drawing.color.asHSB +---@param color table +---@return table|string +function hs.drawing.color.asRGB(color) end + +--- Returns a table containing the colors for the specified system color list or hs.drawing.color collection. +--- +--- Note: Where possible, each color node is provided as its RGB color representation. Where this is not possible, the +--- color node contains the keys list and name which identify the indicated color. This means that you can use the +--- following wherever a color parameter is expected: hs.drawing.color.colorsFor(list)["color-name"] +--- This function provides a tostring metatable method which allows listing the defined colors in the list in the +--- Hammerspoon console with: hs.drawing.colorsFor(list) +--- See also hs.drawing.color.lists +---@param list table +---@return table +function hs.drawing.color.colorsFor(list) end + +--- Returns a table containing the system color lists and hs.drawing.color collections with their defined colors. +--- +--- Note: Where possible, each color node is provided as its RGB color representation. Where this is not possible, the +--- color node contains the keys list and name which identify the indicated color. This means that you can use the +--- following wherever a color parameter is expected: hs.drawing.color.lists()["list-name"]["color-name"] +--- This function provides a tostring metatable method which allows listing the defined color lists in the Hammerspoon +--- console with: hs.drawing.color.lists() +--- See also hs.drawing.color.colorsFor +---@return table +function hs.drawing.color.lists() end + +-- ------------------------------------------------------------ +-- hs.eventtap +-- ------------------------------------------------------------ + +---@class hs.eventtap +hs.eventtap = {} + +---@class eventtap +local eventtap = {} + +--- Returns a table containing the current key modifiers being pressed or in effect +--- at this instant +--- for the keyboard most recently used. +--- +--- Note: This is an instantaneous poll of the current keyboard modifiers for the most recently used keyboard, not a +--- callback. This is useful primarily in conjunction with other modules, such as hs.menubar , when a callback is +--- already in progress or waiting for an event callback is not practical or possible. +--- the numeric value returned is useful if you need to detect device dependent flags or flags which we normally ignore +--- because they are not present (or are accessible another way) on most keyboards. +---@param raw boolean|nil +---@return table +function hs.eventtap.checkKeyboardModifiers(raw) end + +--- Returns a table containing the current mouse buttons being pressed +--- at this instant +--- . +--- +--- Note: This is an instantaneous poll of the current mouse buttons, not a callback. This is useful primarily in +--- conjunction with other modules, such as hs.menubar , when a callback is already in progress or waiting for an event +--- callback is not practical or possible. +---@return table +function hs.eventtap.checkMouseButtons() end + +--- Returns the system-wide setting for the delay between two clicks, to register a double click event +---@return number +function hs.eventtap.doubleClickInterval() end + +--- Checks if macOS is preventing keyboard events from being sent to event taps +--- +--- Note: If secure input is enabled, Hammerspoon is not able to intercept keyboard events +--- Secure input is enabled generally only in situations where an password field is focused in a web browser, system +--- dialog or terminal +---@return boolean +function hs.eventtap.isSecureInputEnabled() end + +--- Returns the system-wide setting for the delay before keyboard repeat events begin +---@return number +function hs.eventtap.keyRepeatDelay() end + +--- Returns the system-wide setting for the interval between repeated keyboard events +---@return number +function hs.eventtap.keyRepeatInterval() end + +--- Generates and emits a single keystroke event pair for the supplied keyboard modifiers and character +--- +--- Note: This function is ideal for sending single keystrokes with a modifier applied (e.g. sending ⌘-v to paste, with +--- hs.eventtap.keyStroke({"cmd"}, "v") ). If you want to emit multiple keystrokes for typing strings of text, see +--- hs.eventtap.keyStrokes() +--- Note that invoking this function with a table (empty or otherwise) for the modifiers argument will force the +--- release of any modifier keys which have been explicitly created by hs.eventtap.event.newKeyEvent and posted that +--- are still in the "down" state. An explicit nil for this argument will not (i.e. the keystroke will inherit any +--- currently "down" modifiers) +---@param modifiers table +---@param character string +---@param delay? number +---@param application? hs.application|nil +---@return any +function hs.eventtap.keyStroke(modifiers, character, delay, application) end + +--- Generates and emits keystroke events for the supplied text +--- +--- Note: If you want to send a single keystroke with keyboard modifiers (e.g. sending ⌘-v to paste), see +--- hs.eventtap.keyStroke() +---@param text string +---@param application? hs.application|nil +---@return any +function hs.eventtap.keyStrokes(text, application) end + +--- Generates a left mouse click event at the specified point +--- +--- Note: This is a wrapper around hs.eventtap.event.newMouseEvent that sends leftmousedown and leftmouseup events) +---@param point table +---@param delay? number +---@return any +function hs.eventtap.leftClick(point, delay) end + +--- Generates a middle mouse click event at the specified point +--- +--- Note: This function is just a wrapper which calls hs.eventtap.otherClick(point, delay, 2) and is included solely +--- for backwards compatibility. +---@param point table +---@param delay? number +---@return any +function hs.eventtap.middleClick(point, delay) end + +--- Generates an "other" mouse click event at the specified point +--- +--- Note: This is a wrapper around hs.eventtap.event.newMouseEvent that sends otherMouseDown and otherMouseUp events) +--- macOS recognizes up to 32 distinct mouse buttons, though few mouse devices have more than 3. The left mouse button +--- corresponds to button number 0 and the right mouse button corresponds to 1; distinct events are used for these +--- mouse buttons, so you should use hs.eventtap.leftClick and hs.eventtap.rightClick respectively. All other mouse +--- buttons are coalesced into the otherMouse events and are distinguished by specifying the specific button with the +--- mouseEventButtonNumber property, which this function does for you. +--- The specific purpose of mouse buttons greater than 2 varies by hardware and application (typically they are not +--- present on a mouse and have no effect in an application) +---@param point table +---@param delay? number +---@param button? number|nil +---@return any +function hs.eventtap.otherClick(point, delay, button) end + +--- Generates a right mouse click event at the specified point +--- +--- Note: This is a wrapper around hs.eventtap.event.newMouseEvent that sends rightmousedown and rightmouseup events) +---@param point table +---@param delay? number +---@return any +function hs.eventtap.rightClick(point, delay) end + +--- Generates and emits a scroll wheel event +---@param offsets table +---@param modifiers any +---@param unit string|nil +---@return event +function hs.eventtap.scrollWheel(offsets, modifiers, unit) end + +--- Create a new event tap object +--- +--- Note: If you specify the argument types as the special table {"all"[, events to ignore]}, then all events (except +--- those you optionally list after the "all" string) will trigger a callback, even events which are not defined in the +--- Quartz Event Reference . +---@param types table +---@param fn function|nil +---@return eventtap +function hs.eventtap.new(types, fn) end + +--- Determine whether or not an event tap object is enabled. +---@return boolean +function eventtap:isEnabled() end + +--- Starts an event tap +---@return any +function eventtap:start() end + +--- Stops an event tap +---@return any +function eventtap:stop() end + +-- ------------------------------------------------------------ +-- hs.eventtap.event +-- ------------------------------------------------------------ + +---@class hs.eventtap.event +hs.eventtap.event = {} + +---@class event +local event = {} + +--- A table containing property types for use with +--- hs.eventtap.event:getProperty() +--- and +--- hs.eventtap.event:setProperty() +--- . The table supports forward (label to number) and reverse (number to label) lookups to increase its flexibility. +---@type table +hs.eventtap.event.properties -> table = nil + +--- A table containing key-value pairs describing the raw modifier flags which can be manipulated with +--- hs.eventtap.event:rawFlags +--- . +---@type table +hs.eventtap.event.rawFlagMasks[] = nil + +--- A table containing event types to be used with +--- hs.eventtap.new(...) +--- and returned by +--- hs.eventtap.event:type() +--- . The table supports forward (label to number) and reverse (number to label) lookups to increase its flexibility. +---@type table +hs.eventtap.event.types -> table = nil + +--- Generates a table containing the keydown and keyup events to generate the keystroke with the specified modifiers. +--- +--- Note: The modifiers table must contain the full name of the modifiers you wish used for the keystroke as defined in +--- hs.keycodes.map -- the Unicode equivalents are not supported by this function. +--- The returned table will always contain an even number of events -- the first half will be the keyDown events and +--- the second half will be the keyUp events. +--- The events have not been posted; the table can be used without change as the return value for a callback to a +--- watcher defined with hs.eventtap.new . +---@param modifiers table +---@param character string +---@return table +function hs.eventtap.event.newKeyEventSequence(modifiers, character) end + +--- Duplicates an +--- hs.eventtap.event +--- event for further modification or injection +---@return event +function event:copy() end + +--- Creates a blank event. You will need to set its type with +--- hs.eventtap.event:setType +--- +--- Note: this is an empty event that you should set a type for and whatever other properties may be appropriate before +--- posting. +---@return event +function hs.eventtap.event.newEvent() end + +--- Creates an event from the data encoded in the string provided. +---@param data string +---@return event +function hs.eventtap.event.newEventFromData(data) end + +--- Creates an gesture event. +--- +--- Note: Valid gestureType values are: +--- beginMagnify - Starts a magnification event with an optional magnification value as a number (defaults to 0). The +--- exact unit of measurement is unknown. +--- endMagnify - Starts a magnification event with an optional magnification value as a number (defaults to 0.1). The +--- exact unit of measurement is unknown. +--- beginRotate - Starts a rotation event with an rotation value in degrees (i.e. a value of 45 turns it 45 degrees +--- left - defaults to 0). +--- endRotate - Starts a rotation event with an rotation value in degrees (i.e. a value of 45 turns it 45 degrees left +--- - defaults to 45). +--- beginSwipeLeft - Begin a swipe left. +--- endSwipeLeft - End a swipe left. +--- beginSwipeRight - Begin a swipe right. +--- endSwipeRight - End a swipe right. +--- beginSwipeUp - Begin a swipe up. +--- endSwipeUp - End a swipe up. +--- beginSwipeDown - Begin a swipe down. +--- endSwipeDown - End a swipe down. +---@param gestureType string +---@param gestureValue? any +---@return event +function hs.eventtap.event.newGesture(gestureType, gestureValue) end + +--- Creates a keyboard event +--- +--- Note: The original version of this constructor utilized a shortcut which merged flagsChanged and keyUp / keyDown +--- events into one. This approach is still supported for backwards compatibility and because it does work in most +--- cases. +--- According to Apple Documentation, the proper way to perform a keypress with modifiers is through multiple key +--- events; for example to generate 'Å', you should do the following: +--- hs +--- . +--- eventtap +--- . +--- event +--- . +--- newKeyEvent +--- ( +--- hs +--- . +--- keycodes +--- . +--- map +--- . +--- shift +--- , +--- true +--- ): +--- post +--- () +--- hs +--- . +--- eventtap +--- . +--- event +--- . +--- newKeyEvent +--- ( +--- hs +--- . +--- keycodes +--- . +--- map +--- . +--- alt +--- , +--- true +--- ): +--- post +--- () +--- hs +--- . +--- eventtap +--- . +--- event +--- . +--- newKeyEvent +--- ( +--- "a" +--- , +--- true +--- ): +--- post +--- () +--- hs +--- . +--- eventtap +--- . +--- event +--- . +--- newKeyEvent +--- ( +--- "a" +--- , +--- false +--- ): +--- post +--- () +--- hs +--- . +--- eventtap +--- . +--- event +--- . +--- newKeyEvent +--- ( +--- hs +--- . +--- keycodes +--- . +--- map +--- . +--- alt +--- , +--- false +--- ): +--- post +--- () +--- hs +--- . +--- eventtap +--- . +--- event +--- . +--- newKeyEvent +--- ( +--- hs +--- . +--- keycodes +--- . +--- map +--- . +--- shift +--- , +--- false +--- ): +--- post +--- () +--- The shortcut method is still supported, though if you run into odd behavior or need to generate flagsChanged events +--- without a corresponding keyUp or keyDown , please check out the syntax demonstrated above. +--- hs +--- . +--- eventtap +--- . +--- event +--- . +--- newKeyEvent +--- ({ +--- "shift" +--- , +--- "alt" +--- }, +--- "a" +--- , +--- true +--- ): +--- post +--- () +--- hs +--- . +--- eventtap +--- . +--- event +--- . +--- newKeyEvent +--- ({ +--- "shift" +--- , +--- "alt" +--- }, +--- "a" +--- , +--- false +--- ): +--- post +--- () +--- The shortcut approach is still limited to generating only the left version of modifiers. +---@param mods any +---@param key string +---@param isdown boolean +---@return event +function hs.eventtap.event.newKeyEvent(mods, key, isdown) end + +--- Creates a new mouse event +---@param eventtype hs.eventtap.event.types +---@param point hs.geometry +---@param modifiers? any +---@return event +function hs.eventtap.event.newMouseEvent(eventtype, point, modifiers) end + +--- Creates a scroll wheel event +---@param offsets table +---@param mods any +---@param unit string|nil +---@return event +function hs.eventtap.event.newScrollEvent(offsets, mods, unit) end + +--- Creates a keyboard event for special keys (e.g. media playback) +--- +--- Note: To set modifiers on a system key event (e.g. cmd/ctrl/etc), see the hs.eventtap.event:setFlags() method +--- The event names are case sensitive +---@param key string +---@param isdown boolean +---@return event +function hs.eventtap.event.newSystemKeyEvent(key, isdown) end + +--- Returns a string containing binary data representing the event. This can be used to record events for later use. +--- +--- Note: You can recreate the event for later posting with hs.eventtap.event.newEventFromData +---@return string +function event:asData() end + +--- Gets the state of a mouse button in the event +--- +--- Note: This method should only be called on mouse events +---@param button number +---@return boolean +function event:getButtonState(button) end + +--- Returns the Unicode character, if any, represented by a keyDown or keyUp event. +--- +--- Note: This method should only be used on keyboard events +--- If clean is true, all modifiers except for Shift are stripped from the character before converting to the Unicode +--- character represented by the keypress. +--- If the keypress does not correspond to a valid Unicode character, an empty string is returned (e.g. if clean is +--- false, then Opt-E will return an empty string, while Opt-Shift-E will return an accent mark). +---@param clean any +---@return string|nil +function event:getCharacters(clean) end + +--- Gets the keyboard modifiers of an event +---@return table +function event:getFlags() end + +--- Gets the raw keycode for the event +--- +--- Note: This method should only be used on keyboard events +---@return keycode +function event:getKeyCode() end + +--- Gets a property of the event +--- +--- Note: The properties are CGEventField values, as documented at https://developer.apple.com/library/mac/documentation/Carbon/Reference/QuartzEventServicesRef/index.html#//apple_ref/c/tdef/CGEventField +---@param prop hs.eventtap.event.properties +---@return number +function event:getProperty(prop) end + +--- Returns raw data about the event +--- +--- Note: Most of the data in CGEventData is already available through other methods, but is presented here without any +--- cleanup or parsing. +--- This method is expected to be used mostly for testing and expanding the range of possibilities available with the +--- hs.eventtap module. If you find that you are regularly using specific data from this method for common or +--- re-usable purposes, consider submitting a request for adding a more targeted method to hs.eventtap or +--- hs.eventtap.event -- it will likely be more efficient and faster for common tasks, something eventtaps need to be +--- to minimize affecting system responsiveness. +---@return table +function event:getRawEventData() end + +--- Returns a table containing more information about some touch related events. +---@return table|nil +function event:getTouchDetails() end + +--- Returns a table of details containing information about touches on the trackpad associated with this event if the +--- event is of the type +--- hs.eventtap.event.types.gesture +--- . +--- +--- Note: device - a string containing a unique identifier for the device on which the touch occurred. At present we do +--- not have a way to match the identifier to a specific touch device, but if multiple such devices are attached to the +--- computer, this value will differ between them. +--- deviceSize - a size table containing keys h and w for the height and width of the touch device in points (72 PPI +--- resolution). +--- force - a number representing a measure of the force of the touch when the device is a forcetouch trackpad. This +--- will be 0.0 for non-forcetouch trackpads and the touchbar. +--- identity - a string specifying a unique identifier for the touch guaranteed to be unique for the life of the touch. +--- This identifier may be used to track the movement of a specific touch (e.g. finger) as it moves through successive +--- callbacks. +--- phase - a string specifying the current phase the touch is considered to be in. The possible values are: "began", +--- "moved", "stationary", "ended", or "cancelled". +--- resting - Resting touches occur when a user simply rests their thumb on the trackpad device. Requires that the +--- foreground window has views accepting resting touches. +--- timestamp - a number representing the time the touch was detected. This number corresponds to seconds since the +--- last system boot, not including time the computer has been asleep. Comparable to hs.timer.absoluteTime() / +--- 1000000000 . +--- touching - a boolean specifying whether or not the touch phase is "began", "moved", or "stationary" (i.e. is not +--- "ended" or "cancelled"). +--- type - a string specifying the type of touch. A "direct" touch will indicate a touchbar, while a trackpad will +--- report "indirect". +--- The following fields will be present when the touch is from a touchpad ( type == "indirect")` +--- normalizedPosition - a point table specifying the x and y coordinates of the touch, each normalized to be a value +--- between 0.0 and 1.0. { x = 0, y = 0 } is the lower left corner of the touch device. +--- previousNormalizedPosition - a point table specifying the x and y coordinates of the previous position for this +--- specific touch (as linked by identity ) normalized to values between 0.0 and 1.0. +--- The following fields will be present when the touch is from the touchbar ( type == "direct")` +--- location - a point table specifying the x and y coordinates of the touch location within the touchbar. +--- previousLocation - a point table specifying the x and y coordinates of the previous location for this specific +--- touch (as linked by identity ) within the touchbar. +---@return table|nil +function event:getTouches() end + +--- Gets the type of the event +--- +--- Note: some newer events are grouped into a more generic event for watching purposes and the specific event type is +--- determined by examining the event through the Cocoa API. The primary example of this is for gestures on a trackpad +--- or touches of the touchbar, as all of these are grouped under the hs.eventtap.event.types.gesture event. For +--- example: myTap = hs . eventtap . new ( { hs . eventtap . event . types . gesture }, function ( e ) local +--- gestureType = e : getType ( true ) if gestureType == hs . eventtap . types . directTouch then -- they touched the +--- touch bar elseif gestureType == hs . eventtap . types . gesture then -- they are touching the trackpad, but it's +--- not for a gesture elseif gestureType == hs . eventtap . types . magnify then -- they're preforming a magnify +--- gesture -- etc -- see hs.eventtap.event.types for more endif end +---@param nsSpecificType any +---@return number +function event:getType(nsSpecificType) end + +--- Gets the single unicode character of an event +---@return string +function event:getUnicodeString() end + +--- Get or set the current mouse pointer location as defined for the event. +--- +--- Note: the use or effect of this method is undefined if the event is not a mouse type event. +---@param pointTable table|nil +---@return event|table +function event:location(pointTable) end + +--- Posts the event to the OS - i.e. emits the keyboard/mouse input defined by the event +---@param app hs.application|nil +---@return hs.eventtap.event +function event:post(app) end + +--- Experimental method to get or set the modifier flags for an event directly. +--- +--- Note: This method is experimental and may undergo changes or even removal in the future +--- See hs.eventtap.event.rawFlagMasks for more information +---@param flags hs.eventtap.event.rawFlagMasks|nil +---@return event|number +function event:rawFlags(flags) end + +--- Sets the keyboard modifiers of an event +---@param table any +---@return event +function event:setFlags(table) end + +--- Sets the raw keycode for the event +--- +--- Note: This method should only be used on keyboard events +---@param keycode number +---@return hs.eventtap.event +function event:setKeyCode(keycode) end + +--- Sets a property of the event +--- +--- Note: The properties are CGEventField values, as documented at https://developer.apple.com/library/mac/documentation/Carbon/Reference/QuartzEventServicesRef/index.html#//apple_ref/c/tdef/CGEventField +---@param prop hs.eventtap.event.properties +---@param value number +---@return hs.eventtap.event +function event:setProperty(prop, value) end + +--- Set the type for this event. +---@param type hs.eventtap.event.types +---@return event +function event:setType(type) end + +--- Sets a unicode string as the output of the event +--- +--- Note: Calling this method will reset any flags previously set on the event (because they don't make any sense, and +--- you should not try to set flags again) +--- This is likely to only work with short unicode strings that resolve to a single character +---@param string string +---@return hs.eventtap.event +function event:setUnicodeString(string) end + +--- Returns the special key and its state if the event is a NSSystemDefined event of subtype AUX_CONTROL_BUTTONS +--- (special-key pressed) +--- +--- Note: CAPS_LOCK seems to sometimes generate 0 or 2 key release events (down == false), especially on builtin laptop +--- keyboards, so it is probably safest (more reliable) to look for cases where down == true only. +--- If the key field contains "undefined", you can use the number in keyCode to look it up in +--- /System/Library/Frameworks/IOKit.framework/Headers/hidsystem/ev_keymap.h . If you believe the numeric value is +--- part of a new system update or was otherwise mistakenly left out, please submit the label (it will defined in the +--- header file as NX_KEYTYPE_something ) and number to the Hammerspoon maintainers at +--- https://github.com/Hammerspoon/hammerspoon with a request for inclusion in the next Hammerspoon update. +---@return table +function event:systemKey() end + +--- Get or set the timestamp of the event. +--- +--- Note: Synthesized events have a timestamp of 0 by default. +--- The timestamp, if specified, is expressed as an integer representing the number of nanoseconds since the system was +--- last booted. See hs.timer.absoluteTime . +--- This field appears to be informational only and is not required when crafting your own events with this module. +---@param absolutetime number|nil +---@return event|number +function event:timestamp(absolutetime) end + +-- ------------------------------------------------------------ +-- hs.expose +-- ------------------------------------------------------------ + +---@class hs.expose +hs.expose = {} + +---@class expose +local expose = {} + +--- Allows customization of the expose behaviour and user interface +---@type any +hs.expose.ui = nil + +--- Creates a new hs.expose instance; it can use a windowfilter to determine which windows to show +--- +--- Note: by default expose will show invisible windows and (unlike the OSX expose) windows from other spaces; use +--- hs.expose.ui or the uiPrefs parameter to change these behaviours. +---@param windowfilter any +---@param uiPrefs? hs.expose.ui|nil +---@param logname? hs.logger|nil +---@param loglevel? hs.logger|nil +---@return hs.expose +function hs.expose.new(windowfilter, uiPrefs, logname, loglevel) end + +--- Hides the expose, if visible, and exits the modal mode +--- +--- Note: Call this function if you need to make sure the modal is exited without waiting for the user to press esc +---@return any +function expose:hide() end + +--- Shows an expose-like screen with modal keyboard hints for switching to, closing or minimizing/unminimizing windows. +--- +--- Note: passing true for activeApplication will simply hide hints/thumbnails for applications other +--- than the active one, without recalculating the hints layout; conversely, setting onlyActiveApplication=true for an +--- expose instance's ui will calculate an optimal layout for the current active application's windows +--- Completing a hint will exit the expose and focus the selected window. +--- Pressing esc will exit the expose and with no action taken. +--- If shift is being held when a hint is completed (the background will be red), the selected +--- window will be closed. If it's the last window of an application, the application will be closed. +--- If alt is being held when a hint is completed (the background will be blue), the selected +--- window will be minimized (if visible) or unminimized/unhidden (if minimized or hidden). +---@param activeApplication any +---@return any +function expose:show(activeApplication) end + +--- Toggles the expose - see +--- hs.expose:show() +--- and +--- hs.expose:hide() +--- +--- Note: passing true for activeApplication will simply hide hints/thumbnails for applications other than the active +--- one, without recalculating the hints layout; conversely, setting onlyActiveApplication=true for an expose +--- instance's ui will calculate an optimal layout for the current active application's windows +--- Completing a hint will exit the expose and focus the selected window. +--- Pressing esc will exit the expose and with no action taken. +--- If shift is being held when a hint is completed (the background will be red), the selected window will be closed. +--- If it's the last window of an application, the application will be closed. +--- If alt is being held when a hint is completed (the background will be blue), the selected window will be minimized +--- (if visible) or unminimized/unhidden (if minimized or hidden). +---@param activeApplication any +---@return any +function expose:toggleShow(activeApplication) end + +-- ------------------------------------------------------------ +-- hs.fnutils +-- ------------------------------------------------------------ + +---@class hs.fnutils +hs.fnutils = {} + +--- Join two tables together +--- +--- Note: table2 cannot be a sparse table, see http://www.luafaq.org/gotchas.html#T6.4 +---@param table1 table +---@param table2 table +---@return table +function hs.fnutils.concat(table1, table2) end + +--- Determine if a table contains a given object +---@param table table +---@param element table +---@return boolean +function hs.fnutils.contains(table, element) end + +--- Copy a table using +--- pairs() +---@param table table +---@return table +function hs.fnutils.copy(table) end + +--- Execute a function across a table (in arbitrary order), and discard the results +---@param table table +---@param fn function +---@return any +function hs.fnutils.each(table, fn) end + +--- Returns true if the application of fn on every entry in table is true. +---@param table table +---@param fn function|nil +---@return boolean +function hs.fnutils.every(table, fn) end + +--- Filter a table by running a predicate function on its elements (in arbitrary order) +--- +--- Note: If table is a pure array table (list-like) without "holes", use hs.fnutils.ifilter() if you need guaranteed +--- in-order +--- processing and for better performance. +---@param table table +---@param fn function +---@return table +function hs.fnutils.filter(table, fn) end + +--- Execute a function across a table and return the first element where that function returns true +---@param table table +---@param fn function +---@return element +function hs.fnutils.find(table, fn) end + +--- Execute a function across a list-like table in order, and discard the results +---@param list table +---@param fn function +---@return any +function hs.fnutils.ieach(list, fn) end + +--- Filter a list-like table by running a predicate function on its elements in order +--- +--- Note: If list has "holes", all elements after the first hole will be lost, as the table is iterated over with +--- ipairs ; +--- use hs.fnutils.map() if your table has holes +---@param list table +---@param fn function +---@return list +function hs.fnutils.ifilter(list, fn) end + +--- Execute a function across a list-like table in order, and collect the results +--- +--- Note: If list has "holes", all elements after the first hole will be lost, as the table is iterated over with +--- ipairs ; +--- use hs.fnutils.map() if your table has holes +---@param list table +---@param fn function +---@return list +function hs.fnutils.imap(list, fn) end + +--- Determine the location in a table of a given object +---@param table table +---@param element table +---@return number|nil +function hs.fnutils.indexOf(table, element) end + +--- Execute a function across a table (in arbitrary order) and collect the results +--- +--- Note: If table is a pure array table (list-like) without "holes", use hs.fnutils.imap() if you need guaranteed +--- in-order +--- processing and for better performance. +---@param table table +---@param fn function +---@return table +function hs.fnutils.map(table, fn) end + +--- Execute, across a table, a function that outputs tables, and concatenate all of those tables together +---@param table table +---@param fn function +---@return table +function hs.fnutils.mapCat(table, fn) end + +--- Reduce a table to a single element, using a function +--- +--- Note: table cannot be a sparse table, see http://www.luafaq.org/gotchas.html#T6.4 +--- The first iteration of the reducer will call fn with the first and second elements of the table. The second +--- iteration will call fn with the result of the first iteration, and the third element. This repeats until there is +--- only one element left +---@param table table +---@param fn function +---@param initial? table +---@return table +function hs.fnutils.reduce(table, fn, initial) end + +--- Returns true if the application of fn on entries in table are true for at least one of the members. +---@param table table +---@param fn function|nil +---@return boolean +function hs.fnutils.some(table, fn) end + +--- Convert string to an array of strings, breaking at the specified separator. +--- +--- Note: Similar to "split" in Perl or "string.split" in Python. +--- Optional parameters nMax and bPlain are identified by their type -- if parameter 3 or 4 is a number or nil, it will +--- be considered a value for nMax ; if parameter 3 or 4 is a boolean value, it will be considered a value for bPlain . +--- Lua patterns are more flexible for pattern matching, but can also be slower if the split point is simple. See +--- §6.4.1 of the Lua_Reference_Manual at http://www.lua.org/manual/5.3/manual.html#6.4.1 for more information on Lua +--- patterns. +---@param sString string +---@param sSeparator any +---@param nMax? string|nil +---@param bPlain? boolean|nil +---@return { array } +function hs.fnutils.split(sString, sSeparator, nMax, bPlain) end + +--- Creates a function that repeatedly iterates a table +--- +--- Note: table cannot be a sparse table, see http://www.luafaq.org/gotchas.html#T6.4 +--- An example usage: f = cycle ({ 4 , 5 , 6 }) { f (), f (), f (), f (), f (), f (), f ()} == { 4 , 5 , 6 , 4 , 5 , 6 +--- , 4 } +---@param table table +---@return fn +function hs.fnutils.cycle(table) end + +--- Returns a new function which takes the provided arguments and pre-applies them as the initial arguments to the +--- provided function. When the new function is later invoked with additional arguments, they are appended to the end +--- of the initial list given and the complete list of arguments is finally passed into the provided function and its +--- result returned. +--- +--- Note: This is best understood with an example which you can test in the Hammerspoon console: Create the function a +--- which has it's initial arguments set to 1,2,3 : +--- a = hs.fnutils.partial(function(...) return table.pack(...) end, 1, 2, 3) Now some examples of using the new +--- function, a(...) : +--- hs.inspect(a("a","b","c")) will return: { 1, 2, 3, "a", "b", "c", n = 6 } +--- hs.inspect(a(4,5,6,7)) will return: { 1, 2, 3, 4, 5, 6, 7, n = 7 } +--- hs.inspect(a(1)) will return: { 1, 2, 3, 1, n = 4 } +---@param fn function +---@param ... any +---@return fn' +function hs.fnutils.partial(fn, ...) end + +--- Creates a function that will collect the result of a series of functions into a table +---@param ... any +---@return fn +function hs.fnutils.sequence(...) end + +--- Iterator for retrieving elements from a table of key-value pairs in the order of the keys. +--- +--- Note: Similar to Perl's sort(keys %hash) +--- for i,v in hs.fnutils.sortByKeys(t[, f]) do ... end +--- e.g. function(m,n) return not (m < n) end would result in reverse alphabetic order. +--- See Programming_In_Lua,_3rd_ed , page 52 for a more complete discussion. +--- function(m,n) if type(m) ~= type(n) then return tostring(m) < tostring(n) else return m < n end +---@param table table +---@param function any +---@return function +function hs.fnutils.sortByKeys(table, function) end + +--- Iterator for retrieving elements from a table of key-value pairs in the order of the values. +--- +--- Note: Similar to Perl's sort { $hash{$a} <=> $hash{$b} } keys %hash +--- for i,v in hs.fnutils.sortByKeyValues(t[, f]) do ... end +--- e.g. function(m,n) return not (m < n) end would result in reverse alphabetic order. +--- See Programming_In_Lua,_3rd_ed , page 52 for a more complete discussion. +--- function(m,n) if type(m) ~= type(n) then return tostring(m) < tostring(n) else return m < n end +---@param table table +---@param function any +---@return function +function hs.fnutils.sortByKeyValues(table, function) end + +-- ------------------------------------------------------------ +-- hs.fs +-- ------------------------------------------------------------ + +---@class hs.fs +hs.fs = {} + +--- A table containing the default list of patterns to ignore when using the +--- hs.fs.fileListForPath +--- . +---@type table +hs.fs.defaultPathListExcludes -> table = nil + +--- Gets the attributes of a file +--- +--- Note: This function uses stat() internally thus if the given filepath is a symbolic link, it is followed (if it +--- points to another link the chain is followed recursively) and the information is about the file it refers to. To +--- obtain information about the link itself, see function hs.fs.symlinkAttributes() +---@param filepath string +---@param aName? string +---@return table|string|nil +---@return error +function hs.fs.attributes(filepath, aName) end + +--- Changes the current working directory to the given path. +---@param path string +---@return boolean|nil +---@return error +function hs.fs.chdir(path) end + +--- Gets the current working directory +---@return string|nil +---@return error +function hs.fs.currentDir() end + +--- Creates an iterator for walking a filesystem path +--- +--- Note: Unlike most functions in this module, hs.fs.dir will throw a Lua error if the supplied path cannot be +--- iterated. +--- The simplest way to use this function is with a for loop. When used in this manner, the for loop itself will take +--- care of closing the directory stream for us, even if we break out of the loop early. for file in +--- hs.fs.dir("/Users/Guest/Documents") do +--- print(file) +--- end +--- It is also possible to use the dir_obj directly if you wish: local iterFn, dirObj = +--- hs.fs.dir("/Users/Guest/Documents") +--- local file = dirObj:next() -- get the first file in the directory +--- while (file) do +--- print(file) +--- file = dirObj:next() -- get the next file in the directory +--- end +--- dirObj:close() -- necessary to make sure that the directory stream is closed +---@param path string +---@return iter_fn +---@return dir_obj +---@return nil +---@return dir_obj +function hs.fs.dir(path) end + +--- Returns the display name of the file or directory at a specified path. +---@param filepath string +---@return string +function hs.fs.displayName(filepath) end + +--- Returns a table containing the paths to all of the files located at the specified path. +--- +--- Note: note that this function only checks to see if the regular expression returns a match for each filename found +--- (not the path, just the filename component of the path). Any captures are ignored. +---@param path string +---@param options any +---@return table +---@return fileCount +---@return dirCount +function hs.fs.fileListForPath(path, options) end + +--- Returns the Uniform Type Identifier for the file location specified. +---@param path string +---@return string|nil +function hs.fs.fileUTI(path) end + +--- Returns the fileUTI's equivalent form in an alternate type specification format. +---@param fileUTI any +---@param type any +---@return string +function hs.fs.fileUTIalternate(fileUTI, type) end + +--- Get the Finder comments for the file or directory at the specified path +--- +--- Note: This function uses hs.osascript to access the file comments through AppleScript +---@param path string +---@return string +function hs.fs.getFinderComments(path) end + +--- Creates a link +---@param old string +---@param new string +---@param symlink? boolean|nil +---@return boolean|nil +---@return error +function hs.fs.link(old, new, symlink) end + +--- Locks a file, or part of it +---@param filehandle any +---@param mode string +---@param start? number|nil +---@param length? number|nil +---@return boolean|nil +---@return error +function hs.fs.lock(filehandle, mode, start, length) end + +--- Locks a directory +--- +--- Note: This is not a low level OS feature, the lock is actually a file created in the path, called lockfile.lfs , so +--- the directory must be writable for this function to succeed +--- The returned lock object can be freed with lock:free() +--- If the lock already exists and is not stale, the error string returned will be "File exists" +---@param path string +---@param seconds_stale number|nil +---@return lock|nil +---@return error +function hs.fs.lockDir(path, seconds_stale) end + +--- Creates a new directory +---@param dirname string +---@return boolean|nil +---@return error +function hs.fs.mkdir(dirname) end + +--- Gets the file path from a binary encoded bookmark. +--- +--- Note: A bookmark provides a persistent reference to a file-system resource. +--- When you resolve a bookmark, you obtain a URL to the resource’s current location. +--- A bookmark’s association with a file-system resource (typically a file or folder) +--- usually continues to work if the user moves or renames the resource, or if the +--- user relaunches your app or restarts the system. +--- No volumes are mounted during the resolution of the bookmark data. +---@param data any +---@return string|nil +---@return string +function hs.fs.pathFromBookmark(data) end + +--- Gets the absolute path of a given path +---@param filepath string +---@return string +function hs.fs.pathToAbsolute(filepath) end + +--- Returns the path as binary encoded bookmark data. +---@param path string +---@return string|nil +function hs.fs.pathToBookmark(path) end + +--- Removes an existing directory +---@param dirname string +---@return boolean|nil +---@return error +function hs.fs.rmdir(dirname) end + +--- Set the Finder comments for the file or directory at the specified path to the comment specified +--- +--- Note: This function uses hs.osascript to access the file comments through AppleScript +---@param path string +---@param comment string +---@return boolean +function hs.fs.setFinderComments(path, comment) end + +--- Gets the attributes of a symbolic link +--- +--- Note: The return values for this function are identical to those provided by hs.fs.attributes() with the following +--- addition: the attribute name "target" is added and specifies a string containing the absolute path that the symlink +--- points to. +---@param filepath string +---@param aname? string +---@return table|string|nil +---@return error +function hs.fs.symlinkAttributes(filepath, aname) end + +--- Adds one or more tags to the Finder tags of a file +---@param filepath string +---@param tags table +---@return any +function hs.fs.tagsAdd(filepath, tags) end + +--- Gets the Finder tags of a file +---@param filepath string +---@return table|nil +function hs.fs.tagsGet(filepath) end + +--- Removes Finder tags from a file +---@param filepath string +---@param tags table +---@return any +function hs.fs.tagsRemove(filepath, tags) end + +--- Sets the Finder tags of a file, removing any that are already set +---@param filepath string +---@param tags table +---@return any +function hs.fs.tagsSet(filepath, tags) end + +--- Returns the path of the temporary directory for the current user. +---@return string +function hs.fs.temporaryDirectory() end + +--- Updates the access and modification times of a file +---@param filepath string +---@param atime? number|nil +---@param mtime? number|nil +---@return boolean|nil +---@return error +function hs.fs.touch(filepath, atime, mtime) end + +--- Unlocks a file or a part of it. +---@param filehandle any +---@param start? number|nil +---@param length? number|nil +---@return boolean|nil +---@return error +function hs.fs.unlock(filehandle, start, length) end + +--- Returns the encoded URL from a path. +---@param path string +---@return string|nil +function hs.fs.urlFromPath(path) end + +-- ------------------------------------------------------------ +-- hs.fs.volume +-- ------------------------------------------------------------ + +---@class hs.fs.volume +hs.fs.volume = {} + +---@class volume +local volume = {} + +---@class hs.fs.volume.volume +---@field didMount any A volume was mounted +---@field didRename any A volume changed either its name or mountpoint (or more likely, both) +---@field didUnmount any A volume was unmounted +---@field willUnmount any A volume is about to be unmounted + +--- A volume was mounted +---@type any +hs.fs.volume.didMount = nil + +--- A volume changed either its name or mountpoint (or more likely, both) +---@type any +hs.fs.volume.didRename = nil + +--- A volume was unmounted +---@type any +hs.fs.volume.didUnmount = nil + +--- A volume is about to be unmounted +---@type any +hs.fs.volume.willUnmount = nil + +--- Returns a table of information about disk volumes attached to the system +--- +--- Note: This is an alias for hs.host.volumeInformation() +--- The possible keys in the table are: +--- NSURLVolumeTotalCapacityKey - Size of the volume in bytes +--- NSURLVolumeAvailableCapacityKey - Available space on the volume in bytes +--- NSURLVolumeIsAutomountedKey - Boolean indicating if the volume was automounted +--- NSURLVolumeIsBrowsableKey - Boolean indicating if the volume can be browsed +--- NSURLVolumeIsEjectableKey - Boolean indicating if the volume should be ejected before its media is removed +--- NSURLVolumeIsInternalKey - Boolean indicating if the volume is an internal drive or an external drive +--- NSURLVolumeIsLocalKey - Boolean indicating if the volume is a local or remote drive +--- NSURLVolumeIsReadOnlyKey - Boolean indicating if the volume is read only +--- NSURLVolumeIsRemovableKey - Boolean indicating if the volume's media can be physically ejected from the drive (e.g. +--- a DVD) +--- NSURLVolumeMaximumFileSizeKey - Maximum file size the volume can support, in bytes +--- NSURLVolumeUUIDStringKey - The UUID of volume's filesystem +--- NSURLVolumeURLForRemountingKey - For remote volumes, the network URL of the volume +--- NSURLVolumeLocalizedNameKey - Localized version of the volume's name +--- NSURLVolumeNameKey - The volume's name +--- NSURLVolumeLocalizedFormatDescriptionKey - Localized description of the volume +--- Not all keys will be present for all volumes +--- The meanings of NSURLVolumeIsEjectableKey and NSURLVolumeIsRemovableKey are not generally useful for determining if +--- a drive is removable in the modern sense (e.g. a USB drive) as much of this terminology dates back to when USB +--- didn't exist and removable drives were things like Floppy/DVD drives. If you're trying to determine if a drive is +--- not fixed into the computer, you may need to use a combination of these keys, but which exact combination you +--- should use, is not consistent across macOS versions. +---@param showHidden boolean|nil +---@return table +function hs.fs.volume.allVolumes(showHidden) end + +--- Unmounts and ejects a volume +---@param path string +---@return boolean +---@return string +function hs.fs.volume.eject(path) end + +--- Creates a watcher object for volume events +---@param fn function +---@return watcher +function hs.fs.volume.new(fn) end + +--- Starts the volume watcher +---@return hs.fs.volume +function volume:start() end + +--- Stops the volume watcher +---@return hs.fs.volume +function volume:stop() end + +-- ------------------------------------------------------------ +-- hs.fs.xattr +-- ------------------------------------------------------------ + +---@class hs.fs.xattr +hs.fs.xattr = {} + +--- Set the extended attribute to the value provided for the path specified. +--- +--- Note: See also hs.fs.xattr.getHumanReadable . +---@param path string +---@param attribute string +---@param options table|nil +---@param position number|nil +---@return string|boolean|nil +function hs.fs.xattr.get(path, attribute, options, position) end + +--- A wrapper to +--- hs.fs.xattr.get +--- which returns non UTF-8 data as a hexadecimal dump provided by +--- hs.utf8.hexDump +--- . +--- +--- Note: This is provided for testing and debugging purposes; in general you probably want hs.fs.xattr.get once you +--- know how to properly understand the data returned for the attribute. +--- This is similar to the long format option in the command line xattr command. +---@param path string +---@param attribute string +---@param options table|nil +---@param position number|nil +---@return string|boolean|nil +function hs.fs.xattr.getHumanReadable(path, attribute, options, position) end + +--- Returns a list of the extended attributes currently defined for the specified file or directory +---@param path string +---@param options table|nil +---@return table +function hs.fs.xattr.list(path, options) end + +--- Removes the specified extended attribute from the file or directory at the path specified. +---@param path string +---@param attribute string +---@param options table|nil +---@return boolean +function hs.fs.xattr.remove(path, attribute, options) end + +--- Set the extended attribute to the value provided for the path specified. +---@param path string +---@param attribute string +---@param value string +---@param options table|nil +---@param position number|nil +---@return boolean +function hs.fs.xattr.set(path, attribute, value, options, position) end + +-- ------------------------------------------------------------ +-- hs.geometry +-- ------------------------------------------------------------ + +---@class hs.geometry +---@field area number A number representing the area of this rect or size; changing it will scale the rect/size - see hs.geometry:scale() +---@field aspect number A number representing the aspect ratio of this rect or size; changing it will reshape the rect/size, keeping its area... +---@field bottomright any Alias for x2y2 +---@field center any A point representing the geometric center of this rect or the midpoint of this vector2; changing it will move the... +---@field h any The height of this rect or size; changing it will keep the rect's x,y corner constant +---@field length number A number representing the length of the diagonal of this rect, or the length of this vector2; changing it will scale... +---@field string hs.geometry The "X,Y/WxH" string for this hs.geometry object ( reduced precision ); useful e.g +---@field table hs.geometry The {x=X,y=Y,w=W,h=H} table for this hs.geometry object; useful e.g +---@field topleft any Alias for xy +---@field w any The width of this rect or size; changing it will keep the rect's x,y corner constant +---@field wh hs.geometry The size component for this hs.geometry object; setting this to a new size will keep the rect's x,y corner constant +---@field x any The x coordinate for this point or rect's corner; changing it will move the rect but keep the same width and height +---@field x1 any Alias for x +---@field x2 any The x coordinate for the second corner of this rect; changing it will affect the rect's width +---@field x2y2 hs.geometry The point denoting the other corner of this hs.geometry object; setting this to a new point will change the rect's... +---@field xy hs.geometry The point component for this hs.geometry object; setting this to a new point will move the rect but keep the same width... +---@field y any The y coordinate for this point or rect's corner; changing it will move the rect but keep the same width and height +---@field y1 any Alias for y +---@field y2 any The y coordinate for the second corner of this rect; changing it will affect the rect's height +hs.geometry = {} + +---@class geometry +---@field area number A number representing the area of this rect or size; changing it will scale the rect/size - see hs.geometry:scale() +---@field length number A number representing the length of the diagonal of this rect, or the length of this vector2; changing it will scale... +---@field string hs.geometry The "X,Y/WxH" string for this hs.geometry object ( reduced precision ); useful e.g +---@field table hs.geometry The {x=X,y=Y,w=W,h=H} table for this hs.geometry object; useful e.g +---@field wh hs.geometry The size component for this hs.geometry object; setting this to a new size will keep the rect's x,y corner constant +---@field x2y2 hs.geometry The point denoting the other corner of this hs.geometry object; setting this to a new point will change the rect's... +---@field xy hs.geometry The point component for this hs.geometry object; setting this to a new point will move the rect but keep the same width... +local geometry = {} + +--- Creates a copy of an hs.geometry object +---@param geom hs.geometry +---@return hs.geometry +function hs.geometry.copy(geom) end + +--- Creates a new hs.geometry object +---@param ... any +---@return hs.geometry +function hs.geometry.new(...) end + +--- Convenience function for creating a point object +---@param x number +---@param y number +---@return hs.geometry point +function hs.geometry.point(x, y) end + +--- Convenience function for creating a rect-table +---@param x number +---@param y number +---@param w number +---@param h number +---@return hs.geometry rect +function hs.geometry.rect(x, y, w, h) end + +--- Convenience function for creating a size object +---@param w number +---@param h number +---@return hs.geometry size +function hs.geometry.size(w, h) end + +--- Returns the angle between the positive x axis and this vector2 +---@return number +function geometry:angle() end + +--- Returns the angle between the positive x axis and the vector connecting this point or rect's center to another +--- point or rect's center +---@param point hs.geometry +---@return number +function geometry:angleTo(point) end + +--- Finds the distance between this point or rect's center and another point or rect's center +---@param point hs.geometry +---@return number +function geometry:distance(point) end + +--- Checks if two geometry objects are equal +---@param other hs.geometry +---@return boolean +function geometry:equals(other) end + +--- Ensure this rect is fully inside +--- bounds +--- , by scaling it down if it's larger (preserving its aspect ratio) and moving it if necessary +---@param bounds hs.geometry +---@return hs.geometry +function geometry:fit(bounds) end + +--- Truncates all coordinates in this object to integers +---@return hs.geometry +function geometry:floor() end + +--- Converts a unit rect within a given frame into a rect +---@param frame hs.geometry +---@return hs.geometry rect +function geometry:fromUnitRect(frame) end + +--- Checks if this hs.geometry object lies fully inside a given rect +---@param rect hs.geometry +---@return boolean +function geometry:inside(rect) end + +--- Returns the intersection rect between this rect and another rect +--- +--- Note: If the two rects don't intersect, the result rect will be a "projection" of the second rect onto this rect's +--- closest edge or corner along the x or y axis; the w and/or h fields in the result rect will be 0. +---@param rect hs.geometry +---@return hs.geometry rect +function geometry:intersect(rect) end + +--- Moves this point/rect +---@param point hs.geometry +---@return hs.geometry +function geometry:move(point) end + +--- Normalizes this vector2 +---@return point +function geometry:normalize() end + +--- Rotates a point around another point N times +---@param aroundpoint hs.geometry +---@param ntimes number +---@return hs.geometry point +function geometry:rotateCCW(aroundpoint, ntimes) end + +--- Scales this vector2/size, or this rect +--- keeping its center constant +---@param size hs.geometry +---@return hs.geometry +function geometry:scale(size) end + +--- Converts a rect into its unit rect within a given frame +--- +--- Note: The resulting unit rect is always clipped within frame 's bounds (via hs.geometry:intersect() ); if frame +--- does not encompass this rect no error will be thrown , but the resulting unit rect won't be a direct match with +--- this rect +--- (i.e. calling :fromUnitRect(frame) on it will return a different rect) +---@param frame hs.geometry +---@return hs.geometry unit rect +function geometry:toUnitRect(frame) end + +--- Returns the type of an hs.geometry object +---@return string +function geometry:type() end + +--- Returns the smallest rect that encloses both this rect and another rect +---@param rect hs.geometry +---@return hs.geometry rect +function geometry:union(rect) end + +--- Returns the vector2 from this point or rect's center to another point or rect's center +---@param point hs.geometry +---@return point +function geometry:vector(point) end + +-- ------------------------------------------------------------ +-- hs.grid +-- ------------------------------------------------------------ + +---@class hs.grid +hs.grid = {} + +--- A bidimensional array (table of tables of strings) holding the keyboard hints (as per +--- hs.keycodes.map +--- ) to be used for the interactive resizing interface. +---@type hs.keycodes.map +hs.grid.HINTS = nil + +--- Allows customization of the modal resizing grid user interface +---@type any +hs.grid.ui = nil + +--- Calls a user specified function to adjust a window's cell +---@param fn function +---@param window hs.window +---@return hs.grid +function hs.grid.adjustWindow(fn, window) end + +--- Gets the cell describing a window +---@param win any +---@return cell +function hs.grid.get(win) end + +--- Gets the +--- hs.geometry +--- rect for a cell on a particular screen +---@param cell hs.geometry +---@param screen hs.screen|hs.screen.find +---@return hs.geometry +function hs.grid.getCell(cell, screen) end + +--- Gets the defined grid size for a given screen or screen resolution +--- +--- Note: if a grid was not set for the specified screen or geometry, the default grid will be returned +--- Usage: +--- local mygrid = hs.grid.getGrid('1920x1080') -- gets the defined grid for all screens with a 1920x1080 resolution +--- local defgrid=hs.grid.getGrid() defgrid.w=defgrid.w+2 -- increases the number of columns in the default grid by 2 +---@param screen hs.screen|hs.screen.find|nil +---@return hs.geometry size +function hs.grid.getGrid(screen) end + +--- Gets the defined grid frame for a given screen or screen resolution. +---@param screen hs.screen|hs.screen.find +---@return hs.geometry rect +function hs.grid.getGridFrame(screen) end + +--- Hides the grid, if visible, and exits the modal resizing mode. +--- +--- Note: Call this function if you need to make sure the modal is exited without waiting for the user to press esc . +--- If an exit callback was provided when invoking the modal interface, calling .hide() will call it +---@return any +function hs.grid.hide() end + +--- Moves and resizes a window to fill the entire grid +---@param window hs.window +---@return hs.grid +function hs.grid.maximizeWindow(window) end + +--- Moves a window one grid cell down the screen, or onto the adjacent screen's grid when necessary +---@param window hs.window +---@return hs.grid +function hs.grid.pushWindowDown(window) end + +--- Moves a window one grid cell to the left, or onto the adjacent screen's grid when necessary +---@param window hs.window +---@return hs.grid +function hs.grid.pushWindowLeft(window) end + +--- Moves a window one cell to the right, or onto the adjacent screen's grid when necessary +---@param window hs.window +---@return hs.grid +function hs.grid.pushWindowRight(window) end + +--- Moves a window one grid cell up the screen, or onto the adjacent screen's grid when necessary +---@param window hs.window +---@return hs.grid +function hs.grid.pushWindowUp(window) end + +--- Resizes a window so its bottom edge moves one grid cell higher +---@param window hs.window +---@return hs.grid +function hs.grid.resizeWindowShorter(window) end + +--- Resizes a window so its bottom edge moves one grid cell lower +--- +--- Note: if the window hits the bottom edge of the screen and is asked to become taller, its top edge will shift +--- further up +---@param window hs.window +---@return hs.grid +function hs.grid.resizeWindowTaller(window) end + +--- Resizes a window to be one cell thinner +---@param window hs.window +---@return hs.grid +function hs.grid.resizeWindowThinner(window) end + +--- Resizes a window to be one cell wider +--- +--- Note: if the window hits the right edge of the screen and is asked to become wider, its left edge will shift +--- further left +---@param window hs.window +---@return hs.grid +function hs.grid.resizeWindowWider(window) end + +--- Sets the cell for a window on a particular screen +---@param win hs.window +---@param cell hs.geometry +---@param screen hs.screen|hs.screen.find|nil +---@return hs.grid +function hs.grid.set(win, cell, screen) end + +--- Sets the grid size for a given screen or screen resolution +---@param grid hs.geometry +---@param screen hs.screen|hs.screen.find|nil +---@param frame hs.geometry|nil +---@return hs.grid +function hs.grid.setGrid(grid, screen, frame) end + +--- Sets the margins between windows +---@param margins hs.geometry +---@return hs.grid +function hs.grid.setMargins(margins) end + +--- Shows the grid and starts the modal interactive resizing process for the focused or frontmost window. +--- +--- Note: In most cases this function should be invoked via hs.hotkey.bind with some keyboard shortcut. +--- In the modal interface, press the arrow keys to jump to adjacent screens; spacebar to maximize/unmaximize; esc to +--- quit without any effect +--- Pressing tab or shift-tab in the modal interface will cycle to the next or previous window; if multipleWindows is +--- false or omitted, the first press will just enable the multiple windows behaviour +--- The keyboard hints assume a QWERTY layout; if you use a different layout, change hs.grid.HINTS accordingly +--- If grid dimensions are greater than 10x10 then you may have to change hs.grid.HINTS depending on your +--- requirements. See note in HINTS . +---@param exitedCallback function|nil +---@param multipleWindows? any +---@return any +function hs.grid.show(exitedCallback, multipleWindows) end + +--- Snaps a window into alignment with the nearest grid lines +---@param win hs.window +---@return hs.grid +function hs.grid.snap(win) end + +--- Toggles the grid and modal resizing mode - see +--- hs.grid.show() +--- and +--- hs.grid.hide() +---@param exitedCallback function|nil +---@param multipleWindows? any +---@return any +function hs.grid.toggleShow(exitedCallback, multipleWindows) end + +-- ------------------------------------------------------------ +-- hs.hash +-- ------------------------------------------------------------ + +---@class hs.hash +hs.hash = {} + +---@class hash +local hash = {} + +--- Calculates a binary MD5 hash +--- +--- Note: this function is provided for backwards compatibility with a previous version of this module and is +--- functionally equivalent to: hs.hash.new("MD5"):append(data):finish():value(true) +---@param data any +---@return data +function hs.hash.bMD5(data) end + +--- Calculates a binary SHA1 hash +--- +--- Note: this function is provided for backwards compatibility with a previous version of this module and is +--- functionally equivalent to: hs.hash.new("SHA1"):append(data):finish():value(true) +---@param data any +---@return data +function hs.hash.bSHA1(data) end + +--- Calculates a binary SHA256 hash +--- +--- Note: this function is provided for backwards compatibility with a previous version of this module and is +--- functionally equivalent to: hs.hash.new("SHA256"):append(data):finish():value(true) +---@param data any +---@return data +function hs.hash.bSHA256(data) end + +--- Calculates a binary SHA512 hash +--- +--- Note: this function is provided for backwards compatibility with a previous version of this module and is +--- functionally equivalent to: hs.hash.new("SHA512"):append(data):finish():value(true) +---@param data any +---@return data +function hs.hash.bSHA512(data) end + +--- Calculates an HMAC using a key and an MD5 hash +--- +--- Note: this function is provided for backwards compatibility with a previous version of this module and is +--- functionally equivalent to: hs.hash.new("hmacMD5", key):append(data):finish():value() +---@param key string +---@param data any +---@return string +function hs.hash.hmacMD5(key, data) end + +--- Calculates an HMAC using a key and a SHA1 hash +--- +--- Note: this function is provided for backwards compatibility with a previous version of this module and is +--- functionally equivalent to: hs.hash.new("hmacSHA1", key):append(data):finish():value() +---@param key string +---@param data any +---@return string +function hs.hash.hmacSHA1(key, data) end + +--- Calculates an HMAC using a key and a SHA256 hash +--- +--- Note: this function is provided for backwards compatibility with a previous version of this module and is +--- functionally equivalent to: hs.hash.new("hmacSHA256", key):append(data):finish():value() +---@param key string +---@param data any +---@return string +function hs.hash.hmacSHA256(key, data) end + +--- Calculates an HMAC using a key and a SHA512 hash +--- +--- Note: this function is provided for backwards compatibility with a previous version of this module and is +--- functionally equivalent to: hs.hash.new("hmacSHA512", key):append(data):finish():value() +---@param key string +---@param data any +---@return string +function hs.hash.hmacSHA512(key, data) end + +--- Calculates an MD5 hash +--- +--- Note: this function is provided for backwards compatibility with a previous version of this module and is +--- functionally equivalent to: hs.hash.new("MD5"):append(data):finish():value() +---@param data any +---@return string +function hs.hash.MD5(data) end + +--- Calculates an SHA1 hash +--- +--- Note: this function is provided for backwards compatibility with a previous version of this module and is +--- functionally equivalent to: hs.hash.new("SHA1"):append(data):finish():value() +---@param data any +---@return string +function hs.hash.SHA1(data) end + +--- Calculates an SHA256 hash +--- +--- Note: this function is provided for backwards compatibility with a previous version of this module and is +--- functionally equivalent to: hs.hash.new("SHA256"):append(data):finish():value() +---@param data any +---@return string +function hs.hash.SHA256(data) end + +--- Calculates an SHA512 hash +--- +--- Note: this function is provided for backwards compatibility with a previous version of this module and is +--- functionally equivalent to: hs.hash.new("SHA512"):append(data):finish():value() +---@param data any +---@return string +function hs.hash.SHA512(data) end + +--- A tale containing the names of the hashing algorithms supported by this module. +---@type any +hs.hash.types = nil + +--- Converts a string containing a binary hash value to its equivalent hexadecimal digits. +--- +--- Note: this is a convenience function for use when you already have a binary hash value that you wish to convert to +--- its hexadecimal equivalent -- the value is not actually validated as the actual hash value for anything specific. +---@param input string +---@return string +function hs.hash.convertBinaryHashToHex(input) end + +--- Converts a string containing a hash value as a string of hexadecimal digits into its binary equivalent. +--- +--- Note: this is a convenience function for use when you already have a hash value that you wish to convert to its +--- binary equivalent. Beyond checking that the input string contains only hexadecimal digits and is an even length, +--- the value is not actually validated as the actual hash value for anything specific. +---@param input string +---@return string +function hs.hash.convertHexHashToBinary(input) end + +--- Calculates the specified hash value for the file at the given path. +--- +--- Note: this is a convenience function that performs the equivalent of hs.new.hash(hash, +--- [secret]):appendFile(path):finish():value() . +---@param hash hs.hash.types +---@param secret any +---@param path string +---@return string +function hs.hash.forFile(hash, secret, path) end + +--- Creates a new context for the specified hash function. +---@param hash string +---@param secret any +---@return hashObject +function hs.hash.new(hash, secret) end + +--- Adds the provided data to the input of the hash function currently in progress for the hashObject. +---@param data string +---@return hashObject|nil +---@return error +function hash:append(data) end + +--- Adds the contents of the file at the specified path to the input of the hash function currently in progress for the +--- hashObject. +---@param path string +---@return hashObject|nil +---@return error +function hash:appendFile(path) end + +--- Finalizes the hash and computes the resulting value. +--- +--- Note: a hash that has been finished can no longer have data appended to it. +---@return hashObject +function hash:finish() end + +--- Returns the name of the hash type the object refers to +---@return string +function hash:type() end + +--- Returns the value of a completed hash, or nil if it is still in progress. +---@param binary number +---@return string|nil +function hash:value(binary) end + +-- ------------------------------------------------------------ +-- hs.hid +-- ------------------------------------------------------------ + +---@class hs.hid +hs.hid = {} + +--- Checks the state of the caps lock via HID +---@return boolean +function hs.hid.capslock.get() end + +--- Assigns capslock to the desired state +---@param state boolean +---@return boolean +function hs.hid.capslock.set(state) end + +--- Toggles the state of caps lock via HID +---@return boolean +function hs.hid.capslock.toggle() end + +-- ------------------------------------------------------------ +-- hs.hid.led +-- ------------------------------------------------------------ + +---@class hs.hid.led +hs.hid.led = {} + +--- Assigns HID LED to the desired state +--- +--- Note: This function controls the LED state only, to modify capslock state, use hs.hid.capslock.set +---@param name string +---@param state boolean +---@return boolean +function hs.hid.led.set(name, state) end + +-- ------------------------------------------------------------ +-- hs.hints +-- ------------------------------------------------------------ + +---@class hs.hints +hs.hints = {} + +--- A fully specified family-face name, preferably the PostScript name, such as Helvetica-BoldOblique or Times-Roman. +--- (The Font Book app displays PostScript names of fonts in the Font Info panel.) +---@type any +hs.hints.fontName = nil + +--- The size of font that should be used. A value of 0.0 will use the default size. +---@type any +hs.hints.fontSize = nil + +--- This controls the set of characters that will be used for window hints. They must be characters found in +--- hs.keycodes.map +---@type hs.keycodes.map +hs.hints.hintChars = nil + +--- Opacity of the application icon. Default is 0.95. +---@type any +hs.hints.iconAlpha = nil + +--- If there are less than or equal to this many windows on screen their titles will be shown in the hints. +---@type any +hs.hints.showTitleThresh = nil + +--- If this is set to "vimperator", every window hint starts with the first character +---@type any +hs.hints.style = nil + +--- If the title is longer than maxSize, the string is truncated, -1 to disable, valid value is >= 6 +---@type string +hs.hints.titleMaxSize = nil + +--- Displays a keyboard hint for switching focus to each window +--- +--- Note: If there are more windows open than there are characters available in hs.hints.hintChars, multiple characters +--- will be used +--- If hints.style is set to "vimperator", every window hint is prefixed with the first character of the parent +--- application's name +--- To display hints only for the currently focused application, try something like: +--- hs.hints.windowHints(hs.window.focusedWindow():application():allWindows()) +---@param windows hs.window|nil +---@param callback hs.window|nil +---@param allowNonStandard boolean|nil +---@return any +function hs.hints.windowHints(windows, callback, allowNonStandard) end + +-- ------------------------------------------------------------ +-- hs.host +-- ------------------------------------------------------------ + +---@class hs.host +hs.host = {} + +--- Gets a list of network addresses for the current machine +--- +--- Note: The results will include IPv4 and IPv6 addresses +---@return table +function hs.host.addresses() end + +--- Query CPU usage statistics for a given time interval using +--- hs.host.cpuUsageTicks +--- and return the results as percentages. +--- +--- Note: If no callback function is provided, Hammerspoon will block (i.e. no other Hammerspoon activity can occur) +--- during execution of this function for period microseconds (1 second = 1,000,000 microseconds). The default period +--- is 1/10 of a second. If period is too small, it is possible that some of the CPU statistics may result in nan +--- (not-a-number). +--- For reference, the top command has a default period between samples of 1 second. +--- The subtables for each core and overall have a __tostring() metamethod which allows listing it's contents in the +--- Hammerspoon console by typing hs.host.cpuUsage()[#] where # is the core you are interested in or the string +--- "overall". +---@param period any +---@param callback function|nil +---@return table +function hs.host.cpuUsage(period, callback) end + +--- Returns a table containing the current cpu usage information for the system in +--- ticks +--- since the most recent system boot. +--- +--- Note: CPU mode ticks are updated during system interrupts and are incremented based upon the mode the CPU is in at +--- the time of the interrupt. By its nature, this is always going to be approximate, and a single call to this +--- function will return the current tick values since the system was last rebooted. +--- To generate a snapshot of the system's usage "at this moment", you must take two samples and calculate the +--- difference between them. The hs.host.cpuUsage function is a wrapper which does this for you and returns the cpu +--- usage statistics as a percentage of the total number of ticks which occurred during the sample period you specify +--- when invoking hs.host.cpuUsage . +--- Historically on Unix based systems, the nice cpu state represents processes for which the execution priority has +--- been reduced to allow other higher priority processes access to more system resources. The source code for the +--- version of the XNU Kernel currently provided by Apple (for macOS 10.12.3) shows this value as returned by the +--- host_processor_info as hardcoded to 0. For completeness, this value is included in the statistics returned by this +--- function, but unless Apple makes a change in the future, it is not expected to provide any useful information. +--- Adapted primarily from code found at http://stackoverflow.com/questions/6785069/get-cpu-percent-usage +---@return table +function hs.host.cpuUsageTicks() end + +--- Returns a newly generated global unique identifier as a string +--- +--- Note: See also hs.host.uuid +--- The global unique identifier for a process includes the host name, process ID, and a time stamp, which ensures that +--- the ID is unique for the network. This property generates a new string each time it is invoked, and it uses a +--- counter to guarantee that strings are unique. +--- This is often used as a file or directory name in conjunction with hs.host.temporaryDirectory() when creating +--- temporary files. +---@return string +function hs.host.globallyUniqueString() end + +--- Returns the model and VRAM size for the installed GPUs. +--- +--- Note: If your GPU reports -1.0 as the memory size, please submit an issue to the Hammerspoon github repository and +--- include any information that you can which may be relevant, such as: Macintosh model, macOS version, is the GPU +--- built in or a third party expansion card, the GPU model and VRAM as best you can determine (see the System +--- Information application in the Utilities folder and look at the Graphics/Display section) and anything else that +--- you think might be important. +---@return table +function hs.host.gpuVRAM() end + +--- Returns the number of seconds the computer has been idle. +--- +--- Note: Idle time is defined as no mouse move nor keyboard entry, etc. and is determined by querying the HID (Human +--- Interface Device) subsystem. +--- This code is directly inspired by code found at http://www.xs-labs.com/en/archives/articles/iokit-idle-time +---@return seconds +function hs.host.idleTime() end + +--- Returns the OS X interface style for the current user. +--- +--- Note: As of OS X 10.10.4, other than the default style, only "Dark" is recognized as a valid style. +---@return string +function hs.host.interfaceStyle() end + +--- Gets the name of the current machine, as displayed in the Finder sidebar +---@return string +function hs.host.localizedName() end + +--- Gets a list of network names for the current machine +--- +--- Note: This function should be used sparingly, as it may involve blocking network access to resolve hostnames +---@return table +function hs.host.names() end + +--- The operating system version as a table containing the major, minor, and patch numbers. +--- +--- Note: for OS X versions prior to 10.10, the version number is approximately determined by evaluating the +--- AppKitVersionNumber. For these operating systems, the approximate key is defined and set to true, as the exact +--- patch level cannot be definitively determined. +--- for OS X Versions starting at 10.10 and going forward, an exact value for the version number can be determined with +--- NSProcessingInfo's operatingSystemVersion selector and the exact key is defined and set to true if this method is +--- used. +---@return table +function hs.host.operatingSystemVersion() end + +--- The operating system version as a human readable string. +--- +--- Note: According to the OS X Developer documentation, "The operating system version string is human readable, +--- localized, and is appropriate for displaying to the user. This string is not appropriate for parsing." +---@return string +function hs.host.operatingSystemVersionString() end + +--- The current thermal state of the computer, as a human readable string +---@return string +function hs.host.thermalState() end + +--- Returns a newly generated UUID as a string +--- +--- Note: See also hs.host.globallyUniqueString +--- UUIDs (Universally Unique Identifiers), also known as GUIDs (Globally Unique Identifiers) or IIDs (Interface +--- Identifiers), are 128-bit values. UUIDs created by NSUUID conform to RFC 4122 version 4 and are created with random +--- bytes. +---@return string +function hs.host.uuid() end + +--- Returns a table containing virtual memory statistics for the current machine, as well as the page size (in bytes) +--- and physical memory size (in bytes). +--- +--- Note: The table returned has a __tostring() metamethod which allows listing it's contents in the Hammerspoon +--- console by typing hs.host.vmStats() . +--- Except for the addition of cacheHits, cacheLookups, pageSize and memSize, the results for this function should be +--- identical to the OS X command vm_stat . +--- Adapted primarily from the source code to Apple's vm_stat command located at +--- http://www.opensource.apple.com/source/system_cmds/system_cmds-643.1.1/vm_stat.tproj/vm_stat.c +---@return table +function hs.host.vmStat() end + +--- Returns a table of information about disk volumes attached to the system +--- +--- Note: The possible keys in the table are: +--- NSURLVolumeTotalCapacityKey - Size of the volume in bytes +--- NSURLVolumeAvailableCapacityKey - Available space on the volume in bytes +--- NSURLVolumeIsAutomountedKey - Boolean indicating if the volume was automounted +--- NSURLVolumeIsBrowsableKey - Boolean indicating if the volume can be browsed +--- NSURLVolumeIsEjectableKey - Boolean indicating if the volume should be ejected before its media is removed +--- NSURLVolumeIsInternalKey - Boolean indicating if the volume is an internal drive or an external drive +--- NSURLVolumeIsLocalKey - Boolean indicating if the volume is a local or remote drive +--- NSURLVolumeIsReadOnlyKey - Boolean indicating if the volume is read only +--- NSURLVolumeIsRemovableKey - Boolean indicating if the volume's media can be physically ejected from the drive (e.g. +--- a DVD) +--- NSURLVolumeMaximumFileSizeKey - Maximum file size the volume can support, in bytes +--- NSURLVolumeUUIDStringKey - The UUID of volume's filesystem +--- NSURLVolumeURLForRemountingKey - For remote volumes, the network URL of the volume +--- NSURLVolumeLocalizedNameKey - Localized version of the volume's name +--- NSURLVolumeNameKey - The volume's name +--- NSURLVolumeLocalizedFormatDescriptionKey - Localized description of the volume +--- Not all keys will be present for all volumes +--- The meanings of NSURLVolumeIsEjectableKey and NSURLVolumeIsRemovableKey are not generally useful for determining if +--- a drive is removable in the modern sense (e.g. a USB drive) as much of this terminology dates back to when USB +--- didn't exist and removable drives were things like Floppy/DVD drives. If you're trying to determine if a drive is +--- not fixed into the computer, you may need to use a combination of these keys, but which exact combination you +--- should use, is not consistent across macOS versions. +---@param showHidden boolean|nil +---@return table +function hs.host.volumeInformation(showHidden) end + +-- ------------------------------------------------------------ +-- hs.host.locale +-- ------------------------------------------------------------ + +---@class hs.host.locale +hs.host.locale = {} + +--- Returns an array table containing the identifiers for the locales available on the system. +--- +--- Note: these values can be used with hs.host.locale.details to get details for a specific locale. +---@return table +function hs.host.locale.availableLocales() end + +--- Returns an string specifying the user's currently selected locale identifier. +--- +--- Note: this value can be used with hs.host.locale.details to get details for the returned locale. +---@return string +function hs.host.locale.current() end + +--- Returns a table containing information about the current or specified locale. +--- +--- Note: If you specify a locale identifier as an argument, it should be based on one of the strings returned by +--- hs.host.locale.availableLocales . Use of an arbitrary string may produce unreliable or inconsistent results. +--- temperatureUnit - http://stackoverflow.com/a/41263725 +--- timeFormatIs24Hour - http://stackoverflow.com/a/1972487 +--- If you are able to identify additional locale or regional settings that are not provided by this function and have +--- a source which describes a reliable method to retrieve this information, please submit an issue at +--- https://github.com/Hammerspoon/hammerspoon with the details. +---@param identifier string|nil +---@return table +function hs.host.locale.details(identifier) end + +--- Returns the localized string for a specific language code. +--- +--- Note: The localeCode and optional baseLocaleCode must be one of the strings returned by +--- hs.host.locale.availableLocales . +---@param localeCode string +---@param baseLocaleCode? string|nil +---@return string|nil +---@return string|nil +function hs.host.locale.localizedString(localeCode, baseLocaleCode) end + +--- Returns the user's language preference order as an array of strings. +---@return table +function hs.host.locale.preferredLanguages() end + +--- Registers a function to be invoked when anything in the user's locale settings change +--- +--- Note: The callback function will not receive any arguments and should return none. You can retrieve the new locale +--- settings with hs.host.locale.localeInformation and check its keys to determine if the change is of interest. +--- Any change made within the Language and Region settings panel will trigger this callback, even changes which are +--- not reflected in the locale information provided by hs.host.locale.localeInformation . +---@param function any +---@return uuidString +function hs.host.locale.registerCallback(function) end + +--- Unregister a callback function when you no longer care about changes to the user's locale +---@param uuidString hs.host.locale.registerCallback +---@return boolean +function hs.host.locale.unregisterCallback(uuidString) end + +-- ------------------------------------------------------------ +-- hs.hotkey +-- ------------------------------------------------------------ + +---@class hs.hotkey +hs.hotkey = {} + +---@class hotkey +local hotkey = {} + +--- Duration of the alert shown when a hotkey created with a +--- message +--- parameter is triggered, in seconds. Default is 1. +---@type any +hs.hotkey.alertDuration = nil + +--- Determines whether the hotkey combination can be assigned a callback through Hammerspoon. +--- +--- Note: The most common reason a hotkey combination cannot be given an assignment by Hammerspoon is because it is in +--- use by the Mac operating system -- see the Shortcuts tab of Keyboard in the System Preferences application or +--- hs.hotkey.systemAssigned . +---@param mods any +---@param key string +---@return boolean +function hs.hotkey.assignable(mods, key) end + +--- Deletes all previously set callbacks for a given keyboard combination +---@param mods any +---@param key string +---@return any +function hs.hotkey.deleteAll(mods, key) end + +--- Disables all previously set callbacks for a given keyboard combination +---@param mods any +---@param key string +---@return any +function hs.hotkey.disableAll(mods, key) end + +--- Returns a list of all currently active hotkeys +---@return table +function hs.hotkey.getHotkeys() end + +--- Creates (and enables) a hotkey that shows all currently active hotkeys (i.e. enabled and not "shadowed" in the +--- current context) while pressed +---@param mods any +---@param key string +---@return hs.hotkey +function hs.hotkey.showHotkeys(mods, key) end + +--- Examine whether a potential hotkey is in use by the macOS system such as the Screen Capture, Universal Access, and +--- Keyboard Navigation keys. +--- +--- Note: this is provided for informational purposes and does not provide a reliable test as to whether or not +--- Hammerspoon can use the combination to create a custom hotkey -- some combinations which return a table can be +--- over-ridden by Hammerspoon while others cannot. See also hs.hotkey.assignable . +---@param mods any +---@param key string +---@return table|boolean +function hs.hotkey.systemAssigned(mods, key) end + +--- Creates a new hotkey and enables it immediately +--- +--- Note: This function is just a wrapper that performs hs.hotkey.new(...):enable() +--- You can create multiple hs.hotkey objects for the same keyboard combination, but only one can be active +--- at any given time - see hs.hotkey:enable() +--- If message is the empty string "" , the alert will just show the triggered keyboard combination +--- If you don't want any alert, you must actually omit the message parameter; a nil in 3rd position +--- will be interpreted as a missing pressedfn +--- You must pass at least one of pressedfn , releasedfn or repeatfn ; to delete a hotkey, use hs.hotkey:delete() +---@param mods any +---@param key string +---@param message hs.alert|nil +---@param pressedfn function|nil +---@param releasedfn function|nil +---@param repeatfn function|nil +---@return hs.hotkey +function hs.hotkey.bind(mods, key, message, pressedfn, releasedfn, repeatfn) end + +--- Creates a hotkey and enables it immediately +--- +--- Note: This function is just a wrapper that performs hs.hotkey.bind(keyspec[1], keyspec[2], ...) +---@param keyspec any +---@param ... any +---@return hs.hotkey +function hs.hotkey.bindSpec(keyspec, ...) end + +--- Creates a new hotkey +--- +--- Note: You can create multiple hs.hotkey objects for the same keyboard combination, but only one can be active +--- at any given time - see hs.hotkey:enable() +--- If message is the empty string "" , the alert will just show the triggered keyboard combination +--- If you don't want any alert, you must actually omit the message parameter; a nil in 3rd position +--- will be interpreted as a missing pressedfn +--- You must pass at least one of pressedfn , releasedfn or repeatfn ; to delete a hotkey, use hs.hotkey:delete() +---@param mods any +---@param key string +---@param message hs.alert|nil +---@param pressedfn function|nil +---@param releasedfn function|nil +---@param repeatfn function|nil +---@return hs.hotkey +function hs.hotkey.new(mods, key, message, pressedfn, releasedfn, repeatfn) end + +--- Disables and deletes a hotkey object +---@return any +function hotkey:delete() end + +--- Disables a hotkey object +---@return hs.hotkey +function hotkey:disable() end + +--- Enables a hotkey object +--- +--- Note: When you enable a hotkey that uses the same keyboard combination as another previously-enabled hotkey, the old +--- one will stop working as it's being "shadowed" by the new one. As soon as the new hotkey is disabled or deleted +--- the old one will trigger again. +---@return hs.hotkey|nil +function hotkey:enable() end + +--- Gets the log level of the hotkey logger instance +---@return number +function hs.hotkey.getLogLevel() end + +--- Sets the log level of the hotkey logger instance +---@param loglevel number +---@return any +function hs.hotkey.setLogLevel(loglevel) end + +-- ------------------------------------------------------------ +-- hs.hotkey.modal +-- ------------------------------------------------------------ + +---@class hs.hotkey.modal +hs.hotkey.modal = {} + +---@class modal +local modal = {} + +--- Creates a new modal state, optionally with a global keyboard combination to trigger it +--- +--- Note: If key is nil, no global hotkey will be registered (all other parameters will be ignored) +---@param mods any +---@param key string +---@param message string|nil +---@return hs.hotkey.modal +function hs.hotkey.modal.new(mods, key, message) end + +--- Creates a hotkey that is enabled/disabled as the modal is entered/exited +---@param mods any +---@param key string +---@param message string|nil +---@param pressedfn function|nil +---@param releasedfn function|nil +---@param repeatfn function|nil +---@return hs.hotkey.modal +function modal:bind(mods, key, message, pressedfn, releasedfn, repeatfn) end + +--- Deletes a modal hotkey object without calling :exited() +---@return any +function modal:delete() end + +--- Enters a modal state +--- +--- Note: This method will enable all of the hotkeys defined in the modal state via hs.hotkey.modal:bind() , +--- and disable the hotkey that entered the modal state (if one was defined) +--- If the modal state was created with a keyboard combination, this method will be called automatically +---@return hs.hotkey.modal +function modal:enter() end + +--- Optional callback for when a modal is entered +--- +--- Note: This is a preexisting function that you should override if you need to use it; the default implementation +--- does nothing. +---@return any +function modal:entered() end + +--- Exits a modal state +--- +--- Note: This method will disable all of the hotkeys defined in the modal state, and enable the hotkey for entering +--- the modal state (if one was defined) +---@return hs.hotkey.modal +function modal:exit() end + +--- Optional callback for when a modal is exited +--- +--- Note: This is a preexisting function that you should override if you need to use it; the default implementation +--- does nothing. +---@return any +function modal:exited() end + +-- ------------------------------------------------------------ +-- hs.http +-- ------------------------------------------------------------ + +---@class hs.http +hs.http = {} + +--- A collection of common HTML Entities (&whatever;) and their UTF8 equivalents. To retrieve the UTF8 sequence for a +--- given entity, reference the table as +--- hs.http.htmlEntities["&key;"] +--- where +--- key +--- is the text of the entity's name or a numeric reference like +--- #number +--- . +---@type hs.http.htmlEntities +hs.http.htmlEntities[] = nil + +--- Sends an HTTP GET request asynchronously +--- +--- Note: If authentication is required in order to download the request, the required credentials must be specified as +--- part of the URL (e.g. "http://user:password@host.com/"). If authentication fails, or credentials are missing, the +--- connection will attempt to continue without credentials. +--- If the request fails, the callback function's first parameter will be negative and the second parameter will +--- contain an error message. The third parameter will be nil +---@param url string +---@param headers table|nil +---@param callback function +---@return any +function hs.http.asyncGet(url, headers, callback) end + +--- Sends an HTTP POST request asynchronously +--- +--- Note: If authentication is required in order to download the request, the required credentials must be specified as +--- part of the URL (e.g. "http://user:password@host.com/"). If authentication fails, or credentials are missing, the +--- connection will attempt to continue without credentials. +--- If the request fails, the callback function's first parameter will be negative and the second parameter will +--- contain an error message. The third parameter will be nil +---@param url string +---@param data string|nil +---@param headers table|nil +---@param callback function +---@return any +function hs.http.asyncPost(url, data, headers, callback) end + +--- Sends an HTTP PUT request asynchronously +--- +--- Note: If authentication is required in order to download the request, the required credentials must be specified as +--- part of the URL (e.g. "http://user:password@host.com/"). If authentication fails, or credentials are missing, the +--- connection will attempt to continue without credentials. +--- If the request fails, the callback function's first parameter will be negative and the second parameter will +--- contain an error message. The third parameter will be nil +---@param url string +---@param data string|nil +---@param headers table|nil +---@param callback function +---@return any +function hs.http.asyncPut(url, data, headers, callback) end + +--- Convert all recognized HTML Entities in the +--- inString +--- to appropriate UTF8 byte sequences and returns the converted text. +--- +--- Note: Recognized HTML Entities are those registered in hs.http.htmlEntities or numeric entity sequences: &#n; where +--- n can be any integer number. +--- This function is especially useful as a post-filter to data retrieved by the hs.http.get and hs.http.asyncGet +--- functions. +---@param inString string +---@return outString +function hs.http.convertHtmlEntities(inString) end + +--- Creates an HTTP request and executes it asynchronously +--- +--- Note: If authentication is required in order to download the request, the required credentials must be specified as +--- part of the URL (e.g. "http://user:password@host.com/"). If authentication fails, or credentials are missing, the +--- connection will attempt to continue without credentials. +--- If the Content-Type response header begins text/ then the response body return value is a UTF8 string. Any other +--- content type passes the response body, unaltered, as a stream of bytes. +--- If enableRedirect is set to true, response body will be empty string. Http body will be dropped even though +--- response has the body. This seems the limitation of 'connection:willSendRequest:redirectResponse' method. +---@param url string +---@param method string +---@param data string|nil +---@param headers table +---@param callback function +---@param cachePolicy|enableRedirect any +---@return any +function hs.http.doAsyncRequest(url, method, data, headers, callback, cachePolicy|enableRedirect) end + +--- Creates an HTTP request and executes it synchronously +--- +--- Note: If authentication is required in order to download the request, the required credentials must be specified as +--- part of the URL (e.g. "http://user:password@host.com/"). If authentication fails, or credentials are missing, the +--- connection will attempt to continue without credentials. +--- This function is synchronous and will therefore block all Lua execution until it completes. You are encouraged to +--- use the asynchronous functions. +--- If you attempt to connect to a local Hammerspoon server created with hs.httpserver , then Hammerspoon will block +--- until the connection times out (60 seconds), return a failed result due to the timeout, and then the hs.httpserver +--- callback function will be invoked (so any side effects of the function will occur, but it's results will be lost). +--- Use hs.http.doAsyncRequest to avoid this. +--- If the Content-Type response header begins text/ then the response body return value is a UTF8 string. Any other +--- content type passes the response body, unaltered, as a stream of bytes. +---@param url string +---@param method string +---@param data any +---@param headers string[]|nil +---@param cachePolicy string|nil +---@return int +---@return string +---@return table +function hs.http.doRequest(url, method, data, headers, cachePolicy) end + +--- Returns a copy of the provided string in which characters that are not valid within an HTTP query key or value are +--- escaped with their %## equivalent. +--- +--- Note: The intent of this function is to provide a valid key or a valid value for a query string, not to validate +--- the entire query string. For this reason, ?, =, +, and & are included in the converted characters. +---@param string string +---@return string +function hs.http.encodeForQuery(string) end + +--- Sends an HTTP GET request to a URL +--- +--- Note: If authentication is required in order to download the request, the required credentials must be specified as +--- part of the URL (e.g. "http://user:password@host.com/"). If authentication fails, or credentials are missing, the +--- connection will attempt to continue without credentials. +--- This function is synchronous and will therefore block all other Lua execution while the request is in progress, you +--- are encouraged to use the asynchronous functions +--- If you attempt to connect to a local Hammerspoon server created with hs.httpserver , then Hammerspoon will block +--- until the connection times out (60 seconds), return a failed result due to the timeout, and then the hs.httpserver +--- callback function will be invoked (so any side effects of the function will occur, but it's results will be lost). +--- Use hs.http.asyncGet to avoid this. +---@param url string +---@param headers table|nil +---@return int +---@return string +---@return table +function hs.http.get(url, headers) end + +--- Sends an HTTP POST request to a URL +--- +--- Note: If authentication is required in order to download the request, the required credentials must be specified as +--- part of the URL (e.g. "http://user:password@host.com/"). If authentication fails, or credentials are missing, the +--- connection will attempt to continue without credentials. +--- This function is synchronous and will therefore block all other Lua execution while the request is in progress, you +--- are encouraged to use the asynchronous functions +--- If you attempt to connect to a local Hammerspoon server created with hs.httpserver , then Hammerspoon will block +--- until the connection times out (60 seconds), return a failed result due to the timeout, and then the hs.httpserver +--- callback function will be invoked (so any side effects of the function will occur, but it's results will be lost). +--- Use hs.http.asyncPost to avoid this. +---@param url string +---@param data string|nil +---@param headers table|nil +---@return int +---@return string +---@return table +function hs.http.post(url, data, headers) end + +--- Sends an HTTP PUT request to a URL +--- +--- Note: If authentication is required in order to download the request, the required credentials must be specified as +--- part of the URL (e.g. "http://user:password@host.com/"). If authentication fails, or credentials are missing, the +--- connection will attempt to continue without credentials. +--- This function is synchronous and will therefore block all other Lua execution while the request is in progress, you +--- are encouraged to use the asynchronous functions +--- If you attempt to connect to a local Hammerspoon server created with hs.httpserver , then Hammerspoon will block +--- until the connection times out (60 seconds), return a failed result due to the timeout, and then the hs.httpserver +--- callback function will be invoked (so any side effects of the function will occur, but it's results will be lost). +--- Use hs.http.asyncPost to avoid this. +---@param url string +---@param data string|nil +---@param headers table|nil +---@return int +---@return string +---@return table +function hs.http.put(url, data, headers) end + +--- Registers an HTML Entity with the specified Unicode codepoint which can later referenced in your code as +--- hs.http.htmlEntity[entity] +--- for convenience and readability. +--- +--- Note: If an entity label was previously registered, this will overwrite the previous value with a new one. +--- The return value is merely syntactic sugar and you do not need to save it locally; it can be safely ignored -- +--- future access to the pre-converted entity should be retrieved as hs.http.htmlEntities[entity] in your code. It +--- looks good when invoked from the console, though ☺. +---@param entity number +---@param codepoint any +---@return string +function hs.http.registerEntity(entity, codepoint) end + +--- Returns a table of keys containing the individual components of the provided url. +--- +--- Note: This function assumes that the URL conforms to RFC 1808. If the URL is malformed or does not conform to +--- RFC1808, then many of these fields may be missing. +--- A contrived example for the url http://user:password@host.site.com:80/path/to%20a/../file.txt;parameter?query1=1&query2=a%28#fragment : hs.inspect(hs.http.urlParts("http://user:password@host.site.com:80/path/to%20a/../file.txt;parameter?query1=1&query2=a%28#fragment")) { +--- absoluteString = "http://user:password@host.site.com:80/path/to%20a/../file.txt;parameter?query1=1&query2=a%28#fragment", +--- absoluteURL = "http://user:password@host.site.com:80/path/to%20a/../file.txt;parameter?query1=1&query2=a%28#fragment", +--- fileSystemRepresentation = "/path/to a/../file.txt", +--- fragment = "fragment", +--- host = "host.site.com", +--- isFileURL = false, +--- lastPathComponent = "file.txt", +--- parameterString = "parameter", +--- password = "password", +--- path = "/path/to a/../file.txt", +--- pathComponents = { "/", "path", "to a", "..", "file.txt" }, +--- pathExtension = "txt", +--- port = 80, +--- query = "query1=1&query2=a%28", +--- queryItems = { { +--- query1 = "1" +--- }, { +--- query2 = "a(" +--- } }, +--- relativePath = "/path/to a/../file.txt", +--- relativeString = "http://user:password@host.site.com:80/path/to%20a/../file.txt;parameter?query1=1&query2=a%28#fragment", +--- resourceSpecifier = "//user:password@host.site.com:80/path/to%20a/../file.txt;parameter?query1=1&query2=a%28#fragment", +--- scheme = "http", +--- standardizedURL = "http://user:password@host.site.com:80/path/file.txt;parameter?query1=1&query2=a%28#fragment", +--- user = "user" +--- } +--- a missing key (e.g. '=value') will be represented as { "" = value } +--- a missing value (e.g. 'key=') will be represented as { key = "" } +--- a missing value with no = (e.g. 'key') will be represented as { key } +--- a missing key and value (e.g. '=') will be represented as { "" = "" } +--- an empty query item (e.g. a query ending in '&' or a query containing && between two other query items) will be +--- represented as { "" } +--- relative URLs are not possible to express properly so baseURL will always be nil and relativePath and +--- relativeString will always match path and absoluteString. +--- These limitations may change in a future update if the need for a more fully compliant URL treatment is determined +--- to be necessary. +---@param url string +---@return table +function hs.http.urlParts(url) end + +-- ------------------------------------------------------------ +-- hs.httpserver +-- ------------------------------------------------------------ + +---@class hs.httpserver +hs.httpserver = {} + +---@class httpserver +local httpserver = {} + +--- Creates a new HTTP or HTTPS server +--- +--- Note: By default, the server will start on a random TCP port and advertise itself with Bonjour. You can check the +--- port with hs.httpserver:getPort() +--- By default, the server will listen on all network interfaces. You can override this with +--- hs.httpserver:setInterface() before starting the server +--- Currently, in HTTPS mode, the server will use a self-signed certificate, which most browsers will warn about. If +--- you want/need to be able to use hs.httpserver with a certificate signed by a trusted Certificate Authority, please +--- file an bug on Hammerspoon requesting support for this. +---@param ssl boolean|nil +---@param bonjour any +---@return object +function hs.httpserver.new(ssl, bonjour) end + +--- Gets the network interface the server is configured to listen on +---@return string|nil +function httpserver:getInterface() end + +--- Gets the Bonjour name the server is configured to advertise itself as +--- +--- Note: This is not the hostname of the server, just its name in Bonjour service lists (e.g. Safari's Bonjour +--- bookmarks menu) +---@return string +function httpserver:getName() end + +--- Gets the TCP port the server is configured to listen on +---@return number +function httpserver:getPort() end + +--- Get or set the maximum allowed body size for an incoming HTTP request. +--- +--- Note: Because the Hammerspoon http server processes incoming requests completely in memory, this method puts a +--- limit on the maximum size for a POST or PUT request. +---@param size number|nil +---@return object|current- +function httpserver:maxBodySize(size) end + +--- Sends a message to the websocket client +---@param message string +---@return object +function httpserver:send(message) end + +--- Sets the request handling callback for an HTTP server object +--- +--- Note: The callback will be passed four arguments: +--- A string containing the type of request (i.e. GET / POST / DELETE /etc) +--- A string containing the path element of the request (e.g. /index.html ) +--- A table containing the request headers +--- A string containing the raw contents of the request body, or the empty string if no body is included in the request. +--- The callback must return three values: +--- A string containing the body of the response +--- An integer containing the response code (e.g. 200 for a successful request) +--- A table containing additional HTTP headers to set (or an empty table, {} , if no extra headers are required) +--- A POST request, often used by HTML forms, will store the contents of the form in the body of the request. +---@param callback function|nil +---@return object +function httpserver:setCallback(callback) end + +--- Sets the network interface the server is configured to listen on +--- +--- Note: As well as real interface names (e.g. en0 ) the following values are valid: +--- An IP address of one of your interfaces +--- localhost +--- loopback +--- nil (which means all interfaces, and is the default) +---@param interface string +---@return object +function httpserver:setInterface(interface) end + +--- Sets the Bonjour name the server should advertise itself as +--- +--- Note: This is not the hostname of the server, just its name in Bonjour service lists (e.g. Safari's Bonjour +--- bookmarks menu) +---@param name string +---@return object +function httpserver:setName(name) end + +--- Sets a password for an HTTP server object +--- +--- Note: It is not currently possible to set multiple passwords for different users, or passwords only on specific +--- paths +---@param password any +---@return object +function httpserver:setPassword(password) end + +--- Sets the TCP port the server is configured to listen on +---@param port number +---@return object +function httpserver:setPort(port) end + +--- Starts an HTTP server object +---@return object +function httpserver:start() end + +--- Stops an HTTP server object +---@return object +function httpserver:stop() end + +--- Enables a websocket endpoint on the HTTP server +--- +--- Note: The callback is passed one string parameter containing the received message +--- The callback must return a string containing the response message +--- Given a path '/mysock' and a port of 8000, the websocket URL is as follows: +--- ws://localhost:8000/mysock +--- wss://localhost:8000/mysock (if SSL enabled) +---@param path string +---@param callback function +---@return object +function httpserver:websocket(path, callback) end + +-- ------------------------------------------------------------ +-- hs.httpserver.hsminweb +-- ------------------------------------------------------------ + +---@class hs.httpserver.hsminweb +hs.httpserver.hsminweb = {} + +---@class hsminweb +local hsminweb = {} + +--- A format string, usable with +--- os.date +--- , which will display a date in the format expected for HTTP communications as described in RFC 822, updated by RFC +--- 1123. +---@type string +hs.httpserver.hsminweb.dateFormatString = nil + +--- HTTP Response Status Codes +---@type any +hs.httpserver.hsminweb.statusCodes = nil + +--- Accessed as +--- self._accessLog +--- . If query logging is enabled for the web server, an Apache style common log entry will be appended to this string +--- for each request. See +--- hs.httpserver.hsminweb:queryLogging +--- . +---@type hs.httpserver.hsminweb +hs.httpserver.hsminweb._accessLog = nil + +--- Accessed as +--- self._errorHandlers[errorCode] +--- . A table whose keyed entries specify the function to generate the error response page for an HTTP error. +---@type function +hs.httpserver.hsminweb._errorHandlers = nil + +--- Accessed as +--- self._serverAdmin +--- . A string containing the administrator for the web server. Defaults to the currently logged in user's short form +--- username and the computer's localized name as returned by +--- hs.host.localizedName() +--- (e.g. "user@computer"). +---@type hs.host.localizedName +hs.httpserver.hsminweb._serverAdmin = nil + +--- Accessed as +--- self._supportMethods[method] +--- . A table whose keyed entries specify whether or not a specified HTTP method is supported by this server. +---@type any +hs.httpserver.hsminweb._supportMethods = nil + +--- The +--- hs.logger +--- instance for the +--- hs.httpserver.hsminweb +--- module. See the documentation for +--- hs.logger +--- for more information. +---@type hs.logger|hs.httpserver.hsminweb +hs.httpserver.hsminweb.log = nil + +--- Returns the current or specified time in the format expected for HTTP communications as described in RFC 822, +--- updated by RFC 1123. +---@param date number|nil +---@return string +function hs.httpserver.hsminweb.formattedDate(date) end + +--- Parse the specified URL into its constituent parts. +--- +--- Note: To simplify the logic used by this module to determine if a request for a directory is properly terminated +--- with a "/", the path components returned by this function do not remove this character from the component, if +--- present. +--- Some extraneous or duplicate keys have been removed. +--- This function is patterned after RFC 3986 while hs.http.urlParts uses OS X API functions which are patterned after +--- RFC 1808. RFC 3986 obsoletes 1808. The primary distinction that affects this module is in regards to parameters +--- for path components in the URI -- RFC 3986 disallows them in schema based URI's (like the URL's that are used for +--- web based traffic). +---@param url string +---@return table +function hs.httpserver.hsminweb.urlParts(url) end + +--- Create a new hsminweb table object representing a Hammerspoon Web Server. +--- +--- Note: a web server's document root is the directory which contains the documents or files to be served by the web +--- server. +--- while an hs.minweb object is actually represented by a Lua table, it has been assigned a meta-table which allows +--- methods to be called directly on it like a user-data object. For most purposes, you should think of this table as +--- the module's userdata. +---@param documentRoot string|nil +---@return hsminwebTable +function hs.httpserver.hsminweb.new(documentRoot) end + +--- Get or set the access-list table for the hsminweb web server +--- +--- Note: The access-list feature works by comparing the request headers against a list of tests which either accept or +--- reject the request. If no access list is set (i.e. it is assigned a value of nil ), then all requests are served. +--- If a table is passed into this method, then any request which is not explicitly accepted by one of the tests +--- provided is rejected (i.e. there is an implicit "reject" at the end of the list). +--- The access-list table is a list of tests which are evaluated in order. The first test which matches a given +--- request determines whether or not the request is accepted or rejected. +--- header - a string value matching the name of a header. While the header name must match exactly, the +--- comparison is case-insensitive (i.e. "X-Remote-addr" and "x-remote-addr" will both match the actual header name +--- used, which is "X-Remote-Addr"). +--- value - a string value specifying the value to compare the header key's value to. +--- isPattern - a boolean indicating whether or not the header key's value should be compared to value as a pattern +--- match (true) -- see Lua documentation 6.4.1, help.lua._man._6_4_1 in the console, or as an exact match (false) +--- isAccepted - a boolean indicating whether or not a match should be accepted (true) or rejected (false) +--- A special entry of the form { '*', '*', '*', true } accepts all further requests and can be used as the final entry +--- if you wish for the access list to function as a list of requests to reject, but to accept any requests which do +--- not match a previous test. +--- A special entry of the form { '*', '*', '*', false } rejects all further requests and can be used as the final +--- entry if you wish for the access list to function as a list of requests to accept, but to reject any requests which +--- do not match a previous test. This is the implicit "default" final test if a table is assigned with the +--- access-list method and does not actually need to be specified, but is included for completeness. +--- Note that any entry after an entry in which the first two parameters are equal to '*' will never actually be used. +--- The tests are performed in order; if you wich to allow one IP address in a range, but reject all others, you should +--- list the accepted IP addresses first. For example: { +--- { 'X-Remote-Addr', '192.168.1.100', false, true }, -- accept requests from 192.168.1.100 +--- { 'X-Remote-Addr', '^192%.168%.1%.', true, false }, -- reject all others from the 192.168.1 subnet +--- { '*', '*', '*', true } -- accept all other requests +--- } +--- Most of the headers available are provided by the requesting web browser, so the exact headers available will vary. +--- You can find some information about common HTTP request headers at: https://en.wikipedia.org/wiki/List_of_HTTP_header_fields. +--- X-Remote-Addr - the remote IPv4 or IPv6 address of the machine making the request, +--- X-Remote-Port - the TCP port of the remote machine where the request originated. +--- X-Server-Addr - the server IPv4 or IPv6 address that the web server received the request from. For machines with +--- multiple interfaces, this will allow you to determine which interface the request was received on. +--- X-Server-Port - the TCP port of the web server that received the request. +---@param table table|nil +---@return hsminwebTable|current- +function hsminweb:accessList(table) end + +--- Get or set the whether or not a directory index is returned when the requested URL specifies a directory and no +--- file matching an entry in the directory indexes table is found. +--- +--- Note: if this value is false, then an attempt to retrieve a URL specifying a directory that does not contain a +--- default file as identified by one of the entries in the hs.httpserver.hsminweb:directoryIndex list will result in a +--- "403.2" error. +---@param flag any +---@return hsminwebTable|current- +function hsminweb:allowDirectory(flag) end + +--- Get or set the whether or not the web server should advertise itself via Bonjour when it is running. +--- +--- Note: this flag can only be changed when the server is not running (i.e. the hs.httpserver.hsminweb:start method +--- has not yet been called, or the hs.httpserver.hsminweb:stop method is called first.) +---@param flag any +---@return hsminwebTable|current- +function hsminweb:bonjour(flag) end + +--- Get or set the whether or not CGI file execution is enabled. +---@param flag any +---@return hsminwebTable|current- +function hsminweb:cgiEnabled(flag) end + +--- Get or set the file extensions which identify files which should be executed as CGI scripts to provide the results +--- to an HTTP request. +--- +--- Note: this list is ignored if hs.httpserver.hsminweb:cgiEnabled is not also set to true. +---@param table file[]|nil +---@return hsminwebTable|current- +function hsminweb:cgiExtensions(table) end + +--- Get or set the file names to look for when the requested URL specifies a directory. +--- +--- Note: Files listed in this table are checked in order, so the first matched is served. If no file match occurs, +--- then the server will return a generated list of the files in the directory, or a "403.2" error, depending upon the +--- value controlled by hs.httpserver.hsminweb:allowDirectory . +---@param table file[]|nil +---@return hsminwebTable|current- +function hsminweb:directoryIndex(table) end + +--- Get or set the whether or not DNS lookups are performed. +--- +--- Note: DNS lookups can be time consuming or even block Hammerspoon for a short time, so they are disabled by default. +--- Currently DNS lookups are (optionally) performed for CGI scripts, but may be added for other purposes in the future +--- (logging, etc.). +---@param flag any +---@return hsminwebTable|current- +function hsminweb:dnsLookup(flag) end + +--- Get or set the document root for the web server. +---@param path string|nil +---@return hsminwebTable|current- +function hsminweb:documentRoot(path) end + +--- Get or set the network interface that the hsminweb web server will listen on +--- +--- Note: See hs.httpserver.setInterface for a description of valid values that can be specified as the interface +--- argument to this method. +--- the interface can only be specified before the hsminweb web server has been started. If you wish to change the +--- listening interface for a running web server, you must stop it with hs.httpserver.hsminweb:stop before invoking +--- this method and then restart it with hs.httpserver.hsminweb:start . +---@param interface string|nil +---@return hsminwebTable|current- +function hsminweb:interface(interface) end + +--- Get or set the extension of files which contain Lua code which should be executed within Hammerspoon to provide the +--- results to an HTTP request. +--- +--- Note: This extension is checked after the extensions given to hs.httpserver.hsminweb:cgiExtensions ; this means +--- that if the same extension set by this method is also in the CGI extensions list, then the file will be interpreted +--- as a CGI script and ignore this setting. +---@param string string|nil +---@return hsminwebTable|current- +function hsminweb:luaTemplateExtension(string) end + +--- Get or set the maximum body size for an HTTP request +--- +--- Note: Because the Hammerspoon http server processes incoming requests completely in memory, this method puts a +--- limit on the maximum size for a POST or PUT request. +--- If the request body exceeds this size, hs.httpserver will respond with a status code of 405 for the method before +--- this module ever receives the request. +---@param size number|nil +---@return hsminwebTable|current- +function hsminweb:maxBodySize(size) end + +--- Get or set the name the web server uses in Bonjour advertisement when the web server is running. +---@param name string|nil +---@return hsminwebTable|current- +function hsminweb:name(name) end + +--- Set a password for the hsminweb web server, or return a boolean indicating whether or not a password is currently +--- set for the web server. +--- +--- Note: the password, if set, is server wide and causes the server to use the Basic authentication scheme with an +--- empty string for the username. +--- this module is an extension to the Hammerspoon core module hs.httpserver , so it has the same limitations regarding +--- server passwords. See the documentation for hs.httpserver.setPassword ( help.hs.httpserver.setPassword in the +--- Hammerspoon console). +---@param password any +---@return hsminwebTable|boolean +function hsminweb:password(password) end + +--- Get or set the name the port the web server listens on +--- +--- Note: due to security restrictions enforced by OS X, the port must be a number greater than 1023 +---@param port number|nil +---@return hsminwebTable|current- +function hsminweb:port(port) end + +--- Get or set the whether or not requests to this web server are logged. +--- +--- Note: If logging is enabled, an Apache common style log entry is appended to self._accesslog for each request made +--- to the web server. +--- Error messages during content generation are always logged to the Hammerspoon console via the hs.logger instance +--- saved to hs.httpserver.hsminweb.log . +---@param flag any +---@return hsminwebTable|current- +function hsminweb:queryLogging(flag) end + +--- Get or set the timeout for a CGI script +--- +--- Note: With the current functionality available in hs.httpserver , any script which is expected to return content +--- for an HTTP request must run in a blocking manner -- this means that no other Hammerspoon activity can be occurring +--- while the script is executing. This parameter lets you set the maximum amount of time such a script can hold +--- things up before being terminated. +--- An alternative implementation of at least some of the methods available in hs.httpserver is being considered which +--- may make it possible to use hs.task for these scripts, which would alleviate this blocking behavior. However, even +--- if this is addressed, a timeout for scripts is still desirable so that a client making a request doesn't sit around +--- waiting forever if a script is malformed. +---@param integer number|nil +---@return hsminwebTable|current- +function hsminweb:scriptTimeout(integer) end + +--- Get or set the whether or not the web server utilizes SSL for HTTP request and response communications. +--- +--- Note: this flag can only be changed when the server is not running (i.e. the hs.httpserver.hsminweb:start method +--- has not yet been called, or the hs.httpserver.hsminweb:stop method is called first.) +--- this module is an extension to the Hammerspoon core module hs.httpserver , so it has the same considerations +--- regarding SSL. See the documentation for hs.httpserver.new ( help.hs.httpserver.new in the Hammerspoon console). +---@param flag any +---@return hsminwebTable|current- +function hsminweb:ssl(flag) end + +--- Start serving pages for the hsminweb web server. +---@return hsminwebTable +function hsminweb:start() end + +--- Stop serving pages for the hsminweb web server. +--- +--- Note: this method is called automatically during garbage collection. +---@return hsminwebTable +function hsminweb:stop() end + +-- ------------------------------------------------------------ +-- hs.httpserver.hsminweb.cgilua +-- ------------------------------------------------------------ + +---@class hs.httpserver.hsminweb.cgilua +hs.httpserver.hsminweb.cgilua = {} + +--- The file name of the running script. Obtained from cgilua.script_path. +---@type any +hs.httpserver.hsminweb.cgilua.script_file = nil + +--- The system path of the running script. Equivalent to the CGI environment variable SCRIPT_FILENAME. +---@type any +hs.httpserver.hsminweb.cgilua.script_path = nil + +--- The directory of the running script. Obtained from cgilua.script_path. +---@type any +hs.httpserver.hsminweb.cgilua.script_pdir = nil + +--- If PATH_INFO represents a directory (i.e. ends with "/"), then this is equal to +--- cgilua.script_vpath +--- . Otherwise, this contains the directory portion of +--- cgilua.script_vpath +--- . +---@type any +hs.httpserver.hsminweb.cgilua.script_vdir = nil + +--- Equivalent to the CGI environment variable PATH_INFO or "/", if no PATH_INFO is set. +---@type any +hs.httpserver.hsminweb.cgilua.script_vpath = nil + +--- The directory used by +--- cgilua.tmpfile +---@type any +hs.httpserver.hsminweb.cgilua.tmp_path = nil + +--- The name of the script as requested in the URL. Equivalent to the CGI environment variable SCRIPT_NAME. +---@type any +hs.httpserver.hsminweb.cgilua.urlpath = nil + +--- Sets the HTTP response type for the content being generated to maintype/subtype. +--- +--- Note: This sets the Content-Type header field for the HTTP response being generated. This will override any +--- previous setting, including the default of "text/html". +---@param maintype any +---@param subtype any +---@return none +function hs.httpserver.hsminweb.cgilua.contentheader(maintype, subtype) end + +--- Executes a lua file (given by filepath) if it exists. +--- +--- Note: This function only interprets the file if it exists; if the file does not exist, it returns an error to the +--- calling code (not the web client) +--- During the processing of a web request, the local directory is temporarily changed to match the local directory of +--- the path of the file being served, as determined by the URL of the request. This is usually different than the +--- Hammerspoon default directory which corresponds to the directory which contains the init.lua file for Hammerspoon. +---@param filename string +---@return results +function hs.httpserver.hsminweb.cgilua.doif(filename) end + +--- Executes a lua file (given by filepath). +--- +--- Note: If the file does not exist, an Internal Server error is returned to the client and an error is logged to the +--- Hammerspoon console. +--- During the processing of a web request, the local directory is temporarily changed to match the local directory of +--- the path of the file being served, as determined by the URL of the request. This is usually different than the +--- Hammerspoon default directory which corresponds to the directory which contains the init.lua file for Hammerspoon. +---@param filename string +---@return results +function hs.httpserver.hsminweb.cgilua.doscript(filename) end + +--- Sends the message to the +--- hs.httpserver.hsminweb +--- log, tagged as an error. +--- +--- Note: Available within a lua template file as cgilua.errorlog +--- By default, messages logged with this method will appear in the Hammerspoon console and are available in the +--- hs.logger history. +---@param msg any +---@return nil +function hs.httpserver.hsminweb.cgilua.errorlog(msg) end + +--- Sets the HTTP response header +--- key +--- to +--- value +--- +--- Note: You should not use this function to set the value for the "Content-Type" key; instead use +--- cgilua.contentheader or cgilua.htmlheader . +---@param key string +---@param value string +---@return none +function hs.httpserver.hsminweb.cgilua.header(key, value) end + +--- Sets the HTTP response type to "text/html" +--- +--- Note: This sets the Content-Type header field for the HTTP response being generated to "text/html". This is the +--- default value, so generally you should not need to call this function unless you have previously changed it with +--- the cgilua.contentheader function. +---@return none +function hs.httpserver.hsminweb.cgilua.htmlheader() end + +--- Returns an absolute URL for the given URI by prepending the path with the scheme, hostname, and port of this web +--- server. +--- +--- Note: If you wish to append query items to the path or expand a relative path into it's full path, see +--- cgilua.mkurlpath . +---@param uri string +---@return string +function hs.httpserver.hsminweb.cgilua.mkabsoluteurl(uri) end + +--- Creates a full document URI from a partial URI, including query arguments if present. +--- +--- Note: This function is intended to be used in conjunction with cgilua.mkabsoluteurl to generate a full URL. If the +--- uri provided does not begin with a "/", then the current directory path is prepended to the uri and any query +--- arguments are appended. +--- e.g. cgilua.mkabsoluteurl(cgiurl.mkurlpath("file.lp", { key = value, ... })) will return a full URL specifying the +--- file file.lp in the current directory with the specified key-value pairs as query arguments. +---@param uri string +---@param args table|nil +---@return string +function hs.httpserver.hsminweb.cgilua.mkurlpath(uri, args) end + +--- Appends the given arguments to the response body. +--- +--- Note: Available within a lua template file as cgilua.print +--- This function works like the lua builtin print command in that it converts all its arguments to strings, separates +--- them with tabs ( \t ), and ends the line with a newline ( \n ) before appending them to the current response body. +---@param ... any +---@return nil +function hs.httpserver.hsminweb.cgilua.print(...) end + +--- Appends the given arguments to the response body. +--- +--- Note: Available within a lua template file as cgilua.put +--- This function works by flattening tables and converting all values except for nil and false to their string +--- representation and then appending them in order to the response body. Unlike cgilua.print , it does not separate +--- values with a tab character or terminate the line with a newline character. +---@param ... any +---@return nil +function hs.httpserver.hsminweb.cgilua.put(...) end + +--- Sends the headers to force a redirection to the given URL adding the parameters in table args to the new URL. +--- +--- Note: This function should generally be followed by a return in your lua template page as no additional processing +--- or output should occur when a request is to be redirected. +---@param url string +---@param args table|nil +---@return none +function hs.httpserver.hsminweb.cgilua.redirect(url, args) end + +--- Returns a string with the value of the CGI environment variable corresponding to varname. +--- +--- Note: "AUTH_TYPE" - If the server supports user authentication, and the script is protected, this is the +--- protocol-specific authentication method used to validate the user. +--- "CONTENT_LENGTH" - The length of the content itself as given by the client. +--- "CONTENT_TYPE" - For queries which have attached information, such as HTTP POST and PUT, this is the content +--- type of the data. +--- "DOCUMENT_ROOT" - the real directory on the server that corresponds to a DOCUMENT_URI of "/". This is the +--- first directory which contains files or sub-directories which are served by the web server. +--- "DOCUMENT_URI" - the path portion of the HTTP URL requested +--- "GATEWAY_INTERFACE" - The revision of the CGI specification to which this server complies. Format: CGI/revision +--- "PATH_INFO" - The extra path information, as given by the client. In other words, scripts can be accessed +--- by their virtual pathname, followed by extra information at the end of this path. The extra information is sent as +--- PATH_INFO. This information should be decoded by the server if it comes from a URL before it is passed to the CGI +--- script. +--- "PATH_TRANSLATED" - The server provides a translated version of PATH_INFO, which takes the path and does any +--- virtual-to-physical mapping to it. +--- "QUERY_STRING" - The information which follows the "?" in the URL which referenced this script. This is the +--- query information. It should not be decoded in any fashion. This variable should always be set when there is query +--- information, regardless of command line decoding. +--- "REMOTE_ADDR" - The IP address of the remote host making the request. +--- "REMOTE_HOST" - The hostname making the request. If the server does not have this information, it should set +--- REMOTE_ADDR and leave this unset. +--- "REMOTE_IDENT" - If the HTTP server supports RFC 931 identification, then this variable will be set to the +--- remote user name retrieved from the server. Usage of this variable should be limited to logging only. +--- "REMOTE_USER" - If the server supports user authentication, and the script is protected, this is the username +--- they have authenticated as. +--- "REQUEST_METHOD" - The method with which the request was made. For HTTP, this is "GET", "HEAD", "POST", etc. +--- "REQUEST_TIME" - the time the server received the request represented as the number of seconds since 00:00:00 +--- UTC on 1 January 1970. Usable with os.date to provide the date and time in whatever format you require. +--- "REQUEST_URI" - the DOCUMENT_URI with any query string present in the request appended. Usually this +--- corresponds to the URL without the scheme or host information. +--- "SCRIPT_FILENAME" - the actual path to the script being executed. +--- "SCRIPT_NAME" - A virtual path to the script being executed, used for self-referencing URLs. +--- "SERVER_NAME" - The server's hostname, DNS alias, or IP address as it would appear in self-referencing URLs. +--- "SERVER_PORT" - The port number to which the request was sent. +--- "SERVER_PROTOCOL" - The name and revision of the information protocol this request came in with. Format: +--- protocol/revision +--- "SERVER_SOFTWARE" - The name and version of the web server software answering the request (and running the +--- gateway). Format: name/version +--- HTTP_ACCEPT, HTTP_ACCEPT_ENCODING, HTTP_ACCEPT_LANGUAGE, HTTP_CACHE_CONTROL, HTTP_CONNECTION, HTTP_DNT, HTTP_HOST, +--- HTTP_USER_AGENT +--- HTTP_X_REMOTE_ADDR, HTTP_X_REMOTE_PORT, HTTP_X_SERVER_ADDR, HTTP_X_SERVER_PORT +--- A list of common request headers and their definitions can be found at +--- https://en.wikipedia.org/wiki/List_of_HTTP_header_fields +---@param varname string +---@return string +function hs.httpserver.hsminweb.cgilua.servervariable(varname) end + +--- Returns two strings with the "first directory" and the "remaining path" of the given path string splitted on the +--- first separator ("/" or ""). +---@param path string +---@return path component +---@return path remainder +function hs.httpserver.hsminweb.cgilua.splitfirst(path) end + +--- Returns two strings with the "directory path" and "file" parts of the given path string splitted on the last +--- separator ("/" or ""). +--- +--- Note: This function used to be called cgilua.splitpath and still can be accessed by this name for compatibility +--- reasons. cgilua.splitpath may be deprecated in future versions. +---@deprecated +---@param path string +---@return directory +---@return file +function hs.httpserver.hsminweb.cgilua.splitonlast(path) end + +--- Returns the file handle to a temporary file for writing, or nil and an error message if the file could not be +--- created for any reason. +--- +--- Note: The file is automatically deleted when the HTTP request has been completed, so if you need for the data to +--- persist, make sure to io.flush or io.close the file handle yourself and copy the file to a more permanent location. +---@param dir any +---@param namefunction function|nil +---@return file +---@return err +function hs.httpserver.hsminweb.cgilua.tmpfile(dir, namefunction) end + +--- Returns a temporary file name used by +--- cgilua.tmpfile +--- . +--- +--- Note: This function uses hs.host.globallyUniqueString to generate a unique file name. +---@return string +function hs.httpserver.hsminweb.cgilua.tmpname() end + +-- ------------------------------------------------------------ +-- hs.httpserver.hsminweb.cgilua.lp +-- ------------------------------------------------------------ + +---@class hs.httpserver.hsminweb.cgilua.lp +hs.httpserver.hsminweb.cgilua.lp = {} + +--- Converts the specified Lua template source into a Lua function. +--- +--- Note: The source provided is first compared to a stored cache of previously translated templates and will re-use an +--- existing translation if the template has been seen before. If the source is unique, cgilua.lp.translate is called +--- on the template source. +--- This function is used internally by cgilua.lp.include , and probably won't be useful unless you want to translate a +--- dynamically generated template -- which has security implications, depending upon what inputs you use to generate +--- this template, because the resulting Lua code will execute within your Hammerspoon environment. Be very careful +--- about your inputs if you choose to ignore this warning. +---@param source string +---@param name function +---@param env table|nil +---@return function +function hs.httpserver.hsminweb.cgilua.lp.compile(source, name, env) end + +--- Includes the template specified by the +--- file +--- parameter. +--- +--- Note: This function is called by the web server to process the template specified by the requested URL. Subsequent +--- invocations of this function can be used to include common or re-used code from other template files and will be +--- included in-line where the cgilua.lp.include function is invoked in the originating template. +--- During the processing of a web request, the local directory is temporarily changed to match the local directory of +--- the path of the file being served, as determined by the URL of the request. This is usually different than the +--- Hammerspoon default directory which corresponds to the directory which contains the init.lua file for Hammerspoon. +--- the __index metamethod points to the _G environment variable in the Hammerspoon Lua instance; this means that any +--- global variable in the Hammerspoon environment is available to the lua code in a template file. +--- the __newindex metamethod points to a function which creates new "global" variables in the template files +--- environment; this means that if a template includes another template file, and that second template file creates a +--- "global" variable, that new variable will be available in the environment of the calling template, but will not be +--- shared with the Hammerspoon global variable space; "global" variables created in this manner will be released when +--- the HTTP request is completed. +--- print is overridden so that its output is streamed into the response body to be returned when the web request +--- completes. It follows the traditional pattern of the print builtin function: multiple arguments are separated by a +--- tab character, the output is terminated with a new-line character, non-string arguments are converted to strings +--- via the tostring builtin function. +--- write is defined as an alternative to print and differs in the following ways from the print function described +--- above: no intermediate tabs or newline are included in the output streamed to the response body. +--- cgilua is defined as a table containing all of the functions included in this support sub-module. +--- CGIVariables - a table containing key-value pairs of the same data available through the cgilua.servervariable +--- function. +--- id - a string, generated via hs.host.globallyUniqueString , unique to this specific HTTP request. +--- log - a table/object representing the hs.httpserver.hsminweb instance of hs.logger . This can be used to +--- log messages to the Hammerspoon console as described in the documentation for hs.logger . +--- this table also contains a table with the key "_". This table contains functions and data used internally, and is +--- described more fully in a supporting document (TBD). It is targeted primarily at custom error functions designed +--- for use with hs.httpserver.hsminweb and should not generally be necessary for Lua template files. +--- method - the method of the HTTP request, most commonly "GET" or "POST" +--- path - the path portion of the requested URL. +--- body - a string containing the response body. As the lua template outputs content, this string is appended to. +--- code - an integer representing the currently expected response code for the HTTP request. +--- headers - a table containing key-value pairs of the currently defined response headers +--- _tmpfiles - used internally to track temporary files used in the completion of this HTTP request; do not modify +--- directly. +---@param file string +---@param env table|nil +---@return none +function hs.httpserver.hsminweb.cgilua.lp.include(file, env) end + +--- Converts the specified Lua template source into Lua code executable within the Hammerspoon environment. +--- +--- Note: This function is used internally by cgilua.lp.include , and probably won't be useful unless you want to +--- translate a dynamically generated template -- which has security implications, depending upon what inputs you use +--- to generate this template, because the resulting Lua code will execute within your Hammerspoon environment. Be +--- very careful about your inputs if you choose to ignore this warning. +--- To ensure that the translated code has access to the cgilua support functions, pass _ENV as the environment +--- argument to the load lua builtin; otherwise any output generated by the resulting function will be sent to the +--- Hammerspoon console and not included in the HTTP response sent back to the client. +---@param source string +---@return luaCode +function hs.httpserver.hsminweb.cgilua.lp.translate(source) end + +-- ------------------------------------------------------------ +-- hs.httpserver.hsminweb.cgilua.urlcode +-- ------------------------------------------------------------ + +---@class hs.httpserver.hsminweb.cgilua.urlcode +hs.httpserver.hsminweb.cgilua.urlcode = {} + +--- Encodes the table of key-value pairs as a query string suitable for inclusion in a URL. +--- +--- Note: the string will be of the form: "key1=value1&key2=value2..." where all of the keys and values are properly +--- escaped using cgilua.urlcode.escape . If you are crafting a URL by hand, the result of this function should be +--- appended to the end of the URL after a "?" character to specify where the query string begins. +---@param table table +---@return string +function hs.httpserver.hsminweb.cgilua.urlcode.encodetable(table) end + +--- URL encodes the provided string, making it safe as a component within a URL. +--- +--- Note: this function assumes that the provided string is a single component and URL encodes all non-alphanumeric +--- characters. Do not use this function to generate a URL query string -- use cgilua.urlcode.encodetable . +---@param string string +---@return string +function hs.httpserver.hsminweb.cgilua.urlcode.escape(string) end + +--- Inserts the specified key and value into the table of key-value pairs. +--- +--- Note: If the key already exists in the table, its value is converted to a table (if it isn't already) and the new +--- value is added to the end of the array of values for the key. +--- This function is used internally by cgilua.urlcode.parsequery or can be used to prepare a table of key-value pairs +--- for cgilua.urlcode.encodetable . +---@param table table +---@param key string +---@param value any +---@return none +function hs.httpserver.hsminweb.cgilua.urlcode.insertfield(table, key, value) end + +--- Parse the query string and store the key-value pairs in the provided table. +--- +--- Note: The specification allows for the same key to be assigned multiple values in an encoded string, but does not +--- specify the behavior; by convention, web servers assign these multiple values to the same key in an array (table). +--- This function follows that convention. This is most commonly used by forms which allow selecting multiple options +--- via check boxes or in a selection list. +--- This function uses cgilua.urlcode.insertfield to build the key-value table. +---@param query number +---@param table table +---@return none +function hs.httpserver.hsminweb.cgilua.urlcode.parsequery(query, table) end + +--- Removes any URL encoding in the provided string. +---@param string string +---@return string +function hs.httpserver.hsminweb.cgilua.urlcode.unescape(string) end + +-- ------------------------------------------------------------ +-- hs.image +-- ------------------------------------------------------------ + +---@class hs.image +hs.image = {} + +---@class image +local image = {} + +--- Table of arrays containing the names of additional internal system images which may also be available for use with +--- hs.drawing.image +--- and +--- hs.image.imageFromName +--- . +---@type table +hs.image.additionalImageNames[] = nil + +--- Table containing the names of internal system images for use with hs.drawing.image +---@type table +hs.image.systemImageNames[] = nil + +--- Gets the EXIF metadata information from an image file. +---@param path string +---@return table|nil +function hs.image.getExifFromPath(path) end + +--- Creates an +--- hs.image +--- object for the file or files specified +---@param file files[] +---@return object +function hs.image.iconForFile(file) end + +--- Creates an +--- hs.image +--- object of the icon for the specified file type. +---@param fileType any +---@return object +function hs.image.iconForFileType(fileType) end + +--- Creates an +--- hs.image +--- object using the icon from an App +---@param bundleID string +---@return object +function hs.image.imageFromAppBundle(bundleID) end + +--- Creates an image from an ASCII representation with the specified context. +--- +--- Note: To use the ASCII diagram image support, see https://github.com/cparnot/ASCIImage and +--- http://cocoamine.net/blog/2015/03/20/replacing-photoshop-with-nsstring +--- The default for lineWidth, when antialiasing is off, is defined within the ASCIImage library. Geometrically it +--- represents one half of the hypotenuse of the unit right-triangle and is a more accurate representation of a "real" +--- point size when dealing with arbitrary angles and lines than 1.0 would be. +---@param ascii string +---@param context? string +---@return object +function hs.image.imageFromASCII(ascii, context) end + +--- Creates an +--- hs.image +--- object from a video file or the album artwork of an audio file or directory +--- +--- Note: If a thumbnail can be generated for a video file, it is returned as an hs.image object, otherwise the +--- filetype icon +--- For audio files, this function first determines the containing directory (if not already a directory) +--- It checks if any of the following common filenames for album art are present: +--- cover.jpg +--- front.jpg +--- art.jpg +--- album.jpg +--- folder.jpg +--- If one of the common album art filenames is found, it is returned as an hs.image object +--- This is faster than extracting image metadata and allows for obtaining artwork associated with file formats such as +--- .flac/.ogg +--- If no common album art filenames are found, it attempts to extract image metadata from the file. This works for +--- .mp3/.m4a files +--- If embedded image metadata is found, it is returned as an hs.image object, otherwise the filetype icon +---@param file string +---@return object +function hs.image.imageFromMediaFile(file) end + +--- Returns the hs.image object for the specified name, if it exists. +--- +--- Note: Some predefined labels corresponding to OS X System default images can be found in hs.image.systemImageNames . +--- an image whose name was explicitly set with the setName method since the last full restart of Hammerspoon +--- Hammerspoon's main application bundle +--- the Application Kit framework (this is where most of the images listed in hs.image.systemImageNames are located) +--- Image names can be assigned by the image creator or by calling the hs.image:setName method on an hs.image object. +---@param string string +---@return object +function hs.image.imageFromName(string) end + +--- Loads an image file +---@param path string +---@return object +function hs.image.imageFromPath(path) end + +--- Creates an +--- hs.image +--- object from the contents of the specified URL. +--- +--- Note: If a callback function is supplied, this function will return nil immediately and the image will be fetched +--- asynchronously +---@param url string +---@param callbackFn? function|nil +---@return object +function hs.image.imageFromURL(url, callbackFn) end + +--- Creates a new bitmap representation of the image and returns it as a new hs.image object +--- +--- Note: a bitmap representation of an image is rendered at the specific size specified (or inherited) when it is +--- generated -- if you later scale it to a different size, the bitmap will be scaled as larger or smaller pixels +--- rather than smoothly. +--- this method may be useful when preparing images for other devices (e.g. hs.streamdeck ). +---@param size table|nil +---@param gray number +---@return imageObject +function image:bitmapRepresentation(size, gray) end + +--- Reads the color of the pixel at the specified location. +---@param point hs.geometry.point +---@return table +function image:colorAt(point) end + +--- Returns a copy of the image +---@return imageObject +function image:copy() end + +--- Returns a copy of the portion of the image specified by the rectangle specified. +---@param rectangle table +---@return object +function image:croppedCopy(rectangle) end + +--- Returns a bitmap representation of the image as a base64 encoded URL string +--- +--- Note: You can convert the string back into an image object with hs.image.imageFromURL , e.g. +--- hs.image.imageFromURL(string) +---@param scale boolean|nil +---@param type any +---@return string +function image:encodeAsURLString(scale, type) end + +--- Get or set the name of the image represented by the hs.image object. +--- +--- Note: see also hs.image:setName for a variant that returns a boolean instead. +---@param name hs.image|nil +---@return imageObject|string +function image:name(name) end + +--- Save the hs.image object as an image of type +--- filetype +--- to the specified filename. +--- +--- Note: Saves image at the size in points (or pixels, if scale is true) as reported by hs.image:size() for the image +--- object +---@param filename string +---@param scale boolean|nil +---@param filetype any +---@return boolean +function image:saveToFile(filename, scale, filetype) end + +--- Assigns the name assigned to the hs.image object. +--- +--- Note: This method is included for backwards compatibility and is considered deprecated. It is equivalent to +--- hs.image:name(name) and true or false . +---@deprecated +---@param Name hs.image +---@return boolean +function image:setName(Name) end + +--- Returns a copy of the image resized to the height and width specified in the size table. +--- +--- Note: This method is included for backwards compatibility and is considered deprecated. It is equivalent to +--- hs.image:copy():size(size, [absolute]) . +---@deprecated +---@param size table +---@param absolute? any +---@return object +function image:setSize(size, absolute) end + +--- Get or set the size of the image represented by the hs.image object. +--- +--- Note: See also hs.image:setSize for creating a copy of the image at a new size. +---@param size table|nil +---@param absolute any +---@return imageObject|size +function image:size(size, absolute) end + +--- Get or set whether the image is considered a template image. +--- +--- Note: Template images consist of black and clear colors (and an alpha channel). Template images are not intended to +--- be used as standalone images and are usually mixed with other content to create the desired final appearance. +--- Images with this flag set to true usually appear lighter than they would with this flag set to false. +---@param state boolean +---@return imageObject|boolean +function image:template(state) end + +--- Converts an image to an ASCII representation of the image in the form of a string. +---@param width number +---@param height number +---@return string +function image:toASCII(width, height) end + +-- ------------------------------------------------------------ +-- hs.inspect +-- ------------------------------------------------------------ + +---@class hs.inspect +hs.inspect = {} + +--- Gets a human readable version of the supplied Lua variable +--- +--- Note: For convenience, you can call this function as hs.inspect(variable) +--- To view the output in Hammerspoon's Console, use print(hs.inspect(variable)) +--- For more information on the options, and some examples, see the upstream docs +---@param variable any +---@param options? any +---@return string +function hs.inspect.inspect(variable, options) end + +-- ------------------------------------------------------------ +-- hs.ipc +-- ------------------------------------------------------------ + +---@class hs.ipc +hs.ipc = {} + +---@class ipc +local ipc = {} + +--- See +--- hs.ipc.cliColors +--- . +---@return table +function hs.ipc.cliGetColors() end + +--- See +--- hs.ipc.cliColors +--- . +---@return any +function hs.ipc.cliResetColors() end + +--- See +--- hs.ipc.cliColors +--- . +---@param table any +---@return table +function hs.ipc.cliSetColors(table) end + +--- Get or set the terminal escape codes used to produce colorized output in the +--- hs +--- command line tool +--- +--- Note: For a brief intro into terminal colors, you can visit a web site like this one +--- http://jafrog.com/2013/11/23/colors-in-terminal.html +--- Lua doesn't support octal escapes in it's strings, so use \x1b or \27 to indicate the escape character e.g. +--- ipc.cliSetColors{ initial = "", input = "\27[33m", output = "\27[38;5;11m" } +--- Changes made with this function are saved with hs.settings with the following labels and will persist through a +--- reload or restart of Hammerspoon: "ipc.cli.color_initial", "ipc.cli.color_input", "ipc.cli.color_output", and +--- "ipc.cli.color_error" +---@param colors any +---@return table +function hs.ipc.cliColors(colors) end + +--- Installs the +--- hs +--- command line tool +--- +--- Note: If this function fails, it is likely that you have some old/broken symlinks. You can use +--- hs.ipc.cliUninstall() to forcibly tidy them up +--- You may need to pre-create /usr/local/bin and /usr/local/share/man/man1 in a terminal using sudo, and adjust +--- permissions so your login user can write to them +---@param path string|nil +---@param silent? any +---@return boolean +function hs.ipc.cliInstall(path, silent) end + +--- Get or set whether or not the command line tool saves a history of the commands you type. +--- +--- Note: If this is enabled, your history is saved in hs.configDir .. ".cli.history" , which is usually +--- "~/.hammerspoon/.cli.history". +--- If you have multiple invocations of the command line tool running at the same time, only the history of the last +--- one cleanly exited is saved; this is a limitation of the readline wrapper Apple has provided for libedit and at +--- present no workaround is known. +--- Changes made with this function are saved with hs.settings with the label "ipc.cli.saveHistory" and will persist +--- through a reload or restart of Hammerspoon. +---@param state boolean +---@return boolean +function hs.ipc.cliSaveHistory(state) end + +--- Get or set whether the maximum number of commands saved when command line tool history saving is enabled. +--- +--- Note: When hs.ipc.cliSaveHistory is enabled, your history is saved in hs.configDir .. ".cli.history" , which is +--- usually "~/.hammerspoon/.cli.history". +--- If you have multiple invocations of the command line tool running at the same time, only the history of the last +--- one cleanly exited is saved; this is a limitation of the readline wrapper Apple has provided for libedit and at +--- present no workaround is known. +--- Changes made with this function are saved with hs.settings with the label "ipc.cli.historyLimit" and will persist +--- through a reload or restart of Hammerspoon. +---@param size hs.ipc.cliSaveHistory|nil +---@return number +function hs.ipc.cliSaveHistorySize(size) end + +--- Gets the status of the +--- hs +--- command line tool +---@param path string|nil +---@param silent? any +---@return boolean +function hs.ipc.cliStatus(path, silent) end + +--- Uninstalls the +--- hs +--- command line tool +--- +--- Note: This function used to be very conservative and refuse to remove symlinks it wasn't sure about, but now it +--- will unconditionally remove whatever it finds at path/bin/hs and path/share/man/man1/hs.1 . This is more likely to +--- be useful in situations where this command is actually needed (please open an Issue on GitHub if you disagree!) +---@param path string|nil +---@param silent? any +---@return boolean +function hs.ipc.cliUninstall(path, silent) end + +--- Create a new local ipcObject for receiving and responding to messages from a remote port +--- +--- Note: a remote port can send messages at any time to a local port; a local port can only respond to messages from a +--- remote port +---@param name string +---@param fn function +---@return ipcObject +function hs.ipc.localPort(name, fn) end + +--- Create a new remote ipcObject for sending messages asynchronously to a local port +--- +--- Note: a remote port can send messages at any time to a local port; a local port can only respond to messages from a +--- remote port +---@param name string +---@return ipcObject +function hs.ipc.remotePort(name) end + +--- Deletes the ipcObject, stopping it as well if necessary +function ipc:delete() end + +--- Returns whether or not the ipcObject represents a remote or local port +--- +--- Note: a remote port can send messages at any time to a local port; a local port can only respond to messages from a +--- remote port +---@return boolean +function ipc:isRemote() end + +--- Returns whether or not the ipcObject port is still valid or not +---@return boolean +function ipc:isValid() end + +--- Returns the name the ipcObject uses for its port when active +---@return string +function ipc:name() end + +--- Sends a message from a remote port to a local port +---@param data string +---@param msgID number +---@param waitTimeout number|nil +---@param oneWay number +---@return status +---@return response +function ipc:sendMessage(data, msgID, waitTimeout, oneWay) end + +-- ------------------------------------------------------------ +-- hs.itunes +-- ------------------------------------------------------------ + +---@class hs.itunes +hs.itunes = {} + +--- Returned by +--- hs.itunes.getPlaybackState() +--- to indicates iTunes is paused +---@type hs.itunes.getPlaybackState +hs.itunes.state_paused = nil + +--- Returned by +--- hs.itunes.getPlaybackState() +--- to indicates iTunes is playing +---@type hs.itunes.getPlaybackState +hs.itunes.state_playing = nil + +--- Returned by +--- hs.itunes.getPlaybackState() +--- to indicates iTunes is stopped +---@type hs.itunes.getPlaybackState +hs.itunes.state_stopped = nil + +--- Displays information for current track on screen +---@return any +function hs.itunes.displayCurrentTrack() end + +--- Skips the current playback forwards by 5 seconds +---@return any +function hs.itunes.ff() end + +--- Gets the name of the current Album +---@return string|nil +function hs.itunes.getCurrentAlbum() end + +--- Gets the name of the current Artist +---@return string|nil +function hs.itunes.getCurrentArtist() end + +--- Gets the name of the current track +---@return string|nil +function hs.itunes.getCurrentTrack() end + +--- Gets the duration (in seconds) of the current song +---@return number +function hs.itunes.getDuration() end + +--- Gets the current playback state of iTunes +---@return hs.itunes.state_stopped|hs.itunes.state_paused|hs.itunes.state_playing +function hs.itunes.getPlaybackState() end + +--- Gets the playback position (in seconds) of the current song +---@return number +function hs.itunes.getPosition() end + +--- Gets the current iTunes volume setting +---@return number +function hs.itunes.getVolume() end + +--- Returns whether iTunes is currently playing +---@return boolean|nil +function hs.itunes.isPlaying() end + +--- Returns whether iTunes is currently open. Most other functions in hs.itunes will automatically start the +--- application, so this function can be used to guard against that. +---@return boolean +function hs.itunes.isRunning() end + +--- Skips to the next itunes track +---@return any +function hs.itunes.next() end + +--- Pauses the current iTunes track +---@return any +function hs.itunes.pause() end + +--- Plays the current iTunes track +---@return any +function hs.itunes.play() end + +--- Toggles play/pause of current iTunes track +---@return any +function hs.itunes.playpause() end + +--- Skips to previous itunes track +---@return any +function hs.itunes.previous() end + +--- Skips the current playback backwards by 5 seconds +---@return any +function hs.itunes.rw() end + +--- Sets the playback position of the current song +---@param pos number +---@return any +function hs.itunes.setPosition(pos) end + +--- Sets the iTunes playback volume +---@param vol number +---@return any +function hs.itunes.setVolume(vol) end + +--- Decreases the iTunes playback volume by 5 +---@return any +function hs.itunes.volumeDown() end + +--- Increases the iTunes playback volume by 5 +---@return any +function hs.itunes.volumeUp() end + +-- ------------------------------------------------------------ +-- hs.json +-- ------------------------------------------------------------ + +---@class hs.json +hs.json = {} + +--- Decodes JSON into a table +--- +--- Note: This is useful for retrieving some of the more complex lua table structures as a persistent setting (see +--- hs.settings ) +---@param jsonString string +---@return table +function hs.json.decode(jsonString) end + +--- Encodes a table as JSON +--- +--- Note: This is useful for storing some of the more complex lua table structures as a persistent setting (see +--- hs.settings ) +---@param val table +---@param prettyprint? boolean|nil +---@return string +function hs.json.encode(val, prettyprint) end + +--- Decodes JSON file into a table. +---@param path string +---@return table|nil +function hs.json.read(path) end + +--- Encodes a table as JSON to a file +---@param data table +---@param path string +---@param prettyprint boolean|nil +---@param replace boolean|nil +---@return boolean +function hs.json.write(data, path, prettyprint, replace) end + +-- ------------------------------------------------------------ +-- hs.keycodes +-- ------------------------------------------------------------ + +---@class hs.keycodes +hs.keycodes = {} + +--- A mapping from string representation of a key to its keycode, and vice versa. +---@type string +hs.keycodes.map = nil + +--- Gets the name of the current keyboard layout +---@return string +function hs.keycodes.currentLayout() end + +--- Gets the icon of the current keyboard layout +---@return hs.image +function hs.keycodes.currentLayoutIcon() end + +--- Get current input method +---@return string +function hs.keycodes.currentMethod() end + +--- Get or set the source id for the keyboard input source +---@param sourceID string|nil +---@return string|boolean +function hs.keycodes.currentSourceID(sourceID) end + +--- Gets an hs.image object for a given keyboard layout or input method +--- +--- Note: Not all layouts/methods have icons, so you should assume this will return nil at some point +---@param sourceName string +---@return hs.image +function hs.keycodes.iconForLayoutOrMethod(sourceName) end + +--- Sets the function to be called when your input source (i.e. qwerty, dvorak, colemac) changes. +--- +--- Note: This may be helpful for rebinding your hotkeys to appropriate keys in the new layout +--- Setting this will un-set functions previously registered by this function. +---@param fn function +---@return any +function hs.keycodes.inputSourceChanged(fn) end + +--- Gets all of the enabled keyboard layouts that the keyboard input source can be switched to +--- +--- Note: Only those layouts which can be explicitly switched to will be included in the table. Keyboard layouts which +--- are part of input methods are not included. See hs.keycodes.methods . +---@param sourceID boolean|nil +---@return table +function hs.keycodes.layouts(sourceID) end + +--- Gets all of the enabled input methods that the keyboard input source can be switched to +--- +--- Note: Keyboard layouts which are not part of an input method are not included in this table. See +--- hs.keycodes.layouts . +---@param sourceID boolean|nil +---@return table +function hs.keycodes.methods(sourceID) end + +--- Changes the system keyboard layout +---@param layoutName string +---@return boolean +function hs.keycodes.setLayout(layoutName) end + +--- Changes the system input method +---@param methodName string +---@return boolean +function hs.keycodes.setMethod(methodName) end + +-- ------------------------------------------------------------ +-- hs.layout +-- ------------------------------------------------------------ + +---@class hs.layout +hs.layout = {} + +---@class hs.layout.layout +---@field left25 any A unit rect which will make a window occupy the left 25% of a screen +---@field left30 any A unit rect which will make a window occupy the left 30% of a screen +---@field left50 any A unit rect which will make a window occupy the left 50% of a screen +---@field left70 any A unit rect which will make a window occupy the left 70% of a screen +---@field left75 any A unit rect which will make a window occupy the left 75% of a screen + +--- A unit rect which will make a window occupy the left 25% of a screen +---@type any +hs.layout.left25 = nil + +--- A unit rect which will make a window occupy the left 30% of a screen +---@type any +hs.layout.left30 = nil + +--- A unit rect which will make a window occupy the left 50% of a screen +---@type any +hs.layout.left50 = nil + +--- A unit rect which will make a window occupy the left 70% of a screen +---@type any +hs.layout.left70 = nil + +--- A unit rect which will make a window occupy the left 75% of a screen +---@type any +hs.layout.left75 = nil + +--- A unit rect which will make a window occupy all of a screen +---@type any +hs.layout.maximized = nil + +--- A unit rect which will make a window occupy the right 25% of a screen +---@type any +hs.layout.right25 = nil + +--- A unit rect which will make a window occupy the right 30% of a screen +---@type any +hs.layout.right30 = nil + +--- A unit rect which will make a window occupy the right 50% of a screen +---@type any +hs.layout.right50 = nil + +--- A unit rect which will make a window occupy the right 70% of a screen +---@type any +hs.layout.right70 = nil + +--- A unit rect which will make a window occupy the right 75% of a screen +---@type any +hs.layout.right75 = nil + +--- Applies a layout to applications/windows +--- +--- Note: If the application name argument is nil, window titles will be matched regardless of which app they belong to +--- If the window title argument is nil, all windows of the specified application will be matched +--- If the window title argument is a function, the function will be called with the application name argument (which +--- may be nil), and should return a table of hs.window objects (even if there is only one window it must be in a table) +--- You can specify both application name and window title if you want to match only one window of a particular +--- application +--- If you specify neither application name or window title, no windows will be matched :) +--- Monitor name is a string, as found in hs.screen:name() or hs.screen:getUUID() . You can also pass an hs.screen +--- object, or a function that returns an hs.screen object. If you pass nil, the first screen will be selected +--- Unit rect will be passed to hs.window.moveToUnit() +--- Frame rect will be passed to hs.window.setFrame() (including menubar and dock) +--- Full-frame rect will be passed to hs.window.setFrame() (ignoring menubar and dock) +--- If either the x or y components of frame/full-frame rect are negative, they will be applied as offsets against the +--- opposite edge of the screen (e.g. If x is -100 then the left edge of the window will be 100 pixels from the right +--- edge of the screen) +--- Only one of the rect arguments will apply to any matched windows. If you specify more than one, the first will win +--- An example usage: layout1 = { { "Mail" , nil , "Color LCD" , hs . layout . maximized , nil , nil }, { "Safari" , +--- nil , "Thunderbolt Display" , hs . layout . maximized , nil , nil }, { "iTunes" , "iTunes" , "Color LCD" , hs . +--- layout . maximized , nil , nil }, { "iTunes" , "MiniPlayer" , "Color LCD" , nil , nil , hs . geometry . rect ( 0 , +--- - 48 , 400 , 48 )}, } ``` +--- An example of a function that works well as a windowTitleComparator is the Lua built-in string.match , which uses +--- Lua Patterns to match strings +---@param table any +---@param windowTitleComparator? any +---@return any +function hs.layout.apply(table, windowTitleComparator) end + +-- ------------------------------------------------------------ +-- hs.location +-- ------------------------------------------------------------ + +---@class hs.location +hs.location = {} + +---@class location +local location = {} + +--- Returns a string describing the authorization status of Hammerspoon's use of Location Services. +--- +--- Note: The first time you use a function which requires Location Services, you will be prompted to grant Hammerspoon +--- access. If you wish to change this permission after the initial prompt, you may do so from the Location Services +--- section of the Security & Privacy section in the System Preferences application. +---@return string +function hs.location.authorizationStatus() end + +--- Measures the distance between two points of latitude and longitude +--- +--- Note: This function does not require Location Services to be enabled for Hammerspoon. +---@param from table +---@param to table +---@return meters +function hs.location.distance(from, to) end + +--- Returns a number giving the current daylight savings time offset +--- +--- Note: This value is derived from the currently configured system timezone, it does not use Location Services +---@return number +function hs.location.dstOffset() end + +--- Returns a table representing the current location +--- +--- Note: This function activates Location Services for Hammerspoon, so the first time you call this, you may be +--- prompted to authorise Hammerspoon to use Location Services. +--- Internally, the Location Services cache is updated whenever additional WiFi networks are detected or lost (not +--- necessarily joined). When update tracking is enabled with the hs.location.start function, calculations based upon +--- the RSSI of all currently seen networks are preformed more often to provide a more precise fix, but it's still +--- based on the WiFi networks near you. +---@return locationTable|nil +function hs.location.get() end + +--- Registers a callback function to be called when the system location is updated +---@param tag string +---@param fn function +---@param distance? function|nil +---@return any +function hs.location.register(tag, fn, distance) end + +--- Gets the state of OS X Location Services +---@return boolean +function hs.location.servicesEnabled() end + +--- Begins location tracking using OS X's Location Services so that registered callback functions can be invoked as the +--- computer location changes. +--- +--- Note: This function activates Location Services for Hammerspoon, so the first time you call this, you may be +--- prompted to authorise Hammerspoon to use Location Services. +---@return boolean +function hs.location.start() end + +--- Stops location tracking. Registered callback functions will cease to receive notification of location changes. +---@return any +function hs.location.stop() end + +--- Returns the time of official sunrise for the supplied location +--- +--- Note: You can turn the return value into a more useful structure, with os.date("*t", returnvalue) +--- For compatibility with the locationTable object returned by hs.location.get , this function can also be invoked as +--- hs.location.sunrise(locationTable, offset[, date]) . +---@param latitude number +---@param longitude number +---@param offset number +---@param date? table|nil +---@return number|string +function hs.location.sunrise(latitude, longitude, offset, date) end + +--- Returns the time of official sunset for the supplied location +--- +--- Note: You can turn the return value into a more useful structure, with os.date("*t", returnvalue) +--- For compatibility with the locationTable object returned by hs.location.get , this function can also be invoked as +--- hs.location.sunset(locationTable, offset[, date]) . +---@param latitude number +---@param longitude number +---@param offset number +---@param date? table|nil +---@return number|string +function hs.location.sunset(latitude, longitude, offset, date) end + +--- Unregisters a callback +---@param tag string +---@return any +function hs.location.unregister(tag) end + +--- Create a new location object which can receive callbacks independent of other Hammerspoon use of Location Services. +--- +--- Note: The locationObject created will receive callbacks independent of all other locationObjects and the legacy +--- callback functions created with hs.location.register . It can also receive callbacks for region changes which are +--- not available through the legacy callback mechanism. +---@return locationObject +function hs.location.new() end + +--- Adds a region to be monitored by Location Services +--- +--- Note: This method activates Location Services for Hammerspoon, so the first time you call this, you may be prompted +--- to authorise Hammerspoon to use Location Services. +--- If the identifier key is not provided, a new UUID string is generated and used as the identifier. +--- If the identifier key matches an already monitored region, this region will replace the existing one. +---@param regionTable table +---@return locationObject|nil +function location:addMonitoredRegion(regionTable) end + +--- Sets or removes the callback function for this locationObject +---@param fn function +---@return locationObject +function location:callback(fn) end + +--- Returns the string identifier for the current region +--- +--- Note: This method activates Location Services for Hammerspoon, so the first time you call this, you may be prompted +--- to authorise Hammerspoon to use Location Services. +---@return identifier|nil +function location:currentRegion() end + +--- Enable callbacks for location changes/refinements for this locationObject +--- +--- Note: This function activates Location Services for Hammerspoon, so the first time you call this, you may be +--- prompted to authorise Hammerspoon to use Location Services. +---@param locationTable any +---@return distance|nil +function location:distanceFrom(locationTable) end + +--- Returns the current location +--- +--- Note: This function activates Location Services for Hammerspoon, so the first time you call this, you may be +--- prompted to authorise Hammerspoon to use Location Services. +--- Internally, the Location Services cache is updated whenever additional WiFi networks are detected or lost (not +--- necessarily joined). When update tracking is enabled with the hs.location.start function, calculations based upon +--- the RSSI of all currently seen networks are preformed more often to provide a more precise fix, but it's still +--- based on the WiFi networks near you. +---@return locationTable|nil +function location:location() end + +--- Returns a table containing the regionTables for the regions currently being monitored for this locationObject +--- +--- Note: This method activates Location Services for Hammerspoon, so the first time you call this, you may be prompted +--- to authorise Hammerspoon to use Location Services. +---@return table|nil +function location:monitoredRegions() end + +--- Removes a monitored region from Location Services +--- +--- Note: This method activates Location Services for Hammerspoon, so the first time you call this, you may be prompted +--- to authorise Hammerspoon to use Location Services. +--- If the identifier key is not provided, a new UUID string is generated and used as the identifier. +--- If the identifier key matches an already monitored region, this region will replace the existing one. +---@param identifier string +---@return locationObject|boolean|nil +function location:removeMonitoredRegion(identifier) end + +--- Enable callbacks for location changes/refinements for this locationObject +--- +--- Note: This function activates Location Services for Hammerspoon, so the first time you call this, you may be +--- prompted to authorise Hammerspoon to use Location Services. +---@return locationObject +function location:startTracking() end + +--- Disable callbacks for location changes/refinements for this locationObject +---@return locationObject +function location:stopTracking() end + +-- ------------------------------------------------------------ +-- hs.location.geocoder +-- ------------------------------------------------------------ + +---@class hs.location.geocoder +hs.location.geocoder = {} + +---@class geocoder +local geocoder = {} + +--- Look up geocoding information for the specified address. +--- +--- Note: This constructor requires internet access and the callback will be invoked with an error message if the +--- internet is not currently accessible. +--- This constructor does not require Location Services to be enabled for Hammerspoon. +---@param address string +---@param fn function +---@return geocoderObject +function hs.location.geocoder.lookupAddress(address, fn) end + +--- Look up geocoding information for the specified address. +--- +--- Note: This constructor requires internet access and the callback will be invoked with an error message if the +--- internet is not currently accessible. +--- This constructor does not require Location Services to be enabled for Hammerspoon. +--- While a partial address can be given, the more information you provide, the more likely the results will be useful. +--- The regionTable only determines sort order if multiple entries are returned, it does not constrain the search. +---@param address string +---@param regionTable hs.location|nil +---@param fn function +---@return geocoderObject +function hs.location.geocoder.lookupAddressNear(address, regionTable, fn) end + +--- Look up geocoding information for the specified location. +--- +--- Note: This constructor requires internet access and the callback will be invoked with an error message if the +--- internet is not currently accessible. +--- This constructor does not require Location Services to be enabled for Hammerspoon. +---@param locationTable hs.location +---@param fn function +---@return geocoderObject +function hs.location.geocoder.lookupLocation(locationTable, fn) end + +--- Cancels the pending or in progress geocoding request. +--- +--- Note: This method has no effect if the geocoding process has already completed. +---@return nil +function geocoder:cancel() end + +--- Returns a boolean indicating whether or not the geocoding process is still active. +---@return boolean +function geocoder:geocoding() end + +-- ------------------------------------------------------------ +-- hs.logger +-- ------------------------------------------------------------ + +---@class hs.logger +---@field level number The log level of the logger instance, as a number between 0 and 5 +hs.logger = {} + +--- Default log level for new logger instances. +---@type any +hs.logger.defaultLogLevel = nil + +--- Returns the global log history +---@return list of log entries +function hs.logger.history() end + +--- Sets or gets the global log history size +--- +--- Note: if you change history size (other than from 0) after creating any logger instances, things will likely break +---@param size number|nil +---@return number +function hs.logger.historySize(size) end + +--- Creates a new logger instance +--- +--- Note: the logger instance created by this method is not a regular object, but a plain table with "static" functions; +--- therefore, do not use the colon syntax for so-called "methods" in this module (as in mylogger.setLogLevel(3) ); +--- you must instead use the regular dot syntax: mylogger.setLogLevel(3) +--- Example: +--- local +--- log +--- = +--- hs +--- . +--- logger +--- . +--- new +--- ( +--- 'mymodule' +--- , +--- 'debug' +--- ) +--- log +--- . +--- i +--- ( +--- 'Initializing' +--- ) +--- -- will print "[mymodule] Initializing" to the console``` +---@param id string +---@param loglevel hs.logger.defaultLogLevel|nil +---@return logger +function hs.logger.new(id, loglevel) end + +--- Prints the global log history to the console +---@param entries number|nil +---@param level? hs.logger.setLogLevel|nil +---@param filter? function +---@param caseSensitive? any +---@return any +function hs.logger.printHistory(entries, level, filter, caseSensitive) end + +--- Sets the log level for all logger instances (including objects' loggers) +---@param lvl any +---@return any +function hs.logger.setGlobalLogLevel(lvl) end + +--- Sets the log level for all currently loaded modules +--- +--- Note: This function only affects module -level loggers, object instances with their own loggers (e.g. +--- windowfilters) won't be affected; +--- you can use hs.logger.setGlobalLogLevel() for those +---@param lvl any +---@return any +function hs.logger.setModulesLogLevel(lvl) end + +--- Logs debug info to the console +---@param ... any +---@return any +function hs.logger.d(...) end + +--- Logs formatted debug info to the console +---@param fmt string +---@param ... any +---@return any +function hs.logger.df(fmt, ...) end + +--- Logs an error to the console +---@param ... any +---@return any +function hs.logger.e(...) end + +--- Logs a formatted error to the console +---@param fmt string +---@param ... any +---@return any +function hs.logger.ef(fmt, ...) end + +--- Logs formatted info to the console +---@param fmt string +---@param ... any +---@return any +function hs.logger.f(fmt, ...) end + +--- Gets the log level of the logger instance +---@return number +function hs.logger.getLogLevel() end + +--- Logs info to the console +---@param ... any +---@return any +function hs.logger.i(...) end + +--- Sets the log level of the logger instance +---@param loglevel number +---@return any +function hs.logger.setLogLevel(loglevel) end + +--- Logs verbose info to the console +---@param ... any +---@return any +function hs.logger.v(...) end + +--- Logs formatted verbose info to the console +---@param fmt string +---@param ... any +---@return any +function hs.logger.vf(fmt, ...) end + +--- Logs a warning to the console +---@param ... any +---@return any +function hs.logger.w(...) end + +--- Logs a formatted warning to the console +---@param fmt string +---@param ... any +---@return any +function hs.logger.wf(fmt, ...) end + +-- ------------------------------------------------------------ +-- hs.math +-- ------------------------------------------------------------ + +---@class hs.math +hs.math = {} + +--- Smallest positive floating point number representable in Hammerspoon +---@type table +hs.math.minFloat = nil + +--- Returns whether or not the value is a finite number +--- +--- Note: This function returns true if the value is a number and both hs.math.isNaN and hs.math.isInfinite return +--- false. +---@param value any +---@return boolean +function hs.math.isFinite(value) end + +--- Returns whether or not the value is the mathematical equivalent of either positive or negative "Infinity" +--- +--- Note: This function specifically checks if the value is equivalent to positive or negative infinity --- it does not +--- do type checking. If value is not a numeric value (e.g. a string), it cannot be equivalent to positive or negative +--- infinity and will return false. +--- Because lua treats any value other than nil and false as true , the return value of this function can be safely +--- used in conditionals when you don't care about the sign of the infinite value. +---@param value any +---@return 1 +---@return -1 +---@return boolean +function hs.math.isInfinite(value) end + +--- Returns whether or not the value is the mathematical equivalent of "Not-A-Number" +--- +--- Note: Mathematical NaN represents an impossible value, usually the result of a calculation, yet is still considered +--- within the domain of mathematics. The most common case is the result of n / 0 as division by 0 is considered +--- undefined or "impossible". +--- This function specifically checks if the value is NaN --- it does not do type checking. If value is not a numeric +--- value (e.g. a string), it cannot be equivalent to NaN and this function will return false. +---@param value any +---@return boolean +function hs.math.isNaN(value) end + +--- Returns a random floating point number between 0 and 1 +---@return number +function hs.math.randomFloat() end + +--- Returns a random integer between the start and end parameters +---@param start number +---@param end number +---@return number +function hs.math.randomFromRange(start, end) end + +-- ------------------------------------------------------------ +-- hs.menubar +-- ------------------------------------------------------------ + +---@class hs.menubar +hs.menubar = {} + +---@class menubar +local menubar = {} + +--- Pre-defined list of image positions for a menubar item +---@type image[] +hs.menubar.imagePositions[] = nil + +--- Creates a new menu bar item object and optionally add it to the system menubar +--- +--- Note: You should call hs.menubar:setTitle() or hs.menubar:setIcon() after creating the object, otherwise it will be +--- invisible +--- Calling this method with inMenuBar equal to false is equivalent to calling hs.menubar.new():removeFromMenuBar(). +--- A hidden menubaritem can be added to the system menubar by calling hs.menubar:returnToMenuBar() or used as a pop-up +--- menu by calling hs.menubar:popupMenu(). +---@param inMenuBar any +---@param autosaveName string +---@return hs.menubar|nil +function hs.menubar.new(inMenuBar, autosaveName) end + +--- Get or set the autosave name of the menubar. By defining an autosave name, macOS can restore the menubar position +--- after reloads. +---@param name string|nil +---@return hs.menubar|current- +function menubar:autosaveName(name) end + +--- Removes the menubar item from the menubar and destroys it +---@return any +function menubar:delete() end + +--- Returns the menubar item frame +--- +--- Note: This will return a frame even if no icon or title is set +---@return hs.geometry rect +function menubar:frame() end + +--- Returns the current icon of the menubar item object. +---@return hs.image +function menubar:icon() end + +--- Get or set the position of a menubar image relative to its text title +---@param position hs.menubar.imagePositions +---@return hs.menubar|current- +function menubar:imagePosition(position) end + +--- Returns a boolean indicating whether or not the specified menu is currently in the OS X menubar. +---@return boolean +function menubar:isInMenuBar() end + +--- Display a menubaritem as a pop up menu at the specified screen point. +--- +--- Note: Items which trigger hs.menubar:setClickCallback() will invoke the callback function, but we cannot control +--- the positioning of any visual elements the function may create -- calling this method on such an object is the +--- equivalent of invoking its callback function directly. +--- This method is blocking. Hammerspoon will be unable to respond to any other activity while the pop-up menu is being +--- displayed. +--- darkMode uses an undocumented macOS API call, so may break in a future release. +---@param point any +---@param darkMode? any +---@return hs.menubar +function menubar:popupMenu(point, darkMode) end + +--- Removes a menu from the system menu bar. The item can still be used as a pop-up menu, unless you also delete it. +---@return hs.menubar +function menubar:removeFromMenuBar() end + +--- Returns a previously removed menu back to the system menu bar. +---@return hs.menubar +function menubar:returnToMenuBar() end + +--- Registers a function to be called when the menubar item is clicked +--- +--- Note: If a menu has been attached to the menubar item, this callback will never be called +--- Has no affect on the display of a pop-up menu, but changes will be be in effect if hs.menubar:returnToMenuBar() is +--- called on the menubaritem. +---@param fn function +---@return hs.menubar +function menubar:setClickCallback(fn) end + +--- Sets the image of a menubar item object. The image will be displayed in the system menubar +--- +--- Note: This method used to return true on success -- this has been changed to return the menubaritem on success to +--- facilitate method chaining. Since Lua treats any value which is not nil or false as "true", this should only +--- affect code where the return value was actually being compared to true, e.g. if result == true then... rather than +--- the (unaffected) if result then... . +--- If you set a title as well as an icon, they will both be displayed next to each other +--- Has no affect on the display of a pop-up menu, but changes will be be in effect if hs.menubar:returnToMenuBar() is +--- called on the menubaritem. +--- Icons should be small, transparent images that roughly match the size of normal menubar icons, otherwise they will +--- look very strange. Note that if you're using an hs.image image object as the icon, you can force it to be resized +--- with hs.image:setSize({w=16,h=16}) +--- Retina scaling is supported if the image is either scalable (e.g. a PDF produced by Adobe Illustrator) or contain +--- multiple sizes (e.g. a TIFF with small and large images). Images will not automatically do the right thing if you +--- have a @2x version present +--- Icons are by default specified as "templates", which allows them to automatically support OS X 10.10's Dark Mode, +--- but this also means they cannot be complicated, colour images. +--- For examples of images that work well, see Hammerspoon.app/Contents/Resources/statusicon.tiff (for a retina-capable +--- multi-image TIFF icon) or https://github.com/jigish/slate/blob/master/Slate/status.pdf (for a scalable vector PDF +--- icon) +--- For guidelines on the sizing of images, see http://alastairs-place.net/blog/2013/07/23/nsstatusitem-what-size-should-your-icon-be/ +---@param imageData any +---@param template? boolean|nil +---@return hs.menubar|nil +function menubar:setIcon(imageData, template) end + +--- Attaches a dropdown menu to the menubar item +--- +--- Note: If you are using the callback function, you should take care not to take too long to generate the menu, as +--- you will block the process and the OS may decide to remove the menubar item +---@param menuTable any +---@return hs.menubar +function menubar:setMenu(menuTable) end + +--- Sets the title of a menubar item object. The title will be displayed in the system menubar +--- +--- Note: If you set an icon as well as a title, they will both be displayed next to each other +--- Has no affect on the display of a pop-up menu, but changes will be be in effect if hs.menubar:returnToMenuBar() is +--- called on the menubaritem. +---@param title string|nil +---@return hs.menubar +function menubar:setTitle(title) end + +--- Sets the tooltip text on a menubar item +--- +--- Note: Has no affect on the display of a pop-up menu, but changes will be be in effect if +--- hs.menubar:returnToMenuBar() is called on the menubaritem. +---@param tooltip string +---@return hs.menubar +function menubar:setTooltip(tooltip) end + +--- Get or set the size for state images when the menu is displayed. +--- +--- Note: An image is used rather than a checkmark or dash only when you set them with the onStateImage , offStateImage +--- , or mixedStateImage keys. If you are not using these keys, then this method will have no visible effect on the +--- menu's rendering. See hs.menubar:setMenu for more information. +--- If you are setting the menu contents with a static table, you should invoke this method before invoking +--- hs.menubar:setMenu , as changes will only go into effect when the table is next converted to a menu structure. +---@param size number +---@return hs.image +function menubar:stateImageSize(size) end + +--- Returns the current title of the menubar item object. +---@param styled boolean|nil +---@return string|styledtextObject +function menubar:title(styled) end + +-- ------------------------------------------------------------ +-- hs.messages +-- ------------------------------------------------------------ + +---@class hs.messages +hs.messages = {} + +--- Sends an iMessage +---@param targetAddress string +---@param message string +---@return any +function hs.messages.iMessage(targetAddress, message) end + +--- Sends an SMS using SMS Relay +---@param targetNumber string +---@param message string +---@return any +function hs.messages.SMS(targetNumber, message) end + +-- ------------------------------------------------------------ +-- hs.midi +-- ------------------------------------------------------------ + +---@class hs.midi +hs.midi = {} + +---@class midi +local midi = {} + +--- A table containing the numeric value for the possible flags returned by the +--- commandType +--- parameter of the callback function. +---@type table +hs.midi.commandTypes[] = nil + +--- A callback that's triggered when a physical or virtual MIDI device is added or removed from the system. +--- +--- Note: devices - A table containing the names of any physically connected MIDI devices as strings. +--- virtualDevices - A table containing the names of any virtual MIDI devices as strings. +--- Example Usage: hs . midi . deviceCallback ( function ( devices , virtualDevices ) print ( hs . inspect ( devices )) +--- print ( hs . inspect ( virtualDevices )) end ) ``` +---@param callbackFn function +---@return none +function hs.midi.deviceCallback(callbackFn) end + +--- Returns a table of currently connected physical MIDI devices. +---@return table +function hs.midi.devices() end + +--- Returns a table of currently available Virtual MIDI sources. This includes devices, such as Native Instruments +--- controllers which present as virtual endpoints rather than physical devices. +---@return table +function hs.midi.virtualSources() end + +--- Creates a new +--- hs.midi +--- object. +--- +--- Note: Example Usage: hs.midi.new(hs.midi.devices()[1]) +---@param deviceName string +---@return hs.midi|nil +function hs.midi.new(deviceName) end + +--- Creates a new +--- hs.midi +--- object. +--- +--- Note: Example Usage: hs.midi.newVirtualSource(hs.midi.virtualSources()[1]) +---@param virtualSource string +---@return hs.midi|nil +function hs.midi.newVirtualSource(virtualSource) end + +--- Sets or removes a callback function for the +--- hs.midi +--- object. +--- +--- Note: Most MIDI keyboards produce a noteOn when you press a key, then noteOff when you release. However, some MIDI +--- keyboards will return a noteOn with 0 velocity instead of noteOff , so you will receive two noteOn commands for +--- every key press/release. +--- object - The hs.midi object. +--- deviceName - The device name as a string. +--- commandType - Type of MIDI message as defined as a string. See hs.midi.commandTypes[] for a list of possibilities. +--- description - Description of the event as a string. This is only really useful for debugging. +--- metadata - A table of data for the MIDI command (see below). +--- note - The note number for the command. Must be between 0 and 127. +--- velocity - The velocity for the command. Must be between 0 and 127. +--- channel - The channel for the command. Must be a number between 15. +--- timestamp - The timestamp for the command as a string. +--- data - Raw MIDI Data as Hex String. +--- isVirtual - true if Virtual MIDI Source otherwise false . +--- note - The note number for the command. Must be between 0 and 127. +--- velocity - The velocity for the command. Must be between 0 and 127. +--- channel - The channel for the command. Must be a number between 15. +--- timestamp - The timestamp for the command as a string. +--- data - Raw MIDI Data as Hex String. +--- isVirtual - true if Virtual MIDI Source otherwise false . +--- note - The note number for the command. Must be between 0 and 127. +--- pressure - Key pressure of the polyphonic key pressure message. In the range 0-127. +--- channel - The channel for the command. Must be a number between 15. +--- timestamp - The timestamp for the command as a string. +--- data - Raw MIDI Data as Hex String. +--- isVirtual - true if Virtual MIDI Source otherwise false . +--- controllerNumber - The MIDI control number for the command. +--- controllerValue - The controllerValue of the command. Only the lower 7-bits of this are used. +--- channel - The channel for the command. Must be a number between 15. +--- timestamp - The timestamp for the command as a string. +--- data - Raw MIDI Data as Hex String. +--- fourteenBitValue - The 14-bit value of the command. +--- fourteenBitCommand - true if the command contains 14-bit value data otherwise, false . +--- isVirtual - true if Virtual MIDI Source otherwise false . +--- programNumber - The program (aka patch) number. From 0-127. +--- channel - The channel for the command. Must be a number between 15. +--- timestamp - The timestamp for the command as a string. +--- data - Raw MIDI Data as Hex String. +--- isVirtual - true if Virtual MIDI Source otherwise false . +--- pressure - Key pressure of the channel pressure message. In the range 0-127. +--- channel - The channel for the command. Must be a number between 15. +--- timestamp - The timestamp for the command as a string. +--- data - Raw MIDI Data as Hex String. +--- isVirtual - true if Virtual MIDI Source otherwise false . +--- pitchChange - A 14-bit value indicating the pitch bend. Center is 0x2000 (8192). Valid range is from +--- 0-16383. +--- channel - The channel for the command. Must be a number between 15. +--- timestamp - The timestamp for the command as a string. +--- data - Raw MIDI Data as Hex String. +--- isVirtual - true if Virtual MIDI Source otherwise false . +--- dataByte1 - Data Byte 1 as integer. +--- dataByte2 - Data Byte 2 as integer. +--- timestamp - The timestamp for the command as a string. +--- data - Raw MIDI Data as Hex String. +--- isVirtual - true if Virtual MIDI Source otherwise false . +--- manufacturerID - The manufacturer ID for the command. This is used by devices to determine if the message is +--- one they support. +--- sysexChannel - The channel of the message. Only valid for universal exclusive messages, will always be 0 for +--- non-universal messages. +--- sysexData - The system exclusive data for the message. For universal messages subID's are included in +--- sysexData, for non-universal messages, any device specific information (such as modelID, versionID or whatever +--- manufactures decide to include) will be included in sysexData. +--- timestamp - The timestamp for the command as a string. +--- data - Raw MIDI Data as Hex String. +--- isVirtual - true if Virtual MIDI Source otherwise false . +--- dataByte1 - Data Byte 1 as integer. +--- dataByte2 - Data Byte 2 as integer. +--- timestamp - The timestamp for the command as a string. +--- data - Raw MIDI Data as Hex String. +--- isVirtual - true if Virtual MIDI Source otherwise false . +--- dataByte1 - Data Byte 1 as integer. +--- dataByte2 - Data Byte 2 as integer. +--- timestamp - The timestamp for the command as a string. +--- data - Raw MIDI Data as Hex String. +--- isVirtual - true if Virtual MIDI Source otherwise false . +--- dataByte1 - Data Byte 1 as integer. +--- dataByte2 - Data Byte 2 as integer. +--- timestamp - The timestamp for the command as a string. +--- data - Raw MIDI Data as Hex String. +--- isVirtual - true if Virtual MIDI Source otherwise false . +--- dataByte1 - Data Byte 1 as integer. +--- dataByte2 - Data Byte 2 as integer. +--- timestamp - The timestamp for the command as a string. +--- data - Raw MIDI Data as Hex String. +--- isVirtual - true if Virtual MIDI Source otherwise false . +--- dataByte1 - Data Byte 1 as integer. +--- dataByte2 - Data Byte 2 as integer. +--- timestamp - The timestamp for the command as a string. +--- data - Raw MIDI Data as Hex String. +--- isVirtual - true if Virtual MIDI Source otherwise false . +--- dataByte1 - Data Byte 1 as integer. +--- dataByte2 - Data Byte 2 as integer. +--- timestamp - The timestamp for the command as a string. +--- data - Raw MIDI Data as Hex String. +--- isVirtual - true if Virtual MIDI Source otherwise false . +--- dataByte1 - Data Byte 1 as integer. +--- dataByte2 - Data Byte 2 as integer. +--- timestamp - The timestamp for the command as a string. +--- data - Raw MIDI Data as Hex String. +--- isVirtual - true if Virtual MIDI Source otherwise false . +--- dataByte1 - Data Byte 1 as integer. +--- dataByte2 - Data Byte 2 as integer. +--- timestamp - The timestamp for the command as a string. +--- data - Raw MIDI Data as Hex String. +--- isVirtual - true if Virtual MIDI Source otherwise false . +--- dataByte1 - Data Byte 1 as integer. +--- dataByte2 - Data Byte 2 as integer. +--- timestamp - The timestamp for the command as a string. +--- data - Raw MIDI Data as Hex String. +--- isVirtual - true if Virtual MIDI Source otherwise false . +--- Example Usage: midiDevice = hs . midi . new ( hs . midi . devices ()[ 3 ]) midiDevice : callback ( function ( +--- object , deviceName , commandType , description , metadata ) print ( "object: " .. tostring ( object )) print ( +--- "deviceName: " .. deviceName ) print ( "commandType: " .. commandType ) print ( "description: " .. description ) +--- print ( "metadata: " .. hs . inspect ( metadata )) end ) ``` +---@param callbackFn function +---@return hs.midi +function midi:callback(callbackFn) end + +--- Returns the display name of a +--- hs.midi +--- object. +---@return string +function midi:displayName() end + +--- Sends an Identity Request message to the +--- hs.midi +--- device. You can use +--- hs.midi:callback() +--- to receive the +--- systemExclusive +--- response. +--- +--- Note: Example Usage: +--- midiDevice +--- = +--- hs +--- . +--- midi +--- . +--- new +--- ( +--- hs +--- . +--- midi +--- . +--- devices +--- ()[ +--- 3 +--- ]) +--- midiDevice +--- : +--- callback +--- ( +--- function +--- ( +--- object +--- , +--- deviceName +--- , +--- commandType +--- , +--- description +--- , +--- metadata +--- ) +--- print +--- ( +--- "object: " +--- .. +--- tostring +--- ( +--- object +--- )) +--- print +--- ( +--- "deviceName: " +--- .. +--- deviceName +--- ) +--- print +--- ( +--- "commandType: " +--- .. +--- commandType +--- ) +--- print +--- ( +--- "description: " +--- .. +--- description +--- ) +--- print +--- ( +--- "metadata: " +--- .. +--- hs +--- . +--- inspect +--- ( +--- metadata +--- )) +--- end +--- ) +--- midiDevice +--- : +--- identityRequest +--- () +--- ``` +---@return none +function midi:identityRequest() end + +--- Returns the online status of a +--- hs.midi +--- object. +---@return boolean +function midi:isOnline() end + +--- Returns +--- true +--- if an +--- hs.midi +--- object is virtual, otherwise +--- false +--- . +---@return boolean +function midi:isVirtual() end + +--- Returns the manufacturer name of a +--- hs.midi +--- object. +---@return string +function midi:manufacturer() end + +--- Returns the model name of a +--- hs.midi +--- object. +---@return string +function midi:model() end + +--- Returns the name of a +--- hs.midi +--- object. +---@return string +function midi:name() end + +--- Sends a command to the +--- hs.midi +--- object. +--- +--- Note: note - The note number for the command. Must be between 0 and 127. Defaults to 0. +--- velocity - The velocity for the command. Must be between 0 and 127. Defaults to 0. +--- channel - The channel for the command. Must be a number between 0 and 16. Defaults to 0, which sends +--- the command to All Channels. +--- note - The note number for the command. Must be between 0 and 127. Defaults to 0. +--- velocity - The velocity for the command. Must be between 0 and 127. Defaults to 0. +--- channel - The channel for the command. Must be a number between 0 and 16. Defaults to 0, which sends +--- the command to All Channels. +--- note - The note number for the command. Must be between 0 and 127. Defaults to 0. +--- pressure - Key pressure of the polyphonic key pressure message. In the range 0-127. Defaults to 0. +--- channel - The channel for the command. Must be a number between 0 and 16. Defaults to 0, which sends +--- the command to All Channels. +--- controllerNumber - The MIDI control number for the command. Defaults to 0. +--- controllerValue - The controllerValue of the command. Only the lower 7-bits of this are used. Defaults to 0. +--- channel - The channel for the command. Must be a number between 0 and 16. Defaults to 0, which sends +--- the command to All Channels. +--- fourteenBitValue - The 14-bit value of the command. Must be between 0 and 16383. Defaults to 0. +--- fourteenBitCommand must be true . +--- fourteenBitCommand - true if the command contains 14-bit value data otherwise, false . controllerValue will be +--- ignored if this is set to true . +--- programNumber - The program (aka patch) number. From 0-127. Defaults to 0. +--- channel - The channel for the command. Must be a number between 0 and 16. Defaults to 0, which sends +--- the command to All Channels. +--- pressure - Key pressure of the channel pressure message. In the range 0-127. Defaults to 0. +--- channel - The channel for the command. Must be a number between 0 and 16. Defaults to 0, which sends +--- the command to All Channels. +--- pitchChange - A 14-bit value indicating the pitch bend. Center is 0x2000 (8192). Valid range is from +--- 0-16383. Defaults to 0. +--- channel - The channel for the command. Must be a number between 0 and 16. Defaults to 0, which sends +--- the command to All Channels. +--- Example Usage: midiDevice = hs . midi . new ( hs . midi . devices ()[ 1 ]) midiDevice : sendCommand ( "noteOn" , { +--- [ "note" ] = 72 , [ "velocity" ] = 50 , [ "channel" ] = 0 , }) hs . timer . usleep ( 500000 ) midiDevice : +--- sendCommand ( "noteOn" , { [ "note" ] = 74 , [ "velocity" ] = 50 , [ "channel" ] = 0 , }) hs . timer . usleep ( +--- 500000 ) midiDevice : sendCommand ( "noteOn" , { [ "note" ] = 76 , [ "velocity" ] = 50 , [ "channel" ] = 0 , }) +--- midiDevice : sendCommand ( "pitchWheelChange" , { [ "pitchChange" ] = 1000 , [ "channel" ] = 0 , }) hs . timer . +--- usleep ( 100000 ) midiDevice : sendCommand ( "pitchWheelChange" , { [ "pitchChange" ] = 2000 , [ "channel" ] = 0 , +--- }) hs . timer . usleep ( 100000 ) midiDevice : sendCommand ( "pitchWheelChange" , { [ "pitchChange" ] = 3000 , [ +--- "channel" ] = 0 , }) ``` +---@param commandType hs.midi.commandTypes +---@param metadata table +---@return boolean +function midi:sendCommand(commandType, metadata) end + +--- Sends a System Exclusive Command to the +--- hs.midi +--- object. +--- +--- Note: Example Usage: midiDevice : sendSysex ( "f07e7f06 01f7" ) ``` +---@param command string +---@return none +function midi:sendSysex(command) end + +--- Set or display whether or not the MIDI device should synthesize audio on your computer. +---@param value any +---@return boolean +function midi:synthesize(value) end + +-- ------------------------------------------------------------ +-- hs.milight +-- ------------------------------------------------------------ + +---@class hs.milight +hs.milight = {} + +---@class milight +local milight = {} + +--- Specifies the maximum brightness value that can be used. Defaults to 25 +---@type any +hs.milight.maxBrightness = nil + +--- Specifies the minimum brightness value that can be used. Defaults to 0 +---@type any +hs.milight.minBrightness = nil + +--- Creates a new bridge object, which will be connected to the supplied IP address and port +--- +--- Note: You can not use 255.255.255.255 as the IP address, to do so requires elevated privileges for the Hammerspoon +--- process +---@param ip string +---@param port? number|nil +---@return bridge +function hs.milight.new(ip, port) end + +--- Deletes an +--- hs.milight +--- object +---@return any +function milight:delete() end + +--- Cycles through the disco modes +---@return boolean +function milight:disco() end + +--- Sends a command to the bridge +--- +--- Note: This is a low level command, you typically should use a specific method for the operation you want to perform +---@param cmd hs.milight.cmd +---@param value? any +---@return boolean +function milight:send(cmd, value) end + +--- Sets brightness for the specified zone +---@param zone number +---@param value number +---@return number +function milight:zoneBrightness(zone, value) end + +--- Sets RGB color for the specified zone +--- +--- Note: The color value is not a normal RGB colour, but rather a lookup in an internal table in the light hardware. +--- While any number between 0 and 255 is valid, there are some useful values worth knowing: +--- 00 - Violet +--- 16 - Royal Blue +--- 32 - Baby Blue +--- 48 - Aqua +--- 64 - Mint Green +--- 80 - Seafoam Green +--- 96 - Green +--- 112 - Lime Green +--- 128 - Yellow +--- 144 - Yellowy Orange +--- 160 - Orange +--- 176 - Red +--- 194 - Pink +--- 210 - Fuchsia +--- 226 - Lilac +--- 240 - Lavender +---@param zone number +---@param value number +---@return boolean +function milight:zoneColor(zone, value) end + +--- Turns off the specified zone +---@param zone number +---@return boolean +function milight:zoneOff(zone) end + +--- Turns on the specified zone +---@param zone number +---@return boolean +function milight:zoneOn(zone) end + +--- Sets the specified zone to white +---@param zone number +---@return boolean +function milight:zoneWhite(zone) end + +-- ------------------------------------------------------------ +-- hs.mjomatic +-- ------------------------------------------------------------ + +---@class hs.mjomatic +hs.mjomatic = {} + +--- Applies a configuration to the currently open windows +--- +--- Note: An example use: +--- mjomatic +--- . +--- go +--- ({ +--- "CCCCCCCCCCCCCiiiiiiiiiii # <-- The windowgram, it defines the shapes and positions of windows" +--- , +--- "CCCCCCCCCCCCCiiiiiiiiiii" +--- , +--- "SSSSSSSSSSSSSiiiiiiiiiii" +--- , +--- "SSSSSSSSSSSSSYYYYYYYYYYY" +--- , +--- "SSSSSSSSSSSSSYYYYYYYYYYY" +--- , +--- "" +--- , +--- "C Google Chrome # <-- window C has application():title() 'Google Chrome'" +--- , +--- "i iTerm" +--- , +--- "Y YoruFukurou" +--- , +--- "S Sublime Text 2" +--- }) +---@param cfg table +---@return any +function hs.mjomatic.go(cfg) end + +-- ------------------------------------------------------------ +-- hs.mouse +-- ------------------------------------------------------------ + +---@class hs.mouse +hs.mouse = {} + +--- Get or set the absolute co-ordinates of the mouse pointer +--- +--- Note: If no parameters are supplied, the current position will be returned. If a point table parameter is supplied, +--- the mouse pointer position will be set and the new co-ordinates returned +---@param point any +---@return point +function hs.mouse.absolutePosition(point) end + +--- Gets the total number of mice connected to your system. +--- +--- Note: This function leverages code from ManyMouse . +--- This function considers any mouse labelled as "Apple Internal Keyboard / Trackpad" to be an internal mouse. +---@param includeInternal boolean +---@return number +function hs.mouse.count(includeInternal) end + +--- Gets the identifier of the current mouse cursor type. +--- +--- Note: Possible values include: arrowCursor, contextualMenuCursor, closedHandCursor, crosshairCursor, +--- disappearingItemCursor, dragCopyCursor, dragLinkCursor, IBeamCursor, operationNotAllowedCursor, pointingHandCursor, +--- resizeDownCursor, resizeLeftCursor, resizeLeftRightCursor, resizeRightCursor, resizeUpCursor, resizeUpDownCursor, +--- IBeamCursorForVerticalLayout or unknown if the cursor type cannot be determined. +--- This function can also return daVinciResolveHorizontalArrows, when hovering over mouse-draggable text-boxes in +--- DaVinci Resolve. This is determined using the "hotspot" value of the cursor. +---@return string +function hs.mouse.currentCursorType() end + +--- Returns a table containing the current mouse buttons being pressed +--- at this instant +--- . +--- +--- Note: This function is a wrapper to hs.eventtap.checkMouseButtons +--- This is an instantaneous poll of the current mouse buttons, not a callback. +---@return table +function hs.mouse.getButtons() end + +--- Gets the screen the mouse pointer is on +---@return screen|nil +function hs.mouse.getCurrentScreen() end + +--- Gets the co-ordinates of the mouse pointer, relative to the screen it is on +--- +--- Note: The co-ordinates returned by this function are relative to the top left pixel of the screen the mouse is on +--- (see hs.mouse.getAbsolutePosition if you need the location in the full desktop space) +---@return point|nil +function hs.mouse.getRelativePosition() end + +--- Gets the names of any mice connected to the system. +--- +--- Note: This function leverages code from ManyMouse . +---@return table +function hs.mouse.names() end + +--- Gets the system-wide direction of scrolling +---@return string +function hs.mouse.scrollDirection() end + +--- Sets the co-ordinates of the mouse pointer, relative to a screen +---@param point table +---@param screen? hs.screen|nil +---@return any +function hs.mouse.setRelativePosition(point, screen) end + +--- Gets/Sets the current system mouse tracking speed setting +--- +--- Note: This is represented in the System Preferences as the "Tracking speed" setting for mice +--- 0.0, 0.125, 0.5, 0.6875, 0.875, 1.0, 1.5, 2.0, 2.5, 3.0 +--- Note that changes to this value will not be noticed immediately by macOS +---@param speed number|nil +---@return number +function hs.mouse.trackingSpeed(speed) end + +-- ------------------------------------------------------------ +-- hs.network +-- ------------------------------------------------------------ + +---@class hs.network +hs.network = {} + +--- Returns a list of the IPv4 and IPv6 addresses for the specified interfaces, or all interfaces if no arguments are +--- given. +--- +--- Note: The order of the IP addresses returned is undefined. +--- If no arguments are provided, then this function returns the same results as hs.host.addresses , but does not block. +---@param interface_list table +---@return table +function hs.network.addresses(interface_list) end + +--- Returns details about the specified interface or the primary interface if no interface is specified. +--- +--- Note: When determining the primary interface, the favorIPv6 flag only determines interface search order. If you +--- specify true for this flag, but no primary IPv6 interface exists (i.e. your DHCP server only provides an IPv4 +--- address an IPv6 is limited to local only traffic), then the primary IPv4 interface will be used instead. +---@param interface | favorIPv6 any +---@return table +function hs.network.interfaceDetails(interface | favorIPv6) end + +--- Returns the user defined name for the specified interface or the primary interface if no interface is specified. +--- +--- Note: Only interfaces which show up in the System Preferences Network panel will have a user defined name. +--- When determining the primary interface, the favorIPv6 flag only determines interface search order. If you specify +--- true for this flag, but no primary IPv6 interface exists (i.e. your DHCP server only provides an IPv4 address an +--- IPv6 is limited to local only traffic), then the primary IPv4 interface will be used instead. +---@param interface | favorIPv6 any +---@return string +function hs.network.interfaceName(interface | favorIPv6) end + +--- Returns a list of interfaces currently active for the system. +--- +--- Note: The names of the interfaces returned by this function correspond to the interface's BSD name, not the user +--- defined name that shows up in the System Preferences's Network panel. +--- This function returns all interfaces, even ones used by the system that are not directly manageable by the user. +---@return table +function hs.network.interfaces() end + +--- Returns the names of the primary IPv4 and IPv6 interfaces. +--- +--- Note: The IPv4 and IPv6 interface names are often, but not always, the same. +---@return ipv4Interface +---@return ipv6Interface +function hs.network.primaryInterfaces() end + +-- ------------------------------------------------------------ +-- hs.network.configuration +-- ------------------------------------------------------------ + +---@class hs.network.configuration +hs.network.configuration = {} + +---@class configuration +local configuration = {} + +--- Opens a session to the dynamic store maintained by the System Configuration server. +---@return storeObject +function hs.network.configuration.open() end + +--- Returns the name of the computer as specified in the Sharing Preferences, and its string encoding +--- +--- Note: You can also retrieve this information as key-value pairs with hs.network.configuration:contents("Setup:/System") +---@return name +---@return encoding +function configuration:computerName() end + +--- Returns the name of the user currently logged into the system, including the users id and primary group id +--- +--- Note: You can also retrieve this information as key-value pairs with hs.network.configuration:contents("State:/Users/ConsoleUser") +---@return name +---@return uid +---@return gid +function configuration:consoleUser() end + +--- Return the contents of the store for the specified keys or keys matching the specified pattern(s) +--- +--- Note: if no parameters are provided, then all key-value pairs in the dynamic store are returned. +---@param keys string +---@param pattern boolean +---@return table +function configuration:contents(keys, pattern) end + +--- Return the DHCP information for the specified service or the primary service if no parameter is specified. +--- +--- Note: a list of possible Service ID's can be retrieved with hs.network.configuration:contents("Setup:/Network/Global/IPv4") +--- generates an error if the service ID is invalid or was not assigned an IP address via DHCP. +---@param serviceID string|nil +---@return table +function configuration:dhcpInfo(serviceID) end + +--- Returns the current local host name for the computer +--- +--- Note: You can also retrieve this information as key-value pairs with hs.network.configuration:contents("Setup:/System") +---@return name +function configuration:hostname() end + +--- Return the keys in the dynamic store which match the specified pattern +---@param keypattern string +---@return table +function configuration:keys(keypattern) end + +--- Returns the current location identifier +--- +--- Note: You can also retrieve this information as key-value pairs with hs.network.configuration:contents("Setup:") +--- If you have different locations defined in the Network preferences panel, this can be used to determine the +--- currently active location. +---@return location +function configuration:location() end + +--- Returns all configured locations +---@return table +function configuration:locations() end + +--- Specify the key(s) or key pattern(s) to monitor for changes. +--- +--- Note: if no parameters are provided, then all key-value pairs in the dynamic store are monitored for changes. +---@param keys string +---@param pattern boolean +---@return storeObject +function configuration:monitorKeys(keys, pattern) end + +--- Returns information about the currently active proxies, if any +--- +--- Note: You can also retrieve this information as key-value pairs with hs.network.configuration:contents("State:/Network/Global/Proxies") +---@return table +function configuration:proxies() end + +--- Set or remove the callback function for a store object +--- +--- Note: The callback function will be invoked each time a monitored key changes value and the callback function +--- should accept two parameters: the storeObject itself, and an array of the keys which contain values that have +--- changed. +--- This method just sets the callback function. You specify which keys to watch with +--- hs.network.configuration:monitorKeys and start or stop the watcher with hs.network.configuration:start or +--- hs.network.configuration:stop +---@param function any +---@return storeObject +function configuration:setCallback(function) end + +--- Switches to a new location +---@param location string +---@return boolean +function configuration:setLocation(location) end + +--- Starts watching the store object for changes to the monitored keys and invokes the callback function (if any) when +--- a change occurs. +--- +--- Note: The callback function should be specified with hs.network.configuration:setCallback and the keys to monitor +--- should be specified with hs.network.configuration:monitorKeys . +---@return storeObject +function configuration:start() end + +--- Stops watching the store object for changes. +---@return storeObject +function configuration:stop() end + +-- ------------------------------------------------------------ +-- hs.network.host +-- ------------------------------------------------------------ + +---@class hs.network.host +hs.network.host = {} + +---@class host +local host = {} + +--- Get IP addresses for the hostname specified. +--- +--- Note: If no callback function is provided, the resolution occurs in a blocking manner which may be noticeable when +--- network access is slow or erratic. +--- If a callback function is provided, this function acts as a constructor, returning a host object and the callback +--- function will be invoked when resolution is complete. The callback function should take two parameters: the string +--- "addresses", indicating that an address resolution occurred, and a table containing the IP addresses identified. +--- Generates an error if network access is currently disabled or the hostname is invalid. +---@param name string +---@param fn? function|nil +---@return table|hostObject +function hs.network.host.addressesForHostname(name, fn) end + +--- Get hostnames for the IP address specified. +--- +--- Note: If no callback function is provided, the resolution occurs in a blocking manner which may be noticeable when +--- network access is slow or erratic. +--- If a callback function is provided, this function acts as a constructor, returning a host object and the callback +--- function will be invoked when resolution is complete. The callback function should take two parameters: the string +--- "names", indicating that hostname resolution occurred, and a table containing the hostnames identified. +--- Generates an error if network access is currently disabled or the IP address is invalid. +---@param address string +---@param fn? function|nil +---@return table|hostObject +function hs.network.host.hostnamesForAddress(address, fn) end + +--- Get the reachability status for the IP address specified. +--- +--- Note: If no callback function is provided, the resolution occurs in a blocking manner which may be noticeable when +--- network access is slow or erratic. +--- If a callback function is provided, this function acts as a constructor, returning a host object and the callback +--- function will be invoked when resolution is complete. The callback function should take two parameters: the string +--- "reachability", indicating that reachability was determined, and the numeric representation of the address +--- reachability status. +--- Generates an error if network access is currently disabled or the IP address is invalid. +--- The numeric representation is made up from a combination of the flags defined in hs.network.reachability.flags . +--- Performs the same reachability test as hs.network.reachability.forAddress . +---@param address string +---@param fn? function|nil +---@return number|hostObject +function hs.network.host.reachabilityForAddress(address, fn) end + +--- Get the reachability status for the IP address specified. +--- +--- Note: If no callback function is provided, the resolution occurs in a blocking manner which may be noticeable when +--- network access is slow or erratic. +--- If a callback function is provided, this function acts as a constructor, returning a host object and the callback +--- function will be invoked when resolution is complete. The callback function should take two parameters: the string +--- "reachability", indicating that reachability was determined, and the numeric representation of the hostname +--- reachability status. +--- Generates an error if network access is currently disabled or the IP address is invalid. +--- The numeric representation is made up from a combination of the flags defined in hs.network.reachability.flags . +--- Performs the same reachability test as hs.network.reachability.forHostName . +---@param name number +---@param fn? function|nil +---@return number|hostObject +function hs.network.host.reachabilityForHostname(name, fn) end + +--- Cancels an in-progress asynchronous host resolution. +--- +--- Note: This method has no effect if the resolution has already completed. +---@return hostObject +function host:cancel() end + +--- Returns whether or not resolution is still in progress for an asynchronous query. +---@return boolean +function host:isRunning() end + +-- ------------------------------------------------------------ +-- hs.network.ping +-- ------------------------------------------------------------ + +---@class hs.network.ping +hs.network.ping = {} + +---@class ping +local ping = {} + +--- Test server availability by pinging it with ICMP Echo Requests. +--- +--- Note: For convenience, you can call this constructor as hs.network.ping(server, ...) +--- the full ping process will take at most count * interval + timeout seconds from didStart to didFinish . +--- the default callback function, if fn is not specified, prints the results of each echo reply as they are received +--- to the Hammerspoon console and a summary once completed. The output should be familiar to anyone who has used ping +--- from the command line. +--- object - the ping object the callback is for +--- message - the message to the callback, in this case "didStart" +--- object - the ping object the callback is for +--- message - the message to the callback, in this case "didFail" +--- error - a string containing the error message that has occurred +--- object - the ping object the callback is for +--- message - the message to the callback, in this case "sendPacketFailed" +--- sequenceNumber - the sequence number of the ICMP packet which has failed to send +--- error - a string containing the error message that has occurred +--- object - the ping object the callback is for +--- message - the message to the callback, in this case "receivedPacket" +--- sequenceNumber - the sequence number of the ICMP packet received +--- object - the ping object the callback is for +--- message - the message to the callback, in this case "didFinish" +---@param server string +---@param count number|nil +---@param interval number|nil +---@param timeout number|nil +---@param class any +---@param fn function +---@return pingObject +function hs.network.ping.ping(server, count, interval, timeout, class, fn) end + +--- Returns a string containing the resolved IPv4 or IPv6 address this pingObject is sending echo requests to. +---@return string +function ping:address() end + +--- Cancels an in progress ping process, terminating it immediately +--- +--- Note: the didFinish message will be sent to the callback function as its final message. +---@return none +function ping:cancel() end + +--- Get or set the number of ICMP Echo Requests that will be sent by the ping process +---@param count number|nil +---@return number|pingObject|nil +function ping:count(count) end + +--- Returns whether or not the ping process is currently paused. +---@return boolean +function ping:isPaused() end + +--- Returns whether or not the ping process is currently active. +--- +--- Note: This method will return false only if the ping process has finished sending all echo requests or if it has +--- been cancelled with hs.network.ping:cancel . To determine if the process is currently sending out echo requests, +--- see hs.network.ping:isPaused . +---@return boolean +function ping:isRunning() end + +--- Returns a table containing information about the ICMP Echo packets sent by this pingObject. +--- +--- Note: Sequence numbers start at 0 while Lua array tables are indexed starting at 1. If you do not specify a +--- sequenceNumber to this method, index 1 of the array table returned will contain a table describing the ICMP Echo +--- packet with sequence number 0, index 2 will describe the ICMP Echo packet with sequence number 1, etc. +--- sent - a number specifying the time at which the echo request for this packet was sent. This number is the number +--- of seconds since January 1, 1970 at midnight, GMT, and is a floating point number, so you should use math.floor on +--- this number before using it as an argument to Lua's os.date function. +--- recv - a number specifying the time at which the echo reply for this packet was received. This number is the number +--- of seconds since January 1, 1970 at midnight, GMT, and is a floating point number, so you should use math.floor on +--- this number before using it as an argument to Lua's os.date function. +--- checksum - The ICMP packet checksum used to ensure data integrity. +--- code - ICMP Control Message Code. Should always be 0. +--- identifier - The ICMP Identifier generated internally for matching request and reply packets. +--- payload - A string containing the ICMP payload for this packet. This has been constructed to cause the ICMP packet +--- to be exactly 64 bytes to match the convention for ICMP Echo Requests. +--- sequenceNumber - The ICMP Sequence Number for this packet. +--- type - ICMP Control Message Type. For ICMPv4, this will be 0 if a reply has been received or 8 no reply has been +--- received yet. For ICMPv6, this will be 129 if a reply has been received or 128 if no reply has been received yet. +--- _raw - A string containing the ICMP packet as raw data. +---@param sequenceNumber number|nil +---@return table +function ping:packets(sequenceNumber) end + +--- Pause an in progress ping process. +---@return pingObject|nil +function ping:pause() end + +--- Resume an in progress ping process, if it has been paused. +---@return pingObject|nil +function ping:resume() end + +--- Returns the number of ICMP Echo Requests which have been sent. +---@return number +function ping:sent() end + +--- Returns the hostname or ip address string given to the +--- hs.network.ping.ping +--- constructor. +---@return string +function ping:server() end + +--- Set or remove the callback function for the pingObject. +--- +--- Note: Because the ping process begins immediately upon creation with the hs.network.ping.ping constructor, it is +--- preferable to assign the callback with the constructor itself. +--- This method is provided as a means of changing the callback based on other events (a change in the current network +--- or location, perhaps.) +--- If you truly wish to create a pingObject with no callback, you will need to do something like +--- hs.network.ping.ping(...):setCallback(function() end) . +---@param fn function|nil +---@return pingObject +function ping:setCallback(fn) end + +--- Returns a string containing summary information about the ping process. +--- +--- Note: The summary string will look similar to the following: +--- --- hostname ping statistics +--- 5 packets transmitted, 5 packets received, 0.0 packet loss +--- round-trip min/avg/max = 2.282/4.133/4.926 ms +--- The number of packets received will match the number that has currently been sent, not necessarily the value +--- returned by hs.network.ping:count . +---@return string +function ping:summary() end + +-- ------------------------------------------------------------ +-- hs.network.ping.echoRequest +-- ------------------------------------------------------------ + +---@class hs.network.ping.echoRequest +hs.network.ping.echoRequest = {} + +---@class echoRequest +local echoRequest = {} + +--- Creates a new ICMP Echo Request object for the server specified. +--- +--- Note: This constructor returns a lower-level object than the hs.network.ping.ping constructor and is more difficult +--- to use. It is recommended that you use this constructor only if hs.network.ping.ping is not sufficient for your +--- needs. +--- For convenience, you can call this constructor as hs.network.ping.echoRequest(server) +---@param server string +---@return echoRequestObject +function hs.network.ping.echoRequest.echoRequest(server) end + +--- Get or set the address family the echoRequestObject should communicate with. +--- +--- Note: Setting this value to "IPv6" or "IPv4" will cause the echoRequestObject to attempt to resolve the server's +--- name into an IPv6 address or an IPv4 address and communicate via ICMPv6 or ICMP(v4) when the +--- hs.network.ping.echoRequest:start method is invoked. A callback with the message "didFail" will occur if the +--- server could not be resolved to an address in the specified family. +--- If this value is set to "any", then the first address which is discovered for the server's name will determine +--- whether ICMPv6 or ICMP(v4) is used, based upon the family of the address. +--- Setting a value with this method will have no immediate effect on an echoRequestObject which has already been +--- started with hs.network.ping.echoRequest:start . You must first stop and then restart the object for any change to +--- have an effect. +---@param family string|nil +---@return echoRequestObject +function echorequest:acceptAddressFamily(family) end + +--- Returns a string representation for the server's IP address, or a boolean if address resolution has not completed +--- yet. +---@return string|boolean|nil +function echorequest:hostAddress() end + +--- Returns the host address family currently in use by this echoRequestObject. +---@return string +function echorequest:hostAddressFamily() end + +--- Returns the name of the target host as provided to the echoRequestObject's constructor +---@return string +function echorequest:hostName() end + +--- Returns the identifier number for the echoRequestObject. +--- +--- Note: ICMP Echo Replies which include this identifier will generate a "receivedPacket" message to the object +--- callback, while replies which include a different identifier will generate a "receivedUnexpectedPacket" message. +---@return number +function echorequest:identifier() end + +--- Returns a boolean indicating whether or not this echoRequestObject is currently listening for ICMP Echo Replies. +---@return boolean +function echorequest:isRunning() end + +--- The sequence number that will be used for the next ICMP packet sent by this object. +--- +--- Note: ICMP Echo Replies which are expected by this object should always be less than this number, with the caveat +--- that this number is a 16-bit integer which will wrap around to 0 after sending a packet with the sequence number +--- 65535. +--- Per the comments in Apple's SimplePing.m file: Why 120? Well, if we send one ping per second, 120 is 2 minutes, +--- which is the standard "max time a packet can bounce around the Internet" value. +---@return number +function echorequest:nextSequenceNumber() end + +--- Get or set whether or not the callback should receive all unexpected packets or only those which carry our +--- identifier. +--- +--- Note: By default, a valid packet (i.e. with a valid checksum) which does not contain our identifier is ignored +--- since it was not intended for our receiver. Only corrupt or packets with our identifier but that were otherwise +--- unexpected will generate a "receivedUnexpectedPacket" callback message. +--- This method optionally allows the echoRequestObject to receive all incoming packets, even ones which are expected +--- by another process or echoRequestObject. +--- If you wish to examine ICMPv6 router advertisement and neighbor discovery packets, you should set this property to +--- true. Note that this module does not provide the necessary tools to decode these packets at present, so you will +--- have to decode them yourself if you wish to examine their contents. +---@param state function|nil +---@return boolean|echoRequestObject +function echorequest:seeAllUnexpectedPackets(state) end + +--- Sends a single ICMP Echo Request packet. +--- +--- Note: By convention, unless you are trying to test for specific network fragmentation or congestion problems, ICMP +--- Echo Requests are generally 64 bytes in length (this includes the 8 byte header, giving 56 bytes of payload data). +--- If you do not specify a payload, a default payload which will result in a packet size of 64 bytes is constructed. +---@param payload string|nil +---@return echoRequestObject|boolean|nil +function echorequest:sendPayload(payload) end + +--- Set or remove the object callback function +--- +--- Note: object - the echoRequestObject itself +--- message - the message to the callback, in this case "didStart" +--- address - a string representation of the IPv4 or IPv6 address of the server specified to the constructor. +--- object - the echoRequestObject itself +--- message - the message to the callback, in this case "didFail" +--- error - a string describing the error that occurred. +--- When this message is received, you do not need to call hs.network.ping.echoRequest:stop -- the object will already +--- have been stopped. +--- object - the echoRequestObject itself +--- message - the message to the callback, in this case "sendPacket" +--- icmp - an ICMP packet table representing the packet which has been sent as described in the header of this module's +--- documentation. +--- seq - the sequence number for this packet. Sequence numbers always start at 0 and increase by 1 every time the +--- hs.network.ping.echoRequest:sendPayload method is called. +--- object - the echoRequestObject itself +--- message - the message to the callback, in this case "sendPacketFailed" +--- icmp - an ICMP packet table representing the packet which was to be sent. +--- seq - the sequence number for this packet. +--- error - a string describing the error that occurred. +--- Unlike "didFail", the echoRequestObject is not stopped when this message occurs; you can try to send another +--- payload if you wish without restarting the object first. +--- object - the echoRequestObject itself +--- message - the message to the callback, in this case "receivedPacket" +--- icmp - an ICMP packet table representing the packet received. +--- seq - the sequence number for this packet. +--- object - the echoRequestObject itself +--- message - the message to the callback, in this case "receivedUnexpectedPacket" +--- icmp - an ICMP packet table representing the packet received. +--- the ICMP packet is corrupt or truncated and cannot be parsed +--- the ICMP Identifier does not match ours and the sequence number is not one we have sent +--- the ICMP type does not match an ICMP Echo Reply +--- When using IPv6, this is especially common because IPv6 uses ICMP for network management functions like Router +--- Advertisement and Neighbor Discovery. +--- In general, it is reasonably safe to ignore these messages, unless you are having problems receiving anything else, +--- in which case it could indicate problems on your network that need addressing. +---@param fn function|nil +---@return echoRequestObject +function echorequest:setCallback(fn) end + +--- Start the echoRequestObject by resolving the server's address and start listening for ICMP Echo Reply packets. +---@return echoRequestObject +function echorequest:start() end + +--- Stop listening for ICMP Echo Reply packets with this object. +---@return echoRequestObject +function echorequest:stop() end + +-- ------------------------------------------------------------ +-- hs.network.reachability +-- ------------------------------------------------------------ + +---@class hs.network.reachability +hs.network.reachability = {} + +---@class reachability +local reachability = {} + +--- A table containing the numeric value for the possible flags returned by the +--- hs.network.reachability:status +--- method or in the +--- flags +--- parameter of the callback function. +---@type table +hs.network.reachability.flags[] = nil + +--- Returns a reachability object for the specified network address. +--- +--- Note: this object will reflect reachability status for any interface available on the computer. To check for +--- reachability from a specific interface, use hs.network.reachability.forAddressPair . +---@param address string +---@return reachabilityObject +function hs.network.reachability.forAddress(address) end + +--- Returns a reachability object for the specified network address from the specified localAddress. +--- +--- Note: this object will reflect reachability status for a specific interface on the computer. To check for +--- reachability from any interface, use hs.network.reachability.forAddress . +--- this constructor can be used to test for a specific local network. +---@param localAddress string +---@param remoteAddress string +---@return reachabilityObject +function hs.network.reachability.forAddressPair(localAddress, remoteAddress) end + +--- Returns a reachability object for the specified host. +--- +--- Note: this object will reflect reachability status for any interface available on the computer. +--- this constructor relies on the hostname being resolvable, possibly through DNS, Bonjour, locally defined, etc. +---@param hostName string +---@return reachabilityObject +function hs.network.reachability.forHostName(hostName) end + +--- Creates a reachability object for testing internet access +--- +--- Note: This is equivalent to hs.network.reachability.forAddress("0.0.0.0") +--- This constructor assumes that a default route for IPv4 traffic is sufficient to determine internet access. If you +--- are on an IPv6 only network which does not also provide IPv4 route mapping, you should probably use something along +--- the lines of hs.network.reachability.forAddress("::") instead. +---@return reachabilityObject +function hs.network.reachability.internet() end + +--- Creates a reachability object for testing IPv4 link local networking +--- +--- Note: This is equivalent to hs.network.reachability.forAddress("169.254.0.0") +--- hs.network.reachability.linklocal():status() & hs.network.reachability.flags.isDirect +--- If the internet is reachable, then this network will also be reachable by default -- use the isDirect flag to +--- ensure that the route is local. +---@return reachabilityObject +function hs.network.reachability.linkLocal() end + +--- Set or remove the callback function for a reachability object +--- +--- Note: The callback function will be invoked each time the status for the given reachability object changes. The +--- callback function should expect 2 arguments, the reachability object itself and a numeric representation of the +--- reachability flags, and should not return anything. +--- This method just sets the callback function. You can start or stop the watcher with hs.network.reachability:start +--- or hs.network.reachability:stop +---@param function any +---@return reachabilityObject +function reachability:setCallback(function) end + +--- Starts watching the reachability object for changes and invokes the callback function (if any) when a change occurs. +--- +--- Note: The callback function should be specified with hs.network.reachability:setCallback . +---@return reachabilityObject +function reachability:start() end + +--- Returns the reachability status for the object +--- +--- Note: The numeric representation is made up from a combination of the flags defined in +--- hs.network.reachability.flags . +---@return number +function reachability:status() end + +--- Returns a string representation of the reachability status for the object +--- +--- Note: This is included primarily for debugging, but may be more useful when you just want a quick look at the +--- reachability status for display or testing. +--- 't'|'-' indicates if the destination is reachable through a transient connection +--- 'R'|'-' indicates if the destination is reachable +--- 'c'|'-' indicates that a connection of some sort is required for the destination to be reachable +--- 'C'|'-' indicates if the destination requires a connection which will be initiated when traffic to the destination +--- is present +--- 'i'|'-' indicates if the destination requires a connection which will require user activity to initiate +--- 'D'|'-' indicates if the destination requires a connection which will be initiated on demand through the +--- CFSocketStream interface +--- 'l'|'-' indicates if the destination is actually a local address +--- 'd'|'-' indicates if the destination is directly connected +---@return string +function reachability:statusString() end + +--- Stops watching the reachability object for changes. +---@return reachabilityObject +function reachability:stop() end + +-- ------------------------------------------------------------ +-- hs.noises +-- ------------------------------------------------------------ + +---@class hs.noises +hs.noises = {} + +---@class noises +local noises = {} + +--- Creates a new listener for mouth noise recognition +---@param fn function +---@return listener +function hs.noises.new(fn) end + +--- Starts listening to the microphone and passing the audio to the recognizer. +---@return self +function noises:start() end + +--- Stops the listener from recording and analyzing microphone input. +---@return self +function noises:stop() end + +-- ------------------------------------------------------------ +-- hs.notify +-- ------------------------------------------------------------ + +---@class hs.notify +hs.notify = {} + +---@class notify +local notify = {} + +--- Convenience array of the possible activation types for a notification, and their reverse for reference. +---@type the[] +hs.notify.activationTypes[] = nil + +--- The string representation of the default notification sound. Use +--- hs.notify:soundName() +--- or set the +--- soundName +--- attribute in +--- hs:notify.new() +--- , to this constant, if you want to use the default sound +---@type string +hs.notify.defaultNotificationSound = nil + +--- A table containing the registered callback functions and their tags. +---@type table +hs.notify.registry[] = nil + +--- A value indicating whether or not a missing notification function tag should cause a warning. Defaults to +--- true +--- . +---@type any +hs.notify.warnAboutMissingFunctionTag = nil + +--- Returns a table containing notifications which have been delivered. +--- +--- Note: Only notifications which have been presented but not cleared, either by the user clicking on the +--- hs.notify:otherButtonTitle or through auto-withdrawal (see hs.notify:autoWithdraw for more details), will be in the +--- array returned. +--- You can use this function along with hs.notify:getFunctionTag to re=register necessary callback functions with +--- hs.notify.register when Hammerspoon is restarted. +--- Since notifications which the user has closed (or cancelled) do not trigger a callback, you can check this table +--- with a timer to see if the user has cleared a notification, e.g. +--- myNotification +--- = +--- hs +--- . +--- notify +--- . +--- new +--- (): +--- send +--- () +--- clearCheck +--- = +--- hs +--- . +--- timer +--- . +--- doEvery +--- ( +--- 10 +--- , +--- function +--- () +--- if +--- not +--- hs +--- . +--- fnutils +--- . +--- contains +--- ( +--- hs +--- . +--- notify +--- . +--- deliveredNotifications +--- (), +--- myNotification +--- ) +--- then +--- if +--- myNotification +--- : +--- activationType +--- () +--- == +--- hs +--- . +--- notify +--- . +--- activationTypes +--- . +--- none +--- then +--- print +--- ( +--- "You dismissed me!" +--- ) +--- else +--- print +--- ( +--- "A regular action occurred, so callback (if any) was invoked" +--- ) +--- end +--- clearCheck +--- : +--- stop +--- () +--- -- either way, no need to keep polling +--- clearCheck +--- = +--- nil +--- end +--- end +--- ) +---@return table +function hs.notify.deliveredNotifications() end + +--- Registers a function callback with the specified tag for a notification. The callback function will be invoked when +--- the user clicks on or interacts with a notification. +--- +--- Note: If a function is already registered with the specified tag, it is replaced by with the new one. +---@param tag string +---@param fn function +---@return id +function hs.notify.register(tag, fn) end + +--- Returns a table containing notifications which are scheduled but have not yet been delivered. +--- +--- Note: Once a notification has been delivered, it is moved to hs.notify.deliveredNotifications or removed, depending +--- upon the users action. +--- You can use this function along with hs.notify:getFunctionTag to re=register necessary callback functions with +--- hs.notify.register when Hammerspoon is restarted. +---@return table +function hs.notify.scheduledNotifications() end + +--- Unregisters a function callback so that it is no longer available as a callback when notifications corresponding to +--- the specified entry are interacted with. +---@param id|tag any +---@return any +function hs.notify.unregister(id|tag) end + +--- Unregisters all functions registered as callbacks. +--- +--- Note: This does not remove the notifications from the User Notification Center, it just removes their callback +--- function for when the user interacts with them. To remove all notifications, see hs.notify.withdrawAll and +--- hs.notify.withdrawAllScheduled +---@return any +function hs.notify.unregisterall() end + +--- Withdraw all delivered notifications from Hammerspoon +--- +--- Note: This will withdraw all notifications for Hammerspoon, including those not sent by this module or that linger +--- from a previous load of Hammerspoon. +---@return any +function hs.notify.withdrawAll() end + +--- Withdraw all scheduled notifications from Hammerspoon +---@return any +function hs.notify.withdrawAllScheduled() end + +--- Creates a new notification object +--- +--- Note: A function-tag is a string key which corresponds to a function stored in the hs.notify.registry table with +--- the hs.notify.register() function. +--- If a notification does not have a title attribute set, OS X will not display it, so by default it will be set to +--- "Notification". You can use the title key in the attributes table, or call hs.notify:title() before displaying the +--- notification to change this. +---@param fn function|nil +---@param attributes any +---@return notification +function hs.notify.new(fn, attributes) end + +--- Shorthand constructor to create and show simple notifications +--- +--- Note: All three textual parameters are required, though they can be empty strings +--- This function is really a shorthand for hs.notify.new(...):send() +--- Notifications created using this function will inherit the default withdrawAfter value, which is 5 seconds. To +--- produce persistent notifications you should use hs.notify.new() with a withdrawAfter attribute of 0. +---@param title string +---@param subTitle string +---@param information any +---@param tag? function +---@return notification +function hs.notify.show(title, subTitle, information, tag) end + +--- Get or set the label of a notification's action button +--- +--- Note: The affects of this method only apply if the user has set Hammerspoon notifications to Alert in the +--- Notification Center pane of System Preferences +--- This value is ignored if hs.notify:hasReplyButton is true. +---@param buttonTitle string|nil +---@return notificationObject|current-setting +function notify:actionButtonTitle(buttonTitle) end + +--- Returns how the notification was activated by the user. +---@return number +function notify:activationType() end + +--- Returns the date and time when a notification was delivered +--- +--- Note: You can turn epoch times into a human readable string or a table of date elements with the os.date() function. +---@return number +function notify:actualDeliveryDate() end + +--- Get or set additional actions which will be displayed for an alert type notification when the user clicks and holds +--- down the action button of the alert. +--- +--- Note: The additional items will be listed in a pop-up menu when the user clicks and holds down the mouse button in +--- the action button of the alert. +--- If the user selects one of the additional actions, hs.notify:activationType will equal +--- hs.notify.activationTypes.additionalActionClicked +--- See also hs.notify:additionalActivationAction +---@param actionsTable any +---@return notificationObject|table +function notify:additionalActions(actionsTable) end + +--- Return the additional action that the user selected from an alert type notification that has additional actions +--- available. +--- +--- Note: If the user selects one of the additional actions, hs.notify:activationType will equal +--- hs.notify.activationTypes.additionalActionClicked +--- See also hs.notify:additionalActions +---@return string|nil +function notify:additionalActivationAction() end + +--- Get or set whether a notification should be presented even if this overrides Notification Center's decision process. +--- +--- Note: This does not affect the return value of hs.notify:presented() -- that will still reflect the decision of the +--- Notification Center +--- Examples of why the users Notification Center would choose not to display a notification would be if Hammerspoon is +--- the currently focussed application, being attached to a projector, or the user having set Do Not Disturb. +--- if the notification was not created by this module, this method will return nil +---@param alwaysPresent any +---@return notificationObject|current-setting +function notify:alwaysPresent(alwaysPresent) end + +--- Get or set whether an alert notification should always show an alternate action menu. +--- +--- Note: This method has no effect unless the user has set Hammerspoon notifications to Alert in the Notification +--- Center pane of System Preferences. +--- hs.notify:additionalActions must also be used for this method to have any effect. +--- WARNING: This method uses a private API. It could break at any time. Please file an issue if it does. +---@param state boolean|nil +---@return notificationObject|boolean +function notify:alwaysShowAdditionalActions(state) end + +--- Get or set whether a notification should automatically withdraw once activated +--- +--- Note: This method has no effect if the user has set Hammerspoon notifications to Alert in the Notification Center +--- pane of System Preferences: clicking on either the action or other button will clear the notification automatically. +--- If a notification which was created before your last reload (or restart) of Hammerspoon and is clicked upon before +--- hs.notify has been loaded into memory, this setting will not be honored because the initial application delegate is +--- not aware of this option and is set to automatically withdraw all notifications which are acted upon. +--- if the notification was not created by this module, this method will return nil +---@param shouldWithdraw boolean|nil +---@return notificationObject|current-setting +function notify:autoWithdraw(shouldWithdraw) end + +--- Get or set a notification's content image. +--- +--- Note: See hs.image for details on how to specify or define an image +--- This method is only supported in OS X 10.9 or greater. A warning will be displayed in the console and the method +--- will be treated as a no-op if used on an unsupported system. +---@param image hs.image|nil +---@return notificationObject|current-setting +function notify:contentImage(image) end + +--- Returns whether the notification has been delivered to the Notification Center +---@return boolean +function notify:delivered() end + +--- Return the name of the function tag the notification will call when activated. +--- +--- Note: This tag should correspond to a function in hs.notify.registry and can be used to either add a replacement +--- with hs.notify.register(...) or remove it with hs.notify.unregister(...) +--- if the notification was not created by this module, this method will return nil +---@return functiontag +function notify:getFunctionTag() end + +--- Get or set the presence of an action button in a notification +--- +--- Note: The affects of this method only apply if the user has set Hammerspoon notifications to Alert in the +--- Notification Center pane of System Preferences +---@param hasButton boolean|nil +---@return notificationObject|current-setting +function notify:hasActionButton(hasButton) end + +--- Get or set whether an alert notification has a "Reply" button for additional user input. +--- +--- Note: This method has no effect unless the user has set Hammerspoon notifications to Alert in the Notification +--- Center pane of System Preferences. +--- hs.notify:hasActionButton must also be true or the "Reply" button will not be displayed. +--- If this is set to true, the action button will be "Reply" even if you have set another one with +--- hs.notify:actionButtonTitle . +---@param state boolean|nil +---@return notificationObject|boolean +function notify:hasReplyButton(state) end + +--- Get or set the informative text of a notification +---@param informativeText string|nil +---@return notificationObject|current-setting +function notify:informativeText(informativeText) end + +--- Get or set the label of a notification's other button +--- +--- Note: The affects of this method only apply if the user has set Hammerspoon notifications to Alert in the +--- Notification Center pane of System Preferences +--- Due to OSX limitations, it is NOT possible to get a callback for this button. +---@param buttonTitle string|nil +---@return notificationObject|current-setting +function notify:otherButtonTitle(buttonTitle) end + +--- Returns whether the users Notification Center decided to display the notification +--- +--- Note: Examples of why the users Notification Center would choose not to display a notification would be if +--- Hammerspoon is the currently focussed application, being attached to a projector, or the user having set Do Not +--- Disturb. +---@return boolean +function notify:presented() end + +--- Get the users input from an alert type notification with a reply button. +--- +--- Note: hs.notify:activationType will equal hs.notify.activationTypes.replied if the user clicked on the Reply button +--- and then clicks on Send. +--- See also hs.notify:hasReplyButton +---@return string|nil +function notify:response() end + +--- Set a placeholder string for alert type notifications with a reply button. +--- +--- Note: In macOS 10.13, this text appears so light that it is almost unreadable; so far no workaround has been found. +--- See also hs.notify:hasReplyButton +---@param string string|nil +---@return notificationObject|string +function notify:responsePlaceholder(string) end + +--- Schedules a notification for delivery in the future. +--- +--- Note: See also hs.notify:send() +--- hs.settings.dateFormat specifies a lua format string which can be used with os.date() to properly present the date +--- and time as a string for use with this method. +---@param date any +---@return notificationObject +function notify:schedule(date) end + +--- Delivers the notification immediately to the users Notification Center. +--- +--- Note: See also hs.notify:schedule() +--- If a notification has been modified, then this will resend it. +--- You can invoke this multiple times if you wish to repeat the same notification. +---@return notificationObject +function notify:send() end + +--- Set a notification's identification image (replace the Hammerspoon icon with a custom image) +--- +--- Note: See hs.image for details on how to specify or define an image +--- WARNING : This method uses a private API. It could break at any time. Please file an issue if it does +---@param image hs.image +---@param withBorder? boolean|nil +---@return notificationObject +function notify:setIdImage(image, withBorder) end + +--- Get or set the sound for a notification +--- +--- Note: Sounds will first be matched against the names of system sounds. If no matches can be found, they will then +--- be searched for in the following paths, in order: +--- ~/Library/Sounds +--- /Library/Sounds +--- /Network/Sounds +--- /System/Library/Sounds +---@param soundName string|nil +---@return notificationObject|current-setting +function notify:soundName(soundName) end + +--- Get or set the subtitle of a notification +---@param subtitleText string|nil +---@return notificationObject|current-setting +function notify:subTitle(subtitleText) end + +--- Get or set the title of a notification +---@param titleText string|nil +---@return notificationObject|current-setting +function notify:title(titleText) end + +--- Withdraws a delivered notification from the Notification Center. +---@return notificationObject +function notify:withdraw() end + +--- Get or set the number of seconds after which to automatically withdraw a notification +--- +--- Note: While this setting applies to both Banner and Alert styles of notifications, it is functionally meaningless +--- for Banner styles +--- A value of 0 will disable auto-withdrawal +--- if the notification was not created by this module, this method will return nil +---@param seconds number|nil +---@return notificationObject|number +function notify:withdrawAfter(seconds) end + +-- ------------------------------------------------------------ +-- hs.osascript +-- ------------------------------------------------------------ + +---@class hs.osascript +hs.osascript = {} + +--- Runs osascript code +---@param source any +---@param language string +---@return boolean +---@return object +---@return descriptor +function hs.osascript._osascript(source, language) end + +--- Runs AppleScript code +--- +--- Note: Use hs.osascript._osascript(source, "AppleScript") if you always want the result as a string, even when a +--- failure occurs +---@param source string +---@return boolean +---@return object +---@return descriptor +function hs.osascript.applescript(source) end + +--- Runs AppleScript code from a source file. +--- +--- Note: This function uses hs.osascript.applescript for execution. +--- Use hs.osascript._osascript(source, "AppleScript") if you always want the result as a string, even when a failure +--- occurs. However, this function can only take a string, and not a file name. +---@param fileName string +---@return boolean +---@return object +---@return descriptor +function hs.osascript.applescriptFromFile(fileName) end + +--- Runs JavaScript code +--- +--- Note: Use hs.osascript._osascript(source, "JavaScript") if you always want the result as a string, even when a +--- failure occurs +---@param source string +---@return boolean +---@return object +---@return descriptor +function hs.osascript.javascript(source) end + +--- Runs JavaScript code from a source file. +--- +--- Note: This function uses hs.osascript.javascript for execution. +--- Use hs.osascript._osascript(source, "JavaScript") if you always want the result as a string, even when a failure +--- occurs. However, this function can only take a string, and not a file name. +---@param fileName string +---@return boolean +---@return object +---@return descriptor +function hs.osascript.javascriptFromFile(fileName) end + +-- ------------------------------------------------------------ +-- hs.pasteboard +-- ------------------------------------------------------------ + +---@class hs.pasteboard +hs.pasteboard = {} + +--- An array whose elements are a table containing the content types for each element on the clipboard. +---@param name string +---@return table +function hs.pasteboard.allContentTypes(name) end + +--- Invokes callback when the specified pasteboard has changed or the timeout is reached. +--- +--- Note: This function can be used to capture the results of a copy operation issued programmatically with +--- hs.application:selectMenuItem or hs.eventtap.keyStroke without resorting to creating your own timers: +--- hs.eventtap.keyStroke({"cmd"}, "c", 0) -- or whatever method you want to trigger the copy +--- hs.pasteboard.callbackWhenChanged(5, function(state) +--- if state then +--- local contents = hs.pasteboard.getContents() +--- -- do what you want with contents +--- else +--- error("copy timeout") -- or whatever fallback you want when it times out +--- end +--- end) +---@param name string +---@param timeout number|nil +---@param callback function +function hs.pasteboard.callbackWhenChanged(name, timeout, callback) end + +--- Gets the number of times the pasteboard owner has changed +--- +--- Note: This is useful for seeing if the pasteboard has been updated by another process +---@param name string|nil +---@return number +function hs.pasteboard.changeCount(name) end + +--- Clear the contents of the pasteboard +---@param name string|nil +---@return any +function hs.pasteboard.clearContents(name) end + +--- Return the UTI strings of the data types for the first pasteboard item on the specified pasteboard. +---@param name string|nil +---@return table +function hs.pasteboard.contentTypes(name) end + +--- Deletes a custom pasteboard +--- +--- Note: You can not delete the system pasteboard, this function should only be called on custom pasteboards you have +--- created +---@param name string +---@return any +function hs.pasteboard.deletePasteboard(name) end + +--- Gets the contents of the pasteboard +---@param name string|nil +---@return string|nil +function hs.pasteboard.getContents(name) end + +--- Return the pasteboard type identifier strings for the specified pasteboard. +---@param name string|nil +---@return table +function hs.pasteboard.pasteboardTypes(name) end + +--- Returns all values in the first item on the pasteboard in a table that maps a UTI value to the raw data of the item +---@param name string +---@return table +function hs.pasteboard.readAllData(name) end + +--- Returns the first item on the pasteboard with the specified UTI. The data on the pasteboard must be encoded as a +--- keyed archive object conforming to NSKeyedArchiver. +--- +--- Note: NSKeyedArchiver specifies an architecture-independent format that is often used in OS X applications to store +--- and transmit objects between applications and when storing data to a file. It works by recording information about +--- the object types and key-value pairs which make up the objects being stored. +--- Only objects which have conversion functions built into Hammerspoon can be converted. A string representation +--- describing unrecognized types wil be returned. If you find a common data type that you believe may be of interest +--- to Hammerspoon users, feel free to contribute a conversion function or make a request in the Hammerspoon Google +--- group or GitHub site. +--- Some applications may define their own classes which can be archived. Hammerspoon will be unable to recognize +--- these types if the application does not make the object type available in one of its frameworks. You may be able +--- to load the necessary framework with package.loadlib("/Applications/appname.app/Contents/Frameworks/frameworkname.framework/frameworkname", "*") before retrieving the data, but a full representation of the data in Hammerspoon is probably not possible without support from the Application's developers. +---@param name string +---@param uti string +---@return any +function hs.pasteboard.readArchiverDataForUTI(name, uti) end + +--- Returns one or more +--- hs.drawing.color +--- tables from the clipboard, or nil if no compatible objects are present. +---@param name string +---@param all any +---@return hs.drawing.color table|array of hs.drawing.color tables +function hs.pasteboard.readColor(name, all) end + +--- Returns the first item on the pasteboard with the specified UTI as raw data +--- +--- Note: The UTI's of the items on the pasteboard can be determined with the hs.pasteboard.allContentTypes and +--- hs.pasteboard.contentTypes functions. +---@param name string +---@param uti string +---@return string +function hs.pasteboard.readDataForUTI(name, uti) end + +--- Returns one or more +--- hs.image +--- objects from the clipboard, or nil if no compatible objects are present. +---@param name string +---@param all any +---@return hs.image|array of hs.image objects +function hs.pasteboard.readImage(name, all) end + +--- Returns the first item on the pasteboard with the specified UTI as a property list item +--- +--- Note: The UTI's of the items on the pasteboard can be determined with the hs.pasteboard.allContentTypes and +--- hs.pasteboard.contentTypes functions. +--- Property lists consist only of certain types of data: tables, strings, numbers, dates, binary data, and Boolean +--- values. +---@param name string +---@param uti string +---@return any +function hs.pasteboard.readPListForUTI(name, uti) end + +--- Returns one or more +--- hs.sound +--- objects from the clipboard, or nil if no compatible objects are present. +---@param name string +---@param all any +---@return hs.sound|array of hs.sound objects +function hs.pasteboard.readSound(name, all) end + +--- Returns one or more strings from the clipboard, or nil if no compatible objects are present. +--- +--- Note: almost all string and styledText objects are internally convertible and will be available with this method as +--- well as hs.pasteboard.readStyledText . If the item is actually an hs.styledtext object, the string will be just the +--- text of the object. +---@param name string +---@param all any +---@return string|array of strings +function hs.pasteboard.readString(name, all) end + +--- Returns one or more +--- hs.styledtext +--- objects from the clipboard, or nil if no compatible objects are present. +--- +--- Note: almost all string and styledText objects are internally convertible and will be available with this method as +--- well as hs.pasteboard.readString . If the item on the clipboard is actually just a string, the hs.styledtext object +--- representation will have no attributes set +---@param name string +---@param all any +---@return hs.styledtext|array of hs.styledtext objects +function hs.pasteboard.readStyledText(name, all) end + +--- Returns one or more strings representing file or resource urls from the clipboard, or nil if no compatible objects +--- are present. +---@param name string +---@param all any +---@return string|array of strings representing file|resource urls +function hs.pasteboard.readURL(name, all) end + +--- Sets the contents of the pasteboard +---@param contents string +---@param name? string|nil +---@return boolean +function hs.pasteboard.setContents(contents, name) end + +--- Returns a table indicating what content types are available on the pasteboard. +--- +--- Note: if the item on the clipboard is actually just a string, the hs.styledtext object representation will have no +--- attributes set +--- if the item is actually an hs.styledtext object, the string representation will be the text without any attributes. +---@param name string +---@return table +function hs.pasteboard.typesAvailable(name) end + +--- Returns the name of a new pasteboard with a name that is guaranteed to be unique with respect to other pasteboards +--- on the computer. +--- +--- Note: to properly manage system resources, you should release the created pasteboard with +--- hs.pasteboard.deletePasteboard when you are certain that it is no longer necessary. +---@return string +function hs.pasteboard.uniquePasteboard() end + +--- Stores in the pasteboard a given table of UTI to data mapping all at once +---@param name string +---@param table any +---@return boolean +function hs.pasteboard.writeAllData(name, table) end + +--- Sets the pasteboard to the contents of the data and assigns its type to the specified UTI. The data will be encoded +--- as an archive conforming to NSKeyedArchiver. +--- +--- Note: NSKeyedArchiver specifies an architecture-independent format that is often used in OS X applications to store +--- and transmit objects between applications and when storing data to a file. It works by recording information about +--- the object types and key-value pairs which make up the objects being stored. +--- Only objects which have conversion functions built into Hammerspoon can be converted. +--- A full list of NSObjects supported directly by Hammerspoon is planned in a future Wiki article. +---@param name string +---@param uti string +---@param data table +---@param add any +---@return boolean +function hs.pasteboard.writeArchiverDataForUTI(name, uti, data, add) end + +--- Sets the pasteboard to the contents of the data and assigns its type to the specified UTI. +--- +--- Note: The UTI's of the items on the pasteboard can be determined with the hs.pasteboard.allContentTypes and +--- hs.pasteboard.contentTypes functions. +---@param name string +---@param uti string +---@param data string +---@param add any +---@return boolean +function hs.pasteboard.writeDataForUTI(name, uti, data, add) end + +--- Sets the pasteboard contents to the object or objects specified. +--- +--- Note: Most applications can only receive the first item on the clipboard. Multiple items on a clipboard are most +--- often used for intra-application communication where the sender and receiver are specifically written with multiple +--- objects in mind. +---@param object any +---@param name string +---@return boolean +function hs.pasteboard.writeObjects(object, name) end + +--- Sets the pasteboard to the contents of the data and assigns its type to the specified UTI. +--- +--- Note: The UTI's of the items on the pasteboard can be determined with the hs.pasteboard.allContentTypes and +--- hs.pasteboard.contentTypes functions. +--- Property lists consist only of certain types of data: tables, strings, numbers, dates, binary data, and Boolean +--- values. +---@param name string +---@param uti string +---@param data any +---@param add any +---@return boolean +function hs.pasteboard.writePListForUTI(name, uti, data, add) end + +-- ------------------------------------------------------------ +-- hs.pasteboard.watcher +-- ------------------------------------------------------------ + +---@class hs.pasteboard.watcher +hs.pasteboard.watcher = {} + +---@class watcher +local watcher = {} + +--- Gets or sets the polling interval (i.e. the frequency the pasteboard watcher checks the pasteboard). +--- +--- Note: This only affects new watchers, not existing/running ones. +--- The default value is 0.25. +---@param value number|nil +---@return number +function hs.pasteboard.watcher.interval(value) end + +--- Creates and starts a new +--- hs.pasteboard.watcher +--- object for watching for Pasteboard changes. +--- +--- Note: Internally this extension uses a single NSTimer to check for changes to the pasteboard count every half a +--- second. +--- Example usage: +--- generalPBWatcher +--- = +--- hs +--- . +--- pasteboard +--- . +--- watcher +--- . +--- new +--- ( +--- function +--- ( +--- v +--- ) +--- print +--- ( +--- string.format +--- ( +--- "General Pasteboard Contents: %s" +--- , +--- v +--- )) +--- end +--- ) +--- specialPBWatcher +--- = +--- hs +--- . +--- pasteboard +--- . +--- watcher +--- . +--- new +--- ( +--- function +--- ( +--- v +--- ) +--- print +--- ( +--- string.format +--- ( +--- "Special Pasteboard Contents: %s" +--- , +--- v +--- )) +--- end +--- , +--- "special" +--- ) +--- hs +--- . +--- pasteboard +--- . +--- writeObjects +--- ( +--- "This is on the general pasteboard." +--- ) +--- hs +--- . +--- pasteboard +--- . +--- writeObjects +--- ( +--- "This is on the special pasteboard." +--- , +--- "special" +--- ) +--- ``` +---@param callbackFn any +---@param name? string|nil +---@return pasteboardWatcher +function hs.pasteboard.watcher.new(callbackFn, name) end + +--- Returns a boolean indicating whether or not the Pasteboard Watcher is currently running. +---@return boolean +function watcher:running() end + +--- Starts an +--- hs.pasteboard.watcher +--- object +---@return timer +function watcher:start() end + +--- Stops an +--- hs.pasteboard.watcher +--- object +---@return timer +function watcher:stop() end + +-- ------------------------------------------------------------ +-- hs.pathwatcher +-- ------------------------------------------------------------ + +---@class hs.pathwatcher +hs.pathwatcher = {} + +---@class pathwatcher +local pathwatcher = {} + +--- Creates a new path watcher object +--- +--- Note: For more information about the event flags, see the official documentation +---@param path string +---@param fn function +---@return watcher +function hs.pathwatcher.new(path, fn) end + +--- Starts a path watcher +---@return hs.pathwatcher +function pathwatcher:start() end + +--- Stops a path watcher +---@return any +function pathwatcher:stop() end + +-- ------------------------------------------------------------ +-- hs.plist +-- ------------------------------------------------------------ + +---@class hs.plist +hs.plist = {} + +--- Loads a Property List file +---@param filepath string +---@return table +function hs.plist.read(filepath) end + +--- Interprets a property list file within a string into a table. +---@param value string +---@param binary boolean|nil +---@return table|nil +function hs.plist.readString(value, binary) end + +--- Writes a Property List file +--- +--- Note: Only simple types can be converted to plist items: +--- Strings +--- Numbers +--- Booleans +--- Tables +--- You should be careful when reading a plist, modifying and writing it - Hammerspoon may not be able to preserve all +--- of the datatypes via Lua +---@param filepath string +---@param data table +---@param binary? boolean|nil +---@return boolean +function hs.plist.write(filepath, data, binary) end + +--- Interprets a property list file within a string into a table. +---@param data table +---@param binary boolean|nil +---@return string|nil +function hs.plist.writeString(data, binary) end + +-- ------------------------------------------------------------ +-- hs.razer +-- ------------------------------------------------------------ + +---@class hs.razer +hs.razer = {} + +---@class razer +local razer = {} + +--- Sets/clears a callback for reacting to device discovery events +---@param fn function +---@return none +function hs.razer.discoveryCallback(fn) end + +--- Gets an hs.razer object for the specified device +---@param num number +---@return razerObject|nil +function hs.razer.getDevice(num) end + +--- Initialises the Razer driver and sets a discovery callback. +--- +--- Note: This function must be called before any other parts of this module are used +---@param fn function +---@return any +function hs.razer.init(fn) end + +--- Gets the number of Razer devices connected +---@return number +function hs.razer.numDevices() end + +--- Runs some basic unit tests when a Razer Tartarus V2 is connected. +--- +--- Note: Because hs.razer relies on a physical device to +--- be connected for testing, this method exists so that +--- Hammerspoon developers can test the extension outside +--- of the usual GitHub tests. It can also be used for +--- user troubleshooting. +---@return none +function hs.razer.unitTests() end + +--- Changes the keyboard backlights to the breath mode. +--- +--- Note: If neither color nor secondaryColor is provided, then random colors will be used. +---@param color any +---@param secondaryColor any +---@return razerObject +---@return boolean +---@return string|nil +function razer:backlightsBreathing(color, secondaryColor) end + +--- Changes the keyboard backlights to custom colours. +--- +--- Note: The order is top to bottom, left to right. You can use nil for any buttons you don't want to light up. +--- Example usage: ```lua +--- hs.razer.new(0):backlightsCustom({hs.drawing.color.red, nil, hs.drawing.color.green, hs.drawing.color.blue}) +---@param colors table +---@return razerObject +---@return boolean +---@return string|nil +function razer:backlightsCustom(colors) end + +--- Turns all the keyboard backlights off. +---@return razerObject +---@return boolean +---@return string|nil +function razer:backlightsOff() end + +--- Changes the keyboard backlights to the reactive mode. +---@param speed number +---@param color hs.drawing.color +---@return razerObject +---@return boolean +---@return string|nil +function razer:backlightsReactive(speed, color) end + +--- Changes the keyboard backlights to the spectrum mode. +---@return razerObject +---@return boolean +---@return string|nil +function razer:backlightsSpectrum() end + +--- Changes the keyboard backlights to the Starlight mode. +--- +--- Note: If neither color nor secondaryColor is provided, then random colors will be used. +---@param speed number +---@param color any +---@param secondaryColor any +---@return razerObject +---@return boolean +---@return string|nil +function razer:backlightsStarlight(speed, color, secondaryColor) end + +--- Changes the keyboard backlights to a single static color. +---@param color hs.drawing.color +---@return razerObject +---@return boolean +---@return string|nil +function razer:backlightsStatic(color) end + +--- Changes the keyboard backlights to the wave mode. +---@param speed number +---@param direction string +---@return razerObject +---@return boolean +---@return string|nil +function razer:backlightsWave(speed, direction) end + +--- Gets or sets the blue status light. +---@param value any +---@return razerObject +---@return boolean|nil +---@return string|nil +function razer:blueStatusLight(value) end + +--- Gets or sets the brightness of a Razer keyboard. +---@param value number +---@return razerObject +---@return number|nil +---@return string|nil +function razer:brightness(value) end + +--- Sets or removes a callback function for the +--- hs.razer +--- object. +--- +--- Note: razerObject - The serial port object that triggered the callback. +--- buttonName - The name of the button as a string. +--- buttonAction - A string containing "pressed", "released", "up" or "down". +---@param callbackFn function +---@return razerObject +function razer:callback(callbackFn) end + +--- Allows you to remap the default Keyboard Layout on a Razer device so that the buttons no longer trigger their +--- factory default actions, or restore the default keyboard layout. +--- +--- Note: This feature currently only works on the Razer Tartarus V2. +---@param enabled boolean +---@return boolean +function razer:defaultKeyboardLayout(enabled) end + +--- Gets or sets the green status light. +---@param value any +---@return razerObject +---@return boolean|nil +---@return string|nil +function razer:greenStatusLight(value) end + +--- Returns the human readable device name of the Razer device. +---@return string +function razer:name() end + +--- Gets or sets the orange status light. +---@param value any +---@return razerObject +---@return boolean|nil +---@return string|nil +function razer:orangeStatusLight(value) end + +-- ------------------------------------------------------------ +-- hs.redshift +-- ------------------------------------------------------------ + +---@class hs.redshift +hs.redshift = {} + +--- A table holding the gamma values for given color temperatures; each key must be a color temperature number in K +--- (useful values are between +---@type table +hs.redshift.COLORRAMP = nil + +--- Subscribes a callback to be notified when the color inversion status changes +--- +--- Note: You can use this to dynamically adjust the UI colors in your modules or configuration, if appropriate. +---@param id hs.redshift.invertUnsubscribe|nil +---@param fn function +---@return any +function hs.redshift.invertSubscribe(id, fn) end + +--- Unsubscribes a previously subscribed color inversion change callback +---@param id string +---@return any +function hs.redshift.invertUnsubscribe(id) end + +--- Checks if the colors are currently inverted +---@return string|boolean +function hs.redshift.isInverted() end + +--- Sets or clears a request for color inversion +--- +--- Note: you can use this function e.g. to automatically invert colors if the ambient light sensor reading drops below +--- a certain threshold ( hs.brightness.DDCauto() can optionally do exactly that) +--- if the user's configuration doesn't explicitly start the redshift module, calling this will have no effect +---@param id string +---@param v boolean|nil +---@return any +function hs.redshift.requestInvert(id, v) end + +--- Sets the schedule and (re)starts the module +---@param colorTemp number +---@param nightStart string +---@param nightEnd string +---@param transition? hs.timer.seconds|nil +---@param invertAtNight? boolean|nil +---@param windowfilterDisable? hs.window.filter|nil +---@param dayColorTemp? number|nil +---@return any +function hs.redshift.start(colorTemp, nightStart, nightEnd, transition, invertAtNight, windowfilterDisable, dayColorTemp) end + +--- Stops the module and disables color adjustment and color inversion +---@return any +function hs.redshift.stop() end + +--- Sets or clears the user override for color temperature adjustment. +--- +--- Note: This function should be bound to a hotkey, e.g.: hs.hotkey.bind('ctrl-cmd','-','Redshift',hs.redshift.toggle) +---@param v any +---@return any +function hs.redshift.toggle(v) end + +--- Sets or clears the user override for color inversion. +--- +--- Note: This function should be bound to a hotkey, e.g.: hs.hotkey.bind('ctrl-cmd','=','Invert',hs.redshift.toggleInvert) +---@param v any +---@return any +function hs.redshift.toggleInvert(v) end + +-- ------------------------------------------------------------ +-- hs.screen +-- ------------------------------------------------------------ + +---@class hs.screen +hs.screen = {} + +---@class screen +local screen = {} + +--- If set to +--- true +--- , the methods +--- hs.screen:toEast() +--- , +--- :toNorth() +--- etc. will disregard screens that lie perpendicularly to the desired axis +---@type hs.screen +hs.screen.strictScreenInDirection = nil + +--- Gets the current state of the screen-related accessibility settings +---@return table +function hs.screen.accessibilitySettings() end + +--- Finds screens +--- +--- Note: for convenience you call this as hs.screen(hint) +--- Example: +--- hs +--- . +--- screen +--- ( +--- 724562417 +--- ) +--- --> Color LCD - by id +--- hs +--- . +--- screen +--- 'Dell' +--- --> DELL U2414M - by name +--- hs +--- . +--- screen +--- 'Built%-in' +--- --> Built-in Retina Display, note the % to escape the hyphen repetition character +--- hs +--- . +--- screen +--- '0,0' +--- --> PHL BDM4065 - by position, same as hs.screen.primaryScreen() +--- hs +--- . +--- screen +--- { +--- x +--- =- +--- 1 +--- , +--- y +--- = +--- 0 +--- } +--- --> DELL U2414M - by position, screen to the immediate left of the primary screen +--- hs +--- . +--- screen +--- '3840x2160' +--- --> PHL BDM4065 - by screen resolution +--- hs +--- . +--- screen +--- '-500,240 700x1300' +--- --> DELL U2414M, by arbitrary rect +---@param hint any +---@return hs.screen +function hs.screen.find(hint) end + +--- Restore the gamma settings to defaults +--- +--- Note: This returns all displays to the gamma tables specified by the user's selected ColorSync display profiles +---@return any +function hs.screen.restoreGamma() end + +--- Returns a list of all connected and enabled screens, along with their "position" relative to the primary screen +--- +--- Note: grid-like arrangements of same-sized screens should behave consistently; but there's no guarantee of a +--- consistent result for more "exotic" screen arrangements +---@return table +function hs.screen.screenPositions() end + +--- Returns all the screens +---@return hs.screen[] +function hs.screen.allScreens() end + +--- Returns the 'main' screen, i.e. the one containing the currently focused window +---@return screen +function hs.screen.mainScreen() end + +--- Gets the primary screen +---@return screen +function hs.screen.primaryScreen() end + +--- Transforms from the absolute coordinate space used by OSX/Hammerspoon to the screen's local coordinate space, where +--- 0,0 +--- is at the screen's top left corner +---@param geom hs.geometry +---@return hs.geometry +function screen:absoluteToLocal(geom) end + +--- Returns a table containing the screen modes supported by the screen. A screen mode is a combination of resolution, +--- scaling factor and colour depth +--- +--- Note: Prior to 0.9.83, only 32-bit colour modes would be returned, but now all colour depths are returned. This has +--- necessitated changing the naming of the modes in the returned table. +--- "points" are not necessarily the same as pixels, because they take the scale factor into account (e.g. +--- "1440x900@2x" is a 2880x1800 screen resolution, with a scaling factor of 2, i.e. with HiDPI pixel-doubled rendering +--- enabled), however, they are far more useful to work with than native pixel modes, when a Retina screen is involved. +--- For non-retina screens, points and pixels are equivalent. +---@return table +function screen:availableModes() end + +--- Returns a table describing the current screen mode +---@return table +function screen:currentMode() end + +--- Gets/Sets the desktop background image for a screen +--- +--- Note: If the user has set a folder of pictures to be alternated as the desktop background, the path to that folder +--- will be returned. +---@param imageURL string +---@return hs.screen +function screen:desktopImageURL(imageURL) end + +--- Returns the screen frame, without the dock or menu. +---@return hs.geometry rect +function screen:frame() end + +--- Returns the absolute rect of a given unit rect within this screen +--- +--- Note: this method is just a convenience wrapper for hs.geometry.fromUnitRect(unitrect,this_screen:frame()) +---@param unitrect hs.geometry +---@return hs.geometry rect +function screen:fromUnitRect(unitrect) end + +--- Returns the screen frame, including the dock and menu. +---@return hs.geometry rect +function screen:fullFrame() end + +--- Gets the screen's brightness +---@return number|nil +function screen:getBrightness() end + +--- Gets the screen's ForceToGray setting +---@return boolean +function hs.screen.getForceToGray() end + +--- Gets the current whitepoint and blackpoint of the screen +---@return whitepoint +---@return blackpoint|nil +function screen:getGamma() end + +--- Gets a table of information about an +--- hs.screen +--- object +---@return table|nil +function screen:getInfo() end + +--- Gets the screen's InvertedPolarity setting +---@return boolean +function hs.screen.getInvertedPolarity() end + +--- Gets the UUID of an +--- hs.screen +--- object +---@return string +function screen:getUUID() end + +--- Returns a screen's unique ID +---@return number +function screen:id() end + +--- Transforms from the screen's local coordinate space, where +--- 0,0 +--- is at the screen's top left corner, to the absolute coordinate space used by OSX/Hammerspoon +---@param geom hs.geometry +---@return hs.geometry +function screen:localToAbsolute(geom) end + +--- Make this screen mirror another +---@param aScreen hs.screen +---@param permanent? any +---@return boolean +function screen:mirrorOf(aScreen, permanent) end + +--- Stops this screen mirroring another +---@param permanent any +---@return boolean +function screen:mirrorStop(permanent) end + +--- Returns the preferred name for the screen set by the manufacturer +---@return string|nil +function screen:name() end + +--- Gets the screen 'after' this one (in arbitrary order); this method wraps around to the first screen. +---@return screen +function screen:next() end + +--- Return a given screen's position relative to the primary screen - see 'hs.screen.screenPositions()' +---@return x +---@return y +function screen:position() end + +--- Gets the screen 'before' this one (in arbitrary order); this method wraps around to the last screen. +---@return screen +function screen:previous() end + +--- Gets/Sets the rotation of a screen +---@param degrees any +---@return boolean|rotation angle +function screen:rotate(degrees) end + +--- Sets the screen's brightness +---@param brightness number +---@return hs.screen +function screen:setBrightness(brightness) end + +--- Sets the screen's ForceToGray mode +---@param ForceToGray boolean +function hs.screen.setForceToGray(ForceToGray) end + +--- Sets the current white point and black point of the screen +--- +--- Note: If the whitepoint and blackpoint specified, are very similar, it will be impossible to read the screen. You +--- should exercise caution, and may wish to bind a hotkey to hs.screen.restoreGamma() when experimenting +---@param whitepoint any +---@param blackpoint any +---@return boolean +function screen:setGamma(whitepoint, blackpoint) end + +--- Sets the screen's InvertedPolarity mode +---@param InvertedPolarity boolean +function hs.screen.setInvertedPolarity(InvertedPolarity) end + +--- Sets the screen to a new mode +--- +--- Note: The available widths/heights/scales can be seen in the output of hs.screen:availableModes() , however, it +--- should be noted that the CoreGraphics subsystem seems to list more modes for a given screen than it is actually +--- prepared to set, so you may find that seemingly valid modes still return false. It is not currently understood why +--- this is so! +---@param width number +---@param height number +---@param scale number +---@param frequency number +---@param depth number +---@return boolean +function screen:setMode(width, height, scale, frequency, depth) end + +--- Sets the origin of a screen in the global display coordinate space. The origin of the main or primary display is +--- (0,0). The new origin is placed as close as possible to the requested location, without overlapping or leaving a +--- gap between displays. If you use this function to change the origin of a mirrored display, the display may be +--- removed from the mirroring set. +---@param x number +---@param y number +---@return boolean +function screen:setOrigin(x, y) end + +--- Sets the screen to be the primary display (i.e. contain the menubar and dock) +---@return boolean +function screen:setPrimary() end + +--- Saves an image of the screen to a JPG file +---@param filePath string +---@param screenRect? hs.geometry|nil +---@return any +function screen:shotAsJPG(filePath, screenRect) end + +--- Saves an image of the screen to a PNG file +---@param filePath string +---@param screenRect? hs.geometry|nil +---@return any +function screen:shotAsPNG(filePath, screenRect) end + +--- Captures an image of the screen +---@param rect table|nil +---@return object +function screen:snapshot(rect) end + +--- Gets the first screen to the east of this one, ordered by proximity to its center or a specified point. +---@param from hs.geometry.rect|hs.geometry.point +---@param strict hs.screen.strictScreenInDirection +---@return hs.screen +function screen:toEast(from, strict) end + +--- Gets the first screen to the north of this one, ordered by proximity to its center or a specified point. +---@param from hs.geometry.rect|hs.geometry.point +---@param strict hs.screen.strictScreenInDirection +---@return hs.screen +function screen:toNorth(from, strict) end + +--- Gets the first screen to the south of this one, ordered by proximity to its center or a specified point. +---@param from hs.geometry.rect|hs.geometry.point +---@param strict hs.screen.strictScreenInDirection +---@return hs.screen +function screen:toSouth(from, strict) end + +--- Returns the unit rect of a given rect, relative to this screen +--- +--- Note: this method is just a convenience wrapper for hs.geometry.toUnitRect(rect,this_screen:frame()) +---@param rect hs.geometry +---@return hs.geometry unitrect +function screen:toUnitRect(rect) end + +--- Gets the first screen to the west of this one, ordered by proximity to its center or a specified point. +---@param from hs.geometry.rect|hs.geometry.point +---@param strict hs.screen.strictScreenInDirection +---@return hs.screen +function screen:toWest(from, strict) end + +-- ------------------------------------------------------------ +-- hs.screen.watcher +-- ------------------------------------------------------------ + +---@class hs.screen.watcher +hs.screen.watcher = {} + +---@class watcher +local watcher = {} + +--- Creates a new screen-watcher. +--- +--- Note: A screen layout change usually involves a change that is made from the Displays Preferences Panel or when a +--- monitor is attached or removed. It can also be caused by a change in the Dock size or presence. +---@param fn function +---@return watcher +function hs.screen.watcher.new(fn) end + +--- Creates a new screen-watcher that is also called when the active screen changes. +--- +--- Note: nil was chosen instead of false for the argument type when this type of change occurs to more closely match +--- the previous behavior of having no argument passed to the callback function. +--- Detecting a change in the active display relies on watching for the NSWorkspaceActiveDisplayDidChangeNotification +--- message which is not documented by Apple. While this message has been around at least since OS X 10.9, because it +--- is undocumented, we cannot be positive that Apple won't remove it in a future OS X update. Because this watcher +--- works by listening for posted messages, should Apple remove this notification, your callback function will no +--- longer receive messages about this change -- it won't crash or change behavior in any other way. This +--- documentation will be updated if this status changes. +--- Plugging in or unplugging a monitor can cause both a screen layout callback and an active screen change callback. +---@param fn function +---@return watcher +function hs.screen.watcher.newWithActiveScreen(fn) end + +--- Starts the screen watcher, making it so fn is called each time the screen arrangement changes +---@return watcher +function watcher:start() end + +--- Stops the screen watcher's fn from getting called until started again +---@return watcher +function watcher:stop() end + +-- ------------------------------------------------------------ +-- hs.serial +-- ------------------------------------------------------------ + +---@class hs.serial +hs.serial = {} + +---@class serial +local serial = {} + +--- Returns a table of currently connected serial ports details, organised by port name. +---@return table +function hs.serial.availablePortDetails() end + +--- Returns a table of currently connected serial ports names. +---@return table +function hs.serial.availablePortNames() end + +--- Returns a table of currently connected serial ports paths. +---@return table +function hs.serial.availablePortPaths() end + +--- A callback that's triggered when a serial port is added or removed from the system. +--- +--- Note: devices - A table containing the names of any serial ports connected as strings. +---@param callbackFn function|nil +---@return none +function hs.serial.deviceCallback(callbackFn) end + +--- Creates a new +--- hs.serial +--- object using the port name. +--- +--- Note: A valid port name can be found by checking hs.serial.availablePortNames() . +---@param portName string +---@return serialPortObject +function hs.serial.newFromName(portName) end + +--- Creates a new +--- hs.serial +--- object using a path. +--- +--- Note: A valid port name can be found by checking hs.serial.availablePortPaths() . +---@param path string +---@return serialPortObject +function hs.serial.newFromPath(path) end + +--- Gets or sets the baud rate for the serial port. +--- +--- Note: This function supports the following standard baud rates as numbers: 300, 1200, 2400, 4800, 9600, 14400, +--- 19200, 28800, 38400, 57600, 115200, 230400. +--- If no baud rate is supplied, it defaults to 115200. +---@param value number|nil +---@param allowNonStandardBaudRates boolean +---@return number|serialPortObject +function serial:baudRate(value, allowNonStandardBaudRates) end + +--- Sets or removes a callback function for the +--- hs.serial +--- object. +--- +--- Note: serialPortObject - The serial port object that triggered the callback. +--- callbackType - A string containing "opened", "closed", "received", "removed" or "error". +--- message - If the callbackType is "received", then this will be the data received as a string. If the callbackType +--- is "error", this will be the error message as a string. +--- hexadecimalString - If the callbackType is "received", then this will be the data received as a hexadecimal string. +---@param callbackFn function +---@return serialPortObject +function serial:callback(callbackFn) end + +--- Closes the serial port. +---@return serialPortObject +function serial:close() end + +--- Gets or sets the number of data bits for the serial port. +---@param value number|nil +---@return number|serialPortObject +function serial:dataBits(value) end + +--- Gets or sets the state of the serial port's DTR (Data Terminal Ready) pin. +--- +--- Note: The default value is false . +--- Setting this to true is most likely required for Arduino devices prior to opening the serial port. +---@param value boolean|nil +---@return boolean|serialPortObject +function serial:dtr(value) end + +--- Gets whether or not a serial port is open. +---@return boolean +function serial:isOpen() end + +--- Returns the name of a +--- hs.serial +--- object. +---@return string +function serial:name() end + +--- Opens the serial port. +---@return serialPortObject|nil +function serial:open() end + +--- Gets or sets the parity for the serial port. +---@param value string|nil +---@return string|serialPortObject +function serial:parity(value) end + +--- Returns the path of a +--- hs.serial +--- object. +---@return string +function serial:path() end + +--- Gets or sets the state of the serial port's RTS (Request to Send) pin. +--- +--- Note: The default value is false . +--- Setting this to true is most likely required for Arduino devices prior to opening the serial port. +---@param value boolean|nil +---@return boolean|serialPortObject +function serial:rts(value) end + +--- Sends data via a serial port. +---@param value string +---@return none +function serial:sendData(value) end + +--- Gets or sets whether the port should echo received data. +--- +--- Note: The default value is false . +---@param value boolean|nil +---@return boolean|serialPortObject +function serial:shouldEchoReceivedData(value) end + +--- Gets or sets the number of stop bits for the serial port. +--- +--- Note: The default value is 1. +---@param value any +---@return number|serialPortObject +function serial:stopBits(value) end + +--- Gets or sets whether the port should use DTR/DSR Flow Control. +--- +--- Note: The default value is false . +---@param value boolean|nil +---@return boolean|serialPortObject +function serial:usesDTRDSRFlowControl(value) end + +--- Gets or sets whether the port should use RTS/CTS Flow Control. +--- +--- Note: The default value is false . +---@param value boolean|nil +---@return boolean|serialPortObject +function serial:usesRTSCTSFlowControl(value) end + +-- ------------------------------------------------------------ +-- hs.settings +-- ------------------------------------------------------------ + +---@class hs.settings +hs.settings = {} + +--- A string representing the ID of the bundle Hammerspoon's settings are stored in . You can use this with the command +--- line tool +--- defaults +--- or other tools which allow access to the +--- User Defaults +--- of applications, to access these outside of Hammerspoon +---@type string +hs.settings.bundleID = nil + +--- A string representing the expected format of date and time when presenting the date and time as a string to +--- hs.setDate() +--- . e.g. +--- os.date(hs.settings.dateFormat) +---@type string +hs.settings.dateFormat = nil + +--- Deletes a setting +---@param key string +---@return boolean +function hs.settings.clear(key) end + +--- Loads a setting +--- +--- Note: This function can load all of the datatypes supported by hs.settings.set() , hs.settings.setData() and +--- hs.settings.setDate() +---@param key string +---@return string|boolean|number|nil|table +function hs.settings.get(key) end + +--- Gets all of the previously stored setting names +--- +--- Note: Use ipairs(hs.settings.getKeys()) to iterate over all available settings +--- Use hs.settings.getKeys()["someKey"] to test for the existence of a particular key +---@return table +function hs.settings.getKeys() end + +--- Saves a setting with common datatypes +--- +--- Note: If no val parameter is provided, it is assumed to be nil +--- This function cannot set dates or raw data types, see hs.settings.setDate() and hs.settings.setData() +--- Assigning a nil value is equivalent to clearing the value with hs.settings.clear +---@param key string +---@param val? any +---@return any +function hs.settings.set(key, val) end + +--- Saves a setting with raw binary data +---@param key string +---@param val any +---@return any +function hs.settings.setData(key, val) end + +--- Saves a setting with a date +--- +--- Note: See hs.settings.dateFormat for a convenient representation of the RFC3339 format, to use with other time/date +--- related functions +---@param key string +---@param val number +---@return any +function hs.settings.setDate(key, val) end + +--- Get or set a watcher to invoke a callback when the specified settings key changes +--- +--- Note: the identifier is required so that multiple callbacks for the same key can be registered by separate modules; +--- it's value doesn't affect what is being watched but does need to be unique between multiple watchers of the same +--- key. +--- Does not work with keys that include a period (.) in the key name because KVO uses dot notation to specify a +--- sequence of properties. If you know of a way to escape periods so that they are watchable as NSUSerDefault key +--- names, please file an issue and share! +---@param identifier function +---@param key string +---@param fn function +---@return identifier +function hs.settings.watchKey(identifier, key, fn) end + +-- ------------------------------------------------------------ +-- hs.sharing +-- ------------------------------------------------------------ + +---@class hs.sharing +hs.sharing = {} + +---@class sharing +local sharing = {} + +--- A table containing the predefined sharing service labels defined by Apple. +---@type table +hs.sharing.builtinSharingServices[] = nil + +--- Returns a table representing a file URL for the path specified. +--- +--- Note: this function is a wrapper to hs.sharing.URL which sets the second argument to true for you. +--- see hs.sharing.URL for more information about the table format returned by this function. +---@param path string +---@return table +function hs.sharing.fileURL(path) end + +--- Returns a table containing the sharing service identifiers which can share the items specified. +--- +--- Note: this function is intended to be used to determine the identifiers for sharing services available on your +--- computer and that may not be included in the hs.sharing.builtinSharingServices table. +---@param items items[] +---@return identifiersTable +function hs.sharing.shareTypesFor(items) end + +--- Returns a table representing the URL specified. +--- +--- Note: If the URL is specified as a table, it is expected to contain a url key with a string value specifying a +--- proper schema and resource locator. +--- Because macOS requires URLs to be represented as a specific object type which has no exact equivalent in Lua, +--- Hammerspoon uses a table with specific keys to allow proper identification of a URL when included as an argument or +--- result type. Use this function or the hs.sharing.fileURL wrapper function when specifying a URL to ensure that the +--- proper keys are defined. +--- url - a string containing the URL with a proper schema and resource locator +--- filePath = a string specifying the actual path to the file in case the url is a file reference URL. Note that +--- setting this field with this method will be silently ignored; the field is automatically inserted if appropriate +--- when returning an NSURL object to lua. +--- __luaSkinType - a string specifying the macOS type this table represents when converted into an Objective-C type +---@param URL string +---@param fileURL string +---@return table +function hs.sharing.URL(URL, fileURL) end + +--- Creates a new sharing object of the type specified by the identifier provided. +---@param type string +---@return sharingObject +function hs.sharing.newShare(type) end + +--- The account name used by the sharing service when posting on Twitter or Sina Weibo. +--- +--- Note: According to the Apple API documentation, only the Twitter and Sina Weibo sharing services will set this +--- property, but this has not been fully tested. +---@return string|nil +function sharing:accountName() end + +--- Returns an alternate image, if one exists, representing the sharing service provided by this sharing object. +---@return hs.image|nil +function sharing:alternateImage() end + +--- If the sharing service provides an array of the attachments included when the data was posted, this method will +--- return an array of file URL tables of the attachments. +--- +--- Note: not all sharing services will set a value for this property. +---@return table|nil +function sharing:attachments() end + +--- Set or clear the callback for the sharingObject. +--- +--- Note: the sharingObject itself +--- "didFail" - an error occurred while attempting to share the items +--- "didShare" - the sharing service has finished sharing the items +--- "willShare" - the sharing service is about to start sharing the items; occurs before sharing actually begins +--- an array (table) containing the items being shared; if the message is "didFail" or "didShare", the items may be in +--- a different order or converted to a different internal type to facilitate sharing. +--- if the message is "didFail", the fourth argument will be a localized description of the error that occurred. +---@param fn function|nil +---@return sharingObject +function sharing:callback(fn) end + +--- Returns a boolean specifying whether or not all of the items specified can be shared with the sharing service +--- represented by the sharingObject. +---@param items items[] +---@return boolean +function sharing:canShareItems(items) end + +--- Returns an image, if one exists, representing the sharing service provided by this sharing object. +---@return hs.image|nil +function sharing:image() end + +--- If the sharing service provides the message body that was posted when sharing has completed, this method will +--- return the message body as a string. +--- +--- Note: not all sharing services will set a value for this property. +---@return string|nil +function sharing:messageBody() end + +--- If the sharing service provides a permanent link to the post when sharing has completed, this method will return +--- the corresponding URL. +--- +--- Note: not all sharing services will set a value for this property. +---@return URL table|nil +function sharing:permanentLink() end + +--- Get or set the subject to be used when the sharing service performs its sharing method. +--- +--- Note: not all sharing services will make use of the value set by this method. +--- the individual recipients should be specified as strings in the format expected by the sharing service; e.g. for +--- items being shared in an email, the recipients should be email address, etc. +---@param recipients recipient[]|nil +---@return sharingObject +function sharing:recipients(recipients) end + +--- The service identifier for the sharing service represented by the sharingObject. +--- +--- Note: this string will match the identifier used to create the sharing service object with hs.sharing.newShare +---@return string +function sharing:serviceName() end + +--- Shares the items specified with the sharing service represented by the sharingObject. +--- +--- Note: You can check to see if all of your items can be shared with the hs.sharing:canShareItems method. +---@param items items[] +---@return sharingObject +function sharing:shareItems(items) end + +--- Get or set the subject to be used when the sharing service performs its sharing method. +--- +--- Note: not all sharing services will make use of the value set by this method. +---@param subject string|nil +---@return sharingObject +function sharing:subject(subject) end + +--- The title for the sharing service represented by the sharingObject. +--- +--- Note: this string differs from the identifier used to create the sharing service object with hs.sharing.newShare +--- and is intended to provide a more friendly label for the service if you need to list or refer to it elsewhere. +---@return string +function sharing:title() end + +-- ------------------------------------------------------------ +-- hs.shortcuts +-- ------------------------------------------------------------ + +---@class hs.shortcuts +hs.shortcuts = {} + +--- Returns a list of available shortcuts +---@return [] +function hs.shortcuts.list() end + +--- Execute a Shortcuts shortcut by name +---@param name string +---@return any +function hs.shortcuts.run(name) end + +-- ------------------------------------------------------------ +-- hs.socket +-- ------------------------------------------------------------ + +---@class hs.socket +hs.socket = {} + +---@class socket +local socket = {} + +--- Timeout for the socket operations, in seconds. +---@type any +hs.socket.timeout = nil + +--- Parses a binary socket address structure into a readable table. +--- +--- Note: Some address family definitions from : +--- address family | number | description +--- :--- | :--- | : +--- AF_UNSPEC | 0 | unspecified +--- AF_UNIX | 1 | local to host (pipes) +--- AF_LOCAL | AF_UNIX | backward compatibility +--- AF_INET | 2 | internetwork: UDP, TCP, etc. +--- AF_NS | 6 | XEROX NS protocols +--- AF_CCITT | 10 | CCITT protocols, X.25 etc +--- AF_APPLETALK | 16 | Apple Talk +--- AF_ROUTE | 17 | Internal Routing Protocol +--- AF_LINK | 18 | Link layer interface +--- AF_INET6 | 30 | IPv6 +---@param sockaddr hs.socket.udp +---@return table|nil +function hs.socket.parseAddress(sockaddr) end + +--- Creates an unconnected asynchronous TCP socket object. +---@param fn function|nil +---@return hs.socket +function hs.socket.new(fn) end + +--- Creates a TCP socket, and binds it to either a port or path (Unix domain socket) for listening. +---@param port | path string +---@param fn? function|nil +---@return hs.socket +function hs.socket.server(port | path, fn) end + +--- Connects an unconnected socket. +--- +--- Note: Either a host/port pair OR a Unix domain socket path must be supplied. If no port is passed, the first +--- parameter is assumed to be a path to the socket file. +---@param host string +---@param port | path string +---@param fn? function|nil +---@return self|nil +function socket:connect(host, port | path, fn) end + +--- Returns the connection status of the socket. +--- +--- Note: If the socket is bound for listening, this method returns true if there is at least one connection. +---@return boolean +function socket:connected() end + +--- Returns the number of connections to the socket. +--- +--- Note: This method returns at most 1 for default (non-listening) sockets. +---@return number +function socket:connections() end + +--- Disconnects the socket, freeing it for reuse. +--- +--- Note: If called on a listening socket with multiple connections, each client is disconnected. +---@return self +function socket:disconnect() end + +--- Returns information about the socket. +---@return table +function socket:info() end + +--- Binds an unconnected socket to either a port or path (Unix domain socket) for listening. +---@param port|path string +---@return self|nil +function socket:listen(port|path) end + +--- Read data from the socket. +--- +--- Note: Results are passed to the socket's callback function , which must be set to use this method. +--- If called on a listening socket with multiple connections, data is read from each of them. +---@param delimiter any +---@param tag? function|nil +---@return self|nil +function socket:read(delimiter, tag) end + +--- Alias for +--- hs.socket:read +---@param delimiter any +---@param tag? any +---@return self +function socket:receive(delimiter, tag) end + +--- Alias for +--- hs.socket:write +---@param message string +---@param tag? any +---@return self +function socket:send(message, tag) end + +--- Sets the read callback for the socket. +--- +--- Note: A callback must be set in order to read data from the socket. +---@param fn function +---@return self +function socket:setCallback(fn) end + +--- Sets the timeout for the socket operations. +--- +--- Note: If the timeout value is negative, the operations will not use a timeout, which is the default. +---@param timeout number +---@return self +function socket:setTimeout(timeout) end + +--- Secures the socket with TLS. +--- +--- Note: The socket will disconnect immediately if TLS negotiation fails. +--- IMPORTANT SECURITY NOTE : The default settings will check to make sure the remote party's certificate is signed by +--- a trusted 3rd party certificate agency (e.g. verisign) and that the certificate is not expired. However it will +--- not verify the name on the certificate unless you give it a name to verify against via peerName . The security +--- implications of this are important to understand. Imagine you are attempting to create a secure connection to +--- MySecureServer.com, but your socket gets directed to MaliciousServer.com because of a hacked DNS server. If you +--- simply use the default settings, and MaliciousServer.com has a valid certificate, the default settings will not +--- detect any problems since the certificate is valid. To properly secure your connection in this particular scenario +--- you should set peerName to "MySecureServer.com". +---@param verify boolean|nil +---@param peerName? string|nil +---@return self +function socket:startTLS(verify, peerName) end + +--- Write data to the socket. +--- +--- Note: If called on a listening socket with multiple connections, data is broadcast to all connected sockets. +---@param message string +---@param tag? number|nil +---@param fn? function|nil +---@return self +function socket:write(message, tag, fn) end + +-- ------------------------------------------------------------ +-- hs.socket.udp +-- ------------------------------------------------------------ + +---@class hs.socket.udp +hs.socket.udp = {} + +---@class udp +local udp = {} + +--- Timeout for the socket operations, in seconds. +---@type any +hs.socket.udp.timeout = nil + +--- Alias for +--- hs.socket.parseAddress +---@param sockaddr any +---@return table|nil +function hs.socket.udp.parseAddress(sockaddr) end + +--- Creates an unconnected asynchronous UDP socket object. +---@param fn function|nil +---@return hs.socket.udp +function hs.socket.udp.new(fn) end + +--- Creates a UDP socket, and binds it to a port for listening. +---@param port number +---@param fn? function|nil +---@return hs.socket.udp +function hs.socket.udp.server(port, fn) end + +--- Enables broadcasting on the underlying socket. +--- +--- Note: By default, the underlying socket in the OS will not allow you to send broadcast messages. +--- In order to send broadcast messages, you need to enable this functionality in the socket. +--- A broadcast is a UDP message to addresses like "192.168.255.255" or "255.255.255.255" that is delivered to every +--- host on the network. +--- The reason this is generally disabled by default (by the OS) is to prevent accidental broadcast messages from +--- flooding the network. +---@param flag boolean|nil +---@return self|nil +function udp:broadcast(flag) end + +--- Immediately closes the socket, freeing it for reuse. Any pending send operations are discarded. +---@return self +function udp:close() end + +--- Returns the closed status of the socket. +--- +--- Note: UDP sockets are typically meant to be connectionless. +--- Sending a packet anywhere, regardless of whether or not the destination receives it, opens the socket until it is +--- explicitly closed. +--- An active listening socket will not be closed, but will not be 'connected' unless the hs.socket.udp:connect method +--- has been called. +---@return boolean +function udp:closed() end + +--- Connects an unconnected socket. +--- +--- Note: By design, UDP is a connectionless protocol, and connecting is not needed. +--- You will only be able to send data to the connected host/port; +--- You will only be able to receive data from the connected host/port; +--- You will receive ICMP messages that come from the connected host/port, such as "connection refused". +--- The actual process of connecting a UDP socket does not result in any communication on the socket, it simply changes +--- the internal state of the socket. +--- You cannot bind a socket for listening after it has been connected. +--- You can only connect a socket once. +---@param host string +---@param port number +---@param fn? function|nil +---@return self|nil +function udp:connect(host, port, fn) end + +--- Returns the connection status of the socket. +--- +--- Note: UDP sockets are typically meant to be connectionless. +--- This method will only return true if the hs.socket.udp:connect method has been explicitly called. +---@return boolean +function udp:connected() end + +--- Enables or disables IPv4 or IPv6 on the underlying socket. By default, both are enabled. +--- +--- Note: hs.socket.udp.new(callback):enableIPv(4, false):listen(port):receive() +--- The convenience constructor hs.socket.server will automatically bind the socket and requires closing and +--- relistening to use this method. +---@param version number +---@param flag? boolean +---@return self|nil +function udp:enableIPv(version, flag) end + +--- Returns information about the socket. +---@return table +function udp:info() end + +--- Binds an unconnected socket to a port for listening. +---@param port number +---@return self|nil +function udp:listen(port) end + +--- Suspends reading of packets from the socket. +--- +--- Note: Call one of the receive methods to resume. +---@return self +function udp:pause() end + +--- Sets the preferred IP version: IPv4, IPv6, or neutral (first to resolve). +--- +--- Note: If a DNS lookup returns only IPv4 results, the socket will automatically use IPv4. +--- If a DNS lookup returns only IPv6 results, the socket will automatically use IPv6. +--- If a DNS lookup returns both IPv4 and IPv6 results, then the protocol used depends on the configured preference. +---@param version any +---@return self +function udp:preferIPv(version) end + +--- Alias for +--- hs.socket.udp:receive +---@param delimiter any +---@param tag? any +---@return self +function udp:read(delimiter, tag) end + +--- Alias for +--- hs.socket.udp:receiveOne +---@param delimiter any +---@param tag? any +---@return self +function udp:readOne(delimiter, tag) end + +--- Reads packets from the socket as they arrive. +--- +--- Note: Results are passed to the callback function , which must be set to use this method. +--- There are two modes of operation for receiving packets: one-at-a-time & continuous. +--- In one-at-a-time mode, you call receiveOne every time you are ready process an incoming UDP packet. +--- Receiving packets one-at-a-time may be better suited for implementing certain state machine code where your state +--- machine may not always be ready to process incoming packets. +--- In continuous mode, the callback is invoked immediately every time incoming udp packets are received. +--- Receiving packets continuously is better suited to real-time streaming applications. +--- You may switch back and forth between one-at-a-time mode and continuous mode. +--- If the socket is currently in one-at-a-time mode, calling this method will switch it to continuous mode. +---@param fn function|nil +---@return self|nil +function udp:receive(fn) end + +--- Reads a single packet from the socket. +--- +--- Note: Results are passed to the callback function , which must be set to use this method. +--- There are two modes of operation for receiving packets: one-at-a-time & continuous. +--- In one-at-a-time mode, you call receiveOne every time you are ready process an incoming UDP packet. +--- Receiving packets one-at-a-time may be better suited for implementing certain state machine code where your state +--- machine may not always be ready to process incoming packets. +--- In continuous mode, the callback is invoked immediately every time incoming udp packets are received. +--- Receiving packets continuously is better suited to real-time streaming applications. +--- You may switch back and forth between one-at-a-time mode and continuous mode. +--- If the socket is currently in continuous mode, calling this method will switch it to one-at-a-time mode +---@param fn function|nil +---@return self|nil +function udp:receiveOne(fn) end + +--- Enables port reuse on the socket. +--- +--- Note: By default, only one socket can be bound to a given IP address & port at a time. +--- To enable multiple processes to simultaneously bind to the same address & port, you need to enable this +--- functionality in the socket. +--- All processes that wish to use the address & port simultaneously must all enable reuse port on the socket bound to +--- that port. +--- Must be called before binding the socket. +---@param flag boolean|nil +---@return self|nil +function udp:reusePort(flag) end + +--- Sends a packet to the destination address. +--- +--- Note: For non-connected sockets, the remote destination is specified for each packet. +--- If the socket has been explicitly connected with connect , only the message parameter and an optional tag and/or +--- write callback can be supplied. +--- Recall that connecting is optional for a UDP socket. +--- For connected sockets, data can only be sent to the connected address. +---@param message string +---@param host? string +---@param port? number +---@param tag? number|nil +---@param fn? function|nil +---@return self +function udp:send(message, host, port, tag, fn) end + +--- Sets the maximum size of the buffer that will be allocated for receive operations. +--- +--- Note: The default maximum size is 9216 bytes. +--- The theoretical maximum size of any IPv4 UDP packet is UINT16_MAX = 65535 . +--- The theoretical maximum size of any IPv6 UDP packet is UINT32_MAX = 4294967295 . +--- Since the OS notifies us of the size of each received UDP packet, the actual allocated buffer size for each packet +--- is exact. +--- In practice the size of UDP packets is generally much smaller than the max. Most protocols will send and receive +--- packets of only a few bytes, or will set a limit on the size of packets to prevent fragmentation in the IP layer. +--- If you set the buffer size too small, the sockets API in the OS will silently discard any extra data. +---@param size number +---@param version? any +---@return self +function udp:setBufferSize(size, version) end + +--- Sets the read callback for the socket. +--- +--- Note: A callback must be set in order to read data from the socket. +---@param fn function +---@return self +function udp:setCallback(fn) end + +--- Sets the timeout for the socket operations. +--- +--- Note: If the timeout value is negative, the operations will not use a timeout, which is the default. +---@param timeout number +---@return self +function udp:setTimeout(timeout) end + +--- Alias for +--- hs.socket.udp:send +---@param message string +---@param tag? any +---@return self +function udp:write(message, tag) end + +-- ------------------------------------------------------------ +-- hs.sound +-- ------------------------------------------------------------ + +---@class hs.sound +hs.sound = {} + +---@class sound +local sound = {} + +--- Gets a table of installed Audio Units Effect names. +--- +--- Note: Example usage: hs.inspect(hs.audiounit.getAudioEffectNames()) +---@return table +function hs.sound.getAudioEffectNames() end + +--- Gets the supported sound file types +--- +--- Note: This function is unlikely to be tremendously useful, as filename extensions are essentially meaningless. The +--- data returned by hs.sound.soundTypes() is far more valuable +---@return table +function hs.sound.soundFileTypes() end + +--- Gets the supported UTI sound file formats +---@return table +function hs.sound.soundTypes() end + +--- Gets a table of available system sounds +--- +--- Note: The sounds listed by this function can be loaded using hs.sound.getByName() +---@return table +function hs.sound.systemSounds() end + +--- Creates an +--- hs.sound +--- object from a file +---@param path string +---@return sound|nil +function hs.sound.getByFile(path) end + +--- Creates an +--- hs.sound +--- object from a named sound +--- +--- Note: Sounds can only be loaded by name if they are System Sounds (i.e. those found in ~/Library/Sounds, +--- /Library/Sounds, /Network/Library/Sounds and /System/Library/Sounds) or are sound files that have previously been +--- loaded and named +---@param name string +---@return sound|nil +function hs.sound.getByName(name) end + +--- Get or set the current seek offset within an +--- hs.sound +--- object. +---@param seekTime number|nil +---@return soundObject|seconds +function sound:currentTime(seekTime) end + +--- Get or set the playback device to use for an +--- hs.sound +--- object +--- +--- Note: To obtain the UID of a sound device, see hs.audiodevice:uid() +---@param deviceUID hs.audiodevice|nil +---@return soundObject|UID string +function sound:device(deviceUID) end + +--- Gets the length of an +--- hs.sound +--- object +---@return seconds +function sound:duration() end + +--- Gets the current playback state of an +--- hs.sound +--- object +---@return boolean +function sound:isPlaying() end + +--- Get or set the looping behaviour of an +--- hs.sound +--- object +--- +--- Note: If you have registered a callback function for completion of a sound's playback, it will not be called when +--- the sound loops +---@param loop boolean|nil +---@return soundObject|boolean +function sound:loopSound(loop) end + +--- Get or set the name of an +--- hs.sound +--- object +--- +--- Note: If remove the sound name by specifying nil , the sound will automatically be set to stop when Hammerspoon is +--- reloaded. +---@param soundName string|nil +---@return soundObject|name string +function sound:name(soundName) end + +--- Pauses an +--- hs.sound +--- object +---@return soundObject|boolean +function sound:pause() end + +--- Plays an +--- hs.sound +--- object +---@return soundObject|boolean +function sound:play() end + +--- Resumes playing a paused +--- hs.sound +--- object +---@return soundObject|boolean +function sound:resume() end + +--- Set or remove the callback for receiving completion notification for the sound object. +--- +--- Note: state - a boolean flag indicating if the sound completed playing. Returns true if playback completes +--- properly, or false if a decoding error occurs or if the sound is stopped early with hs.sound:stop . +--- sound - the soundObject userdata +---@param function function +---@return soundObject +function sound:setCallback(function) end + +--- Stops playing an +--- hs.sound +--- object +---@return soundObject|boolean +function sound:stop() end + +--- Get or set whether a sound should be stopped when Hammerspoon reloads its configuration +--- +--- Note: This method can only be used on a named hs.sound object, see hs.sound:name() +---@param stopOnReload boolean|nil +---@return soundObject|boolean +function sound:stopOnReload(stopOnReload) end + +--- Get or set the playback volume of an +--- hs.sound +--- object +---@param level number +---@return soundObject|number +function sound:volume(level) end + +-- ------------------------------------------------------------ +-- hs.spaces +-- ------------------------------------------------------------ + +---@class hs.spaces +hs.spaces = {} + +--- Specifies how long to delay before performing the accessibility actions for +--- hs.spaces.gotoSpace +--- and +--- hs.spaces.removeSpace +---@type hs.spaces.gotoSpace|hs.spaces.removeSpace +hs.spaces.MCwaitTime = nil + +--- Returns the currently visible (active) space for the specified screen. +---@param screen hs.screen|hs.screen.mainScreen|hs.screen.primaryScreen|nil +---@return number|nil +---@return error +function hs.spaces.activeSpaceOnScreen(screen) end + +--- Returns a key-value table specifying the active spaces for all screens. +--- +--- Note: the table returned has its __tostring metamethod set to hs.inspect to simplify inspecting the results when +--- using the Hammerspoon Console. +---@return table|nil +---@return error +function hs.spaces.activeSpaces() end + +--- Adds a new space on the specified screen +--- +--- Note: This function creates a new space by opening up the Mission Control display and then programmatically +--- invoking the button to add a new space. This is unavoidable. You can minimize, but not entirely remove, the visual +--- shift to the Mission Control display by by enabling "Reduce motion" in System Preferences -> Accessibility -> +--- Display. +--- If you intend to perform multiple actions which require the Mission Control display (( +--- hs.spaces.missionControlSpaceNames , hs.spaces.addSpaceToScreen , hs.spaces.removeSpace , or hs.spaces.gotoSpace ), +--- you can pass in false as the final argument to prevent the automatic closure of the Mission Control display -- this +--- will reduce the visual side-affects to one transition instead of many. +---@param screen hs.screen|hs.screen.mainScreen|hs.screen.primaryScreen|nil +---@param closeMC any +---@return boolean|nil +---@return errMsg +function hs.spaces.addSpaceToScreen(screen, closeMC) end + +--- Returns a Kay-Value table containing the IDs of all spaces for all screens. +--- +--- Note: the table returned has its __tostring metamethod set to hs.inspect to simplify inspecting the results when +--- using the Hammerspoon Console. +---@return table|nil +---@return error +function hs.spaces.allSpaces() end + +--- Opens the Mission Control display +--- +--- Note: Does nothing if the Mission Control display is not currently visible. +--- This function uses Accessibility features provided by the Dock to close Mission Control and is used internally when +--- performing the hs.spaces.gotoSpace , hs.spaces.addSpaceToScreen , and hs.spaces.removeSpace functions. +--- It is possible to invoke the above mentioned functions and prevent them from auto-closing Mission Control -- this +--- may be useful if you wish to perform multiple actions and want to minimize the visual side-effects. You can then +--- use this function when you are done. +function hs.spaces.closeMissionControl() end + +--- Returns a table containing information about the managed display spaces +--- +--- Note: the format and detail of this table is too complex and varied to describe here; suffice it to say this is the +--- workhorse for this module and a careful examination of this table may be informative, but is not required in the +--- normal course of using this module. +---@return table|nil +---@return error +function hs.spaces.data_managedDisplaySpaces() end + +--- Generate a table containing the results of +--- hs.axuielement.buildTree +--- on the Mission Control Accessibility group of the Dock. +--- +--- Note: Like hs.spaces.data_managedDisplaySpaces , this function is not required for general usage of this module; +--- rather it is provided for those who wish to examine the internal data that makes this module possible more closely +--- to see if there might be other information or functionality that they would like to explore. +--- Note that the hs.axuielement objects within the table returned will be invalid by the time you can examine them -- +--- this is why the attributes and values will also be contained in the resulting tree. +--- Example usage: hs.spaces.data_missionControlAXUIElementData(function(results) hs.console.clearConsole() ; +--- print(hs.inspect(results)) end) +---@param callback hs.axuielement.buildTree +function hs.spaces.data_missionControlAXUIElementData(callback) end + +--- Returns the space ID of the currently focused space +--- +--- Note: usually the currently active screen will be returned by hs.screen.mainScreen() ; however some full screen +--- applications may have focus without updating which screen is considered "main". You can use this function, and look +--- up the screen UUID with hs.spaces.spaceDisplay to determine the "true" focused screen if required. +---@return number +function hs.spaces.focusedSpace() end + +--- Change to the specified space. +--- +--- Note: This function changes to a space by opening up the Mission Control display and then programmatically invoking +--- the button to activate the space. This is unavoidable. You can minimize, but not entirely remove, the visual shift +--- to the Mission Control display by by enabling "Reduce motion" in System Preferences -> Accessibility -> Display. +--- The action of changing to a new space automatically closes the Mission Control display, so unlike ( +--- hs.spaces.missionControlSpaceNames , hs.spaces.addSpaceToScreen , and hs.spaces.removeSpace , there is no flag you +--- can specify to leave Mission Control visible. When possible, you should generally invoke this function last if you +--- are performing multiple actions and want to minimize the amount of time the Mission Control display is visible and +--- reduce the visual side affects. +--- The Accessibility elements required to change to a space are not created until the Mission Control display is fully +--- visible. Because of this, there is a built in delay when invoking this function that can be adjusted by changing +--- the value of hs.spaces.MCwaitTime . +---@param spaceID number +---@return boolean|nil +---@return errMsg +function hs.spaces.gotoSpace(spaceID) end + +--- Returns a table containing the space names as they appear in Mission Control associated with their space ID. This +--- is provided for informational purposes only -- all of the functions of this module use the spaceID to insure +--- accuracy. +--- +--- Note: the table returned has its __tostring metamethod set to hs.inspect to simplify inspecting the results when +--- using the Hammerspoon Console. +--- This function works by opening up the Mission Control display and then grabbing the names from the Accessibility +--- elements created. This is unavoidable. You can minimize, but not entirely remove, the visual shift to the Mission +--- Control display by by enabling "Reduce motion" in System Preferences -> Accessibility -> Display. +--- If you intend to perform multiple actions which require the Mission Control display ( +--- hs.spaces.missionControlSpaceNames , hs.spaces.addSpaceToScreen , hs.spaces.removeSpace , or hs.spaces.gotoSpace ), +--- you can pass in false as the final argument to prevent the automatic closure of the Mission Control display -- this +--- will reduce the visual side-affects to one transition instead of many. +--- the desktop or application name(s) as they appear at the top of the Mission Control screen when you invoke it +--- manually (or with hs.spaces.toggleMissionControl() entered into the Hammerspoon console). +--- hs.host.operatingSystemVersionString() +--- hs.host.locale.current() +--- hs.inspect(hs.host.locale.preferredLanguages()) +--- hs.inspect(hs.host.locale.details()) +--- hs.spaces.screensHaveSeparateSpaces() +---@param closeMC any +---@return table|nil +---@return error +function hs.spaces.missionControlSpaceNames(closeMC) end + +--- Moves the window with the specified windowID to the space specified by spaceID. +--- +--- Note: a window can only be moved from a user space to another user space -- you cannot move the window of a full +--- screen (or tiled) application to another space. you also cannot move a window to the same space as a full screen +--- application unless force is set to true and even then it works for floating windows only. +---@param window hs.window +---@param spaceID number +---@param force? boolean|nil +---@return boolean|nil +---@return error +function hs.spaces.moveWindowToSpace(window, spaceID, force) end + +--- Opens the Mission Control display +--- +--- Note: Does nothing if the Mission Control display is already visible. +--- This function uses Accessibility features provided by the Dock to open up Mission Control and is used internally +--- when performing the hs.spaces.gotoSpace , hs.spaces.addSpaceToScreen , and hs.spaces.removeSpace functions. +--- It is unlikely you will need to invoke this by hand, and the public interface to this function may go away in the +--- future. +function hs.spaces.openMissionControl() end + +--- Removes the specified space. +--- +--- Note: You cannot remove a currently active space -- move to another one first with hs.spaces.gotoSpace . +--- If a screen has only one user space (i.e. not a full screen application window or tiled set), it cannot be removed. +--- This function removes a space by opening up the Mission Control display and then programmatically invoking the +--- button to remove the specified space. This is unavoidable. You can minimize, but not entirely remove, the visual +--- shift to the Mission Control display by by enabling "Reduce motion" in System Preferences -> Accessibility -> +--- Display. +--- If you intend to perform multiple actions which require the Mission Control display (( +--- hs.spaces.missionControlSpaceNames , hs.spaces.addSpaceToScreen , hs.spaces.removeSpace , or hs.spaces.gotoSpace ), +--- you can pass in false as the final argument to prevent the automatic closure of the Mission Control display -- this +--- will reduce the visual side-affects to one transition instead of many. +--- The Accessibility elements required to change to a space are not created until the Mission Control display is fully +--- visible. Because of this, there is a built in delay when invoking this function that can be adjusted by changing +--- the value of hs.spaces.MCwaitTime . +---@param spaceID number +---@param closeMC any +---@return boolean|nil +---@return errMsg +function hs.spaces.removeSpace(spaceID, closeMC) end + +--- Determine if the user has enabled the "Displays Have Separate Spaces" option within Mission Control. +---@return boolean +function hs.spaces.screensHaveSeparateSpaces() end + +--- Sets the initial value for +--- hs.spaces.MCwaitTime +--- to be set to when this module first loads. +--- +--- Note: this function uses the hs.settings module to store the default time in the key "hs_spaces_MCwaitTime". +---@param time hs.spaces.MCwaitTime|nil +function hs.spaces.setDefaultMCwaitTime(time) end + +--- Returns the screen UUID for the screen that the specified space is on. +--- +--- Note: the space does not have to be currently active (visible) to determine which screen the space belongs to. +---@param spaceID number +---@return string|nil +---@return error +function hs.spaces.spaceDisplay(spaceID) end + +--- Returns a table containing the IDs of the spaces for the specified screen in their current order. +--- +--- Note: the table returned has its __tostring metamethod set to hs.inspect to simplify inspecting the results when +--- using the Hammerspoon Console. +---@param screen hs.screen|hs.screen.mainScreen|hs.screen.primaryScreen|nil +---@return table|nil +---@return error +function hs.spaces.spacesForScreen(screen) end + +--- Returns a string indicating whether the space is a user space or a full screen/tiled application space. +---@param spaceID number +---@return string|nil +---@return error +function hs.spaces.spaceType(spaceID) end + +--- Toggles the current applications Exposé display +--- +--- Note: this is the same functionality as provided by the System Preferences -> Mission Control -> Hot Corners... -> +--- Application Windows setting or the App Exposé trackpad swipe gesture (3 or 4 fingers down). +function hs.spaces.toggleAppExpose() end + +--- Toggles the Launch Pad display. +--- +--- Note: this is the same functionality as provided by the System Preferences -> Mission Control -> Hot Corners... -> +--- Launch Pad setting, the Launch Pad touchbar icon, or the Launch Pad trackpad swipe gesture (Pinch with thumb and +--- three fingers). +function hs.spaces.toggleLaunchPad() end + +--- Toggles the Mission Control display +--- +--- Note: this is the same functionality as provided by the System Preferences -> Mission Control -> Hot Corners... -> +--- Mission Control setting, the Mission Control touchbar icon, or the Mission Control trackpad swipe gesture (3 or 4 +--- fingers up). +function hs.spaces.toggleMissionControl() end + +--- Toggles moving all windows on/off screen to display the desktop underneath. +--- +--- Note: this is the same functionality as provided by the System Preferences -> Mission Control -> Hot Corners... -> +--- Desktop setting, the Show Desktop touchbar icon, or the Show Desktop trackpad swipe gesture (Spread with thumb and +--- three fingers). +function hs.spaces.toggleShowDesktop() end + +--- Returns a table containing the window IDs of +--- all +--- windows on the specified space +--- +--- Note: the table returned has its __tostring metamethod set to hs.inspect to simplify inspecting the results when +--- using the Hammerspoon Console. +--- The list of windows includes all items which are considered "windows" by macOS -- this includes visual elements +--- usually considered unimportant like overlays, tooltips, graphics, off-screen windows, etc. so expect a lot of false +--- positives in the results. +--- In addition, due to the way Accessibility objects work, only those window IDs that are present on the currently +--- visible spaces will be finable with hs.window or exist within hs.window.allWindows() . +--- This function will prune Hammerspoon canvas elements from the list because we "own" these and can identify their +--- window ID's programmatically. This does not help with other applications, however. +--- as hs.window.filter is scheduled to undergo a re-write soon to (hopefully) dramatically speed it up, I am providing +--- this function as is at present for those who wish to experiment with it; however, I hope to make it more useful in +--- the coming months and the contents may change in the future (the format won't, but hopefully the useless extras +--- will disappear requiring less pruning logic on your end). +---@param spaceID number +---@return table|nil +---@return error +function hs.spaces.windowsForSpace(spaceID) end + +--- Returns a table containing the space IDs for all spaces that the specified window is on. +--- +--- Note: the table returned has its __tostring metamethod set to hs.inspect to simplify inspecting the results when +--- using the Hammerspoon Console. +--- If the window ID does not specify a valid window, then an empty array will be returned. +--- For example, the container windows for hs.canvas objects which have the canJoinAllSpaces behavior set will appear +--- on all spaces and the table returned by this function will contain all spaceIDs for the screen which displays the +--- canvas. +---@param window hs.window +---@return table|nil +---@return error +function hs.spaces.windowSpaces(window) end + +-- ------------------------------------------------------------ +-- hs.spaces.watcher +-- ------------------------------------------------------------ + +---@class hs.spaces.watcher +hs.spaces.watcher = {} + +---@class watcher +local watcher = {} + +--- Creates a new watcher for Space change events +---@param handler function +---@return watcher +function hs.spaces.watcher.new(handler) end + +--- Starts the Spaces watcher +---@return any +function watcher:start() end + +--- Stops the Spaces watcher +---@return any +function watcher:stop() end + +-- ------------------------------------------------------------ +-- hs.speech +-- ------------------------------------------------------------ + +---@class hs.speech +hs.speech = {} + +---@class speech +local speech = {} + +--- Returns a table containing a variety of properties describing and defining the specified voice. +--- +--- Note: All of the names that have been encountered thus far follow this pattern for their full name: +--- com.apple.speech.synthesis.voice.*name* . You can provide this suffix or not as you prefer when specifying a voice +--- name. +---@param voice any +---@return table +function hs.speech.attributesForVoice(voice) end + +--- Returns a list of the currently installed voices for speech synthesis. +--- +--- Note: All of the names that have been encountered thus far follow this pattern for their full name: +--- com.apple.speech.synthesis.voice.*name* . This prefix is normally suppressed unless you pass in true. +---@param full any +---@return array +function hs.speech.availableVoices(full) end + +--- Returns the name of the currently selected default voice for the user. This voice is the voice selected in the +--- System Preferences for Dictation & Speech as the System Voice. +--- +--- Note: All of the names that have been encountered thus far follow this pattern for their full name: +--- com.apple.speech.synthesis.voice.*name* . This prefix is normally suppressed unless you pass in true. +---@param full any +---@return string +function hs.speech.defaultVoice(full) end + +--- Returns whether or not the system is currently using a speech synthesizer in any application to generate speech. +--- +--- Note: See also hs.speech:speaking . +---@return boolean +function hs.speech.isAnyApplicationSpeaking() end + +--- Creates a new speech synthesizer object for use by Hammerspoon. +--- +--- Note: All of the names that have been encountered thus far follow this pattern for their full name: +--- com.apple.speech.synthesis.voice.*name* . You can provide this suffix or not as you prefer when specifying a voice +--- name. +--- You can change the voice later with the hs.speech:voice method. +---@param voice string|nil +---@return synthesizerObject +function hs.speech.new(voice) end + +--- Resumes a paused speech synthesizer. +---@return synthesizerObject +function speech:continue() end + +--- Returns whether or not the synthesizer is currently paused. +--- +--- Note: If an error occurs retrieving this value, the details will be logged in the system logs which can be viewed +--- with the Console application. You can also have such messages logged to the Hammerspoon console by setting the +--- module's log level to at least Information (This can be done with the following, or similar, command: +--- hs.speech.log.level = 3 . See hs.logger for more information) +---@return boolean|nil +function speech:isPaused() end + +--- Returns whether or not the synthesizer is currently speaking, either to an audio device or to a file. +--- +--- Note: If an error occurs retrieving this value, the details will be logged in the system logs which can be viewed +--- with the Console application. You can also have such messages logged to the Hammerspoon console by setting the +--- module's log level to at least Information (This can be done with the following, or similar, command: +--- hs.speech.log.level = 3 . See hs.logger for more information) +---@return boolean|nil +function speech:isSpeaking() end + +--- Gets or sets the pitch modulation for the synthesizer's voice. +--- +--- Note: Pitch modulation is expressed as a floating-point value in the range of 0.000 to 127.000. These values +--- correspond to MIDI note values, where 60.000 is equal to middle C on a piano scale. The most useful speech pitches +--- fall in the range of 40.000 to 55.000. A pitch modulation value of 0.000 corresponds to a monotone in which all +--- speech is generated at the frequency corresponding to the speech pitch. Given a speech pitch value of 46.000, a +--- pitch modulation of 2.000 would mean that the widest possible range of pitches corresponding to the actual +--- frequency of generated text would be 44.000 to 48.000. +--- If an error occurs retrieving or setting this value, the details will be logged in the system logs which can be +--- viewed with the Console application. You can also have such messages logged to the Hammerspoon console by setting +--- the module's log level to at least Information (This can be done with the following, or similar, command: +--- hs.speech.log.level = 3 . See hs.logger for more information) +---@param modulation number|nil +---@return synthesizerObject|modulation|nil +function speech:modulation(modulation) end + +--- Pauses the output of the speech synthesizer. +---@param where any +---@return synthesizerObject +function speech:pause(where) end + +--- Returns the phonemes which would be spoken if the text were to be synthesized. +--- +--- Note: This method only returns a phonetic representation of the text if a Macintalk voice has been selected. The +--- more modern higher quality voices do not use a phonetic representation and an empty string will be returned if this +--- method is used. +--- You can modify the phonetic representation and feed it into hs.speech:speak if you find that the default +--- interpretation is not correct. You will need to set the input mode to Phonetic by prefixing the text with "[[inpt +--- PHON]]". +--- The specific phonetic symbols recognized by a given voice can be queried by examining the array returned by +--- hs.speech:phoneticSymbols after setting an appropriate voice. +---@param text string +---@return string +function speech:phonemes(text) end + +--- Returns an array of the phonetic symbols recognized by the synthesizer for the current voice. +--- +--- Note: Symbol - The textual representation of this phoneme when returned by hs.speech:phonemes or that you +--- should use for this sound when crafting a phonetic string yourself. +--- Opcode - The numeric opcode passed to the callback for the "willSpeakPhoneme" message corresponding to this +--- phoneme. +--- Example - An example word which contains the sound the phoneme represents +--- HiliteEnd - The character position in the Example where this phoneme's sound begins +--- HiliteStart - The character position in the Example where this phoneme's sound ends +--- Only the older, MacinTalk style voices support phonetic text. The more modern, higher quality voices are not +--- rendered phonetically and will return nil for this method. +--- If an error occurs retrieving this value, the details will be logged in the system logs which can be viewed with +--- the Console application. You can also have such messages logged to the Hammerspoon console by setting the module's +--- log level to at least Information (This can be done with the following, or similar, command: hs.speech.log.level = +--- 3 . See hs.logger for more information) +---@return array|nil +function speech:phoneticSymbols() end + +--- Gets or sets the base pitch for the synthesizer's voice. +--- +--- Note: Typical voice frequencies range from around 90 hertz for a low-pitched male voice to perhaps 300 hertz for a +--- high-pitched child’s voice. These frequencies correspond to approximate pitch values in the ranges of 30.000 to +--- 40.000 and 55.000 to 65.000, respectively. +--- If an error occurs retrieving or setting this value, the details will be logged in the system logs which can be +--- viewed with the Console application. You can also have such messages logged to the Hammerspoon console by setting +--- the module's log level to at least Information (This can be done with the following, or similar, command: +--- hs.speech.log.level = 3 . See hs.logger for more information) +---@param pitch number|nil +---@return synthesizerObject|pitch|nil +function speech:pitch(pitch) end + +--- Gets or sets the synthesizers speaking rate (words per minute). +--- +--- Note: The range of supported rates is not predefined by the Speech Synthesis framework; but the synthesizer may +--- only respond to a limited range of speech rates. Average human speech occurs at a rate of 180.0 to 220.0 words per +--- minute. +---@param rate number|nil +---@return synthesizerObject|rate +function speech:rate(rate) end + +--- Reset a synthesizer back to its default state. +--- +--- Note: This method will reset a synthesizer to its default state, including pitch, modulation, volume, rate, etc. +--- The changes go into effect immediately, if queried, but will not affect a synthesis in progress. +--- If an error occurs retrieving or setting this value, the details will be logged in the system logs which can be +--- viewed with the Console application. You can also have such messages logged to the Hammerspoon console by setting +--- the module's log level to at least Information (This can be done with the following, or similar, command: +--- hs.speech.log.level = 3 . See hs.logger for more information) +---@return synthesizerObject|nil +function speech:reset() end + +--- Sets or removes a callback function for the synthesizer. +--- +--- Note: provides 3 additional arguments: startIndex, endIndex, and the full text being spoken. +--- startIndex and endIndex can be used as string.sub(text, startIndex, endIndex) to get the specific word being spoken. +--- provides 1 additional argument: the opcode of the phoneme about to be spoken. +--- this callback message will only occur when using Macintalk voices; modern higher quality voices are not +--- phonetically based and will not generate this message. +--- the opcode can be tied to a specific phoneme by looking it up in the table returned by hs.speech:phoneticSymbols . +--- provides 3 additional arguments: the index in the original text where the error occurred, the text being spoken, +--- and an error message. +--- Special Note: I have never been able to trigger this callback message, even with malformed embedded command +--- sequences, so... looking for validation of the code or fixes. File an issue if you have suggestions. +--- provides 1 additional argument: the synchronization number provided in the text. +--- A synchronization number can be embedded in text to be spoken by including [[sync #]] in the text where you wish +--- the callback to occur. The number is limited to 32 bits and can be presented as a base 10 or base 16 number +--- (prefix with 0x). +--- provides 1 additional argument: a boolean flag indicating whether or not the synthesizer finished because synthesis +--- is complete (true) or was stopped early with hs.speech:stop (false). +---@param fn function +---@return synthesizerObject +function speech:setCallback(fn) end + +--- Starts speaking the provided text through the system's current audio device. +---@param textToSpeak any +---@return synthesizerObject +function speech:speak(textToSpeak) end + +--- Returns whether or not this synthesizer is currently generating speech. +--- +--- Note: See also hs.speech.isAnyApplicationSpeaking . +---@return boolean +function speech:speaking() end + +--- Starts speaking the provided text and saves the audio as an AIFF file. +---@param textToSpeak any +---@param destination any +---@return synthesizerObject +function speech:speakToFile(textToSpeak, destination) end + +--- Stops the output of the speech synthesizer. +---@param where any +---@return synthesizerObject +function speech:stop(where) end + +--- Gets or sets whether or not the synthesizer uses the speech feedback window. +--- +--- Note: Special Note: I am not sure where the visual feedback actually occurs -- I have not been able to locate a +--- feedback window for synthesis in 10.11; however the method is defined and not marked deprecated, so I include it in +--- the module. If anyone has more information, please file an issue and the documentation will be updated. +---@deprecated +---@param flag any +---@return synthesizerObject|boolean +function speech:usesFeedbackWindow(flag) end + +--- Gets or sets the active voice for a synthesizer. +--- +--- Note: All of the names that have been encountered thus far follow this pattern for their full name: +--- com.apple.speech.synthesis.voice.*name* . You can provide this suffix or not as you prefer when specifying a voice +--- name. +--- The voice cannot be changed while the synthesizer is currently producing output. +--- If you change the voice while a synthesizer is paused, the current synthesis will be terminated and the voice will +--- be changed. +---@param full | voice any +---@return synthesizerObject|voice +function speech:voice(full | voice) end + +--- Gets or sets the synthesizers speaking volume. +--- +--- Note: Volume units lie on a scale that is linear with amplitude or voltage. A doubling of perceived loudness +--- corresponds to a doubling of the volume. +---@param volume number|nil +---@return synthesizerObject|volume +function speech:volume(volume) end + +-- ------------------------------------------------------------ +-- hs.speech.listener +-- ------------------------------------------------------------ + +---@class hs.speech.listener +hs.speech.listener = {} + +---@class listener +local listener = {} + +--- Creates a new speech recognizer object for use by Hammerspoon. +--- +--- Note: You can change the title later with the hs.speech.listener:title method. +---@param title string +---@return recognizerObject +function hs.speech.listener.new(title) end + +--- Get or set whether or not the speech recognizer should block other recognizers when it is active. +---@param flag any +---@return recognizerObject +function listener:blocksOtherRecognizers(flag) end + +--- Get or set the commands this speech recognizer will listen for. +--- +--- Note: The list of commands will appear in the Dictation Commands window, if it is visible, under the title of this +--- speech recognizer. The text of each command is a possible value which may be sent as the second argument to a +--- callback function for this speech recognizer, if one is defined. +--- Setting this to an empty list does not disable the speech recognizer, but it does make it of limited use, other +--- than to provide a title in the Dictation Commands window. To disable the recognizer, use the +--- hs.speech.listener:stop or hs.speech.listener:delete methods. +---@param commandsArray strings[]|nil +---@return recognizerObject +function listener:commands(commandsArray) end + +--- Disables the speech recognizer and removes it from the possible available speech recognizers. +--- +--- Note: this disables the speech recognizer and removes it from the list in the Dictation Commands window. The +--- object is effectively destroyed, so you will need to create a new one with hs.speech.listener.new if you want to +--- bring it back. +--- if this was the only speech recognizer currently available, the Dictation Commands window and feedback display will +--- be removed from the users display. +--- this method is automatically called during a reload or restart of Hammerspoon. +---@return recognizerObject +function listener:delete() end + +--- Get or set whether or not the speech recognizer is active only when the Hammerspoon application is active. +---@param flag any +---@return recognizerObject +function listener:foregroundOnly(flag) end + +--- Returns a boolean value indicating whether or not the recognizer is currently enabled (started). +---@return boolean +function listener:isListening() end + +--- Sets or removes a callback function for the speech recognizer. +--- +--- Note: Possible string values for the command spoken are set with the hs.speech.listener:commands method. +--- Removing the callback does not disable the speech recognizer, but it does make it of limited use, other than to +--- provide a list in the Dictation Commands window. To disable the recognizer, use the hs.speech.listener:stop or +--- hs.speech.listener:delete methods. +---@param fn function +---@return recognizerObject +function listener:setCallback(fn) end + +--- Make the speech recognizer active. +---@return recognizerObject +function listener:start() end + +--- Disables the speech recognizer. +--- +--- Note: this only disables the speech recognizer. To completely remove it from the list in the Dictation Commands +--- window, use hs.speech.listener:delete . +---@return recognizerObject +function listener:stop() end + +--- Get or set the title for a speech recognizer. +---@param title string +---@return recognizerObject +function listener:title(title) end + +-- ------------------------------------------------------------ +-- hs.spoons +-- ------------------------------------------------------------ + +---@class hs.spoons +hs.spoons = {} + +--- Map a number of hotkeys according to a definition table +---@param def table +---@param map table|nil +---@return none +function hs.spoons.bindHotkeysToSpec(def, map) end + +--- Check if a given Spoon is installed. +---@param name string +---@return table|nil +function hs.spoons.isInstalled(name) end + +--- Check if a given Spoon is loaded. +---@param name string +---@return boolean|nil +function hs.spoons.isLoaded(name) end + +--- Return a list of installed/loaded Spoons +---@return table +function hs.spoons.list() end + +--- Create a skeleton for a new Spoon +---@param name string +---@param basedir any +---@param metadata table|nil +---@param template any +---@return string|nil +function hs.spoons.newSpoon(name, basedir, metadata, template) end + +--- Return full path of an object within a spoon directory, given its partial path. +---@param partial any +---@return string +function hs.spoons.resourcePath(partial) end + +--- Return path of the current spoon. +---@param n any +---@return string +function hs.spoons.scriptPath(n) end + +--- Declaratively load and configure a Spoon +---@param name string +---@param arg any +---@param noerror any +---@return boolean|nil +function hs.spoons.use(name, arg, noerror) end + +-- ------------------------------------------------------------ +-- hs.spotify +-- ------------------------------------------------------------ + +---@class hs.spotify +hs.spotify = {} + +--- Returned by +--- hs.spotify.getPlaybackState() +--- to indicates Spotify is paused +---@type hs.spotify.getPlaybackState +hs.spotify.state_paused = nil + +--- Returned by +--- hs.spotify.getPlaybackState() +--- to indicates Spotify is playing +---@type hs.spotify.getPlaybackState +hs.spotify.state_playing = nil + +--- Returned by +--- hs.spotify.getPlaybackState() +--- to indicates Spotify is stopped +---@type hs.spotify.getPlaybackState +hs.spotify.state_stopped = nil + +--- Displays information for current track on screen +---@return any +function hs.spotify.displayCurrentTrack() end + +--- Skips the playback position forwards by 5 seconds +---@return any +function hs.spotify.ff() end + +--- Gets the name of the album of the current track +---@return string|nil +function hs.spotify.getCurrentAlbum() end + +--- Gets the name of the artist of the current track +---@return string|nil +function hs.spotify.getCurrentArtist() end + +--- Gets the name of the current track +---@return string|nil +function hs.spotify.getCurrentTrack() end + +--- Gets the artwork URL of the current track +---@return string|nil +function hs.spotify.getCurrentTrackArtworkURL() end + +--- Gets the id of the current track +---@return string|nil +function hs.spotify.getCurrentTrackId() end + +--- Gets the duration (in seconds) of the current song +---@return number +function hs.spotify.getDuration() end + +--- Gets the current playback state of Spotify +---@return hs.spotify.state_stopped|hs.spotify.state_paused|hs.spotify.state_playing +function hs.spotify.getPlaybackState() end + +--- Gets the playback position (in seconds) in the current song +---@return number +function hs.spotify.getPosition() end + +--- Gets the Spotify volume setting +---@return number +function hs.spotify.getVolume() end + +--- Returns whether Spotify is currently playing +---@return boolean|nil +function hs.spotify.isPlaying() end + +--- Returns whether Spotify is currently open. Most other functions in hs.spotify will automatically start the +--- application, so this function can be used to guard against that. +---@return boolean +function hs.spotify.isRunning() end + +--- Skips to the next Spotify track +---@return any +function hs.spotify.next() end + +--- Pauses the current Spotify track +---@return any +function hs.spotify.pause() end + +--- Plays the current Spotify track +---@return any +function hs.spotify.play() end + +--- Toggles play/pause of current Spotify track +---@return any +function hs.spotify.playpause() end + +--- Plays the Spotify track with the given id +---@param id string +---@return any +function hs.spotify.playTrack(id) end + +--- Skips to previous Spotify track +---@return any +function hs.spotify.previous() end + +--- Skips the playback position backwards by 5 seconds +---@return any +function hs.spotify.rw() end + +--- Sets the playback position in the current song +---@param pos number +---@return any +function hs.spotify.setPosition(pos) end + +--- Sets the Spotify volume setting +---@param vol number +---@return any +function hs.spotify.setVolume(vol) end + +--- Reduces the volume by 5 +---@return any +function hs.spotify.volumeDown() end + +--- Increases the volume by 5 +---@return any +function hs.spotify.volumeUp() end + +-- ------------------------------------------------------------ +-- hs.spotlight +-- ------------------------------------------------------------ + +---@class hs.spotlight +hs.spotlight = {} + +---@class spotlight +local spotlight = {} + +--- A list of defined attribute keys as discovered in the macOS 10.12 SDK framework headers. +---@type defined[] +hs.spotlight.commonAttributeKeys[] = nil + +--- A table of key-value pairs describing predefined search scopes for Spotlight queries +---@type table +hs.spotlight.definedSearchScopes[] = nil + +--- Creates a new spotlightObject to use for Spotlight searches. +---@return spotlightObject +function hs.spotlight.new() end + +--- Creates a new spotlightObject that limits its searches to the current results of another spotlightObject. +---@param spotlightObject any +---@return spotlightObject +function hs.spotlight.newWithin(spotlightObject) end + +--- Get or specify the specific messages that should generate a callback. +--- +--- Note: Valid messages for the table are: "didFinish", "didStart", "didUpdate", and "inProgress". See +--- hs.spotlight:setCallback for more details about the messages. +---@param messages function|nil +---@return table|spotlightObject +function spotlight:callbackMessages(messages) end + +--- Returns the number of results for the spotlightObject's query +--- +--- Note: 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. +--- For convenience, metamethods have been added to the spotlightObject which allow you to use #spotlightObject as a +--- shortcut for spotlightObject:count() . +---@return number +function spotlight:count() end + +--- Returns the grouped results for a Spotlight query. +--- +--- Note: 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 indices. +---@return table +function spotlight:groupedResults() end + +--- Get or set the grouping attributes for the Spotlight query. +--- +--- Note: 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. +--- This method allows you to access results grouped by the values of specific attributes. See hs.spotlight.group for +--- more information on using and accessing grouped results. +--- Note that not all attributes can be used as a grouping attribute. In such cases, the grouped result will contain +--- all results and an attribute value of nil. +---@param attributes items[]|nil +---@return table|spotlightObject +function spotlight:groupingAttributes(attributes) end + +--- Returns a boolean specifying whether or not the query is in the active gathering phase. +--- +--- Note: 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. +---@return boolean +function spotlight:isGathering() end + +--- Returns a boolean specifying if the query is active or inactive. +--- +--- Note: 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. +---@return boolean +function spotlight:isRunning() end + +--- Specify the query string for the spotlightObject +--- +--- Note: Setting this property while a query is running stops the query and discards the current results. The receiver +--- immediately starts a new query. +--- 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 +--- If the query string does not conform to an NSPredicate query string, this method will return an error. If the +--- query string does conform to an NSPredicate query string, this method will accept the query string, but if it does +--- not conform to the Metadata query format, which is a subset of the NSPredicate query format, the error will be +--- generated when you attempt to start the query with hs.spotlight:start . At present, starting a query is the only +--- way to fully guarantee that a query is in a valid format. +--- [[ kMDItemContentType == "com.apple.application-bundle" ]] +--- [[ kMDItemFSName like " Explore " ]] +--- [[ kMDItemFSName like "AppleScript Editor.app" or kMDItemAlternateNames like "AppleScript Editor"]] +--- Not all attributes appear to be usable in a query; see hs.spotlight.item:attributes for a possible explanation. +--- As a convenience, the __call metamethod has been setup for spotlightObject so that you can use +--- spotlightObject("query") as a shortcut for spotlightObject:queryString("query"):start . Because this shortcut +--- includes an explicit start, this should be appended after you have set the callback function if you require a +--- callback (e.g. spotlightObject:setCallback(fn)("query") ). +---@param query number +---@return spotlightObject +function spotlight:queryString(query) end + +--- Returns the spotlightItemObject at the specified index of the spotlightObject +--- +--- Note: For convenience, metamethods have been added to the spotlightObject which allow you to use +--- spotlightObject[index] as a shortcut for spotlightObject:resultAtIndex(index) . +---@param index number +---@return spotlightItemObject +function spotlight:resultAtIndex(index) end + +--- Get or set the search scopes allowed for the Spotlight query. +--- +--- Note: Setting this property while a query is running stops the query and discards the current results. The receiver +--- immediately starts a new query. +--- if an item is a string and matches one of the values in the hs.spotlight.definedSearchScopes table, then the scope +--- for that item will be added to the valid search scopes. +--- if an item is a string and does not match one of the predefined values, it is treated as a path on the local system +--- and will undergo tilde prefix expansion befor being added to the search scopes (i.e. "~/" will be expanded to +--- "/Users/username/"). +--- if an item is a table, it will be treated as a file URL table. +---@param scope items[]|nil +---@return table|spotlightObject +function spotlight:searchScopes(scope) end + +--- Set or remove the callback function for the Spotlight search object. +--- +--- Note: obj - the spotlightObject performing the search +--- message - the message to the callback, in this case "didStart" +--- obj - the spotlightObject performing the search +--- message - the message to the callback, in this case "inProgress" +--- kMDQueryUpdateAddedItems - an array table of spotlightItem objects that have been added to the results +--- kMDQueryUpdateChangedItems - an array table of spotlightItem objects that have changed since they were first added +--- to the results +--- kMDQueryUpdateRemovedItems - an array table of spotlightItem objects that have been removed since they were first +--- added to the results +--- obj - the spotlightObject performing the search +--- message - the message to the callback, in this case "didFinish" +--- obj - the spotlightObject performing the search +--- message - the message to the callback, in this case "didUpdate" +--- updateTable - a table containing one or more of the keys described for the updateTable argument of the "inProgress" +--- message. +--- All of the results are always available through the hs.spotlight:resultAtIndex method and metamethod shortcuts +--- described in the hs.spotlight and hs.spotlight.item documentation headers; the results provided by the "didUpdate" +--- and "inProgress" messages are just a convenience and can be used if you wish to parse partial results. +---@param fn function +---@return spotlightObject +function spotlight:setCallback(fn) end + +--- Get or set the sorting preferences for the results of a Spotlight query. +--- +--- Note: Setting this property while a query is running stops the query and discards the current results. The receiver +--- immediately starts a new query. +--- key - a string specifying the attribute to sort by +--- ascending - a boolean, default true, specifying whether the sort order should be ascending (true) or descending +--- (false). +--- This method attempts to specify the sorting order of the results returned by the Spotlight query. +--- Note that not all attributes can be used as an attribute in a sort descriptor. In such cases, the sort descriptor +--- will have no affect on the order of returned items. +---@param attributes items[]|nil +---@return table|spotlightObject +function spotlight:sortDescriptors(attributes) end + +--- Begin the gathering phase of a Spotlight query. +--- +--- Note: 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. +---@return spotlightObject +function spotlight:start() end + +--- Stop the Spotlight query. +--- +--- Note: 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. +---@return spotlightObject +function spotlight:stop() end + +--- Get or set the time interval at which the spotlightObject will send "didUpdate" messages during the initial +--- gathering phase. +---@param interval number|nil +---@return number|spotlightObject +function spotlight:updateInterval(interval) end + +--- Get or set the attributes for which value list summaries are produced for the Spotlight query. +--- +--- Note: 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. +--- This method allows you to specify attributes for which you wish to gather summary information about. See +--- hs.spotlight:valueLists for more information about value list summaries. +--- Note that not all attributes can be used as a value list attribute. In such cases, the summary for the attribute +--- will specify all results and an attribute value of nil. +---@param attributes items[]|nil +---@return table|spotlightObject +function spotlight:valueListAttributes(attributes) end + +--- Returns the value list summaries for the Spotlight query +--- +--- Note: 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. +---@return table +function spotlight:valueLists() end + +-- ------------------------------------------------------------ +-- hs.spotlight.group +-- ------------------------------------------------------------ + +---@class hs.spotlight.group +hs.spotlight.group = {} + +---@class group +local group = {} + +--- Returns the name of the attribute the spotlightGroupObject results are grouped by. +---@return string +function group:attribute() end + +--- Returns the number of query results contained in the spotlightGroupObject. +--- +--- Note: For convenience, metamethods have been added to the spotlightGroupObject which allow you to use +--- #spotlightGroupObject as a shortcut for spotlightGroupObject:count() . +---@return number +function group:count() end + +--- Returns the spotlightItemObject at the specified index of the spotlightGroupObject +--- +--- Note: For convenience, metamethods have been added to the spotlightGroupObject which allow you to use +--- spotlightGroupObject[index] as a shortcut for spotlightGroupObject:resultAtIndex(index) . +---@param index number +---@return spotlightItemObject +function group:resultAtIndex(index) end + +--- Returns the subgroups of the spotlightGroupObject +--- +--- Note: Subgroups are created when you supply more than one grouping attribute to hs.spotlight:groupingAttributes . +---@return table +function group:subgroups() end + +--- Returns the value for the attribute the spotlightGroupObject results are grouped by. +---@return any +function group:value() end + +-- ------------------------------------------------------------ +-- hs.spotlight.item +-- ------------------------------------------------------------ + +---@class hs.spotlight.item +hs.spotlight.item = {} + +---@class item +local item = {} + +--- Returns a list of attributes associated with the spotlightItemObject +--- +--- Note: This list of attributes is usually not a complete list of the attributes available for a given +--- spotlightItemObject. Many of the known attribute names are included in the hs.spotlight.commonAttributeKeys +--- constant array, but even this is not an exhaustive list -- an application may create and assign any key it wishes +--- to an entity for inclusion in the Spotlight metadata database. +--- A common attribute, which is not usually included in the results of this method is the "kMDItemPath" attribute +--- which specifies the local path to the file the entity represents. This is included here for reference, as it is a +--- commonly desired value that is not obviously available for almost all Spotlight entries. +--- It is believed that only those keys which are explicitly set when an item is added to the Spotlight database are +--- included in the array returned by this method. Any attribute which is calculated or restricted in a sandboxed +--- application appears to require an explicit request. This is, however, conjecture, and when in doubt you should +--- explicitly check for the attributes you require with hs.spotlight.item:valueForAttribute and not rely solely on the +--- results from this method. +---@return table +function item:attributes() end + +--- Returns the value for the specified attribute of the spotlightItemObject +--- +--- Note: See hs.spotlight.item:attributes for information about possible attribute names. +--- For convenience, metamethods have been added to the spotlightItemObject which allow you to use +--- spotlightItemObject.attribute as a shortcut for spotlightItemObject:valueForAttribute(attribute) . +---@param attribute string +---@return any +function item:valueForAttribute(attribute) end + +-- ------------------------------------------------------------ +-- hs.streamdeck +-- ------------------------------------------------------------ + +---@class hs.streamdeck +hs.streamdeck = {} + +---@class streamdeck +local streamdeck = {} + +--- Sets/clears a callback for reacting to device discovery events +---@param fn function +---@return any +function hs.streamdeck.discoveryCallback(fn) end + +--- Gets an hs.streamdeck object for the specified device +---@param num number +---@return hs.streamdeck +function hs.streamdeck.getDevice(num) end + +--- Initialises the Stream Deck driver and sets a discovery callback +--- +--- Note: This function must be called before any other parts of this module are used +---@param fn function +---@return any +function hs.streamdeck.init(fn) end + +--- Gets the number of Stream Deck devices connected +---@return number +function hs.streamdeck.numDevices() end + +--- Sets/clears the button callback function for a Stream Deck device +---@param fn function +---@return hs.streamdeck +function streamdeck:buttonCallback(fn) end + +--- Gets the layout of buttons a Stream Deck device has +---@return number +function streamdeck:buttonLayout() end + +--- Sets/clears the knob/encoder callback function for a Stream Deck Plus. +---@param fn function +---@return hs.streamdeck +function streamdeck:encoderCallback(fn) end + +--- Gets the firmware version of a Stream Deck device +---@return string +function streamdeck:firmwareVersion() end + +--- Gets the width and height of the buttons in pixels +---@return table +function streamdeck:imageSize() end + +--- Resets a Stream Deck device +---@return hs.streamdeck +function streamdeck:reset() end + +--- Sets/clears the screen callback function for a Stream Deck Plus's touch screen (above the encoder knobs). +---@param fn function +---@return hs.streamdeck +function streamdeck:screenCallback(fn) end + +--- Gets the serial number of a Stream Deck device +---@return string +function streamdeck:serialNumber() end + +--- Sets the brightness of a Stream Deck device +---@param brightness number +---@return hs.streamdeck +function streamdeck:setBrightness(brightness) end + +--- Sets a button on the Stream Deck device to the specified color +---@param button number +---@param color hs.drawing.color +---@return hs.streamdeck +function streamdeck:setButtonColor(button, color) end + +--- Sets the image of a button on the Stream Deck device +---@param button number +---@param image hs.image +---@return hs.streamdeck +function streamdeck:setButtonImage(button, image) end + +--- Sets the image of the screen on the Stream Deck device +---@param encoder number +---@param image hs.image +---@return hs.streamdeck +function streamdeck:setScreenImage(encoder, image) end + +-- ------------------------------------------------------------ +-- hs.styledtext +-- ------------------------------------------------------------ + +---@class hs.styledtext +hs.styledtext = {} + +---@class styledtext +local styledtext = {} + +---@class hs.styledtext.styledtext +---@field defaultFonts any A table containing the system default fonts and sizes. +---@field fontTraits -> table any A table for containing Font Trait masks for use with hs.styledtext.fontNamesWithTraits(...) +---@field lineAppliesTo any A table of values indicating how the line for underlining or strike-through are applied to the text. +---@field linePatterns any A table of patterns which apply to the line for underlining or strike-through. +---@field lineStyles any A table of styles which apply to the line for underlining or strike-through. + +--- A table containing the system default fonts and sizes. +---@type table +hs.styledtext.defaultFonts = nil + +--- A table for containing Font Trait masks for use with +--- hs.styledtext.fontNamesWithTraits(...) +---@type table +hs.styledtext.fontTraits -> table = nil + +--- A table of values indicating how the line for underlining or strike-through are applied to the text. +---@type table +hs.styledtext.lineAppliesTo = nil + +--- A table of patterns which apply to the line for underlining or strike-through. +---@type table +hs.styledtext.linePatterns = nil + +--- A table of styles which apply to the line for underlining or strike-through. +---@type table +hs.styledtext.lineStyles = nil + +--- Returns the font which most closely matches the given font and the trait change requested. +---@param fontTable any +---@param trait number +---@return table +function hs.styledtext.convertFont(fontTable, trait) end + +--- Returns the names of all font families installed for the system. +---@return table +function hs.styledtext.fontFamilies() end + +--- Get information about the font Specified in the attributes table. +---@param font any +---@return table +function hs.styledtext.fontInfo(font) end + +--- Returns the names of all installed fonts for the system. +---@return table +function hs.styledtext.fontNames() end + +--- Returns the names of all installed fonts for the system with the specified traits. +--- +--- Note: specifying 0 or an empty table will match all fonts that are neither italic nor bold. This would be the same +--- list as you'd get with { hs.styledtext.fontTraits.unBold, hs.styledtext.fontTraits.unItalic } as the parameter. +---@param fontTraitMask any +---@return table +function hs.styledtext.fontNamesWithTraits(fontTraitMask) end + +--- Get the path of a font. +---@param font string +---@return table +function hs.styledtext.fontPath(font) end + +--- Returns an array containing fonts available for the specified font family or nil if no fonts for the specified +--- family are present. +---@param familyName string +---@return table +function hs.styledtext.fontsForFamily(familyName) end + +--- Loads a font from a file at the specified path. +---@param path string +---@return boolean +---@return string +function hs.styledtext.loadFont(path) end + +--- Checks to see if a font is valid. +---@param font string +---@return boolean +function hs.styledtext.validFont(font) end + +--- Create an +--- hs.styledtext +--- object from the string provided, converting ANSI SGR color and some font sequences into the appropriate attributes. +--- Attributes to apply to the resulting string may also be optionally provided. +--- +--- Note: Because a font is required for the SGR sequences indicating Bold and Italic, the base font is determined +--- using the following logic: +--- if no attributes table is provided, the font is assumed to be the default for hs.drawing as returned by the +--- hs.drawing.defaultTextStyle function +--- if an attributes table is provided and it defines a font attribute, this font is used. +--- if an attributes table is provided, but it does not provide a font attribute, the NSAttributedString default of +--- Helvetica at 12 points is used. +--- As the most common use of this constructor is likely to be from the output of a terminal shell command, you will +--- most likely want to specify a fixed-pitch (monospace) font. You can get a list of installed fixed-pitch fonts by +--- typing hs.styledtext.fontNamesWithTraits(hs.styledtext.fontTraits.fixedPitchFont) into the Hammerspoon console. +--- See the module description documentation ( help.hs.styledtext ) for a description of the attributes table format +--- which can be provided for the optional second argument. +--- This function was modeled after the ANSIEscapeHelper.m file at https://github.com/balthamos/geektool-3 in the +--- /NerdTool/classes directory. +---@param string string +---@param attributes hs.styledtext|nil +---@return styledText +function hs.styledtext.ansi(string, attributes) end + +--- Converts the provided data into a styled text string. +--- +--- Note: See also hs.styledtext.getStyledTextFromFile +---@param data string +---@param type any +---@return styledText +function hs.styledtext.getStyledTextFromData(data, type) end + +--- Converts the data in the specified file into a styled text string. +--- +--- Note: See also hs.styledtext.getStyledTextFromData +---@param file any +---@param type any +---@return styledText +function hs.styledtext.getStyledTextFromFile(file, type) end + +--- Create an +--- hs.styledtext +--- object from the string or table representation provided. Attributes to apply to the resulting string may also be +--- optionally provided. +--- +--- Note: See hs.styledtext:asTable for a description of the table representation of an hs.styledtext object +--- See the module description documentation ( help.hs.styledtext ) for a description of the attributes table format +--- which can be provided for the optional second argument. +--- Passing an hs.styledtext object as the first parameter without specifying an attributes table is the equivalent of +--- invoking hs.styledtext:copy . +---@param string string +---@param attributes hs.styledtext|nil +---@return styledText +function hs.styledtext.new(string, attributes) end + +--- Returns the table representation of the +--- hs.styledtext +--- object or its specified substring. +--- +--- Note: starts and ends follow the conventions of i and j for Lua's string.sub function. +--- The attribute which contains an attachment (image) for a converted RTFD or other document is known to set the +--- unsupportedFields flag. +--- The indexes in the table returned are relative to their position in the original hs.styledtext object. If you want +--- the table version of a substring which does not start at index position 1 that can be safely fed as a "proper" +--- table version of an hs.styledtext object into another function or constructor, the proper way to generate it is +--- `destination = object:sub(i,j):asTable(). +--- See the module description documentation ( help.hs.styledtext ) for a description of the attributes table format +---@param starts hs.styledtext|nil +---@param ends hs.styledtext|nil +---@return table +function styledtext:asTable(starts, ends) end + +--- Returns the internal numerical representation of the characters in the +--- hs.styledtext +--- object specified by the given indices. Mimics the Lua +--- string.byte +--- function. +--- +--- Note: starts and ends follow the conventions of i and j for Lua's string.sub function. +---@param starts hs.styledtext|nil +---@param ends hs.styledtext|nil +---@return number +---@return .. +function styledtext:byte(starts, ends) end + +--- Converts the styledtext object into the data format specified. +---@param type any +---@return string +function styledtext:convert(type) end + +--- Create a copy of the +--- hs.styledtext +--- object. +---@param styledText hs.styledtext +---@return styledText +function styledtext:copy(styledText) end + +--- Returns the indices of the first occurrence of the specified pattern in the text of the +--- hs.styledtext +--- object. Mimics the Lua +--- string.find +--- function. +--- +--- Note: Any captures returned are returned as Lua Strings, not as hs.styledtext objects. +---@param pattern string +---@param init number|nil +---@param plain any +---@return start +---@return end +---@return ...|nil +function styledtext:find(pattern, init, plain) end + +--- Returns the text of the +--- hs.styledtext +--- object as a Lua String +--- +--- Note: starts and ends follow the conventions of i and j for Lua's string.sub function. +---@param starts hs.styledtext|nil +---@param ends hs.styledtext|nil +---@return string +function styledtext:getString(starts, ends) end + +--- Returns an iterator function which will return the captures (or the entire pattern) of the next match of the +--- specified pattern in the text of the +--- hs.styledtext +--- object each time it is called. Mimics the Lua +--- string.gmatch +--- function. +--- +--- Note: Any captures (or the entire pattern) returned by the iterator are returned as Lua Strings, not as +--- hs.styledtext objects. +---@param pattern string +---@return iterator-function +function styledtext:gmatch(pattern) end + +--- Determine if the +--- styledText +--- object is identical to the one specified. +--- +--- Note: comparing two hs.styledtext objects with the == operator only compares whether or not the string values are +--- identical. This method also compares their attributes. +---@param styledText hs.styledtext +---@return boolean +function styledtext:isIdentical(styledText) end + +--- Returns the length of the text of the +--- hs.styledtext +--- object. Mimics the Lua +--- string.len +--- function. +---@return number +function styledtext:len() end + +--- Returns a copy of the +--- hs.styledtext +--- object with all alpha characters converted to lower case. Mimics the Lua +--- string.lower +--- function. +---@return styledText +function styledtext:lower() end + +--- Returns the first occurrence of the captures in the specified pattern (or the complete pattern, if no captures are +--- specified) in the text of the +--- hs.styledtext +--- object. Mimics the Lua +--- string.match +--- function. +--- +--- Note: Any captures (or the entire pattern) returned are returned as Lua Strings, not as hs.styledtext objects. +---@param pattern string +---@param init number|nil +---@return match ...|nil +function styledtext:match(pattern, init) end + +--- Return a copy of the +--- hs.styledtext +--- object containing the changes to its attributes specified in the +--- attributes +--- table. +--- +--- Note: starts and ends follow the conventions of i and j for Lua's string.sub function. +--- See the module description documentation ( help.hs.styledtext ) for a list of officially recognized attribute label +--- names. +--- The officially recognized attribute labels were chosen for brevity or for consistency with conventions used in +--- Hammerspoon's other modules. If you know the Objective-C name for an attribute, you can list it instead of an +--- officially recognized label, allowing the removal of attributes which this module cannot manipulate in other ways. +---@param attributes hs.styledtext +---@param starts hs.styledtext|nil +---@param ends hs.styledtext|nil +---@return styledText +function styledtext:removeStyle(attributes, starts, ends) end + +--- Returns an +--- hs.styledtext +--- object which contains +--- n +--- repetitions of the +--- hs.styledtext +--- object, optionally with +--- separator +--- between each repetition. Mimics the Lua +--- string.rep +--- function. +---@param n number +---@param separator hs.styledtext|nil +---@return styledText +function styledtext:rep(n, separator) end + +--- Return a copy of the +--- hs.styledtext +--- object containing the changes to its attributes specified in the +--- attributes +--- table. +--- +--- Note: starts and ends follow the conventions of i and j for Lua's string.sub function except that starts must refer +--- to an index preceding or equal to ends , even after negative and out-of-bounds indices are adjusted for. +--- See the module description documentation ( help.hs.styledtext ) for a description of the attributes table format +---@param string string +---@param starts hs.styledtext|nil +---@param ends hs.styledtext|nil +---@param clear any +---@return styledText +function styledtext:setString(string, starts, ends, clear) end + +--- Return a copy of the +--- hs.styledtext +--- object containing the changes to its attributes specified in the +--- attributes +--- table. +--- +--- Note: starts and ends follow the conventions of i and j for Lua's string.sub function. +--- See the module description documentation ( help.hs.styledtext ) for a description of the attributes table format +---@param attributes table +---@param starts hs.styledtext|nil +---@param ends hs.styledtext|nil +---@param clear any +---@return styledText +function styledtext:setStyle(attributes, starts, ends, clear) end + +--- Returns a substring, including the style attributes, specified by the given indices from the +--- hs.styledtext +--- object. Mimics the Lua +--- string.sub +--- function. +--- +--- Note: starts and ends follow the conventions of i and j for Lua's string.sub function. +---@param starts hs.styledtext +---@param ends hs.styledtext|nil +---@return styledText +function styledtext:sub(starts, ends) end + +--- Returns a copy of the +--- hs.styledtext +--- object with all alpha characters converted to upper case. Mimics the Lua +--- string.upper +--- function. +---@return styledText +function styledtext:upper() end + +-- ------------------------------------------------------------ +-- hs.tabs +-- ------------------------------------------------------------ + +---@class hs.tabs +hs.tabs = {} + +--- Places all the windows of an app into one place and tab them +---@param app hs.application +---@return any +function hs.tabs.enableForApp(app) end + +--- Focuses a specific tab of an app +--- +--- Note: If num is higher than the number of tabs, the last tab will be focussed +---@param app hs.application +---@param num number +---@return any +function hs.tabs.focusTab(app, num) end + +--- Gets a list of the tabs of a window +--- +--- Note: This function can be used when writing tab switchers +---@param app hs.application +---@return the[] +function hs.tabs.tabWindows(app) end + +-- ------------------------------------------------------------ +-- hs.tangent +-- ------------------------------------------------------------ + +---@class hs.tangent +hs.tangent = {} + +---@class hs.tangent.tangent +---@field fromHub -> table any Definitions for IPC Commands from the HUB to Hammerspoon. +---@field panelType -> table any Tangent Panel Types. +---@field toHub -> table any Definitions for IPC Commands from Hammerspoon to the HUB. + +--- Definitions for reserved action IDs. +---@type any +hs.tangent.reserved.action -> table = nil + +--- Definitions for IPC Commands from the HUB to Hammerspoon. +---@type any +hs.tangent.fromHub -> table = nil + +--- Tangent Panel Types. +---@type any +hs.tangent.panelType -> table = nil + +--- A table of reserved parameter IDs. +---@type table +hs.tangent.reserved.parameter -> table = nil + +--- Definitions for IPC Commands from Hammerspoon to the HUB. +---@type any +hs.tangent.toHub -> table = nil + +--- Automatically send the "Application Definition" response. Defaults to +--- true +--- . +---@type any +hs.tangent.automaticallySendApplicationDefinition -> boolean = nil + +--- IP Address that the Tangent Hub is located at. Defaults to 127.0.0.1. +---@type any +hs.tangent.ipAddress -> number = nil + +--- The port that Tangent Hub monitors. Defaults to 64246. +---@type any +hs.tangent.port -> number = nil + +--- Sets a callback when new messages are received. +--- +--- Note: Full documentation for the Tangent API can be downloaded here . +--- The callback function should expect 1 argument and should not return anything. +--- id - the message ID of the incoming message +--- metadata - A table of data for the Tangent command (see below). +--- connected - Connection to Tangent Hub successfully established. +--- disconnected - The connection to Tangent Hub was dropped. +--- protocolRev - The revision number of the protocol. +--- numPanels - The number of panels connected. +--- panelID - The ID of the panel. +--- panelType - The type of panel connected. +--- data - The raw data from the Tangent Hub +--- paramID - The ID value of the parameter. +--- increment - The incremental value which should be applied to the parameter. +--- paramID - The ID value of the parameter. +--- paramID - The ID value of the parameter. +--- menuID - The ID value of the menu. +--- increment - The incremental amount by which the menu index should be changed which will always be an integer value +--- of +1 or -1. +--- menuID - The ID value of the menu. +--- menuID - The ID value of the menu. +--- actionID - The ID value of the action. +--- modeID - The ID value of the mode. +--- jogValue - The number of jog steps to move the transport. +--- shuttleValue - An incremental value to add to the shuttle speed. +--- actionID - The ID value of the action. +--- panelID - The ID of the panel as reported in the InitiateComms command. +--- numButtons - The number of buttons on the panel. +--- numEncoders - The number of encoders on the panel. +--- numDisplays - The number of displays on the panel. +--- numDisplayLines - The number of lines for each display on the panel. +--- numDisplayChars - The number of characters on each line of each display on the panel. +--- panelID - The ID of the panel as reported in the InitiateComms command. +--- buttonID - The hardware ID of the button +--- panelID - The ID of the panel as reported in the InitiateComms command. +--- buttonID - The hardware ID of the button. +--- panelID - The ID of the panel as reported in the InitiateComms command. +--- paramID - The hardware ID of the encoder. +--- increment - The incremental value. +--- panelID - The ID of the panel as reported in the InitiateComms command. +--- panelID - The ID of the panel as reported in the InitiateComms command. +--- state - The connected state of the panel, true if connected, false if disconnected. +---@return boolean +function hs.tangent.callback() end + +--- Connects to the Tangent Hub. +---@param applicationName string +---@param systemPath string +---@param userPath? string +---@return boolean +---@return errorMessage +function hs.tangent.connect(applicationName, systemPath, userPath) end + +--- Checks to see whether or not you're successfully connected to the Tangent Hub. +---@return boolean +function hs.tangent.connected() end + +--- Disconnects from the Tangent Hub. +---@return none +function hs.tangent.disconnect() end + +--- Checks to see whether or not the Tangent Hub software is installed. +---@return boolean +function hs.tangent.isTangentHubInstalled() end + +--- Sends a "bytestring" message to the Tangent Hub. +--- +--- Note: This should be a full encoded string for the command you want to send, withouth the leading 'size' section, +--- which the function will calculate automatically. +--- In general, you should use the more specific functions that package the command for you, such as +--- sendParameterValue(...) . This function can be used to send a message that this API doesn't yet support. +--- Full documentation for the Tangent API can be downloaded here . +---@param byteString string +---@return boolean +---@return string +function hs.tangent.send(byteString) end + +--- Tells the Hub that a large number of software-controls have changed. +--- +--- Note: The Hub responds by requesting all the current values of software-controls it is currently controlling. +---@return boolean +---@return string +function hs.tangent.sendAllChange() end + +--- Sends the application details to the Tangent Hub. +--- +--- Note: If no details are provided the ones stored in the module are used. +---@param appName string +---@param systemPath string +---@param userPath string +---@return boolean +---@return string +function hs.tangent.sendApplicationDefinition(appName, systemPath, userPath) end + +--- Updates the Hub with a number of character strings that will be displayed on connected panels if there is space. +--- +--- Note: Strings may either be 32 character, single height or 16 character double-height. They will be displayed in +--- the order received; the first string displayed at the top of the display. +--- If a string is not defined as double-height then it will occupy the next line. +--- If a string is defined as double-height then it will occupy the next 2 lines. +--- The maximum number of lines which will be used by the application must be indicated in the Controls XML file. +--- Text which exceeds 32 (single-height) or 16 (double-height) characters will be truncated. +--- If all text is single-height, the doubleHeight table can be omitted. +---@param messages messages[] +---@param doubleHeight? boolean[]|nil +---@return boolean +---@return string +function hs.tangent.sendDisplayText(messages, doubleHeight) end + +--- Highlights the control on any panel where this feature is available. +--- +--- Note: When applied to Modes, buttons which are mapped to the reserved "Go To Mode" action for this particular mode +--- will highlight. +---@param targetID string +---@param active any +---@return boolean +---@return string +function hs.tangent.sendHighlightControl(targetID, active) end + +--- Sets the Indicator of the control on any panel where this feature is available. +--- +--- Note: This indicator is driven by the atDefault argument for Parameters and Menus. This command therefore only +--- applies to controls mapped to Actions and Modes. +--- When applied to Modes, buttons which are mapped to the reserved "Go To Mode" action for this particular mode will +--- have their indicator set. +---@param targetID string +---@param indicated any +---@return boolean +---@return string +function hs.tangent.sendIndicateControl(targetID, indicated) end + +--- Updates the Hub with a menu value. +--- +--- Note: The Hub then updates the displays of any panels which are currently showing the menu. +--- If a value of nil is sent then the Hub will not attempt to display a value for the menu. However the atDefault flag +--- will still be recognised. +---@param menuID string +---@param value string +---@param atDefault? any +---@return boolean +---@return string +function hs.tangent.sendMenuString(menuID, value, atDefault) end + +--- Updates the Hub with a mode value. +--- +--- Note: The Hub then changes mode and requests all the current values of software-controls it is controlling. +---@param modeID string +---@return boolean +---@return string +function hs.tangent.sendModeValue(modeID) end + +--- Requests the Hub to respond with a sequence of PanelConnectionState (0x35) commands to report the +--- connected/disconnected status of each configured panel +--- +--- Note: A single request may result in multiple state responses. +---@return any +function hs.tangent.sendPanelConnectionStatesRequest() end + +--- Updates the Hub with a parameter value. +--- +--- Note: The Hub then updates the displays of any panels which are currently showing the parameter value. +---@param paramID string +---@param value any +---@param atDefault? any +---@return boolean +---@return string +function hs.tangent.sendParameterValue(paramID, value, atDefault) end + +--- Renames a control dynamically. +--- +--- Note: The string supplied will replace the normal text which has been derived from the Controls XML file. +--- To remove any existing replacement name set newName to "" , this will remove any renaming and return the system to +--- the normal display text +--- When applied to Modes, the string displayed on buttons which mapped to the reserved "Go To Mode" action for this +--- particular mode will also change. +---@param targetID string +---@param newName string +---@return boolean +---@return string +function hs.tangent.sendRenameControl(targetID, newName) end + +--- Updates the Hub with text that will be displayed on a specific panel at the given line and starting position where +--- supported by the panel capabilities. +--- +--- Note: Only used when working in Unmanaged panel mode. +--- If the most significant bit of any individual text character in message is set it will be displayed as inversed +--- with dark text on a light background. +---@param panelID string +---@param displayID string +---@param lineNum number +---@param pos any +---@param message string +---@return boolean +---@return string +function hs.tangent.sendUnmanagedDisplayWrite(panelID, displayID, lineNum, pos, message) end + +--- Requests the Hub to respond with an UnmanagedPanelCapabilities (0x30) command. +--- +--- Note: Only used when working in Unmanaged panel mode +---@param panelID string +---@return boolean +---@return string +function hs.tangent.sendUnmanagedPanelCapabilitiesRequest(panelID) end + +--- Sets the Log Level. +---@param loglevel number +---@return none +function hs.tangent.setLogLevel(loglevel) end + +-- ------------------------------------------------------------ +-- hs.task +-- ------------------------------------------------------------ + +---@class hs.task +hs.task = {} + +---@class task +local task = {} + +--- Creates a new hs.task object +--- +--- Note: The arguments are not processed via a shell, so you do not need to do any quoting or escaping. They are +--- passed to the executable exactly as provided. +--- When using a stream callback, the callback may be invoked one last time after the termination callback has already +--- been invoked. In this case, the task argument to the stream callback will be nil rather than the task userdata +--- object and the return value of the stream callback will be ignored. +---@param launchPath string +---@param callbackFn any +---@param streamCallbackFn? any +---@param arguments? table|nil +---@return hs.task +function hs.task.new(launchPath, callbackFn, streamCallbackFn, arguments) end + +--- Closes the task's stdin +--- +--- Note: This should only be called on tasks with a streaming callback - tasks without it will automatically close +--- stdin when any data supplied via hs.task:setInput() has been written +--- This is primarily useful for sending EOF to long-running tasks +---@return hs.task +function task:closeInput() end + +--- Returns the environment variables as a table for the task. +--- +--- Note: if you have not yet set an environment table with the hs.task:setEnvironment method, this method will return +--- a copy of the Hammerspoon environment table, as this is what the task will inherit by default. +---@return environment +function task:environment() end + +--- Interrupts the task +--- +--- Note: This will send SIGINT to the process +---@return hs.task +function task:interrupt() end + +--- Test if a task is still running. +--- +--- Note: A task which has not yet been started yet will also return false. +---@return boolean +function task:isRunning() end + +--- Pauses the task +--- +--- Note: If the task is not paused, the error message will be printed to the Hammerspoon Console +--- This method can be called multiple times, but a matching number of hs.task:resume() calls will be required to allow +--- the process to continue +---@return boolean +function task:pause() end + +--- Gets the PID of a running/finished task +--- +--- Note: The PID will still be returned if the task has already completed and the process terminated +---@return number +function task:pid() end + +--- Resumes the task +--- +--- Note: If the task is not resumed successfully, the error message will be printed to the Hammerspoon Console +---@return boolean +function task:resume() end + +--- Set or remove a callback function for a task. +---@param fn function|nil +---@return hs.task +function task:setCallback(fn) end + +--- Sets the environment variables for the task. +--- +--- Note: If you do not set an environment table with this method, the task will inherit the environment variables of +--- the Hammerspoon application. Set this to an empty table if you wish for no variables to be set for the task. +---@param environment table +---@return hs.task|boolean +function task:setEnvironment(environment) end + +--- Sets the standard input data for a task +--- +--- Note: This method can be called before the task has been started, to prepare some input for it (particularly if it +--- is not a streaming task) +--- If this method is called multiple times, any input that has not been passed to the task already, is discarded (for +--- streaming tasks, the data is generally consumed very quickly, but for now there is no way to synchronize this) +---@param inputData string +---@return hs.task +function task:setInput(inputData) end + +--- Set a stream callback function for a task +--- +--- Note: For information about the requirements of the callback function, see hs.task.new() +--- If a callback is removed without it previously having returned false, any further stdout/stderr output from the +--- task will be silently discarded +---@param fn function|nil +---@return hs.task +function task:setStreamingCallback(fn) end + +--- Sets the working directory for the task. +--- +--- Note: You can only set the working directory if the task has not already been started. +--- This will only set the directory that the task starts in. The task itself can change the directory while it is +--- running. +---@param path string +---@return hs.task|boolean +function task:setWorkingDirectory(path) end + +--- Starts the task +--- +--- Note: If the task does not start successfully, the error message will be printed to the Hammerspoon Console +---@return hs.task|boolean +function task:start() end + +--- Terminates the task +--- +--- Note: This will send SIGTERM to the process +---@return hs.task +function task:terminate() end + +--- Returns the termination reason for a task, or false if the task is still running. +---@return exitCode|boolean +function task:terminationReason() end + +--- Returns the termination status of a task, or false if the task is still running. +---@return exitCode|boolean +function task:terminationStatus() end + +--- Blocks Hammerspoon until the task exits +--- +--- Note: All Lua and Hammerspoon activity will be blocked by this method. Its use is highly discouraged. +---@return hs.task +function task:waitUntilExit() end + +--- Returns the working directory for the task. +--- +--- Note: This only returns the directory that the task starts in. If the task changes the directory itself, this +--- value will not reflect that change. +---@return path +function task:workingDirectory() end + +-- ------------------------------------------------------------ +-- hs.timer +-- ------------------------------------------------------------ + +---@class hs.timer +hs.timer = {} + +---@class timer +local timer = {} + +--- Returns the absolute time in nanoseconds since the last system boot. +--- +--- Note: this value does not include time that the system has spent asleep +--- this value is used for the timestamps in system generated events. +---@return nanoseconds +function hs.timer.absoluteTime() end + +--- Converts days to seconds +---@param n number +---@return sec +function hs.timer.days(n) end + +--- Converts hours to seconds +---@param n number +---@return seconds +function hs.timer.hours(n) end + +--- Returns the number of seconds since local time midnight +---@return number +function hs.timer.localTime() end + +--- Converts minutes to seconds +---@param n number +---@return seconds +function hs.timer.minutes(n) end + +--- Converts a string with a time of day or a duration into number of seconds +---@param timeOrDuration number +---@return seconds +function hs.timer.seconds(timeOrDuration) end + +--- Gets the (fractional) number of seconds since the UNIX epoch (January 1, 1970) +--- +--- Note: This has much better precision than os.time() , which is limited to whole seconds. +---@return sec +function hs.timer.secondsSinceEpoch() end + +--- Blocks Lua execution for the specified time +--- +--- Note: Use of this function is strongly discouraged, as it blocks all main-thread execution in Hammerspoon. This +--- means no hotkeys or events will be processed in that time, no GUI updates will happen, and no Lua will execute. +--- This is only provided as a last resort, or for extremely short sleeps. For all other purposes, you really should be +--- splitting up your code into multiple functions and calling hs.timer.doAfter() +---@param microsecs number +---@return any +function hs.timer.usleep(microsecs) end + +--- Converts weeks to seconds +---@param n number +---@return sec +function hs.timer.weeks(n) end + +--- Calls a function after a delay +--- +--- Note: There is no need to call :start() on the returned object, the timer will be already running. +--- The callback can be cancelled by calling the :stop() method on the returned object before sec seconds have passed. +---@param sec number +---@param fn function +---@return timer +function hs.timer.doAfter(sec, fn) end + +--- Creates and starts a timer which will perform +--- fn +--- at the given (local) +--- time +--- and then (optionally) repeat it every +--- interval +--- . +--- +--- Note: The timer can trigger up to 1 second early or late +--- If it's 19:00, hs.timer.doAt("20:00",somefn) will set the timer 1 hour from now +--- If it's 21:00, hs.timer.doAt("20:00",somefn) will set the timer 23 hours from now +--- If it's 21:00, hs.timer.doAt("20:00","6h",somefn) will set the timer 5 hours from now (at 02:00) +--- To run a job every hour on the hour from 8:00 to 20:00: for h=8,20 do hs.timer.doAt(h..":00","1d",runJob) end +---@param time number +---@param repeatInterval? number +---@param fn? function +---@param continueOnError? function|nil +---@return timer +function hs.timer.doAt(time, repeatInterval, fn, continueOnError) end + +--- Repeats fn every interval seconds. +--- +--- Note: This function is a shorthand for hs.timer.new(interval, fn):start() +---@param interval number +---@param fn function +---@return timer +function hs.timer.doEvery(interval, fn) end + +--- Creates and starts a timer which will perform +--- actionFn +--- every +--- checkinterval +--- seconds until +--- predicateFn +--- returns true. The timer is automatically stopped when +--- predicateFn +--- returns true. +--- +--- Note: The timer is passed as an argument to actionFn so that it may stop the timer prematurely (i.e. before +--- predicateFn returns true) if desired. +--- See also hs.timer.doWhile , which is essentially the opposite of this function +---@param predicateFn function +---@param actionFn function +---@param checkInterval? number +---@return timer +function hs.timer.doUntil(predicateFn, actionFn, checkInterval) end + +--- Creates and starts a timer which will perform +--- actionFn +--- every +--- checkinterval +--- seconds while +--- predicateFn +--- returns true. The timer is automatically stopped when +--- predicateFn +--- returns false. +--- +--- Note: The timer is passed as an argument to actionFn so that it may stop the timer prematurely (i.e. before +--- predicateFn returns false) if desired. +--- See also hs.timer.doUntil , which is essentially the opposite of this function +---@param predicateFn function +---@param actionFn function +---@param checkInterval? number +---@return timer +function hs.timer.doWhile(predicateFn, actionFn, checkInterval) end + +--- Creates a new +--- hs.timer +--- object for repeating interval callbacks +--- +--- Note: The returned object does not start its timer until its :start() method is called +--- If interval is 0, the timer will not repeat (because if it did, it would be repeating as fast as your machine can +--- manage, which seems generally unwise) +--- For non-zero intervals, the lowest acceptable value for the interval is 0.00001s. Values >0 and <0.00001 will be +--- coerced to 0.00001 +---@param interval number +---@param fn function +---@param continueOnError? function|nil +---@return timer +function hs.timer.new(interval, fn, continueOnError) end + +--- Creates and starts a timer which will perform +--- actionFn +--- when +--- predicateFn +--- returns true. The timer is automatically stopped when +--- actionFn +--- is called. +--- +--- Note: The timer is stopped before actionFn is called, but the timer is passed as an argument to actionFn so that +--- the actionFn may restart the timer to be called again the next time predicateFn returns true. +--- See also hs.timer.waitWhile , which is essentially the opposite of this function +---@param predicateFn function +---@param actionFn function +---@param checkInterval? number +---@return timer +function hs.timer.waitUntil(predicateFn, actionFn, checkInterval) end + +--- Creates and starts a timer which will perform +--- actionFn +--- when +--- predicateFn +--- returns false. The timer is automatically stopped when +--- actionFn +--- is called. +--- +--- Note: The timer is stopped before actionFn is called, but the timer is passed as an argument to actionFn so that +--- the actionFn may restart the timer to be called again the next time predicateFn returns false. +--- See also hs.timer.waitUntil , which is essentially the opposite of this function +---@param predicateFn function +---@param actionFn function +---@param checkInterval? number +---@return timer +function hs.timer.waitWhile(predicateFn, actionFn, checkInterval) end + +--- Immediately fires a timer +--- +--- Note: This cannot be used on a timer which has already stopped running +---@return timer +function timer:fire() end + +--- Returns the number of seconds until the timer will next trigger +--- +--- Note: The return value may be a negative integer in two circumstances: +--- Hammerspoon's runloop is backlogged and is catching up on missed timer triggers +--- The timer object is not currently running. In this case, the return value of this method is the number of seconds +--- since the last firing (you can check if the timer is running or not, with hs.timer:running() +---@return number +function timer:nextTrigger() end + +--- Returns a boolean indicating whether or not the timer is currently running. +---@return boolean +function timer:running() end + +--- Sets the next trigger time of a timer +--- +--- Note: If the timer is not already running, this will start it +---@param seconds number +---@return timer +function timer:setNextTrigger(seconds) end + +--- Starts an +--- hs.timer +--- object +--- +--- Note: The timer will not call the callback immediately, the timer will wait until it fires +--- If the callback function results in an error, the timer will be stopped to prevent repeated error notifications +--- (see the continueOnError parameter to hs.timer.new() to override this) +---@return timer +function timer:start() end + +--- Stops an +--- hs.timer +--- object +---@return timer +function timer:stop() end + +-- ------------------------------------------------------------ +-- hs.timer.delayed +-- ------------------------------------------------------------ + +---@class hs.timer.delayed +hs.timer.delayed = {} + +---@class delayed +local delayed = {} + +--- Creates a new delayed timer +--- +--- Note: These timers are meant to be long-lived: once instantiated, there's no way to remove them from the run loop; +--- create them once at the module level. +--- Delayed timers have specialized methods that behave differently from regular timers. When the :start() method is +--- invoked, the timer will wait for delay seconds before calling fn() ; this is referred to as the callback countdown. +--- If :start() is invoked again before delay has elapsed, the countdown starts over again. +--- You can use a delayed timer to coalesce processing of unpredictable asynchronous events into a single callback; for +--- example, if you have an event stream that happens in "bursts" of dozens of events at once, set an appropriate delay +--- to wait for things to settle down, and then your callback will run just once. +---@param delay number +---@param fn function +---@return hs.timer.delayed +function hs.timer.delayed.new(delay, fn) end + +--- Returns the time left in the callback countdown +---@return number|nil +function delayed:nextTrigger() end + +--- Returns a boolean indicating whether the callback countdown is running +---@return boolean +function delayed:running() end + +--- Changes the callback countdown duration +--- +--- Note: if the callback countdown is running, calling this method will restart it +---@param delay number +---@return hs.timer.delayed +function delayed:setDelay(delay) end + +--- Starts or restarts the callback countdown +---@param delay number|nil +---@return hs.timer.delayed +function delayed:start(delay) end + +--- Cancels the callback countdown, if running; the callback will therefore not be triggered +---@return hs.timer.delayed +function delayed:stop() end + +-- ------------------------------------------------------------ +-- hs.uielement +-- ------------------------------------------------------------ + +---@class hs.uielement +hs.uielement = {} + +---@class uielement +local uielement = {} + +--- Gets the currently focused UI element +---@return element|nil +function hs.uielement.focusedElement() end + +--- Returns whether the UI element represents an application. +---@return boolean +function uielement:isApplication() end + +--- Returns whether the UI element represents a window. +---@return boolean +function uielement:isWindow() end + +--- Creates a new watcher +---@param handler function +---@param userData? any +---@return hs.uielement.watcher|nil +function uielement:newWatcher(handler, userData) end + +--- Returns the role of the element. +---@return string +function uielement:role() end + +--- Returns the selected text in the element +--- +--- Note: Many applications (e.g. Safari, Mail, Firefox) do not implement the necessary accessibility features for this +--- to work in their web views +---@return string|nil +function uielement:selectedText() end + +-- ------------------------------------------------------------ +-- hs.uielement.watcher +-- ------------------------------------------------------------ + +---@class hs.uielement.watcher +hs.uielement.watcher = {} + +---@class watcher +local watcher = {} + +--- Returns the element the watcher is watching. +---@return object +function watcher:element() end + +--- Returns the PID of the element being watched +---@return number +function watcher:pid() end + +--- Tells the watcher to start watching for the given list of events. +--- +--- Note: See hs.uielement.watcher for a list of events. You may also specify arbitrary event names as strings. +--- Does nothing if the watcher has already been started. To start with different events, stop it first. +---@param events any +---@return hs.uielement.watcher +function watcher:start(events) end + +--- Tells the watcher to stop listening for events. +--- +--- Note: This is automatically called if the element is destroyed. +---@return hs.uielement.watcher +function watcher:stop() end + +-- ------------------------------------------------------------ +-- hs.urlevent +-- ------------------------------------------------------------ + +---@class hs.urlevent +hs.urlevent = {} + +--- A function that should handle http:// and https:// URL events +---@type function +hs.urlevent.httpCallback = nil + +--- A function that should handle mailto: URL events +---@type function +hs.urlevent.mailtoCallback = nil + +--- Registers a callback for a hammerspoon:// URL event +--- +--- Note: The callback function should accept two parameters: +--- eventName - A string containing the name of the event +--- params - A table containing key/value string pairs containing any URL parameters that were specified in the URL +--- senderPID - An integer containing the PID of the sending application, if available (otherwise -1) +--- fullURL - A string containing the full, original URL +--- Given the URL hammerspoon://doThingA?value=1 The event name is doThingA and the callback's params argument will be +--- a table containing {["value"] = "1"} and fullURL will be hammerspoon://doThingA?value=1 +---@param eventName string +---@param callback function|nil +---@return any +function hs.urlevent.bind(eventName, callback) end + +--- Gets all of the application bundle identifiers of applications able to handle a URL scheme +---@param scheme string +---@return table +function hs.urlevent.getAllHandlersForScheme(scheme) end + +--- Gets the application bundle identifier of the application currently registered to handle a URL scheme +---@param scheme string +---@return string +function hs.urlevent.getDefaultHandler(scheme) end + +--- Opens a URL with the default application +---@param url string +---@return boolean +function hs.urlevent.openURL(url) end + +--- Opens a URL with a specified application +---@param url string +---@param bundleID string +---@return boolean +function hs.urlevent.openURLWithBundle(url, bundleID) end + +--- Sets the default system handler for URLs of a given scheme +--- +--- Note: Changing the default handler for http/https URLs will display a system prompt asking the user to confirm the +--- change +---@param scheme string +---@param bundleID? string|nil +---@return any +function hs.urlevent.setDefaultHandler(scheme, bundleID) end + +--- Stores a URL handler that will be restored when Hammerspoon or reloads its config +--- +--- Note: You don't have to call this function if you want Hammerspoon to permanently be your default handler. Only use +--- this if you want the handler to be automatically reverted to something else when Hammerspoon exits/reloads. +---@param scheme string +---@param bundleID string +---@return any +function hs.urlevent.setRestoreHandler(scheme, bundleID) end + +-- ------------------------------------------------------------ +-- hs.usb +-- ------------------------------------------------------------ + +---@class hs.usb +hs.usb = {} + +--- Gets details about currently attached USB devices +---@return table|nil +function hs.usb.attachedDevices() end + +-- ------------------------------------------------------------ +-- hs.usb.watcher +-- ------------------------------------------------------------ + +---@class hs.usb.watcher +hs.usb.watcher = {} + +---@class watcher +local watcher = {} + +--- Creates a new watcher for USB device events +---@param fn function +---@return watcher +function hs.usb.watcher.new(fn) end + +--- Starts the USB watcher +---@return watcher +function watcher:start() end + +--- Stops the USB watcher +---@return watcher +function watcher:stop() end + +-- ------------------------------------------------------------ +-- hs.utf8 +-- ------------------------------------------------------------ + +---@class hs.utf8 +hs.utf8 = {} + +--- A collection of UTF-8 characters already converted from codepoint and available as convenient key-value pairs. +--- UTF-8 printable versions of common Apple and OS X special keys are predefined and others can be added with +--- hs.utf8.registerCodepoint(label, codepoint) +--- for your own use. +---@type hs.utf8.registerCodepoint +hs.utf8.registeredKeys[] = nil + +--- Returns the provided string with all non-printable ascii characters escaped, except Return, Linefeed, and Tab. +--- +--- Note: Because Unicode characters outside of the basic ascii alphabet are multi-byte characters, any UTF8 or other +--- Unicode encoded character will be broken up into their individual bytes and likely escaped by this function. +--- utf8.charpattern , which contains the regular expression for matching valid UTF8 encoded sequences, results in +--- (null) in the Hammerspoon console, but hs.utf8.asciiOnly(utf8.charpattern) will display +--- [\x00-\x7F\xC2-\xF4][\x80-\xBF]* . +---@param string table +---@param all? any +---@return string +function hs.utf8.asciiOnly(string, all) end + +--- Wrapper to +--- utf8.char(...) +--- which ensures that all codepoints return valid UTF8 characters. +--- +--- Note: Valid codepoint values are from 0x0000 - 0x10FFFF (0 - 1114111) +--- If the codepoint provided is a string that starts with U+, then the 'U+' is converted to a '0x' so that lua can +--- properly treat the value as numeric. +--- This includes out of range codepoints as well as the Unicode Surrogate codepoints (U+D800 - U+DFFF) +---@param ... any +---@return string +function hs.utf8.codepointToUTF8(...) end + +--- Replace invalid UTF8 character sequences in +--- inString +--- with +--- replacementChar +--- so it can be safely displayed in the console or other destination which requires valid UTF8 encoding. +--- +--- Note: This function is a slight modification to code found at http://notebook.kulchenko.com/programming/fixing-malformed-utf8-in-lua. +--- If replacementChar is a multi-byte character (like U+FFFD) or multi character string, then the string length of +--- outString will be longer than the string length of inString . The character positions in posTable will reflect +--- these new positions in outString . +--- To calculate the character position of the invalid characters in inString , use something like the following: +--- outString, outErrors = hs.utf8.fixUTF8(inString, replacement) +--- inErrors = {} +--- for i,p in ipairs(outErrors) do +--- table.insert(inErrors, p - ((i - 1) * string.length(replacement) - 1)) +--- end Where replacement is utf8.char(0xFFFD) , if you leave it out of the hs.utf8.fixUTF8 function in the first line. +---@param inString string +---@param replacementChar? string|nil +---@return outString +---@return posTable +function hs.utf8.fixUTF8(inString, replacementChar) end + +--- Returns a hex dump of the provided string. This is primarily useful for examining the exact makeup of binary data +--- contained in a Lua String as individual bytes for debugging purposes. +--- +--- Note: Like hs.utf8.asciiOnly, this function will break up Unicode characters into their individual bytes. +--- As an example: hs.utf8.hexDump(utf8.charpattern) will return 00 : 5B 00 2D 7F C2 2D F4 5D 5B 80 2D BF 5D 2A : +--- [.-..-.][.-.]* +---@param inputString string +---@param count? number|nil +---@return string +function hs.utf8.hexDump(inputString, count) end + +--- Registers a Unicode codepoint under the given label as a UTF-8 string of bytes which can be referenced by the label +--- later in your code as +--- hs.utf8.registeredKeys[label] +--- for convenience and readability. +--- +--- Note: If a codepoint label was previously registered, this will overwrite the previous value with a new one. +--- Because many of the special keys you may want to register have different variants, this allows you to easily modify +--- the existing predefined defaults to suite your preferences. +--- The return value is merely syntactic sugar and you do not need to save it locally; it can be safely ignored -- +--- future access to the pre-converted codepoint should be retrieved as hs.utf8.registeredKeys[label] in your code. It +--- looks good when invoked from the console, though ☺. +---@param label string +---@param codepoint any +---@return string +function hs.utf8.registerCodepoint(label, codepoint) end + +--- Returns the label name for a UTF8 character, as it is registered in +--- hs.utf8.registeredKeys[] +--- . +--- +--- Note: For parity with hs.utf8.registeredKeys , this can also be invoked as if it were an array: i.e. +--- hs.utf8.registeredLabels(char) is equivalent to hs.utf8.registeredLabels[char] +---@param utf8char hs.utf8.registeredKeys +---@return string +function hs.utf8.registeredLabels(utf8char) end + +-- ------------------------------------------------------------ +-- hs.vox +-- ------------------------------------------------------------ + +---@class hs.vox +hs.vox = {} + +--- Add media URL to current list +---@param url string +---@return any +function hs.vox.addurl(url) end + +--- Skips the playback position backwards by about 7 seconds +---@return any +function hs.vox.backward() end + +--- Decreases the player volume +---@return any +function hs.vox.decreaseVolume() end + +--- Skips the playback position backwards by about 14 seconds +---@return any +function hs.vox.fastBackward() end + +--- Skips the playback position forwards by about 17 seconds +---@return any +function hs.vox.fastForward() end + +--- Skips the playback position forwards by about 7 seconds +---@return any +function hs.vox.forward() end + +--- Gets the artist of current Album +---@return string|nil +function hs.vox.getAlbumArtist() end + +--- Gets the name of the album of the current track +---@return string|nil +function hs.vox.getCurrentAlbum() end + +--- Gets the name of the artist of the current track +---@return string|nil +function hs.vox.getCurrentArtist() end + +--- Gets the current playback state of vox +---@return any +function hs.vox.getPlayerState() end + +--- Gets the uniqueID of the current track +---@return string|nil +function hs.vox.getUniqueID() end + +--- Increases the player volume +---@return any +function hs.vox.increaseVolume() end + +--- Returns whether VOX is currently open +---@return boolean +function hs.vox.isRunning() end + +--- Skips to the next track +---@return any +function hs.vox.next() end + +--- Pauses the current vox track +---@return any +function hs.vox.pause() end + +--- Plays the current vox track +---@return any +function hs.vox.play() end + +--- Toggles play/pause of current vox track +---@return any +function hs.vox.playpause() end + +--- Play media from the given URL +---@param url string +---@return any +function hs.vox.playurl(url) end + +--- Skips to previous track +---@return any +function hs.vox.previous() end + +--- Toggle shuffle state of current list +---@return any +function hs.vox.shuffle() end + +--- Toggle playlist +---@return any +function hs.vox.togglePlaylist() end + +--- Displays information for current track on screen +---@return any +function hs.vox.trackInfo() end + +-- ------------------------------------------------------------ +-- hs.watchable +-- ------------------------------------------------------------ + +---@class hs.watchable +hs.watchable = {} + +---@class watchable +local watchable = {} + +--- Creates a table that can be watched by other modules for key changes +--- +--- Note: This constructor is used by code which wishes to share state information which other code may register to +--- watch. +--- You may specify any string name as a path, but it must be unique -- an error will occur if the path name has +--- already been registered. +--- All key-value pairs stored within this table are potentially watchable by external code -- if you wish to keep some +--- data private, do not store it in this table. +--- externalChanges will apply to all keys within this table -- if you wish to only allow some keys to be externally +--- modifiable, you will need to register separate paths. +--- If external changes are enabled, you will need to register your own watcher with hs.watchable.watch if action is +--- required when external changes occur. +---@param path table +---@param externalChanges table|nil +---@return table +function hs.watchable.new(path, externalChanges) end + +--- Creates a watcher that will be invoked when the specified key in the specified path is modified. +--- +--- Note: This constructor is used by code which wishes to watch state information which is being shared by other code. +--- The callback function is invoked after the new value has already been set -- the callback is a "didChange" +--- notification, not a "willChange" notification. +--- If the key (specified as a separate argument or as the final component of path) is "*", then all key-value pair +--- changes that occur for the table specified by the path will invoke a callback. This is a shortcut for watching an +--- entire table, rather than just a specific key-value pair of the table. +--- It is possible to register a watcher for a path that has not been registered with hs.watchable.new yet. Retrieving +--- the current value with hs.watchable:value in such a case will return nil. +---@param path string +---@param key function +---@param callback function +---@return hs.watchable +function hs.watchable.watch(path, key, callback) end + +--- Get or set whether this watcher should be notified even when the new value is identical to the current value +---@param notify function|nil +---@return hs.watchable +function watchable:alwaysNotify(notify) end + +--- Change or remove the callback function for the watchableObject. +--- +--- Note: see hs.watchable.watch for a description of the arguments the callback function should expect. +---@param fn function|nil +---@return hs.watchable +function watchable:callback(fn) end + +--- Externally change the value of the key-value pair being watched by the watchableObject +--- +--- Note: if external changes are not allowed for the specified path, this method generates an error +---@param key table +---@param value any +---@return hs.watchable +function watchable:change(key, value) end + +--- Temporarily stop notifications about the key-value pair(s) watched by this watchableObject. +--- +--- Note: Only pauses notifications for this specific watchableObject -- if other watchers are set for the path watched +--- by this watcher, they will still receive notifications if enabled and not paused. +---@return hs.watchable +function watchable:pause() end + +--- Removes the watchableObject so that key-value pairs watched by this object no longer generate notifications. +--- +--- Note: Only releases this specific watchableObject -- if other watchers are set for the path watched by this object, +--- they remain bound. +---@return nil +function watchable:release() end + +--- Resume notifications about the key-value pair(s) watched by this watchableObject which were previously paused. +--- +--- Note: Only resumes notifications for this specific watchableObject -- if other watchers are set for the path +--- watched by this watcher are currently paused, they will remain paused. +---@return hs.watchable +function watchable:resume() end + +--- Get the current value for the key-value pair being watched by the watchableObject +---@param key table +---@return any +function watchable:value(key) end + +-- ------------------------------------------------------------ +-- hs.websocket +-- ------------------------------------------------------------ + +---@class hs.websocket +hs.websocket = {} + +---@class websocket +local websocket = {} + +--- Creates a new websocket connection. +--- +--- Note: The callback should accept two parameters. +--- open - The websocket connection has been opened +--- closed - The websocket connection has been closed +--- fail - The websocket connection has failed +--- received - The websocket has received a message +--- pong - A pong request has been received +--- The second parameter is a string with the received message or an error message. +--- ws://localhost:8000/mysock +--- wss://localhost:8000/mysock (if SSL enabled) +---@param url string +---@param callback function +---@return object +function hs.websocket.new(url, callback) end + +--- Closes a websocket connection. +---@return object +function websocket:close() end + +--- Sends a message to the websocket client. +--- +--- Note: Forcing a text representation by setting isData to false may alter the data if it +--- contains invalid UTF8 character sequences (the default string behavior is to make +--- sure everything is "printable" by converting invalid sequences into the Unicode +--- Invalid Character sequence). +---@param message string +---@param isData? boolean|nil +---@return object +function websocket:send(message, isData) end + +--- Gets the status of a websocket. +---@return string +function websocket:status() end + +-- ------------------------------------------------------------ +-- hs.webview +-- ------------------------------------------------------------ + +---@class hs.webview +hs.webview = {} + +---@class webview +local webview = {} + +--- Because use of this method can easily lead to a crash, useful methods from +--- hs.drawing +--- have been added to the +--- hs.webview +--- module itself. If you believe that a useful method has been overlooked, please submit an issue. +---@return hs.drawing +function webview:asHSDrawing() end + +--- Returns an hs.window object for the webview so that you can use hs.window methods on it. +---@return hs.window +function webview:asHSWindow() end + +--- Deprecated; you should use +--- hs.webview:level +--- instead. +--- +--- Note: see the notes for hs.drawing.windowLevels +---@deprecated +---@param theLevel any +---@return hs.drawing +function webview:setLevel(theLevel) end + +--- A table of common OID values found in SSL certificates. SSL certificates provided to the callback function for +--- hs.webview:sslCallback +--- or in the results of +--- hs.webview:certificateChain +--- use OID strings as the keys which describe the properties of the certificate and this table can be used to get a +--- more common name for the keys you are most likely to see. +---@type table +hs.webview.certificateOIDs[] = nil + +--- A table containing valid masks for the webview window. +---@type table +hs.webview.windowMasks[] = nil + +--- Get or set whether or not the title text appears in the webview window. +--- +--- Note: See also hs.webview:windowStyle and hs.webview.windowMasks . +--- When a toolbar is attached to the webview, this function can be used to specify whether the Toolbar appears +--- underneath the webview window's title ("visible") or in the window's title bar itself, as seen in applications like +--- Safari ("hidden"). When the title is hidden, the toolbar will only display the toolbar items as icons without +--- labels, and ignores changes made with hs.webview.toolbar:displayMode . +--- If a toolbar is attached to the webview, you can achieve the same effect as this method with +--- hs.webview:attachedToolbar():inTitleBar(boolean) +---@param state boolean +---@return webviewObject|string +function webview:titleVisibility(state) end + +--- Create a webviewObject and optionally modify its preferences. +--- +--- Note: To set the initial URL, use the hs.webview:url method before showing the webview object. +--- Preferences can only be set when the webview object is created. To change the preferences of an open webview, you +--- will need to close it and recreate it with this method. +--- developerExtrasEnabled is not listed in Apple's documentation, but is included in the WebKit2 documentation. +---@param rect any +---@param preferencesTable any +---@param userContentController hs.webview.usercontent|nil +---@return webviewObject +function hs.webview.new(rect, preferencesTable, userContentController) end + +--- Create a webviewObject with some presets common to an interactive web browser. +--- +--- Note: The parameters are the same as for hs.webview.new -- check there for more details +--- This constructor is just a short-hand for hs.webview.new(...):allowTextEntry(true):allowGestures(true):windowStyle(15) , which specifies a webview with a title bar, title bar buttons (zoom, close, minimize), and allows form entry and gesture support for previous and next pages. +--- hs.webview:allowGestures +--- hs.webview:allowTextEntry +--- hs.webview:windowStyle +--- hs.webview.windowMasks +---@param rect any +---@param preferencesTable table|nil +---@param userContentController hs.webview.usercontent|nil +---@return webviewObject +function hs.webview.newBrowser(rect, preferencesTable, userContentController) end + +--- Get or set whether or not the webview will respond to gestures from a trackpad or magic mouse. Default is false. +--- +--- Note: This is a shorthand method for getting or setting both hs.webview:allowMagnificationGestures and +--- hs.webview:allowNavigationGestures . +--- This method will set both types of gestures to true or false, if given an argument, but will only return true if +--- both gesture types are currently true; if either or both gesture methods are false, then this method will return +--- false. +---@param value any +---@return webviewObject +function webview:allowGestures(value) end + +--- Get or set whether or not the webview will respond to magnification gestures from a trackpad or magic mouse. +--- Default is false. +---@param value any +---@return webviewObject +function webview:allowMagnificationGestures(value) end + +--- Get or set whether or not the webview will respond to the navigation gestures from a trackpad or magic mouse. +--- Default is false. +---@param value any +---@return webviewObject +function webview:allowNavigationGestures(value) end + +--- Get or set whether or not the webview allows new windows to be opened from it by any method. Defaults to true. +--- +--- Note: This method allows you to prevent a webview from being able to open a new window by any method. This +--- includes right-clicking on a link and selecting "Open in a New Window", JavaScript pop-ups, links with the target +--- of "__blank", etc. +--- If you just want to prevent automatic JavaScript windows, set the preference value +--- javaScriptCanOpenWindowsAutomatically to false when creating the web view - this method blocks all methods. +---@param value any +---@return webviewObject +function webview:allowNewWindows(value) end + +--- Get or set whether or not the webview can accept keyboard for web form entry. Defaults to false. +---@param value any +---@return webviewObject +function webview:allowTextEntry(value) end + +--- Get or set the alpha level of the window containing the hs.webview object. +---@param alpha number|nil +---@return webviewObject +function webview:alpha(alpha) end + +--- Get or attach/detach a toolbar to/from the webview. +--- +--- Note: this method is a convenience wrapper for the hs.webview.toolbar.attachToolbar function. +--- If the toolbarObject is currently attached to another window when this method is called, it will be detached from +--- the original window and attached to the webview. If you wish to attach the same toolbar to multiple webviews, see +--- hs.webview.toolbar:copy . +---@param toolbar hs.webview.toolbar +---@return webviewObject +function webview:attachedToolbar(toolbar) end + +--- Get or set the window behavior settings for the webview object. +--- +--- Note: Window behaviors determine how the webview object is handled by Spaces and Exposé. See +--- hs.drawing.windowBehaviors for more information. +---@param behavior number|nil +---@return webviewObject +function webview:behavior(behavior) end + +--- Get or set the window behavior settings for the webview object using labels defined in +--- hs.drawing.windowBehaviors +--- . +--- +--- Note: Window behaviors determine how the webview object is handled by Spaces and Exposé. See +--- hs.drawing.windowBehaviors for more information. +---@param behaviorTable table|nil +---@return webviewObject +function webview:behaviorAsLabels(behaviorTable) end + +--- Places the drawing object on top of normal windows +---@param aboveEverything boolean|nil +---@return webviewObject +function webview:bringToFront(aboveEverything) end + +--- Returns the certificate chain for the most recently committed navigation of the webview. +--- +--- Note: This method is only supported by OS X 10.11 and newer +--- A navigation which was performed via HTTP instead of HTTPS will return an empty array. +--- For OIDs which specify a type of "date" -- e.g. "2.5.29.24" (invalidityDate) -- the number provided represents the +--- number of seconds since 12:00:00 AM, January 1, 1970 and can be used directly with the Lua os.date command. +--- For OIDs which are known to represent a date, but specify its type as a "number" -- e.g. +--- "2.16.840.1.113741.2.1.1.1.7" (X509V1ValidityNotAfter) or "2.16.840.1.113741.2.1.1.1.6" (X509V1ValidityNotBefore) +--- -- the epoch is 12:00:00 AM, Jan 1, 2001. To convert these dates into a format usable by Lua, you will need to do +--- something similar to the following: os.date("%c", value + os.time({year=2001,month=1,day=1,hour=0,min=0,sec=0}) +---@return table|nil +function webview:certificateChain() end + +--- Returns an array of webview objects which have been opened as children of this webview. +---@return array +function webview:children() end + +--- If the webview is closable, this will get or set whether or not the Escape key is allowed to close the webview +--- window. +--- +--- Note: If this is set to true, Escape will only close the window if no other element responds to the Escape key +--- first (e.g. if you are editing a text input field, the Escape will be captured by the text field, not by the +--- webview Window.) +---@param flag hs.webview|nil +---@return webviewObject +function webview:closeOnEscape(flag) end + +--- Set or display whether or not the +--- hs.webview +--- window should display in dark mode. +---@param state hs.webview|nil +---@return boolean +function webview:darkMode(state) end + +--- Destroys the webview object, optionally fading it out first (if currently visible). +--- +--- Note: This method is automatically called during garbage collection, notably during a Hammerspoon termination or +--- reload, with a fade time of 0. +---@param propagate any +---@param fadeOutTime number|nil +---@return none +function webview:delete(propagate, fadeOutTime) end + +--- Get or set whether or not the webview should delete itself when its window is closed. +--- +--- Note: If set to true, a webview object will be deleted when the user clicks on the close button of a titled and +--- closable webview (see hs.webview.windowStyle ). +--- Children of an explicitly created webview automatically have this attribute set to true. To cause closed children +--- to remain after the user closes the parent, you can set this to false with a policy callback function when it +--- receives the "newWindow" action. +---@param value hs.webview.new|nil +---@return webviewObject +function webview:deleteOnClose(value) end + +--- Returns the estimated percentage of expected content that has been loaded. Will equal 1.0 when all content has +--- been loaded. +---@return number +function webview:estimatedProgress() end + +--- Execute JavaScript within the context of the current webview and optionally receive its result or error in a +--- callback function. +---@param script any +---@param callback function +---@return webviewObject +function webview:evaluateJavaScript(script, callback) end + +--- Get or set whether or not invalid SSL server certificates that are approved by the ssl callback function are +--- accepted as valid for browsing with the webview. +--- +--- Note: In order for this setting to have any effect, you must also register an ssl callback function with +--- hs.webview:sslCallback which should return true if the certificate should be granted an exception or false if it +--- should not. For a certificate to be granted an exception, both this method and the result of the callback must be +--- true. +--- it is not signed by a recognized certificate authority - most commonly this means the certificate is self-signed. +--- the certificate has expired +--- the certificate has a common name (web site server name) other than the one requested (e.g. the certificate's +--- common name is www.site.com, but it is being used for something else, possibly just https://site.com, possibly +--- something else entirely +--- some corporate proxy servers don't handle SSL properly and can cause a certificate to appear invalid even when they +--- are valid (this is less common then it used to be, but does still occur occasionally) +--- potentially nefarious reasons including man-in-the-middle attacks or phishing scams. +--- The Hammerspoon server provided by hs.httpserver uses a self-signed certificate when set to use SSL, so it will be +--- considered invalid for reason 1 above. +--- If the certificate has been granted an exception in another application which registers the exception in the user's +--- keychain (e.g. Safari), then the certificate is no longer considered invalid and this setting has no effect for +--- that certificate. +---@param flag function|nil +---@return webviewObject +function webview:examineInvalidCertificates(flag) end + +--- Get or set the frame of the webview window. +--- +--- Note: a rect-table is a table with key-value pairs specifying the new top-left coordinate on the screen of the +--- webview window (keys x and y ) and the new size (keys h and w ). The table may be crafted by any method which +--- includes these keys, including the use of an hs.geometry object. +---@param rect table|nil +---@return webviewObject +function webview:frame(rect) end + +--- Move to the previous page in the webview's history, if possible. +---@return webviewObject +function webview:goBack() end + +--- Move to the next page in the webview's history, if possible. +---@return webviewObject +function webview:goForward() end + +--- Hides the webview object +---@param fadeOutTime number|nil +---@return webviewObject +function webview:hide(fadeOutTime) end + +--- Returns the URL history for the current webview as an array. +---@return historyTable +function webview:historyList() end + +--- Returns an hs.window object for the webview so that you can use hs.window methods on it. +--- +--- Note: hs.window:minimize only works if the webview is minimizable (see hs.webview.windowStyle ) +--- hs.window:setSize only works if the webview is resizable (see hs.webview.windowStyle ) +--- hs.window:close only works if the webview is closable (see hs.webview.windowStyle ) +--- hs.window:maximize will reposition the webview to the upper left corner of your screen, but will only resize the +--- webview if the webview is resizable (see hs.webview.windowStyle ) +---@return hs.window +function webview:hswindow() end + +--- Render the given HTML in the webview with an optional base URL for relative links. +--- +--- Note: Web Pages generated in this manner are not added to the webview history list +---@param html any +---@param baseURL string +---@return webviewObject +---@return navigationIdentifier +function webview:html(html, baseURL) end + +--- Returns a boolean value indicating if all content current displayed in the webview was loaded over securely +--- encrypted connections. +---@return boolean +function webview:isOnlySecureContent() end + +--- Checks to see if a webview window is visible or not. +---@return boolean +function webview:isVisible() end + +--- Get or set the window level +--- +--- Note: see the notes for hs.drawing.windowLevels +---@param theLevel hs.drawing.windowLevels|nil +---@return hs.drawing +function webview:level(theLevel) end + +--- Returns a boolean value indicating whether or not the webview is still loading content. +---@return boolean +function webview:loading() end + +--- Get or set the webviews current magnification level. Default is 1.0. +---@param value number|nil +---@return webviewObject +function webview:magnification(value) end + +--- Sets a callback for tracking a webview's navigation process. +--- +--- Note: The return value of the callback function is ignored except when the action argument is equal to +--- didFailNavigation or didFailProvisionalNavigation . If the return value when the action argument is one of these +--- values is a string, it will be treated as html and displayed in the webview as the error message. If the return +--- value is the boolean value true, then no change will be made to the webview (it will continue to display the +--- previous web page). All other return values or no return value at all, if these navigation actions occur, will +--- cause a default error page to be displayed in the webview. +---@param fn function +---@return webviewObject +function webview:navigationCallback(fn) end + +--- Get the most recent navigation identifier for the specified webview. +--- +--- Note: This navigation identifier can be used to track the progress of a webview with the navigation callback +--- function - see hs.webview.navigationCallback . +---@return navigationID +function webview:navigationID() end + +--- Moves webview object above webview2, or all webview objects in the same presentation level, if webview2 is not +--- given. +--- +--- Note: If the webview object and webview2 are not at the same presentation level, this method will move the webview +--- object as close to the desired relationship without changing the webview object's presentation level. See +--- hs.webview.level . +---@param webview2 any +---@return webviewObject +function webview:orderAbove(webview2) end + +--- Moves webview object below webview2, or all webview objects in the same presentation level, if webview2 is not +--- given. +--- +--- Note: If the webview object and webview2 are not at the same presentation level, this method will move the webview +--- object as close to the desired relationship without changing the webview object's presentation level. See +--- hs.webview.level . +---@param webview2 any +---@return webviewObject +function webview:orderBelow(webview2) end + +--- Get the parent webview object for the calling webview object, or nil if the webview has no parent. +---@return webviewObject|nil +function webview:parent() end + +--- Sets a callback to approve or deny web navigation activity. +--- +--- Note: With the newWindow action, the navigationCallback and policyCallback are automatically replicated for the new +--- window from its parent. If you wish to disable these for the new window or assign a different set of callback +--- functions, you can do so before returning true in the callback function with the webview argument provided. +---@param fn function +---@return webviewObject +function webview:policyCallback(fn) end + +--- Returns whether or not the webview browser is set up for private browsing (i.e. uses a non-persistent datastore) +--- +--- Note: This method is only supported by OS X 10.11 and newer +--- See hs.webview.datastore and hs.webview.new for more information. +---@return boolean +function webview:privateBrowsing() end + +--- Reload the page in the webview, optionally performing end-to-end revalidation using cache-validating conditionals +--- if possible. +---@param validate any +---@return webviewObject +---@return navigationIdentifier +function webview:reload(validate) end + +--- Places the webview object behind normal windows, between the desktop wallpaper and desktop icons +---@return webviewObject +function webview:sendToBack() end + +--- Get or set whether or not the webview window has shadows. Default to false. +---@param value any +---@return webviewObject +function webview:shadow(value) end + +--- Displays the webview object +---@param fadeInTime number|nil +---@return webviewObject +function webview:show(fadeInTime) end + +--- Get or set the size of a webview window +--- +--- Note: a size-table is a table with key-value pairs specifying the size (keys h and w ) the webview should be +--- resized to. The table may be crafted by any method which includes these keys, including the use of an hs.geometry +--- object. +---@param size table|nil +---@return webviewObject +function webview:size(size) end + +--- Sets a callback to examine an invalid SSL certificate and determine if an exception should be granted. +--- +--- Note: The callback function should return true if an exception should be granted for this certificate or false if +--- it should be rejected. +--- even if this callback returns true , the certificate will only be granted an exception if +--- hs.webview:examineInvalidCertificates has also been set to true . +--- once an invalid certificate has been granted an exception, the exception will remain in effect until the webview +--- object is deleted. +--- the callback is only invoked for invalid certificates -- if a certificate is valid, or once an exception has been +--- granted, the callback will not (no longer) be called for that certificate. +--- If the certificate has been granted an exception in another application which registers the exception in the user's +--- keychain (e.g. Safari), then the certificate is no longer considered invalid and this callback will not be invoked. +---@param fn function +---@return webviewObject +function webview:sslCallback(fn) end + +--- Stop loading additional content for the webview. +--- +--- Note: this method does not stop the loading of the primary content for the page at the specified URL +--- The documentation from Apple is unclear and experimentation has shown that if this method is applied before the +--- content of the specified URL has loaded, it can cause the webview to lock up; however it appears to stop the +--- loading of additional resources specified for the content (external script files, external style files, AJAX +--- queries, etc.) and should be used in this context. +---@return webviewObject +function webview:stopLoading() end + +--- Get the title of the page displayed in the webview. +---@return title +function webview:title() end + +--- Get or set the top-left coordinate of the webview window +--- +--- Note: a point-table is a table with key-value pairs specifying the new top-left coordinate on the screen of the +--- webview (keys x and y ). The table may be crafted by any method which includes these keys, including the use of an +--- hs.geometry object. +---@param point table|nil +---@return webviewObject +function webview:topLeft(point) end + +--- Get or set whether or not the webview background is transparent. Default is false. +--- +--- Note: When enabled, the webview's background color is equal to the body's background-color (transparent by default) +--- Setting background-color:rgba(0, 225, 0, 0.3) on will give a translucent green webview background +---@param value any +---@return webviewObject +function webview:transparent(value) end + +--- Get or set the URL to render for the webview. +--- +--- Note: The networkServiceType field of the URL request table is a hint to the operating system about what the +--- underlying traffic is used for. This hint enhances the system's ability to prioritize traffic, determine how +--- quickly it needs to wake up the Wi-Fi radio, and so on. By providing accurate information, you improve the ability +--- of the system to optimally balance battery life, performance, and other considerations. Likewise, inaccurate +--- information can have a deleterious effect on your system performance and battery life. +---@param URL string +---@return webviewObject +---@return navigationIdentifier|url +function webview:url(URL) end + +--- Returns a table of keys containing the individual components of the URL for the webview. +--- +--- Note: This method is a wrapper to the hs.http.urlParts function wich uses the OS X APIs, based on RFC 1808. +--- You may also want to consider the hs.httpserver.hsminweb.urlParts function for a version more consistent with RFC +--- 3986. +---@return table +function webview:urlParts() end + +--- Get or set the webview's user agent string +--- +--- Note: This method is only supported by OS X 10.11 and newer +--- The default user string used by webview objects will be something like this (the exact version numbers will differ, +--- depending upon your OS X version): +--- "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_5) AppleWebKit/601.6.17 (KHTML, like Gecko)" +--- By default, this method will return the empty string ("") when queried -- this indicates that the default, shown +--- above, is used. You can also return to this default by setting the user agent to "" with this method (e.g. +--- hs.webview:userAgent("") ). +--- Some web sites tailor content based on the user string or use it for other internal purposes (tracking, statistics, +--- page availability, layout, etc.). Common user-agent strings can be found at +--- http://www.useragentstring.com/pages/useragentstring.php. +--- If you have set the user agent application name with the applicationName parameter to the hs.webview.new +--- constructor, it will be ignored unless this value is "", i.e. the default user agent string. If you wish to +--- specify an application name after the user agent string and use a custom string, include the application name in +--- your custom string. +---@param agent string +---@return webviewObject +function webview:userAgent(agent) end + +--- Set or clear a callback for updates to the webview window +---@param fn function +---@return webviewObject +function webview:windowCallback(fn) end + +--- Get or set the window display style +---@param mask any +---@return webviewObject|currentMask +function webview:windowStyle(mask) end + +--- Sets the title for the webview window. +--- +--- Note: The title will be hidden unless the window style includes the "titled" style (see hs.webview.windowStyle and +--- hs.webview.windowMasks ) +---@param title string +---@return webviewObject +function webview:windowTitle(title) end + +-- ------------------------------------------------------------ +-- hs.webview.datastore +-- ------------------------------------------------------------ + +---@class hs.webview.datastore +hs.webview.datastore = {} + +---@class datastore +local datastore = {} + +--- Returns a list of the currently available data types within a datastore. +--- +--- Note: WKWebsiteDataTypeDiskCache - On-disk caches. +--- WKWebsiteDataTypeOfflineWebApplicationCache - HTML offline web application caches. +--- WKWebsiteDataTypeMemoryCache - In-memory caches. +--- WKWebsiteDataTypeLocalStorage - HTML local storage. +--- WKWebsiteDataTypeCookies - Cookies. +--- WKWebsiteDataTypeSessionStorage - HTML session storage. +--- WKWebsiteDataTypeIndexedDBDatabases - WebSQL databases. +--- WKWebsiteDataTypeWebSQLDatabases - IndexedDB databases. +---@return table +function hs.webview.datastore.websiteDataTypes() end + +--- Returns an object representing the default datastore for Hammerspoon +--- hs.webview +--- instances. +--- +--- Note: this is the datastore used unless otherwise specified when creating an hs.webview instance. +---@return datastoreObject +function hs.webview.datastore.default() end + +--- Returns an object representing the datastore for the specified +--- hs.webview +--- instance. +--- +--- Note: When running on a system with OS X 10.11 or later, this method will also be added to the metatable for +--- hs.webview objects so that you can retrieve a webview's datastore with hs.webview:datastore() . +--- This method can be used to identify the datastore in use for a webview if you wish to create a new instance using +--- the same datastore. +---@param webview hs.webview +---@return datastoreObject +function hs.webview.datastore.fromWebview(webview) end + +--- Returns an object representing a newly created non-persistent (private) datastore for use with a Hammerspoon +--- hs.webview +--- instance. +--- +--- Note: The datastore represented by this object will be initially empty. You can use this function to create a +--- non-persistent datastore that you wish to share among multiple hs.webview instances. Once a datastore is created, +--- you assign it to a hs.webview instance by including the datastore key in the hs.webview.new constructor's +--- preferences table and setting it equal to this key. All webview instances created with this datastore object will +--- share web caches, cookies, etc. but will still be isolated from the default datastore and it will be purged from +--- memory when the webviews are deleted, or Hammerspoon is restarted. +--- Using the datastore key in the webview's constructor differs from the private key -- use of the private key will +--- override the datastore key and will create a separate non-persistent datastore for the webview instance. See +--- hs.webview.new for more information. +---@return datastoreObject +function hs.webview.datastore.newPrivate() end + +--- Generates a list of the datastore records of the specified type, and invokes the callback function with the list. +--- +--- Note: only those sites with one or more of the specified data types are returned +--- for the sites returned, only those data types that were present in the query will be included in the list, even if +--- the site has data of another type in the datastore. +---@param dataTypes table +---@param callback function +---@return datastoreObject +function datastore:fetchRecords(dataTypes, callback) end + +--- Returns whether or not the datastore is persistent. +--- +--- Note: Note that this value is the inverse of hs.webview:privateBrowsing() , since private browsing uses a +--- non-persistent datastore. +---@return boolean +function datastore:persistent() end + +--- Removes the specified types of data from the datastore if the data was added or changed since the given date. +--- +--- Note: Yes, you read the description correctly -- removes data newer then the date specified. I've not yet found a +--- way to remove data older then the date specified (to expire old data, for example) but updates or suggestions are +--- welcome in the Hammerspoon Google group or GitHub web site. +--- to specify that all data types that qualify should be removed, specify the function +--- hs.webview.datastore.websiteDataTypes() . as the second argument. +--- For example, to purge the Hammerspoon default datastore of all data, you can do the following: +--- hs.webview.datastore.default():removeRecordsAfter(0, hs.webview.datastore.websiteDataTypes()) +---@param date string +---@param dataTypes string +---@param callback function|nil +---@return datastoreObject +function datastore:removeRecordsAfter(date, dataTypes, callback) end + +--- Remove data from the datastore of the specified type(s) for the specified site(s). +--- +--- Note: to specify that all data types that qualify should be removed, specify the function +--- hs.webview.datastore.websiteDataTypes() . as the second argument. +---@param displayNames string +---@param dataTypes string +---@param callback function|nil +---@return datastoreObject +function datastore:removeRecordsFor(displayNames, dataTypes, callback) end + +-- ------------------------------------------------------------ +-- hs.webview.toolbar +-- ------------------------------------------------------------ + +---@class hs.webview.toolbar +hs.webview.toolbar = {} + +---@class toolbar +local toolbar = {} + +--- A table containing some pre-defined toolbar item priority values for use when determining item order in the toolbar. +---@type table +hs.webview.toolbar.itemPriorities = nil + +--- An array containing string identifiers for supported system defined toolbar items. +---@type string +hs.webview.toolbar.systemToolbarItems = nil + +--- Get or attach/detach a toolbar to the webview, chooser, or console. +--- +--- Note: This function is not expected to be used directly (though it can be) -- it is added to the hs.webview and +--- hs.chooser object metatables so that it may be invoked as hs.webview:attachedToolbar([toolbarObject | nil]) / +--- hs.chooser:attachedToolbar([toolbarObject | nil]) and to the hs.console module so that it may be invoked as +--- hs.console.toolbar([toolbarObject | nil]) . +--- If the toolbar is currently attached to another window when this function is called, it will be detached from the +--- original window and attached to the new one specified by this function. +---@param obj1 any +---@param obj2 any +---@return obj1 +function hs.webview.toolbar.attachToolbar(obj1, obj2) end + +--- Get or set whether or not the toolbar appears in the containing window's titlebar, similar to Safari. +--- +--- Note: When this value is true, the toolbar, when visible, will appear in the window's title bar similar to the +--- toolbar as seen in applications like Safari. In this state, the toolbar will set the display of the toolbar items +--- to icons without labels, ignoring changes made with hs.webview.toolbar:displayMode . +--- This method is only valid when the toolbar is attached to a webview, chooser, or the console. +---@param state boolean +---@return toolbarObject|boolean +function toolbar:inTitleBar(state) end + +--- Checks to see is a toolbar name is already in use +---@param toolbarName string +---@return boolean +function hs.webview.toolbar.uniqueName(toolbarName) end + +--- Creates a new toolbar for a webview, chooser, or the console. +--- +--- Note: Toolbar names must be unique, but a toolbar may be copied with hs.webview.toolbar:copy if you wish to attach +--- it to multiple windows (webview, chooser, or console). +--- See hs.webview.toolbar:addItems for a description of the format for toolbarTable +---@param toolbarName string +---@param toolbarTable table|nil +---@return toolbarObject +function hs.webview.toolbar.new(toolbarName, toolbarTable) end + +--- Add one or more toolbar items to the toolbar +--- +--- Note: id - A unique string identifier required for each toolbar item and group. This key cannot be changed after +--- an item has been created. +--- allowedAlone - a boolean value, default true, specifying whether or not the toolbar item can be added to the +--- toolbar, programmatically or through the customization panel, (true) or whether it can only be added as a member of +--- a group (false). +--- default - a boolean value, default matching the value of allowedAlone for this item, indicating whether or not this +--- toolbar item or group should be displayed in the toolbar by default, unless overridden by user customization or a +--- saved configuration (when such options are enabled). +--- enable - a boolean value, default true, indicating whether or not the toolbar item is active (and can be clicked +--- on) or inactive and greyed out. This field is ignored when applied to a toolbar group; apply it to the group +--- members instead. +--- fn - a callback function, or false to remove, specific to the toolbar item. This property is ignored if assigned to +--- the button group. This function will override the toolbar callback defined with hs.webview.toolbar:setCallback for +--- this specific item. The function should expect three (four, if the item is a searchfield ) arguments and return +--- none. See hs.webview.toolbar:setCallback for information about the callback's arguments. +--- groupMembers - an array (table) of strings specifying the toolbar item ids that are members of this toolbar item +--- group. If set to false, this field is removed and the item is reset back to being a regular toolbar item. Note +--- that you cannot change a currently visible toolbar item to or from being a group; it must first be removed from +--- active toolbar with hs.webview.toolbar:removeItem . +--- image - an hs.image object, or false to remove, specifying the image to use as the toolbar item's icon when icon's +--- are displayed in the toolbar or customization panel. This key is ignored for a toolbar item group, but not for it's +--- individual members. +--- label - a string label, or false to remove, for the toolbar item or group when text is displayed in the toolbar or +--- in the customization panel. For a toolbar item, the default is the id string; for a group, the default is false . +--- If a group has a label assigned to it, the group label will be displayed for the group of items it contains. If a +--- group does not have a label, the individual items which make up the group will each display their individual labels. +--- priority - an integer value used to determine toolbar item order and which items are displayed or put into the +--- overflow menu when the number of items in the toolbar exceed the width of the window in which the toolbar is +--- attached. Some example values are provided in the hs.webview.toolbar.itemPriorities table. If a toolbar item is in +--- a group, it's priority is ignored and the item group is ordered by the item group's priority. +--- searchHistory - an array (table) of strings, specifying previous searches to automatically include in the search +--- field menu, if searchPredefinedMenuTitle is not false +--- searchHistoryAutosaveName - a string specifying the key name to save search history with in the application +--- defaults (accessible through hs.settings ). If this value is set, search history will be maintained through +--- restarts of Hammerspoon. +--- searchHistoryLimit - the maximum number of items to store in the search field history. +--- searchPredefinedMenuTitle - a string or boolean specifying how a predefined list of search field "response" should +--- be included in the search field menu. If this item is true , this list of items specified for +--- searchPredefinedSearches will be displayed in a submenu with the title "Predefined Searches". If this item is a +--- string, the list of items will be displayed in a submenu with the title specified by this string value. If this +--- item is false , then the search field menu will only contain the items specified in searchPredefinedSearches and no +--- search history will be included in the menu. +--- searchPredefinedSearches - an array (table) of strings specifying the items to be listed in the predefined search +--- submenu. If set to false, any existing menu will be removed and the search field menu will be reset to the default. +--- searchReleaseFocusOnCallback - a boolean, default false, specifying whether or not focus leaves the search field +--- text box when the callback is invoked. Setting this to true can be useful if you want subsequent keypresses to be +--- caught by the webview after reacting to the value entered into the search field by the user. +--- searchText - a string specifying the text to display in the search field. +--- searchWidth - the width of the search field text entry box. +--- selectable - a boolean value, default false, indicating whether or not this toolbar item is selectable (i.e. +--- highlights, like a selected tab) when clicked on. Only one selectable toolbar item can be highlighted at a time, +--- and you can get or set/reset the selected item with hs.webview.toolbar:selectedItem . +--- tag - an integer value which can be used for own purposes; has no affect on the visual aspect of the item or its +--- behavior. +--- tooltip - a string label, or false to remove, which is displayed as a tool tip when the user hovers the mouse over +--- the button or button group. If a button is in a group, it's tooltip is ignored in favor of the group tooltip. +---@param toolbarTable table +---@return toolbarObject +function toolbar:addItems(toolbarTable) end + +--- Returns an array of all toolbar item identifiers defined for this toolbar. +---@return array +function toolbar:allowedItems() end + +--- Get or set whether or not the toolbar autosaves changes made to the toolbar. +--- +--- Note: If the toolbar is set to autosave, then a user-defaults entry is created in org.hammerspoon.Hammerspoon +--- domain with the key "NSToolbar Configuration XXX" where XXX is the toolbar identifier specified when the toolbar +--- was created. +--- the default item identifiers that are displayed when the toolbar is first created or when the user drags the +--- default set from the customization panel. +--- the current display mode (icon, text, both) +--- the current size mode (regular, small) +--- whether or not the toolbar is currently visible +--- the currently shown identifiers and their order +--- Note that the labels, icons, callback functions, etc. are not saved -- these are determined at toolbar creation +--- time, by the hs.webview.toolbar:addItems , or by the hs.webview.toolbar:modifyItem method and can differ between +--- invocations of toolbars with the same identifier and button identifiers. +---@param bool any +---@return toolbarObject|boolean +function toolbar:autosaves(bool) end + +--- Get or set whether or not the user is allowed to customize the toolbar with the Customization Panel. +--- +--- Note: the customization panel can be pulled up by right-clicking on the toolbar or by invoking +--- hs.webview.toolbar:customizePanel . +---@param bool any +---@return toolbarObject|boolean +function toolbar:canCustomize(bool) end + +--- Returns a copy of the toolbar object. +---@return toolbarObject +function toolbar:copy() end + +--- Opens the toolbar customization panel. +---@return toolbarObject +function toolbar:customizePanel() end + +--- Deletes the toolbar, removing it from its window if it is currently attached. +---@return none +function toolbar:delete() end + +--- Deletes the toolbar item specified completely from the toolbar, removing it first, if the toolbar item is currently +--- active. +--- +--- Note: This method completely removes the toolbar item from the toolbar's definition dictionary, thus removing it +--- from active use in the toolbar as well as removing it from the customization panel, if supported. If you only want +--- to remove a toolbar item from the active toolbar, consider hs.webview.toolbar:removeItem . +---@param identifier any +---@return toolbarObject +function toolbar:deleteItem(identifier) end + +--- Get or set the toolbar's display mode. +---@param mode string|nil +---@return toolbarObject +function toolbar:displayMode(mode) end + +--- The identifier for this toolbar. +---@return identifier +function toolbar:identifier() end + +--- Insert or move the toolbar item to the index position specified +--- +--- Note: the toolbar position must be between 1 and the number of currently active toolbar items. +---@param id string +---@param index number +---@return toolbarObject +function toolbar:insertItem(id, index) end + +--- Returns a boolean indicating whether or not the toolbar is currently attached to a window. +---@return boolean +function toolbar:isAttached() end + +--- Indicates whether or not the customization panel is currently open for the toolbar. +---@return boolean +function toolbar:isCustomizing() end + +--- Returns a table containing details about the specified toolbar item +--- +--- Note: For a list of the most of the possible toolbar item attribute keys, see hs.webview.toolbar:addItems . +--- The table will also include privateCallback which will be a boolean indicating whether or not this toolbar item has +--- a private callback function assigned (true) or uses the toolbar's general callback function (false). +--- toolbar - the toolbar object the item belongs to +--- subItems - if the toolbar item is actually a group, this will contain a table with basic information about the +--- members of the group. If you wish to get the full details for each sub-member, you may iterate on the identifiers +--- provided in groupMembers . +---@param id string +---@return table +function toolbar:itemDetails(id) end + +--- Returns an array of the toolbar item identifiers currently assigned to the toolbar. +---@return array +function toolbar:items() end + +--- Modify the toolbar item specified by the "id" key in the table argument. +--- +--- Note: You cannot change a toolbar item's id +--- For a list of the possible toolbar item attribute keys, see hs.webview.toolbar:addItems . +---@param table any +---@return toolbarObject +function toolbar:modifyItem(table) end + +--- Get or set whether or not the global callback function is invoked when a toolbar item is added or removed from the +--- toolbar. +---@param bool any +---@return toolbarObject|boolean +function toolbar:notifyOnChange(bool) end + +--- Remove the toolbar item at the index position specified, or with the specified identifier, if currently present in +--- the toolbar. +--- +--- Note: the toolbar position must be between 1 and the number of currently active toolbar items. +---@param index | identifier any +---@return toolbarObject +function toolbar:removeItem(index | identifier) end + +--- Returns a table containing the settings which will be saved for the toolbar if +--- hs.webview.toolbar:autosaves +--- is true. +--- +--- Note: If the toolbar is set to autosave, then a user-defaults entry is created in org.hammerspoon.Hammerspoon +--- domain with the key "NSToolbar Configuration XXX" where XXX is the toolbar identifier specified when the toolbar +--- was created. +--- This method is provided if you do not wish for changes to the toolbar to be autosaved for every change, but may +--- wish to save it programmatically under specific conditions. +---@return table +function toolbar:savedSettings() end + +--- Get or set the selected toolbar item +--- +--- Note: Only toolbar items which were defined as selectable when created with hs.webview.toolbar.new can be selected +--- with this method. +---@param item any +---@return toolbarObject +function toolbar:selectedItem(item) end + +--- Programmatically focus the search field for keyboard input. +--- +--- Note: if there is current text in the searchfield, it will be selected so that any subsequent typing by the user +--- will replace the current value in the searchfield. +---@param identifier string|nil +---@return toolbarObject|boolean +function toolbar:selectSearchField(identifier) end + +--- Get or set whether or not the toolbar shows a separator between the toolbar and the main window contents. +---@param bool any +---@return toolbarObject|boolean +function toolbar:separator(bool) end + +--- Sets or removes the global callback function for the toolbar. +--- +--- Note: the global callback function is invoked for a toolbar button item that does not have a specific function +--- assigned directly to it. +--- if hs.webview.toolbar:notifyOnChange is set to true, then this callback function will also be invoked when a +--- toolbar item is added or removed from the toolbar either programmatically with hs.webview.toolbar:insertItem and +--- hs.webview.toolbar:removeItem or under user control with hs.webview.toolbar:customizePanel and the callback +--- function will receive a string of "add" or "remove" as a fourth argument. +---@param fn function|nil +---@return toolbarObject +function toolbar:setCallback(fn) end + +--- Get or set the toolbar's size. +---@param size string|nil +---@return toolbarObject +function toolbar:sizeMode(size) end + +--- Get or set the toolbar's style. +--- +--- Note: This is only available for macOS 11.0+. Will return nil if getting on an earlier version of macOS. +--- automatic - A style indicating that the system determines the toolbar’s appearance and location. +--- expanded - A style indicating that the toolbar appears below the window title. +--- preference - A style indicating that the toolbar appears below the window title with toolbar items centered in the +--- toolbar. +--- unified - A style indicating that the toolbar appears next to the window title. +--- unifiedCompact - A style indicating that the toolbar appears next to the window title and with reduced margins to +--- allow more focus on the window’s contents. +---@param style string|nil +---@return toolbarObject +function toolbar:toolbarStyle(style) end + +--- Get or set whether or not the toolbar is currently visible in the window it is attached to. +---@param bool any +---@return toolbarObject|boolean +function toolbar:visible(bool) end + +--- Returns an array of the currently visible toolbar item identifiers. +---@return array +function toolbar:visibleItems() end + +-- ------------------------------------------------------------ +-- hs.webview.usercontent +-- ------------------------------------------------------------ + +---@class hs.webview.usercontent +hs.webview.usercontent = {} + +---@class usercontent +local usercontent = {} + +--- Create a new user content controller for a webview and create the message port with the specified name for +--- JavaScript message support. +--- +--- Note: This object should be provided as the final argument to the hs.webview.new constructor in order to tie the +--- webview to this content controller. All new windows which are created from this parent webview will also use this +--- controller. +--- See hs.webview.usercontent:setCallback for more information about the message port. +---@param name string +---@return usercontentControllerObject +function hs.webview.usercontent.new(name) end + +--- Add a script to be injected into webviews which use this user content controller. +---@param scriptTable any +---@return usercontentControllerObject +function usercontent:injectScript(scriptTable) end + +--- Removes all user scripts currently defined for this user content controller. +--- +--- Note: The WKUserContentController class only allows for removing all scripts. If you need finer control, make a +--- copy of the current scripts with hs.webview.usercontent.userScripts() first so you can recreate the scripts you +--- want to keep. +---@return usercontentControllerObject +function usercontent:removeAllScripts() end + +--- Set or remove the callback function to handle message posted to this user content's message port. +--- +--- Note: Within your (injected or served) JavaScript, you can post messages via the message port created with the +--- constructor like this: try { +--- webkit.messageHandlers. name >.postMessage( message-object ); +--- } catch(err) { +--- console.log('The controller does not exist yet'); +--- } +--- Where name matches the name specified in the constructor and message-object is the object to post to the function. +--- This object can be a number, string, date, array, dictionary(table), or nil. +---@param fn function +---@return usercontentControllerObject +function usercontent:setCallback(fn) end + +--- Get a table containing all of the currently defined injection scripts for this user content controller +--- +--- Note: Because the WKUserContentController class only allows for removing all scripts, you can use this method to +--- generate a list of all scripts, modify it, and then use it in a loop to reapply the scripts if you need to remove +--- just a few scripts. +---@return array +function usercontent:userScripts() end + +-- ------------------------------------------------------------ +-- hs.wifi +-- ------------------------------------------------------------ + +---@class hs.wifi +hs.wifi = {} + +---@class wifi +local wifi = {} + +--- Connect the interface to a wireless network +--- +--- Note: Enterprise WiFi networks are not currently supported. Please file an issue on GitHub if you need support for +--- enterprise networks +--- This function blocks Hammerspoon until the operation is completed +--- If multiple access points are available with the same SSID, one will be chosen at random to connect to +---@param network string +---@param passphrase string +---@param interface? hs.wifi.interfaces|nil +---@return boolean +function hs.wifi.associate(network, passphrase, interface) end + +--- Gets a list of available WiFi networks +--- +--- Note: WARNING: This function will block all Lua execution until the scan has completed. It's probably not very +--- sensible to use this function very much, if at all. +---@param interface hs.wifi.interfaces|nil +---@return table +function hs.wifi.availableNetworks(interface) end + +--- Gets the name of the current WiFi network +---@param interface hs.wifi.interfaces|nil +---@return string|nil +function hs.wifi.currentNetwork(interface) end + +--- Disconnect the interface from its current network. +---@param interface hs.wifi.interfaces|nil +---@return nil +function hs.wifi.disassociate(interface) end + +--- Returns a table containing details about the wireless interface. +---@param interface hs.wifi.interfaces|nil +---@return table +function hs.wifi.interfaceDetails(interface) end + +--- Returns a list of interface names for WLAN devices attached to the system +--- +--- Note: For most systems, this will be one interface, but the result is still returned as an array. +---@return table +function hs.wifi.interfaces() end + +--- Turns a wifi interface on or off +---@param state boolean +---@param interface hs.wifi.interfaces|nil +---@return boolean +function hs.wifi.setPower(state, interface) end + +--- Perform a scan for available wifi networks in the background (non-blocking) +--- +--- Note: If you pass in nil as the callback function, the scan occurs but no callback function is called. This can be +--- useful to update the cachedScanResults entry returned by hs.wifi.interfaceDetails . +--- The callback function should expect one argument which will be a table if the scan was successful or a string +--- containing an error message if it was not. The table will be an array of available networks. Each entry in the +--- array will be a table containing the following keys: +--- beaconInterval - The beacon interval (ms) for the network. +--- bssid - The basic service set identifier (BSSID) for the network. +--- countryCode - The country code (ISO/IEC 3166-1:1997) for the network. +--- ibss - Whether or not the network is an IBSS (ad-hoc) network. +--- informationElementData - Information element data included in beacon or probe response frames as an array of +--- integers. +--- noise - The aggregate noise measurement (dBm) for the network. +--- PHYModes - A table containing the PHY Modes supported by the network. +--- rssi - The aggregate received signal strength indication (RSSI) measurement (dBm) for the network. +--- security - A table containing the security types supported by the network. +--- ssid - The service set identifier (SSID) for the network, encoded as a string. +--- ssidData - The service set identifier (SSID) for the network, returned as data (1-32 octets). +--- wlanChannel - A table containing details about the channel the network is on. The table will contain the +--- following keys: +--- band - The channel band. +--- number - The channel number. +--- width - The channel width. +--- You can convert this data into a Lua string by passing the array as an argument to +--- string.char(table.unpack(results.informationElementData)) , but note that this field contains arbitrary binary data +--- and should not be treated or considered as a displayable string. It requires additional parsing, depending upon the +--- specific information you need from the probe or beacon response. +--- For debugging purposes, if you wish to view the contents of this field as a string, make sure to wrap +--- string.char(table.unpack(results.informationElementData)) with hs.utf8.asciiOnly or hs.utf8.hexDump , rather than +--- just print the result directly. +--- As an example using hs.wifi.interfaceDetails whose cachedScanResults key is an array of entries identical to the +--- argument passed to this constructor's callback function: +--- function dumpIED(interface) +--- local interface = interface or "en0" +--- local cleanupFunction = hs.utf8.hexDump -- or hs.utf8.asciiOnly if you prefer +--- local cachedScanResults = hs.wifi.interfaceDetails(interface).cachedScanResults +--- if not cachedScanResults then +--- hs.wifi.availableNetworks() -- blocking, so only do if necessary +--- cachedScanResults = hs.wifi.interfaceDetails(interface).cachedScanResults +--- end +--- for i, v in ipairs(cachedScanResults) do +--- print(v.ssid .. " on channel " .. v.wlanChannel.number .. " beacon data:") +--- print(cleanupFunction(string.char(table.unpack(v.informationElementData)))) +--- end +--- end +--- These precautions are in response to Hammerspoon GitHub Issue #859. As binary data, even when cleaned up with the +--- Console's UTF8 wrapper code, some valid UTF8 sequences have been found to cause crashes in the OSX CoreText API +--- during rendering. While some specific sequences have made the rounds on the Internet, the specific code analysis +--- at http://www.theregister.co.uk/2015/05/27/text_message_unicode_ios_osx_vulnerability/ suggests a possible cause of +--- the problem which may be triggered by other currently unknown sequences as well. As the sequences aren't at +--- present predictable, we can't add to the UTF8 wrapper already in place for the Hammerspoon console. +---@param fn function +---@param interface hs.wifi.interfaces|nil +---@return scanObject +function hs.wifi.backgroundScan(fn, interface) end + +--- Returns whether or not a scan object has completed its scan for wireless networks. +--- +--- Note: This will be set whether or not an actual callback function was invoked. This method can be checked to see +--- if the cached data for the cachedScanResults entry returned by hs.wifi.interfaceDetails has been updated. +---@return boolean +function wifi:isDone() end + +-- ------------------------------------------------------------ +-- hs.wifi.watcher +-- ------------------------------------------------------------ + +---@class hs.wifi.watcher +hs.wifi.watcher = {} + +---@class watcher +local watcher = {} + +--- A table containing the possible event types that this watcher can monitor for. +---@type table +hs.wifi.watcher.eventTypes[] = nil + +--- Creates a new watcher for WiFi network events +--- +--- Note: For backwards compatibility, only "SSIDChange" is watched for by default, so existing code can continue to +--- ignore the callback function arguments unless you add or change events with the hs.wifi.watcher:watchingFor . +--- watcher - the watcher object itself +--- message - the message specifying the event, in this case "SSIDChange" +--- interface - the name of the interface for which the event occurred +--- Use hs.wifi.currentNetwork([interface]) to identify the new network, which may be nil when you leave a network. +--- watcher - the watcher object itself +--- message - the message specifying the event, in this case "BSSIDChange" +--- interface - the name of the interface for which the event occurred +--- watcher - the watcher object itself +--- message - the message specifying the event, in this case "countryCodeChange" +--- interface - the name of the interface for which the event occurred +--- watcher - the watcher object itself +--- message - the message specifying the event, in this case "linkChange" +--- interface - the name of the interface for which the event occurred +--- watcher - the watcher object itself +--- message - the message specifying the event, in this case "linkQualityChange" +--- interface - the name of the interface for which the event occurred +--- rssi - the RSSI value for the currently associated network on the Wi-Fi interface +--- rate - the transmit rate for the currently associated network on the Wi-Fi interface +--- watcher - the watcher object itself +--- message - the message specifying the event, in this case "modeChange" +--- interface - the name of the interface for which the event occurred +--- watcher - the watcher object itself +--- message - the message specifying the event, in this case "powerChange" +--- interface - the name of the interface for which the event occurred +--- watcher - the watcher object itself +--- message - the message specifying the event, in this case "scanCacheUpdated" +--- interface - the name of the interface for which the event occurred +---@param fn function +---@return watcher +function hs.wifi.watcher.new(fn) end + +--- Starts the SSID watcher +---@return watcher +function watcher:start() end + +--- Stops the SSID watcher +---@return watcher +function watcher:stop() end + +--- Get or set the specific types of wifi events to generate a callback for with this watcher. +--- +--- Note: the possible values for this method are described in hs.wifi.watcher.eventTypes . +--- the special string "all" specifies that all event types should be watched for. +---@param messages function|nil +---@return watcher|current- +function watcher:watchingFor(messages) end + +-- ------------------------------------------------------------ +-- hs.window +-- ------------------------------------------------------------ + +---@class hs.window +hs.window = {} + +---@class window +local window = {} + +--- The default duration for animations, in seconds. Initial value is 0.2; set to 0 to disable animations. +---@type any +hs.window.animationDuration (number) = nil + +--- Using +--- hs.window:setFrame() +--- in some cases does not work as expected: namely, the bottom (or Dock) edge, and edges between screens, might +---@type hs.window +hs.window.setFrameCorrectness = nil + +--- Returns all windows +--- +--- Note: visibleWindows() , orderedWindows() , get() , find() , and several more functions and methods in this and +--- other +--- modules make use of this function, so it is important to understand its limitations +--- This function queries all applications for their windows every time it is invoked; if you need to call it a lot and +--- performance is not acceptable consider using the hs.window.filter module +--- if Displays have separate Spaces is on (in System Preferences>Mission Control) the current Space is defined +--- as the union of all currently visible Spaces +--- minimized windows and hidden windows (i.e. belonging to hidden apps, e.g. via cmd-h) are always considered +--- to be in the current Space +--- This function filters out the desktop "window"; use hs.window.desktop() to address it. (Note however that +--- hs.application.get'Finder':allWindows() will include the desktop in the returned list) +--- Beside the limitations discussed above, this function will return all windows as reported by OSX, including some +--- "windows" that one wouldn't expect: for example, every Google Chrome (actual) window has a companion window for its +--- status bar; therefore you might get unexpected results - in the Chrome example, calling +--- hs.window.focusWindowSouth() from a Chrome window would end up "focusing" its status bar, and therefore the proper +--- window itself, seemingly resulting +--- in a no-op. In order to avoid such surprises you can use the hs.window.filter module, and more specifically +--- the default windowfilter ( hs.window.filter.default ) which filters out known cases of not-actual-windows +--- Some windows will not be reported by OSX - e.g. things that are on different Spaces, or things that are Full Screen +---@return list of hs.window objects +function hs.window.allWindows() end + +--- Returns the desktop "window" +--- +--- Note: The desktop belongs to Finder.app: when Finder is the active application, you can focus the desktop by cycling +--- through windows via cmd-` +--- The desktop window has no id, a role of AXScrollArea and no subrole +--- The desktop is filtered out from hs.window.allWindows() (and downstream uses) +---@return hs.window +function hs.window.desktop() end + +--- Gets all invisible windows +---@return list of hs.window objects +function hs.window.invisibleWindows() end + +--- Gets a table containing all the window data retrieved from +--- CGWindowListCreate +--- . +--- +--- Note: This allows you to get window information without Accessibility Permissions. +---@param allWindows any +---@return table +function hs.window.list(allWindows) end + +--- Gets all minimized windows +---@return list of hs.window objects +function hs.window.minimizedWindows() end + +--- Returns all visible windows, ordered from front to back +---@return list of hs.window objects +function hs.window.orderedWindows() end + +--- Enables/Disables window shadows +--- +--- Note: This function uses a private, undocumented OS X API call, so it is not guaranteed to work in any future OS X +--- release +---@param shadows boolean +---@return any +function hs.window.setShadows(shadows) end + +--- Returns a snapshot of the window specified by the ID as an +--- hs.image +--- object +--- +--- Note: See also method hs.window:snapshot() +--- Because the window ID cannot always be dynamically determined, this function will allow you to provide the ID of a +--- window that was cached earlier. +---@param ID string +---@param keepTransparency? number +---@return hs.image-object +function hs.window.snapshotForID(ID, keepTransparency) end + +--- Sets the timeout value used in the accessibility API. +---@param value number +---@return boolean +function hs.window.timeout(value) end + +--- Gets all visible windows +---@return list of hs.window objects +function hs.window.visibleWindows() end + +--- Finds windows +--- +--- Note: for convenience you can call this as hs.window(hint) +--- see also hs.window.get +--- for more sophisticated use cases and/or for better performance if you call this a lot, consider using +--- hs.window.filter +--- Usage: +--- -- by id +--- hs.window(8812):title() --> Hammerspoon Console +--- -- by title +--- hs.window'bash':application():name() --> Terminal +---@param hint hs.window +---@return hs.window +function hs.window.find(hint) end + +--- Returns the window that has keyboard/mouse focus +---@return window +function hs.window.focusedWindow() end + +--- Returns the focused window or, if no window has focus, the frontmost one +---@return hs.window +function hs.window.frontmostWindow() end + +--- Gets a specific window +--- +--- Note: see also hs.window.find and hs.application:getWindow() +---@param hint hs.window +---@return hs.window +function hs.window.get(hint) end + +--- Gets the +--- hs.application +--- object the window belongs to +---@return app|nil +function window:application() end + +--- Makes the window the main window of its application +--- +--- Note: Make a window become the main window does not transfer focus to the application. See hs.window.focus() +---@return window +function window:becomeMain() end + +--- Centers the window on a screen +---@param screen hs.screen|hs.screen.find|nil +---@param ensureInScreenBounds? any +---@param duration? hs.window.animationDuration|nil +---@return hs.window +function window:centerOnScreen(screen, ensureInScreenBounds, duration) end + +--- Closes the window +---@return boolean +function window:close() end + +--- Focuses the window +---@return hs.window +function window:focus() end + +--- Focuses the tab in the window's tab group at index, or the last tab if index is out of bounds +--- +--- Note: This method works with document tab groups and some app tabs, like Chrome and Safari. +---@param index number +---@return boolean +function window:focusTab(index) end + +--- Focuses the nearest possible window to the east (i.e. right) +--- +--- Note: If you don't pass candidateWindows , Hammerspoon will query for the list of all visible windows +--- every time this method is called; this can be slow, and some undesired "windows" could be included +--- (see the notes for hs.window.allWindows() ); consider using the equivalent methods in hs.window.filter instead +---@param candidateWindows candidate[]|nil +---@param frontmost? boolean|nil +---@param strict? boolean|nil +---@return boolean +function window:focusWindowEast(candidateWindows, frontmost, strict) end + +--- Focuses the nearest possible window to the north (i.e. up) +--- +--- Note: If you don't pass candidateWindows , Hammerspoon will query for the list of all visible windows +--- every time this method is called; this can be slow, and some undesired "windows" could be included +--- (see the notes for hs.window.allWindows() ); consider using the equivalent methods in hs.window.filter instead +---@param candidateWindows candidate[]|nil +---@param frontmost? boolean|nil +---@param strict? boolean|nil +---@return boolean +function window:focusWindowNorth(candidateWindows, frontmost, strict) end + +--- Focuses the nearest possible window to the south (i.e. down) +--- +--- Note: If you don't pass candidateWindows , Hammerspoon will query for the list of all visible windows +--- every time this method is called; this can be slow, and some undesired "windows" could be included +--- (see the notes for hs.window.allWindows() ); consider using the equivalent methods in hs.window.filter instead +---@param candidateWindows candidate[]|nil +---@param frontmost? boolean|nil +---@param strict? boolean|nil +---@return boolean +function window:focusWindowSouth(candidateWindows, frontmost, strict) end + +--- Focuses the nearest possible window to the west (i.e. left) +--- +--- Note: If you don't pass candidateWindows , Hammerspoon will query for the list of all visible windows +--- every time this method is called; this can be slow, and some undesired "windows" could be included +--- (see the notes for hs.window.allWindows() ); consider using the equivalent methods in hs.window.filter instead +---@param candidateWindows candidate[]|nil +---@param frontmost? boolean|nil +---@param strict? boolean|nil +---@return boolean +function window:focusWindowWest(candidateWindows, frontmost, strict) end + +--- Gets the frame of the window in absolute coordinates +---@return hs.geometry rect +function window:frame() end + +--- Gets the unique identifier of the window +---@return number|nil +function window:id() end + +--- Gets the fullscreen state of the window +---@return boolean|nil +function window:isFullScreen() end + +--- Determines if a window is maximizable +---@return boolean|nil +function window:isMaximizable() end + +--- Gets the minimized state of the window +---@return boolean +function window:isMinimized() end + +--- Determines if the window is a standard window +--- +--- Note: "Standard window" means that this is not an unusual popup window, a modal dialog, a floating window, etc. +---@return boolean +function window:isStandard() end + +--- Determines if a window is visible (i.e. not hidden and not minimized) +--- +--- Note: This does not mean the user can see the window - it may be obscured by other windows, or it may be off the +--- edge of the screen +---@return boolean +function window:isVisible() end + +--- Maximizes the window +--- +--- Note: The window will be resized as large as possible, without obscuring the dock/menu +---@param duration hs.window.animationDuration|nil +---@return hs.window +function window:maximize(duration) end + +--- Minimizes the window +--- +--- Note: This method will always animate per your system settings and is not affected by hs.window.animationDuration +---@return window +function window:minimize() end + +--- Moves the window +---@param rect hs.geometry +---@param screen? hs.screen|hs.screen.find|nil +---@param ensureInScreenBounds? any +---@param duration? hs.window.animationDuration|nil +---@return hs.window +function window:move(rect, screen, ensureInScreenBounds, duration) end + +--- Moves the window one screen east (i.e. right) +---@param noResize number +---@param ensureInScreenBounds any +---@param duration? hs.window.animationDuration|nil +---@return hs.window +function window:moveOneScreenEast(noResize, ensureInScreenBounds, duration) end + +--- Moves the window one screen north (i.e. up) +---@param noResize number +---@param ensureInScreenBounds any +---@param duration? hs.window.animationDuration|nil +---@return hs.window +function window:moveOneScreenNorth(noResize, ensureInScreenBounds, duration) end + +--- Moves the window one screen south (i.e. down) +---@param noResize number +---@param ensureInScreenBounds any +---@param duration? hs.window.animationDuration|nil +---@return hs.window +function window:moveOneScreenSouth(noResize, ensureInScreenBounds, duration) end + +--- Moves the window one screen west (i.e. left) +---@param noResize number +---@param ensureInScreenBounds any +---@param duration? hs.window.animationDuration|nil +---@return hs.window +function window:moveOneScreenWest(noResize, ensureInScreenBounds, duration) end + +--- Moves the window to a given screen, retaining its relative position and size +---@param screen hs.screen|hs.screen.find +---@param noResize? number +---@param ensureInScreenBounds? any +---@param duration? hs.window.animationDuration|nil +---@return hs.window +function window:moveToScreen(screen, noResize, ensureInScreenBounds, duration) end + +--- Moves and resizes the window to occupy a given fraction of the screen +--- +--- Note: An example, which would make a window fill the top-left quarter of the screen: +--- win:moveToUnit'[0.0,0.0,0.5,0.5]' +---@param unitrect hs.geometry +---@param duration? hs.window.animationDuration|nil +---@return hs.window +function window:moveToUnit(unitrect, duration) end + +--- Gets every window except this one +---@return list of hs.window objects +function window:otherWindowsAllScreens() end + +--- Gets other windows on the same screen +---@return list of hs.window objects +function window:otherWindowsSameScreen() end + +--- Brings a window to the front of the screen without focussing it +---@return window +function window:raise() end + +--- Gets the role of the window +---@return string +function window:role() end + +--- Gets the screen which the window is on +--- +--- Note: While windows can be dragged to span multiple screens, part of the window will disappear when the mouse is +--- released. The screen returned by this method will be the part of the window that remains visible. +---@return hs.screen +function window:screen() end + +--- Sends the window to the back +--- +--- Note: Due to the way this method works and OSX limitations, calling this method when you have a lot of randomly +--- overlapping (as opposed to neatly tiled) windows might be visually jarring, and take a fair amount of time to +--- complete. So if you don't use orderly layouts, or if you have a lot of windows in general, you're probably better +--- off using hs.application:hide() (or simply cmd-h ) +--- This method works by focusing all overlapping windows behind this one, front to back. If called on the focused +--- window, this method will switch focus to the topmost window under this one; otherwise, the currently focused window +--- will regain focus after this window has been sent to the back. +---@return hs.window +function window:sendToBack() end + +--- Sets the frame of the window in absolute coordinates +---@param rect hs.geometry +---@param duration? hs.window.animationDuration|nil +---@return hs.window +function window:setFrame(rect, duration) end + +--- Sets the frame of the window in absolute coordinates, possibly adjusted to ensure it is fully inside the screen +---@param rect hs.geometry +---@param duration? hs.window.animationDuration|nil +---@return hs.window +function window:setFrameInScreenBounds(rect, duration) end + +--- Sets the frame of the window in absolute coordinates, using the additional workarounds described in +--- hs.window.setFrameCorrectness +---@param rect hs.geometry +---@param duration? hs.window.animationDuration|nil +---@return hs.window +function window:setFrameWithWorkarounds(rect, duration) end + +--- Sets the fullscreen state of the window +---@param fullscreen boolean +---@return window +function window:setFullScreen(fullscreen) end + +--- Resizes the window +---@param size table +---@return window +function window:setSize(size) end + +--- Moves the window to a given point +---@param point table +---@return window +function window:setTopLeft(point) end + +--- Gets the size of the window +---@return size +function window:size() end + +--- Returns a snapshot of the window as an +--- hs.image +--- object +--- +--- Note: See also function hs.window.snapshotForID() +---@param keepTransparency number +---@return hs.image-object +function window:snapshot(keepTransparency) end + +--- Gets the subrole of the window +--- +--- Note: This typically helps to determine if a window is a special kind of window - such as a modal window, or a +--- floating window +---@return string +function window:subrole() end + +--- Gets the number of tabs in the window has +--- +--- Note: Intended for use with the focusTab method, if this returns a number, then focusTab can switch between that +--- many tabs. +---@return number|nil +function window:tabCount() end + +--- Gets the title of the window +---@return string +function window:title() end + +--- Toggles the fullscreen state of the window +--- +--- Note: Not all windows support being full-screened +---@return hs.window +function window:toggleFullScreen() end + +--- Toggles the zoom state of the window (this is effectively equivalent to clicking the green maximize/fullscreen +--- button at the top left of a window) +---@return window +function window:toggleZoom() end + +--- Gets the absolute co-ordinates of the top left of the window +---@return point +function window:topLeft() end + +--- Un-minimizes the window +---@return window +function window:unminimize() end + +--- Gets all windows to the east of this window +--- +--- Note: If you don't pass candidateWindows , Hammerspoon will query for the list of all visible windows every time +--- this method is called; this can be slow, and some undesired "windows" could be included (see the notes for +--- hs.window.allWindows() ); consider using the equivalent methods in hs.window.filter instead +---@param candidateWindows candidate[]|nil +---@param frontmost? boolean|nil +---@param strict? boolean|nil +---@return list of hs.window objects +function window:windowsToEast(candidateWindows, frontmost, strict) end + +--- Gets all windows to the north of this window +--- +--- Note: If you don't pass candidateWindows , Hammerspoon will query for the list of all visible windows every time +--- this method is called; this can be slow, and some undesired "windows" could be included (see the notes for +--- hs.window.allWindows() ); consider using the equivalent methods in hs.window.filter instead +---@param candidateWindows candidate[]|nil +---@param frontmost? boolean|nil +---@param strict? boolean|nil +---@return list of hs.window objects +function window:windowsToNorth(candidateWindows, frontmost, strict) end + +--- Gets all windows to the south of this window +--- +--- Note: If you don't pass candidateWindows , Hammerspoon will query for the list of all visible windows every time +--- this method is called; this can be slow, and some undesired "windows" could be included (see the notes for +--- hs.window.allWindows() ); consider using the equivalent methods in hs.window.filter instead +---@param candidateWindows candidate[]|nil +---@param frontmost? boolean|nil +---@param strict? boolean|nil +---@return list of hs.window objects +function window:windowsToSouth(candidateWindows, frontmost, strict) end + +--- Gets all windows to the west of this window +--- +--- Note: If you don't pass candidateWindows , Hammerspoon will query for the list of all visible windows every time +--- this method is called; this can be slow, and some undesired "windows" could be included (see the notes for +--- hs.window.allWindows() ); consider using the equivalent methods in hs.window.filter instead +---@param candidateWindows candidate[]|nil +---@param frontmost? boolean|nil +---@param strict? boolean|nil +---@return list of hs.window objects +function window:windowsToWest(candidateWindows, frontmost, strict) end + +--- Gets a rect-table for the location of the zoom button (the green button typically found at the top left of a window) +--- +--- Note: The co-ordinates in the rect-table (i.e. the x and y values) are in absolute co-ordinates, not relative to +--- the window the button is part of, or the screen the window is on +--- Although not perfect as such, this method can provide a useful way to find a region of the titlebar suitable for +--- simulating mouse click events on, with hs.eventtap +---@return rect-table|nil +function window:zoomButtonRect() end + +-- ------------------------------------------------------------ +-- hs.window.filter +-- ------------------------------------------------------------ + +---@class hs.window.filter +hs.window.filter = {} + +---@class filter +local filter = {} + +---@class hs.window.filter.filter +---@field default any The default windowfilter; it filters apps whose windows are transient in nature so that you're unlikely (and often +---@field defaultCurrentSpace any A copy of the default windowfilter (see hs.window.filter.default ) that only allows windows in the current +---@field hasNoWindows any Pseudo-event for hs.window.filter:subscribe() : the windowfilter now rejects all windows +---@field hasWindow any Pseudo-event for hs.window.filter:subscribe() : the windowfilter now allows one window +---@field sortByCreated any Sort order for hs.window.filter:getWindows() : windows are sorted in order of creation, oldest... + +--- The default windowfilter; it filters apps whose windows are transient in nature so that you're unlikely (and often +---@type any +hs.window.filter.default = nil + +--- A copy of the default windowfilter (see +--- hs.window.filter.default +--- ) that only allows windows in the current +---@type hs.window.filter.default +hs.window.filter.defaultCurrentSpace = nil + +--- Pseudo-event for +--- hs.window.filter:subscribe() +--- : the windowfilter now rejects all windows +---@type hs.window.filter +hs.window.filter.hasNoWindows = nil + +--- Pseudo-event for +--- hs.window.filter:subscribe() +--- : the windowfilter now allows one window +---@type hs.window.filter +hs.window.filter.hasWindow = nil + +--- Sort order for +--- hs.window.filter:getWindows() +--- : windows are sorted in order of creation, oldest first (see also +--- hs.window.filter:setSortOrder() +--- ) +---@type hs.window.filter +hs.window.filter.sortByCreated = nil + +--- Sort order for +--- hs.window.filter:getWindows() +--- : windows are sorted in order of creation, newest first (see also +--- hs.window.filter:setSortOrder() +--- ) +---@type hs.window.filter +hs.window.filter.sortByCreatedLast = nil + +--- Sort order for +--- hs.window.filter:getWindows() +--- : windows are sorted in order of focus received, least recently first (see also +--- hs.window.filter:setSortOrder() +--- ) +---@type hs.window.filter +hs.window.filter.sortByFocused = nil + +--- Sort order for +--- hs.window.filter:getWindows() +--- : windows are sorted in order of focus received, most recently first (see also +--- hs.window.filter:setSortOrder() +--- ) +---@type hs.window.filter +hs.window.filter.sortByFocusedLast = nil + +--- Pseudo-event for +--- hs.window.filter:subscribe() +--- : a previously rejected window (or a newly created one) is now allowed +---@type hs.window.filter +hs.window.filter.windowAllowed = nil + +--- Event for +--- hs.window.filter:subscribe() +--- : a new window was created +---@type hs.window.filter +hs.window.filter.windowCreated = nil + +--- Event for +--- hs.window.filter:subscribe() +--- : a window was destroyed +---@type hs.window.filter +hs.window.filter.windowDestroyed = nil + +--- Event for +--- hs.window.filter:subscribe() +--- : a window received focus +---@type hs.window.filter +hs.window.filter.windowFocused = nil + +--- Event for +--- hs.window.filter:subscribe() +--- : a window was expanded to fullscreen +---@type hs.window.filter +hs.window.filter.windowFullscreened = nil + +--- Event for +--- hs.window.filter:subscribe() +--- : a window was hidden (its app was hidden, e.g. via +--- cmd-h +--- ) +---@type hs.window.filter +hs.window.filter.windowHidden = nil + +--- Event for +--- hs.window.filter:subscribe() +--- : a window is now in the current Mission Control Space, due to +---@type hs.window.filter +hs.window.filter.windowInCurrentSpace = nil + +--- Event for +--- hs.window.filter:subscribe() +--- : a window was minimized +---@type hs.window.filter +hs.window.filter.windowMinimized = nil + +--- Event for +--- hs.window.filter:subscribe() +--- : a window was moved or resized, including toggling fullscreen/maximize +---@type hs.window.filter +hs.window.filter.windowMoved = nil + +--- Event for +--- hs.window.filter:subscribe() +--- : a window that used to be in the current Mission Control Space isn't anymore, +---@type hs.window.filter +hs.window.filter.windowNotInCurrentSpace = nil + +--- Event for +--- hs.window.filter:subscribe() +--- : a window is no longer +--- actually +--- visible on any screen because it was minimized, closed, +---@type hs.window.filter +hs.window.filter.windowNotOnScreen = nil + +--- Event for +--- hs.window.filter:subscribe() +--- : a window is no longer "visible" (in +--- any +--- Mission Control Space, as per +--- hs.window:isVisible() +--- ) +---@type hs.window.filter|hs.window +hs.window.filter.windowNotVisible = nil + +--- Event for +--- hs.window.filter:subscribe() +--- : a window became +--- actually +--- visible on screen (i.e. it's "visible" as per +--- hs.window:isVisible() +---@type hs.window.filter|hs.window +hs.window.filter.windowOnScreen = nil + +--- Pseudo-event for +--- hs.window.filter:subscribe() +--- : a previously allowed window (or a window that's been destroyed) is now rejected +---@type hs.window.filter +hs.window.filter.windowRejected = nil + +--- Pseudo-event for +--- hs.window.filter:subscribe() +--- : the list of allowed windows (as per +--- windowfilter:getWindows() +--- ) has changed +---@type hs.window.filter +hs.window.filter.windowsChanged = nil + +--- Event for +--- hs.window.filter:subscribe() +--- : a window's title changed +---@type hs.window.filter +hs.window.filter.windowTitleChanged = nil + +--- Event for +--- hs.window.filter:subscribe() +--- : a window lost focus +---@type hs.window.filter +hs.window.filter.windowUnfocused = nil + +--- Event for +--- hs.window.filter:subscribe() +--- : a window was reverted back from fullscreen +---@type hs.window.filter +hs.window.filter.windowUnfullscreened = nil + +--- Event for +--- hs.window.filter:subscribe() +--- : a window was unhidden (its app was unhidden, e.g. via +--- cmd-h +--- ) +---@type hs.window.filter +hs.window.filter.windowUnhidden = nil + +--- Event for +--- hs.window.filter:subscribe() +--- : a window was unminimized +---@type hs.window.filter +hs.window.filter.windowUnminimized = nil + +--- Event for +--- hs.window.filter:subscribe() +--- : a window became "visible" (in +--- any +--- Mission Control Space, as per +--- hs.window:isVisible() +--- ) +---@type hs.window.filter|hs.window +hs.window.filter.windowVisible = nil + +--- A table for window roles (as per +--- hs.window:subrole() +--- ) that are allowed by default. +---@type table +hs.window.filter.allowedWindowRoles = nil + +--- Tells all windowfilters whether to refresh all windows when the user switches to a different Mission Control Space. +---@type any +hs.window.filter.forceRefreshOnSpaceChange = nil + +--- A table of application names (as per +--- hs.application:name() +--- ) that are always ignored by this module. +---@type table +hs.window.filter.ignoreAlways = nil + +--- Convenience function to focus the nearest window to the east +--- +--- Note: This is a convenience wrapper that performs hs.window.filter.defaultCurrentSpace:focusWindowEast(nil,nil,true) +---@return any +function hs.window.filter.focusEast() end + +--- Convenience function to focus the nearest window to the north +--- +--- Note: This is a convenience wrapper that performs hs.window.filter.defaultCurrentSpace:focusWindowNorth(nil,nil,true) +---@return any +function hs.window.filter.focusNorth() end + +--- Convenience function to focus the nearest window to the south +--- +--- Note: This is a convenience wrapper that performs hs.window.filter.defaultCurrentSpace:focusWindowSouth(nil,nil,true) +---@return any +function hs.window.filter.focusSouth() end + +--- Convenience function to focus the nearest window to the west +--- +--- Note: This is a convenience wrapper that performs hs.window.filter.defaultCurrentSpace:focusWindowWest(nil,nil,true) +---@return any +function hs.window.filter.focusWest() end + +--- Checks whether an app is a known non-GUI app, as per +--- hs.window.filter.ignoreAlways +---@param appname hs.application +---@return boolean +function hs.window.filter.isGuiApp(appname) end + +--- Callback to inform all windowfilters that the user initiated a switch to a (numbered) Mission Control Space. +--- +--- Note: Only use this function if "Displays have separate Spaces" and "Automatically rearrange Spaces" are OFF in +--- System Preferences>Mission Control +--- Calling this function will set hs.window.filter.forceRefreshOnSpaceChange to false +--- If you defined one or more Spaces-aware windowfilters (i.e. when the currentSpace field of a filter is present), +--- windows need refreshing at every space change anyway, so using this callback will not result in improved performance +--- See hs.window.filter.forceRefreshOnSpaceChange for an overview of Spaces limitations in Hammerspoon. If you often +--- (or always) change Space via the "numbered" Mission Control keyboard shortcuts (by default, ctrl-1 etc.), you can +--- call this function from your init.lua when intercepting these shortcuts; for example: +--- hs.hotkey.bind('ctrl','1',nil,function()hs.window.filter.switchedToSpace(1)end) +--- hs.hotkey.bind('ctrl','2',nil,function()hs.window.filter.switchedToSpace(2)end) +--- -- etc. +--- Using this callback results in slightly better performance than setting forceRefreshOnSpaceChange to true , since +--- already visited Spaces are remembered and no refreshing is necessary when switching back to those. +---@param space number +---@return any +function hs.window.filter.switchedToSpace(space) end + +--- Returns a copy of an hs.window.filter object that you can further restrict or expand +---@param windowfilter hs.window.filter +---@param logname? hs.logger|nil +---@param loglevel? hs.logger|nil +---@return hs.window.filter +function hs.window.filter.copy(windowfilter, logname, loglevel) end + +--- Creates a new hs.window.filter instance +---@param fn function +---@param logname? hs.logger|nil +---@param loglevel? hs.logger|nil +---@return hs.window.filter +function hs.window.filter.new(fn, logname, loglevel) end + +--- Sets the windowfilter to allow all visible windows belonging to a specific app +--- +--- Note: this is just a convenience wrapper for windowfilter:setAppFilter(appname,{visible=true}) +---@param appname hs.application +---@return hs.window.filter +function filter:allowApp(appname) end + +--- Focuses the nearest window to the east of a given window +--- +--- Note: This is a convenience wrapper that performs hs.window.focusWindowEast(window,self:getWindows(),...) +--- You'll likely want to add :setCurrentSpace(true) to the windowfilter used for this method call +---@param window hs.window|hs.window.frontmostWindow|nil +---@param frontmost boolean|nil +---@param strict boolean|nil +---@return any +function filter:focusWindowEast(window, frontmost, strict) end + +--- Focuses the nearest window to the south of a given window +--- +--- Note: This is a convenience wrapper that performs hs.window.focusWindowNorth(window,self:getWindows(),...) +--- You'll likely want to add :setCurrentSpace(true) to the windowfilter used for this method call +---@param window hs.window|hs.window.frontmostWindow|nil +---@param frontmost boolean|nil +---@param strict boolean|nil +---@return any +function filter:focusWindowNorth(window, frontmost, strict) end + +--- Focuses the nearest window to the north of a given window +--- +--- Note: This is a convenience wrapper that performs hs.window.focusWindowSouth(window,self:getWindows(),...) +--- You'll likely want to add :setCurrentSpace(true) to the windowfilter used for this method call +---@param window hs.window|hs.window.frontmostWindow|nil +---@param frontmost boolean|nil +---@param strict boolean|nil +---@return any +function filter:focusWindowSouth(window, frontmost, strict) end + +--- Focuses the nearest window to the west of a given window +--- +--- Note: This is a convenience wrapper that performs hs.window.focusWindowWest(window,self:getWindows(),...) +--- You'll likely want to add :setCurrentSpace(true) to the windowfilter used for this method call +---@param window hs.window|hs.window.frontmostWindow|nil +---@param frontmost boolean|nil +---@param strict boolean|nil +---@return any +function filter:focusWindowWest(window, frontmost, strict) end + +--- Return a table with all the filtering rules defined for this windowfilter +---@return table +function filter:getFilters() end + +--- Gets the current windows allowed by this windowfilter +---@param sortOrder hs.window.filter.sortBy|hs.window.filter|nil +---@return list of hs.window objects +function filter:getWindows(sortOrder) end + +--- Checks if an app is allowed by the windowfilter +---@param appname hs.application +---@return boolean +function filter:isAppAllowed(appname) end + +--- Checks if a window is allowed by the windowfilter +---@param window hs.window +---@return boolean +function filter:isWindowAllowed(window) end + +--- Stops the windowfilter event subscriptions; no more event callbacks will be triggered, but the subscriptions remain +--- intact for a subsequent call to +--- hs.window.filter:resume() +---@return hs.window.filter +function filter:pause() end + +--- Sets the windowfilter to outright reject any windows belonging to a specific app +--- +--- Note: this is just a convenience wrapper for windowfilter:setAppFilter(appname,false) +---@param appname hs.application +---@return hs.window.filter +function filter:rejectApp(appname) end + +--- Resumes the windowfilter event subscriptions +---@return hs.window.filter +function filter:resume() end + +--- Sets the detailed filtering rules for the windows of a specific app +--- +--- Note: Passing focused=true in filter will (naturally) result in the windowfilter ever allowing 1 window at most +--- If you want to allow all windows for an app, including invisible ones, pass an empty table for filter +--- Spaces-aware windowfilters might experience a (sometimes significant) delay after every Space switch, since (due to +--- OS X limitations) they must re-query for the list of all windows in the current Space every time. +--- If System Preferences>Mission Control>Displays have separate Spaces is on , the current Space is defined as the +--- union of all the Spaces that are currently visible +--- This table explains the effects of different combinations of visible and currentSpace , showing which windows will +--- be allowed: +--- |visible= nil | true | false | +--- |currentSpace|------------------------------------------|------------------------------|--------------| +--- | nil |all |visible in ANY space |min and hidden| +--- | true |visible in CURRENT space+min and hidden |visible in CURRENT space |min and hidden| +--- | false |visible in OTHER space only+min and hidden|visible in OTHER space only |none | +---@param appname hs.application +---@param filter function +---@return hs.window.filter +function filter:setAppFilter(appname, filter) end + +--- Sets whether the windowfilter should only allow (or reject) windows in the current Mission Control Space +--- +--- Note: This is just a convenience wrapper for setting the currentSpace field in the override filter (other +--- fields will be left untouched); per-app filters will maintain their currentSpace field, if present, as is +--- Spaces-aware windowfilters might experience a (sometimes significant) delay after every Space switch, since +--- (due to OS X limitations) they must re-query for the list of all windows in the current Space every time. +---@param val boolean +---@return hs.window.filter +function filter:setCurrentSpace(val) end + +--- Set the default filtering rules to be used for apps without app-specific rules +---@param filter hs.window.filter +---@return hs.window.filter +function filter:setDefaultFilter(filter) end + +--- Sets multiple filtering rules +--- +--- Note: every filter definition in filters will overwrite the preexisting one for the relevant application, if +--- present; +--- this also applies to the special default and override filters, if included +---@param filters table +---@return hs.window.filter +function filter:setFilters(filters) end + +--- Set overriding filtering rules that will be applied for all apps before any app-specific rules +---@param filter hs.window.filter +---@return hs.window.filter +function filter:setOverrideFilter(filter) end + +--- Sets the allowed screen regions for this windowfilter +--- +--- Note: This is just a convenience wrapper for setting the allowRegions field in the override filter (other fields +--- will be left untouched); per-app filters will maintain their allowRegions and rejectRegions fields, if present +---@param regions hs.geometry +---@return hs.window.filter +function filter:setRegions(regions) end + +--- Sets the allowed screens for this windowfilter +--- +--- Note: This is just a convenience wrapper for setting the allowScreens field in the override filter (other +--- fields will be left untouched); per-app filters will maintain their allowScreens and rejectScreens fields, if +--- present +---@param screens any +---@return hs.window.filter +function filter:setScreens(screens) end + +--- Sets the sort order for this windowfilter's +--- :getWindows() +--- method +--- +--- Note: The default sort order for all windowfilters (that is, until changed by this method) is +--- hs.window.filter.sortByFocusedLast +---@param sortOrder hs.window.filter.sortBy +---@return hs.window.filter +function filter:setSortOrder(sortOrder) end + +--- Subscribe to one or more events on the allowed windows +--- +--- Note: Passing lists means that all the fn s will be called when any of the event s fires, so it's not a shortcut +--- for subscribing distinct callbacks to distinct events; use a map or chained :subscribe calls for that. +--- Use caution with immediate : if for example you're subscribing to hs.window.filter.windowUnfocused , fn (s) will be +--- called for all the windows except the currently focused one. +--- If the windowfilter was paused with hs.window.filter:pause() , calling this will resume it. +---@param event string +---@param fn function +---@param immediate? function|nil +---@return hs.window.filter +function filter:subscribe(event, fn, immediate) end + +--- Removes one or more event subscriptions +--- +--- Note: You must pass at least one of event or fn +--- If calling this on the default (or any other shared use) windowfilter, do not pass events, as that would remove all +--- the callbacks for the events including ones subscribed elsewhere that you might not be aware of. You should +--- instead keep references to your functions and pass in those. +---@param event string +---@param fn? function +---@return hs.window.filter +function filter:unsubscribe(event, fn) end + +--- Removes all event subscriptions +--- +--- Note: You should not use this on the default windowfilter or other shared-use windowfilters +---@return hs.window.filter +function filter:unsubscribeAll() end + +--- Gets all visible windows allowed by this windowfilter that lie to the east a given window +--- +--- Note: This is a convenience wrapper that returns hs.window.windowsToEast(window,self:getWindows(),...) +--- You'll likely want to add :setCurrentSpace(true) to the windowfilter used for this method call (or just use +--- hs.window.filter.defaultCurrentSpace ) +---@param window hs.window|hs.window.frontmostWindow|nil +---@param frontmost boolean|nil +---@param strict boolean|nil +---@return hs.window +function filter:windowsToEast(window, frontmost, strict) end + +--- Gets all visible windows allowed by this windowfilter that lie to the north a given window +--- +--- Note: This is a convenience wrapper that returns hs.window.windowsToNorth(window,self:getWindows(),...) +--- You'll likely want to add :setCurrentSpace(true) to the windowfilter used for this method call (or just use +--- hs.window.filter.defaultCurrentSpace ) +---@param window hs.window|hs.window.frontmostWindow|nil +---@param frontmost boolean|nil +---@param strict boolean|nil +---@return hs.window +function filter:windowsToNorth(window, frontmost, strict) end + +--- Gets all visible windows allowed by this windowfilter that lie to the south a given window +--- +--- Note: This is a convenience wrapper that returns hs.window.windowsToSouth(window,self:getWindows(),...) +--- You'll likely want to add :setCurrentSpace(true) to the windowfilter used for this method call (or just use +--- hs.window.filter.defaultCurrentSpace ) +---@param window hs.window|hs.window.frontmostWindow|nil +---@param frontmost boolean|nil +---@param strict boolean|nil +---@return hs.window +function filter:windowsToSouth(window, frontmost, strict) end + +--- Gets all visible windows allowed by this windowfilter that lie to the west a given window +--- +--- Note: This is a convenience wrapper that returns hs.window.windowsToWest(window,self:getWindows(),...) +--- You'll likely want to add :setCurrentSpace(true) to the windowfilter used for this method call (or just use +--- hs.window.filter.defaultCurrentSpace ) +---@param window hs.window|hs.window.frontmostWindow|nil +---@param frontmost boolean|nil +---@param strict boolean|nil +---@return hs.window +function filter:windowsToWest(window, frontmost, strict) end + +-- ------------------------------------------------------------ +-- hs.window.highlight +-- ------------------------------------------------------------ + +---@class hs.window.highlight +hs.window.highlight = {} + +--- Allows customization of the highlight overlays and behaviour. +---@type any +hs.window.highlight.ui = nil + +--- Starts the module +--- +--- Note: overlay mode is disabled by default - see hs.window.highlight.ui.overlayColor +---@param windowfilterIsolate hs.window.filter|hs.window.highlight.toggleIsolate|nil +---@param windowfilterOverlay? hs.window.filter|nil +---@return any +function hs.window.highlight.start(windowfilterIsolate, windowfilterOverlay) end + +--- Stops the module and disables focused window highlighting (both "overlay" and "isolate" mode) +---@return any +function hs.window.highlight.stop() end + +--- Sets or clears the user override for "isolate" mode. +--- +--- Note: This function should be bound to a hotkey, e.g.: hs.hotkey.bind('ctrl-cmd','\','Isolate',hs.window.highlight.toggleIsolate) +---@param v any +---@return any +function hs.window.highlight.toggleIsolate(v) end + +-- ------------------------------------------------------------ +-- hs.window.layout +-- ------------------------------------------------------------ + +---@class hs.window.layout +hs.window.layout = {} + +---@class layout +local layout = {} + +--- When "active mode" windowlayouts apply a rule, they will pause briefly for this amount of time in seconds, to allow +--- windows +---@type any +hs.window.layout.applyDelay = nil + +--- The number of seconds to wait, after a screen configuration change has been detected, before +---@type number +hs.window.layout.screensChangedDelay = nil + +--- Applies a layout +--- +--- Note: this is a convenience wrapper for "passive mode" use that creates, applies, and deletes a windowlayout object; +--- do not use shared windowfilters in rules , as they'll be deleted; you can just use constructor argument maps instead +---@param rules hs.window.layout.new +---@return any +function hs.window.layout.applyLayout(rules) end + +--- Pauses all active windowlayout instances +---@return any +function hs.window.layout.pauseAllInstances() end + +--- Resumes all active windowlayout instances +---@return any +function hs.window.layout.resumeAllInstances() end + +--- Creates a new hs.window.layout instance +---@param rules table +---@param logname? hs.logger|nil +---@param loglevel? hs.logger|nil +---@return hs.window.layout +function hs.window.layout.new(rules, logname, loglevel) end + +--- Applies the layout +--- +--- Note: if a screen configuration is defined for this windowfilter, and currently not satisfied, this method will do +--- nothing +---@return hs.window.layout +function layout:apply() end + +--- Return a table with all the rules (and the screen configuration, if present) defined for this windowlayout +---@return table +function layout:getRules() end + +--- Pauses an active windowlayout instance; while paused no automatic window management will occur +---@return hs.window.layout +function layout:pause() end + +--- Resumes an active windowlayout instance after it was paused +--- +--- Note: if a screen configuration is defined for this windowfilter, and currently not satisfied, this method will do +--- nothing +---@return hs.window.layout +function layout:resume() end + +--- Determines the screen configuration that permits applying this windowlayout +--- +--- Note: If screens is nil , any previous screen configuration is removed, and this windowlayout will be always allowed +--- For "active" windowlayouts, call this method before calling hs.window.layout:start() +--- By using hs.geometry size objects as hints you can define separate layouts for the same physical screen at +--- different resolutions +--- With this method you can define different windowlayouts for different screen configurations (as per System +--- Preferences->Displays->Arrangement). +--- "passive mode" use: you call :apply() on both on your chosen hotkey (via hs.hotkey:bind() ), but only the +--- appropriate layout for the current arrangement will be applied +--- "active mode" use: you just call :start() on both windowlayouts; as you switch between workplaces (by attaching or +--- detaching external screens) the correct layout "kicks in" automatically - this is in effect a convenience wrapper +--- that calls :pause() on the no longer relevant layout, and :resume() on the appropriate one, at every screen +--- configuration change +---@param screens any +---@return hs.window.layout +function layout:setScreenConfiguration(screens) end + +--- Puts a windowlayout instance in "active mode" +--- +--- Note: If a screen configuration is defined for this windowfilter, and currently not satisfied, this windowfilter +--- will be put in "active mode" but will remain paused until the screen configuration requirements are met +--- When in active mode, a windowlayout instance will constantly monitor the windowfilters for its rules, by +--- subscribing to all the relevant events. As soon as any change is detected (e.g. when you drag a window, switch +--- focus, open or close apps/windows, etc.) the relative rule will be automatically re-applied. In other words, the +--- rules you defined will remain enforced all the time, instead of waiting for manual intervention via +--- hs.window.layout:apply() . +---@return hs.window.layout +function layout:start() end + +--- Stops a windowlayout instance (i.e. not in "active mode" anymore) +---@return hs.window.layout +function layout:stop() end + +-- ------------------------------------------------------------ +-- hs.window.switcher +-- ------------------------------------------------------------ + +---@class hs.window.switcher +hs.window.switcher = {} + +---@class switcher +local switcher = {} + +--- Allows customization of the switcher behaviour and user interface +---@type any +hs.window.switcher.ui = nil + +--- Shows the switcher (if not yet visible) and selects the next window +--- +--- Note: the switcher will be dismissed (and the selected window focused) when all modifier keys are released +---@return any +function hs.window.switcher.nextWindow() end + +--- Shows the switcher (if not yet visible) and selects the previous window +--- +--- Note: the switcher will be dismissed (and the selected window focused) when all modifier keys are released +---@return any +function hs.window.switcher.previousWindow() end + +--- Creates a new switcher instance; it can use a windowfilter to determine which windows to show +---@param windowfilter any +---@param uiPrefs? hs.window.switcher.ui|nil +---@param logname? hs.logger|nil +---@param loglevel? hs.logger|nil +---@return hs.window.switcher +function hs.window.switcher.new(windowfilter, uiPrefs, logname, loglevel) end + +--- Shows the switcher instance (if not yet visible) and selects the next window +--- +--- Note: the switcher will be dismissed (and the selected window focused) when all modifier keys are released +---@return any +function switcher:next() end + +--- Shows the switcher instance (if not yet visible) and selects the previous window +--- +--- Note: the switcher will be dismissed (and the selected window focused) when all modifier keys are released +---@return any +function switcher:previous() end + +-- ------------------------------------------------------------ +-- hs.window.tiling +-- ------------------------------------------------------------ + +---@class hs.window.tiling +hs.window.tiling = {} + +--- Tile (or fit) windows into a rect +--- +--- Note: To ensure all windows are placed in a row (side by side), use a very small aspect ratio (for "tall and +--- narrow" windows) like 0.01; +--- similarly, to have all windows in a column, use a very large aspect ratio (for "short and wide") like 100 +--- Hidden and minimized windows will be processed as well: the rect will have "gaps" where the invisible windows +--- would lie, that will get filled as the windows get unhidden/unminimized +---@param windows hs.window +---@param rect hs.geometry +---@param desiredAspect? hs.geometry|nil +---@param processInOrder? any +---@param preserveRelativeArea? any +---@param animationDuration? hs.window.animationDuration|nil +---@return any +function hs.window.tiling.tileWindows(windows, rect, desiredAspect, processInOrder, preserveRelativeArea, animationDuration) end \ No newline at end of file diff --git a/base/hammerspoon/init.lua b/base/hammerspoon/init.lua new file mode 100644 index 0000000..620b767 --- /dev/null +++ b/base/hammerspoon/init.lua @@ -0,0 +1,204 @@ +-- ╭─────────────────────────────────────────────────────────╮ +-- │ Hammerspoon config file │ +-- ╰─────────────────────────────────────────────────────────╯ +-- init.lua — Pure Hammerspoon window controls +-- Converted from skhdrc logic; expanded with per‑display grids, +-- app rules with groups, wrap‑around focus, cross‑display moves, +-- and overlay/notification toggles. +-- Author: Ismo Vuorinen (ivuorinen) + +-------------------------------------------------- +-- Caps Lock as Meh key (Shift+Control+Alt) +-------------------------------------------------- +-- Prerequisites: +-- 1. Go to System Settings → Keyboard → Keyboard Shortcuts → Modifier Keys +-- 2. Set Caps Lock to "No Action" (you mentioned you already did this) +-- 3. Install Karabiner-Elements: brew install --cask karabiner-elements +-- 4. Open Karabiner-Elements, go to "Simple Modifications" +-- 5. Add: caps_lock → f18 +-- +-- Then you can use F18 as your Meh key in Hammerspoon: +local f18 = hs.hotkey.modal.new() + +-- Capture F18 key press/release +hs.hotkey.bind({}, 'F18', function() + f18:enter() +end, function() + f18:exit() +end) + +-- Meh (F18/Caps Lock) key bindings for window management +-- These provide quick access to common window operations + +-- Helper function to get focused window +local function W() + return hs.window.focusedWindow() +end + +-- Window positioning: thirds (U/I/O) +f18:bind({}, 'u', function() + local w = W() + if w then + w:moveToUnit({ x = 0, y = 0, w = 1 / 3, h = 1 }, 0) + end +end) +f18:bind({}, 'i', function() + local w = W() + if w then + w:moveToUnit({ x = 1 / 3, y = 0, w = 1 / 3, h = 1 }, 0) + end +end) +f18:bind({}, 'o', function() + local w = W() + if w then + w:moveToUnit({ x = 2 / 3, y = 0, w = 1 / 3, h = 1 }, 0) + end +end) + +-- Window positioning: half width, full height (Y) +f18:bind({}, 'y', function() + local w = W() + if w then + w:moveToUnit({ x = 0, y = 0, w = 0.5, h = 1 }, 0) + end +end) + +-- Cycle through all windows (H/L) +-- We need to maintain state to properly cycle through all windows +local windowCycleIndex = 1 +local windowCycleList = {} +local lastCycleTime = 0 + +local function getWindowCycleList() + local currentTime = hs.timer.secondsSinceEpoch() + -- Reset if more than 2 seconds have passed since last cycle + if currentTime - lastCycleTime > 2 then + windowCycleIndex = 1 + windowCycleList = hs.window.orderedWindows() + end + lastCycleTime = currentTime + return windowCycleList +end + +f18:bind({}, 'h', function() + local windows = getWindowCycleList() + if #windows <= 1 then + return + end + + -- Cycle backward + windowCycleIndex = windowCycleIndex - 1 + if windowCycleIndex < 1 then + windowCycleIndex = #windows + end + + windows[windowCycleIndex]:focus() +end) + +f18:bind({}, 'l', function() + local windows = getWindowCycleList() + if #windows <= 1 then + return + end + + -- Cycle forward + windowCycleIndex = windowCycleIndex + 1 + if windowCycleIndex > #windows then + windowCycleIndex = 1 + end + + windows[windowCycleIndex]:focus() +end) + +-- Window sizing: maximize (Up/J) and center (Down) +f18:bind({}, 'up', function() + local w = W() + if w then + w:maximize(0) + end +end) +f18:bind({}, 'j', function() + local w = W() + if w then + w:maximize(0) + end +end) +f18:bind({}, 'down', function() + local w = W() + if not w then + return + end + local f = w:frame() + local sf = w:screen():frame() + if f.w < sf.w * 0.95 then + w:maximize(0) + else + local ww, hh = math.floor(sf.w * 0.5), math.floor(sf.h * 0.9) + local xx = sf.x + math.floor((sf.w - ww) / 2) + local yy = sf.y + math.floor((sf.h - hh) / 2) + w:setFrame({ x = xx, y = yy, w = ww, h = hh }, 0) + end +end) +f18:bind({}, 'k', function() + local w = W() + if w then + local sf = w:screen():frame() + local ww, hh = math.floor(sf.w * 0.9), math.floor(sf.h * 0.9) + local xx = sf.x + math.floor((sf.w - ww) / 2) + local yy = sf.y + math.floor((sf.h - hh) / 2) + w:setFrame({ x = xx, y = yy, w = ww, h = hh }, 0) + end +end) + +-- Move to next/previous screen (. and ,) +f18:bind({}, '.', function() + local w = W() + if w then + local s = w:screen() + local ns = s:toEast() or s:toWest() + if ns then + w:moveToScreen(ns, true, true, 0) + end + end +end) +f18:bind({}, ',', function() + local w = W() + if w then + local s = w:screen() + local ps = s:toWest() or s:toEast() + if ps then + w:moveToScreen(ps, true, true, 0) + end + end +end) + +-- Window positioning: halves (Left/Right arrows) +f18:bind({}, 'left', function() + local w = W() + if w then + w:moveToUnit(hs.layout.left50, 0) + end +end) +f18:bind({}, 'right', function() + local w = W() + if w then + w:moveToUnit(hs.layout.right50, 0) + end +end) + +-- Paste from clipboard with Meh + V +f18:bind({}, 'v', function() + hs.eventtap.keyStrokes(hs.pasteboard.getContents()) +end) + +-- Paste 1Password secret with Meh + P +f18:bind({}, 'p', function() + local output, status = hs.execute('op read "op://Svea/3hzhctmvovbwlgulv7mgy25rf4/login-input"', true) + if status then + hs.eventtap.keyStrokes(output:gsub('%s+$', '')) -- trim trailing whitespace + else + hs.alert.show('1Password CLI error') + end +end) + +-- require 'generate_emmylua' diff --git a/config/homebrew/Brewfile b/config/homebrew/Brewfile index 122ac09..48821d5 100644 --- a/config/homebrew/Brewfile +++ b/config/homebrew/Brewfile @@ -38,6 +38,8 @@ brew "openssl@3" brew "cryptography" # YAML Parser brew "libyaml" +# Display directories as trees (with optional color/HTML output) +brew "tree" # Automate deployment, configuration, and upgrading brew "ansible" # Checks ansible playbooks for practices and behaviour @@ -104,7 +106,7 @@ brew "glib" brew "cargo-binstall" # Multi-platform support library with a focus on asynchronous I/O brew "libuv" -# Platform built on V8 to build network applications +# Open-source, cross-platform JavaScript runtime environment brew "node", link: false # CLI tool for analyzing Claude Code usage from local JSONL files brew "ccusage" @@ -230,6 +232,8 @@ brew "luarocks" brew "lzip" # Swiss Army Knife for macOS brew "m-cli" +# Cross platform, open source .NET development framework +brew "mono" # Collection of tools that nobody wrote when UNIX was young brew "moreutils" # NCurses Disk Usage @@ -290,8 +294,8 @@ brew "tflint" brew "tfsec" # Terminal multiplexer brew "tmux" -# Display directories as trees (with optional color/HTML output) -brew "tree" +# Extremely fast Python package installer and resolver, written in Rust +brew "uv" # Tool for creating isolated virtual python environments brew "virtualenv" # Command-line interface to the WakaTime api @@ -349,13 +353,18 @@ cask "fantastical" cask "font-jetbrains-mono" cask "font-jetbrains-mono-nerd-font" cask "font-monaspace" +cask "font-monaspace-nf" cask "font-open-sans" # GIT client cask "fork" +# Desktop automation application +cask "hammerspoon" # HTTP and GraphQL Client cask "insomnia" # JetBrains tools manager cask "jetbrains-toolbox" +# Keyboard customiser +cask "karabiner-elements" # End-to-end encryption software cask "keybase" # Kubernetes IDE diff --git a/config/karabiner/karabiner.json b/config/karabiner/karabiner.json new file mode 100644 index 0000000..2e6943b --- /dev/null +++ b/config/karabiner/karabiner.json @@ -0,0 +1,68 @@ +{ + "profiles": [ + { + "complex_modifications": { + "rules": [ + { + "description": "Change right_command+hjkl to arrow keys", + "manipulators": [ + { + "from": { + "key_code": "h", + "modifiers": { + "mandatory": ["right_command"], + "optional": ["any"] + } + }, + "to": [{ "key_code": "left_arrow" }], + "type": "basic" + }, + { + "from": { + "key_code": "j", + "modifiers": { + "mandatory": ["right_command"], + "optional": ["any"] + } + }, + "to": [{ "key_code": "down_arrow" }], + "type": "basic" + }, + { + "from": { + "key_code": "k", + "modifiers": { + "mandatory": ["right_command"], + "optional": ["any"] + } + }, + "to": [{ "key_code": "up_arrow" }], + "type": "basic" + }, + { + "from": { + "key_code": "l", + "modifiers": { + "mandatory": ["right_command"], + "optional": ["any"] + } + }, + "to": [{ "key_code": "right_arrow" }], + "type": "basic" + } + ] + } + ] + }, + "name": "Default profile", + "selected": true, + "simple_modifications": [ + { + "from": { "key_code": "caps_lock" }, + "to": [{ "key_code": "f18" }] + } + ], + "virtual_hid_keyboard": { "keyboard_type_v2": "iso" } + } + ] +} \ No newline at end of file