{"id":17383820,"url":"https://github.com/sunaku/wmiirc","last_synced_at":"2025-07-08T11:34:06.614Z","repository":{"id":479614,"uuid":"105139","full_name":"sunaku/wmiirc","owner":"sunaku","description":"Ruby configuration for WMII window manager","archived":false,"fork":false,"pushed_at":"2024-03-01T16:51:25.000Z","size":1306,"stargazers_count":84,"open_issues_count":4,"forks_count":25,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-15T10:09:12.013Z","etag":null,"topics":["ruby","window-manager","yaml-configuration"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sunaku.png","metadata":{"files":{"readme":"README.markdown","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2009-01-11T06:58:26.000Z","updated_at":"2025-03-22T10:30:30.000Z","dependencies_parsed_at":"2022-07-20T15:18:04.001Z","dependency_job_id":null,"html_url":"https://github.com/sunaku/wmiirc","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sunaku%2Fwmiirc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sunaku%2Fwmiirc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sunaku%2Fwmiirc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sunaku%2Fwmiirc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sunaku","download_url":"https://codeload.github.com/sunaku/wmiirc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249048738,"owners_count":21204306,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["ruby","window-manager","yaml-configuration"],"created_at":"2024-10-16T07:43:54.555Z","updated_at":"2025-04-15T10:09:31.479Z","avatar_url":"https://github.com/sunaku.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"sunaku's wmii configuration in Ruby and YAML\n==============================================================================\n\n![Floating](https://github.com/sunaku/wmiirc/raw/gh-pages/floating.png)\n![Tiling](https://github.com/sunaku/wmiirc/raw/gh-pages/tiling.png)\n\nThis is a [Ruby] and [YAML] based configuration of the [wmii] window manager.\nIt manipulates wmii through the [Rumai] library (which speaks directly to wmii\nvia the 9P2000 protocol and features [an interactive Ruby shell][RumaiShell]\nfor live experimentation) and offers a near \"Desktop Environment\" experience:\n\n  * Status bar applets with mouse, keyboard, and menu access.\n  * System, dialog, and menu (with history) integration.\n  * Client grouping and mass manipulation thereof.\n  * View and client access by menu and alphanumeric keys.\n  * Automated client arrangements with optional persistence.\n  * Detaching clients from current view and restoring them.\n  * Zooming clients to temporary views and restoring them.\n  * Closing all clients before exiting the window manager.\n  * Script and stdout/err logging with automatic rotation.\n  * Crash handling with error trace and recovery console.\n  * Session state propagation between wmiirc instances.\n  * And oh so much more... :-]\n\nAll of this can be configured to suit your needs, of course.  This wmii\nconfiguration was also described in the following articles in the past:\n\n  * \u003chttps://sunaku.github.io/wmii-3.1-ruby-config.html\u003e\n  * \u003chttp://wmii.suckless.org/alternative_wmiirc_scripts\u003e\n\nAPI documentation for Ruby code that powers this configuration is here:\n\n  * \u003chttps://sunaku.github.io/wmiirc/api/\u003e\n\n[Ruby]: http://ruby-lang.org\n[YAML]: http://yaml.org\n[wmii]: http://wmii.suckless.org\n[Rumai]: http://snk.tuxfamily.org/lib/rumai/\n[RumaiShell]: http://snk.tuxfamily.org/lib/rumai/#_usage\n[Kwalify]: http://www.kuwata-lab.com/kwalify/\n\n------------------------------------------------------------------------------\nRequirements\n------------------------------------------------------------------------------\n\n  * [wmii] 3.9 or newer.  I recommend that you use [my personal fork\n    of wmii-hg]( https://github.com/sunaku/wmii ) for best results.\n\n    Note that the `display/status/arrange` status bar applet requires a\n    [patched version of wmii-hg revision 2758 or greater](\n    https://github.com/sunaku/wmii/commit/33bf199436213788078581a8a94c2dcc98d6af16\n    ) in order to *persist* automated client arrangements.\n\n  * [Ruby] 2 or newer.\n\n  * If you want to use the `status/weather.yaml` status bar applet,\n    uncomment the following line in the `Gemfile` and restart wmii:\n\n        gem 'barometer'\n\n  * If you want to use the `status/music/mpd.yaml` status bar applet,\n    uncomment the following line in the `Gemfile` and restart wmii:\n\n        gem 'librmpd'\n\n------------------------------------------------------------------------------\nInstalling\n------------------------------------------------------------------------------\n\nBackup:\n\n    mv ~/.wmii ~/.wmii.backup\n    mv ~/.wmii-hg ~/.wmii-hg.backup\n\nInstall:\n\n    git clone https://github.com/sunaku/wmiirc.git ~/.wmii\n    ln -s ~/.wmii ~/.wmii-hg\n\nBranch:\n\n    cd ~/.wmii\n    make branch\n\n------------------------------------------------------------------------------\nConfiguring\n------------------------------------------------------------------------------\n\n  * Edit the `~/.wmii/config.yaml` file (see the \"Configuration File Format\"\n    section below) to suit your needs.  See [my personal configuration file](\n    https://github.com/sunaku/wmiirc/blob/personal/config.yaml ) for example.\n\n  * If wmii is already running, run `~/.wmii/wmiirc` or invoke the \"reload\"\n    action from within an existing wmiirc instance to apply your changes.\n\n### Configuration File Format\n\nAll Ruby code snippets in the configuration file have access to a `CONFIG`\nconstant which contains the data from the fully expanded configuration.  They\nalso have access to a `SESSION` constant which is a hash that is automatically\npersisted across multiple instances of the wmiirc.\n\n  * **custom:** Any value of your own choosing to use in your configuration.\n    For example, you can define a list of applications to always launch\n    (unless they're already running) whenever your configuration starts:\n\n        custom:\n          startup:\n            - wpa_gui -t   # network manager\n            - claws-mail   # e-mail client\n            - redshift-gtk # color temperature\n\n        script:\n          after: |\n            Array(CONFIG['custom']['startup']). # \u003c== NOTICE THE KEYS HERE !!!\n            each {|app| launch! app unless system 'pgrep', '-f', app }\n\n  * **import:** A list of files to inject into this one before evaluating it.\n    Imported files may themselves import other files, recursively.  The\n    contents of each successive imported file are merged with the previous\n    one while *overwriting* the imported content in the following manner:\n\n      * If the object being overwritten is a hash, then:\n\n        * For keys that are present in the old hash but absent in the new\n          hash, key-value pairs from the old hash are retained.\n\n        * For keys that are present in the new hash but absent in the old\n          hash, key-value pairs from the new hash are added.\n\n        * For keys in common between the old and new hashes, key-value pairs\n          from the old hash are replaced by key-value pairs from the new hash.\n\n      * If the object being overwritten is an array, then items from the new\n        array are appended to end of the old array.\n\n      * If the object being overwritten is a scalar value such as a string,\n        integer, or boolean, then the old value is replaced by the new value.\n\n  * **ignore:** A list of files to remove from the **import** statement above.\n\n  * **require:** A list of Ruby libraries to load before evaluating this\n    configuration file.  If a library is a RubyGem, you can constrain its\n    version number like this:\n\n          require:\n            - some_gem\n            - another_gem: '\u003e= 1.0.9'\n            - yet_another_gem: ['\u003e= 1.0.9', '\u003c 2']\n            - some_ruby_library\n\n  * **script:** Arbitrary logic to evaluate while processing this file.\n\n    * **before:** Array of Ruby code snippets to evaluate before processing\n      the overall configuration.\n\n    * **after:** Array of Ruby code snippets to evaluate after processing the\n      overall configuration.\n\n  * **status:** Status bar applet definitions.\n\n      All Ruby code snippets that are evaluated inside a `Wmiirc::Status`\n      object have access to a `refresh` method that triggers redrawing of\n      the label of that status bar applet.  They also have access to a `@id`\n      variable which is a sequence number counting the number of instances of\n      this particular status bar applet that have been created thus far.\n\n      * **_name of the status bar applet that you want to define_:**\n\n        * **params:** Hash of parameters to pass to the constructor.  These\n          are later available as instance variables in the Ruby code\n          snippets that are evaluated inside this status bar applet.\n\n        * **refresh:** Number of seconds to wait before updating the label.\n          To disable automatic refreshing, set this parameter to 0 (zero).\n\n        * **script:** Ruby code to evaluate in the `Wmiirc::Status` object.\n\n        * **label:** Ruby code whose result is displayed as the content.\n          This code is placed in a `label()` method in the `Wmiirc::Status`\n          object.\n\n        * **control:**\n\n          * **event:** Hash of event name to Ruby code to evaluate in the\n            `Wmiirc::Status` object.\n\n          * **action:** Hash of action name to Ruby code to evaluate in\n            the `Wmiirc::Status` object.\n\n          * **mouse_action:** Hash of mouse event name to action name.\n\n  * **display:** Appearance settings.\n\n    * **bar:** Where to display the horizontal status bar?\n\n    * **font:** Font to use in all text drawn by wmii.\n\n    * **border:** Thickness of client border (measured in pixels).\n\n    * **color:** Color schemes for everything drawn by wmii.  These are\n      expressed in `#foreground #background #border` format, where\n      *foreground*, *background*, and *border* are 6-digit HEX values.\n\n      * **desktop:** Color of the desktop background (single color only).\n\n      * **focus:** Colors of things that have focus.\n\n      * **normal:** Colors of things that do not have focus.\n\n    * **columns:** Settings for columns drawn by wmii.\n\n        * **mode:** The wmii \"colmode\" setting.\n\n        * **rule:** The wmii \"colrules\" setting.\n\n    * **client:** Settings for clients handled by wmii.  See the documentation\n      for the underlying wmii \"rules\" setting for more information.\n\n        * **_rule to apply_:** Array of strings that represent regular\n          expressions to match against a string containing a newly created\n          client's WM_CLASS and WM_NAME attributes separated by a colon (:).\n\n    * **refresh:** Refresh rate for status bar applets (measured in seconds).\n\n    * **status:** Status bar applet instances.\n\n        All Ruby code snippets that are evaluated inside a `Wmiirc::Status`\n        object have access to a `refresh` method that triggers redrawing of\n        the label of that status bar applet.  They also have access to a `@id`\n        variable which is a sequence number counting the number of instances\n        of this particular status bar applet that have been created thus far.\n\n        * **- _name of the status bar applet that you want to instantiate_:**\n\n          * **params:** Hash of parameters to pass to the constructor.  These\n            are later available as instance variables in the Ruby code\n            snippets that are evaluated inside this status bar applet.\n\n          * **refresh:** Number of seconds to wait before updating the label.\n            To disable automatic refreshing, set this parameter to 0 (zero).\n\n          * **script:** Ruby code to evaluate in the `Wmiirc::Status` object.\n\n          * **label:** Ruby code whose result is displayed as the content.\n            This code is placed in a `label()` method in the `Wmiirc::Status`\n            object.\n\n            * **control:**\n\n              * **event:** Hash of event name to Ruby code to evaluate in the\n                `Wmiirc::Status` object.\n\n              * **action:** Hash of action name to Ruby code to evaluate in\n                the `Wmiirc::Status` object.\n\n              * **mouse_action:** Hash of mouse event name to action name.\n\n  * **control:** Interaction settings.\n\n    * **action:** Hash of action name to Ruby code to evaluate.\n\n    * **event:** Hash of event name to Ruby code to evaluate.\n\n        The Ruby code has access to an \"argv\" variable which is a list of\n        arguments that were passed to the event.\n\n        Keep in mind that these event handlers *block* the wmiirc event loop.\n        In other words, no new events can be handled until the current one\n        finishes. So try to keep your event handlers short and quick.\n\n        If your event handler needs to perform a long-running operation, then be\n        sure to wrap that operation inside a Ruby thread.\n\n    * **mouse:** Mapping from X mouse codes to event names.\n\n      * **grab:** The wmii \"grabmod\" setting.\n\n    * **keyboard:** Hash of shortcut prefix name to shortcut key sequence.\n\n    * **keyboard_action:** Hash of shortcut key sequence to action name.\n\n        A key sequence may contain `${...}` expressions which are replaced\n        with the value corresponding to `...` in the \"control:keyboard\"\n        section of this configuration.\n\n        For example, if the \"control:keyboard\" section was defined as follows,\n        then the `${d},${c}` key sequence would be expanded into `Mod4-y,y`.\n\n            control:\n              keyboard:\n                a: 4\n                b: Mod${a}\n                c: y\n                d: ${b}-${c}\n\n------------------------------------------------------------------------------\nRunning\n------------------------------------------------------------------------------\n\n  * Ensure that your `~/.xinitrc` allows you to restart wmii without having to\n    lose your running applications if wmii crashes or is accidentally killed:\n\n        xterm -e tail -f ~/.wmii/wmiirc.log \u0026\n        while true; do wmii\n          xmessage 'INSERT COIN TO CONTINUE' \\\n          -buttons 'Insert Coin:0,Game Over' \\\n          -default 'Insert Coin' -timeout 30 \\\n          -center || break\n        done\n\n    For a working example, see [my personal configuration file](\n    https://github.com/sunaku/home/blob/master/.xinitrc ).\n\n  * Run `startx` and wmii will automatically find and load this configuration.\n\n------------------------------------------------------------------------------\nUpgrading\n------------------------------------------------------------------------------\n\n    cd ~/.wmii\n    make rebase\n\nIf this fails because Git reports that you have unstaged changes, you can\nstash your changes away temporarily and restore them after the upgrade:\n\n    git stash\n    make rebase # now it works\n    git stash apply\n\n------------------------------------------------------------------------------\nHacking\n------------------------------------------------------------------------------\n\nTo use the development version of [Rumai] directly from its source code\nrepository (instead of the currently published gem version), run this:\n\n    cd ~/.wmii\n    make rumai\n\n------------------------------------------------------------------------------\nContributing\n------------------------------------------------------------------------------\n\nFork this project on GitHub and send pull requests.\n\n------------------------------------------------------------------------------\nBugs, Features, Issues, Questions\n------------------------------------------------------------------------------\n\nFile a report on [the issue tracker](http://github.com/sunaku/wmiirc/issues/).\n\n------------------------------------------------------------------------------\nLicense\n------------------------------------------------------------------------------\n\n[Spare A Life]: https://sunaku.github.io/vegan-for-life.html\n\u003e Like my work? :+1:  Please [spare a life] today as thanks!\n:cow::pig::chicken::fish::speak_no_evil::v::revolving_hearts:\n\nCopyright 2006 Suraj N. Kurapati \u003chttps://github.com/sunaku\u003e\n\nReleased under the ISC license.  See the LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsunaku%2Fwmiirc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsunaku%2Fwmiirc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsunaku%2Fwmiirc/lists"}