{"id":28606211,"url":"https://github.com/halffd/havel","last_synced_at":"2026-05-02T11:35:37.762Z","repository":{"id":261541408,"uuid":"879196604","full_name":"Halffd/Havel","owner":"Halffd","description":"Hotkey Manager and Window Control System","archived":false,"fork":false,"pushed_at":"2026-04-12T01:24:18.000Z","size":23148,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-12T03:25:35.950Z","etag":null,"topics":["automation","cpp","gtk","hotkey","linux","lua","scripting","window-management","x11"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Halffd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-10-27T09:09:52.000Z","updated_at":"2026-04-12T01:24:22.000Z","dependencies_parsed_at":"2024-12-05T07:18:29.809Z","dependency_job_id":"e9ed8811-aee8-4df7-8a09-4430300cf4b5","html_url":"https://github.com/Halffd/Havel","commit_stats":null,"previous_names":["halffd/hvc","halffd/havel"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/Halffd/Havel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Halffd%2FHavel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Halffd%2FHavel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Halffd%2FHavel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Halffd%2FHavel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Halffd","download_url":"https://codeload.github.com/Halffd/Havel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Halffd%2FHavel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31803238,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T11:13:53.975Z","status":"ssl_error","status_checked_at":"2026-04-14T11:13:53.299Z","response_time":153,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","cpp","gtk","hotkey","linux","lua","scripting","window-management","x11"],"created_at":"2025-06-11T19:39:44.582Z","updated_at":"2026-04-14T15:32:10.070Z","avatar_url":"https://github.com/Halffd.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n**Havel** is a powerful utility for managing windows and hotkeys across multiple platforms, with a focus on Linux X11 environments. It allows for complex window management, hotkey configurations, and automated tasks via its own Havel scripting language.\n\n## 📋 Table of Contents\n- [Features](#features)\n- [Installation](#installation)\n- [Syntax Reference](#syntax-reference)\n- [Keywords](#keywords)\n- [Conditional Hotkeys](#conditional-hotkeys)\n- [Examples](#examples)\n- [Building](#building)\n- [Troubleshooting](#troubleshooting)\n\n## Features\n\n- Global hotkey registration and management\n- Dynamic conditional hotkeys with runtime evaluation\n- Window tracking and manipulation\n- Havel scripting language for complex automation (replacing Lua)\n- Configurable via text files\n- Cross-platform support\n\n## Installation\n\n### Prerequisites\n- C++17 compatible compiler (GCC 9+ or Clang 10+)\n- CMake 3.10+\n- X11 development libraries (on Linux)\n- Qt6 development libraries\n\n## Syntax Reference\n\n### Basic Hotkey Mapping\n```\nhotkey =\u003e action\n```\n\n### Pipeline Transformations\n```\ndata | transform1 | transform2\n```\n\n### Blocks\n```\nhotkey =\u003e {\n    // multiple statements\n}\n```\n\n### Variables\n```\nlet variable_name = value\n```\n\n### Conditional Logic\n```\nif condition { ... } else { ... }\n```\n\n## Keywords\n\n| Keyword | Purpose | Example |\n|---------|---------|---------|\n| `let` | Variable declaration | `let x = 5` |\n| `if/else` | Conditional execution | `if x \u003e 0 { ... } else { ... }` |\n| `when` | Conditional block | `when condition { ... }` |\n| `fn` | Function definition | `fn name(args) =\u003e ...` |\n| `return` | Function return | `return value` |\n| `import` | Module import | `import module from \"path\"` |\n| `config` | Configuration block | `config { ... }` |\n| `devices` | Device configuration | `devices { ... }` |\n| `modes` | Mode configuration | `modes { ... }` |\n\n## Conditional Hotkeys\n\n### Postfix Conditional Syntax\n```\nhotkey =\u003e action if condition\n```\n\n### Prefix Conditional Syntax\n```\nhotkey if condition =\u003e action\n```\n\n### When Blocks\n```\nwhen condition {\n    hotkey1 =\u003e action1\n    hotkey2 =\u003e action2\n}\n```\n\n### Nested Conditions\n```\nwhen outer_condition {\n    hotkey if inner_condition =\u003e action\n}\n```\nExample:\n```hv\nF1 when mode gaming =\u003e { print(\"Gaming mode active\") }\n!C if remapCapslock == false =\u003e map(\"capslock\", \"esc\")\n```\n\n### When Blocks\nGroup multiple hotkeys under a shared condition:\n\n```hv\nwhen mode gaming {\n    ^!A =\u003e click()\n    ^!B =\u003e click(\"right\")\n    F1 if health \u003c 50 =\u003e send(\"e\")\n}\n```\n\nAll conditions are evaluated dynamically at runtime, allowing variables to change and trigger hotkeys accordingly.\n\n## New Features (Latest)\n\n### Traits\nInterface-based polymorphism without inheritance:\n```havel\ntrait Drawable { fn draw() }\nimpl Drawable for Circle { fn draw() { ... } }\nlet c = Circle(10)\nc.draw()  // Calls impl method\n```\n\n### const\nImmutable variable bindings:\n```havel\nconst x = 10\nx = 20  // Error!\n```\n\n### Enhanced repeat\nNow accepts variables and expressions:\n```havel\nlet n = 3\nrepeat n { print(n) }\nrepeat 2 + 3 { print(\"expression\") }\n```\n\n### Shell Commands\n```havel\n$ firefox              // Fire-and-forget\nlet out = `echo hello` // Capture output\nprint(out.stdout)\n```\n\n### Screenshot with Image Data\n```havel\nlet r = screenshot.full()\nprint(r.path)   // File path\nprint(r.data)   // Base64 image data\nprint(r.width)  // Dimensions\n```\n\n### Struct Methods\n```havel\nstruct Point {\n  x, y\n  fn init(x, y) { this.x = x; this.y = y }\n  fn move(dx, dy) { this.x += dx; this.y += dy }\n}\nlet p = Point(10, 20)  // Constructor sugar\np.move(5, 5)\n```\n\n### Type Conversions\n```havel\nint(3.9)      // 3\nstr(123)      // \"123\"\nlist(1,2,3)   // [1, 2, 3]\nset_(1,2,2)   // [1, 2] (unique)\n```\n\n### Fuzzy Float Comparison\n```havel\napprox(0.1 + 0.2, 0.3)  // true\n```\n\n### Config Sections (Hyprland-Style)\n```havel\nlet step = 2\nbrightness {\n  step = num(step) / 10\n  current = 0.5\n}\nmonitor \"HDMI-0\" {\n  brightness = 0.8\n}\nprint(config.brightness.step)  // 0.2\n```\n\n### Debounced Config Saves\n```havel\n// Automatic 500ms debounce prevents write storms\nconfig.set(\"Key\", \"value\", true)  // Single save after batch\nconfig.forceSave()                 // Immediate save\n```\n\n## Examples\n\n### Basic Hotkey\n```\nF1 =\u003e send(\"Hello World!\")\n```\n\n### With Conditional Logic\n```\n^V when title \"Discord\" =\u003e {\n    let clip = clipboard.get\n    if clip | matches(\"^\\d+\") || has(\"secret\") {\n        let text = \"\"\n        let length = len(clip)\n        for i in 1..length {\n            text += \"*\"\n        }\n        send(\"$clip\")\n    } else {\n        send(clip)\n    }\n}\n```\n\n### Conditional Hotkey\n```\n^!A if window.active.title.contains(\"Chrome\") =\u003e send(\"^F5\")\n```\n\n### When Block\n```\nwhen mode coding {\n    ^!S =\u003e send(\"^s\")\n    ^!F =\u003e send(\"^f\")\n    ^!G =\u003e send(\"^g\")\n}\n```\n\n### With Built-in Help\nThe language includes a built-in `help()` function for interactive learning:\n- `help()` - Show main help page\n- `help(\"syntax\")` - Show syntax reference\n- `help(\"keywords\")` - Show all keywords\n- `help(\"hotkeys\")` - Show hotkey features\n- `help(\"modules\")` - Show available modules\n\n## Building the Project\n```bash\n# Build release\n./build.sh 1 build\n\n# Run havel script file\n./build-release/havel script.hv\n\n# Run REPL\n./build-release/havwl\n```\n\nAlternatively, you can use the Makefile:\n```bash\nmake\n```\n\n## Troubleshooting\n\nIf you encounter build issues, please refer to the [BUILD_ISSUES.md](BUILD_ISSUES.md) file for common problems and solutions.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Directory Structure\n\n- `/src` - Source code\n- `/include` - Header files\n- `/config` - Configuration files\n- `/log` - Log files\n- `/build` - Build directory\n- `/scripts` - Scripts examples\n\n## Embedding Havel\n\nHavel can be easily embedded in C++ applications (games, window managers, etc.):\n\n```cpp\n#include \u003cHavel.hpp\u003e\n\nint main() {\n    havel::VM vm;\n    \n    // Load and run code\n    vm.load(R\"(\n        fn add(a, b) { return a + b }\n        print(add(5, 3))\n    )\");\n    \n    return 0;\n}\n```\n\nSee [embed/README.md](embed/README.md) for full documentation.\n\n### Examples\n\n- [Basic embedding](examples/example_embed.cpp)\n- [Game integration](examples/example_game.cpp)\n- [Window manager](examples/example_wm.cpp)\n\n### C API\n\nA C API is also available for embedding in other languages:\n\n```c\n#include \u003cHavel-cAPI.h\u003e\n\nHavelVM* vm = havel_vm_create();\nhavel_vm_load(vm, \"print(\\\"Hello from C!\\\")\", \"script\");\nhavel_vm_destroy(vm);\n```\n\nSee [include/Havel-cAPI.h](include/Havel-cAPI.h) for the full C API.\n\n### Wayland support\nFuture plan is embedding it into a compositor\nHavel-wm currently in developme\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhalffd%2Fhavel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhalffd%2Fhavel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhalffd%2Fhavel/lists"}