uh-wm 0.0.9 → 0.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d964f7fa9ddc317e9e179e07a20cd462457a7a80
-  data.tar.gz: 93baa823c8b9fbc18fef96b37ad79416daa7059e
+  metadata.gz: 304d345d72ebfed7045a3ac0cd0bdb58fe8fbd31
+  data.tar.gz: cb5379acb77ac283dbb0f28b27e4e93fe9e13b5f
 SHA512:
-  metadata.gz: 613887c13875de0901994d0dad1ff57ff4ba45f175fb149e0e6e6ef85ec1c7d9fc6d4faceb00e199ef40ec8c571f80c77bff4ef02bc355389dba9e6dd0b19936
-  data.tar.gz: 9182b6a47768f16bfe5e0fae1db0e8d3dc1f6f75b3213ba267842025a3cabb7e39144f7f8173f8e805389e8cf01ec8b614a5c5eb15e29d0811b4d10bce240e02
+  metadata.gz: fdc8985073e35f6d54f1d627e0233ab0ebdad4cfe25ce0baf8d7b1847083f942fc91fbf9e36ee4bac812f489df4bc190660d947bcdcf8e6f5454380376363897
+  data.tar.gz: a69f26be2e7bfd9781222840f0bec1508d962f7fc192e2b5908718dd496f7a996827cee6f6abc92b2639e173766b7a10164772cd8d6f221ba2966cc79a52bc09

data/README.md

@@ -17,13 +17,13 @@ specific messages, so it's easy to write your own layout.
   Main features:
 
   * Xinerama support;
-  * multiple event handling strategy: blocking or multiplexing
-    with `select()`;
-  * configuration with a run control file (ruby DSL);
+  * different adapters for event handling: blocking, multiplexing
+    with `select()` or `kqueue()`;
+  * configuration with a run control file;
   * key bindings with user defined code as callback;
   * configurable modifier key;
   * support user-defined layout strategies;
-  * program execution;
+  * external program execution;
   * no re-parenting (therefore, no window decoration either);
   * no grabbing of the modifier key alone;
   * no mouse handling;
@@ -64,9 +64,9 @@ options:
 Configuration
 -------------
 
-  uhwm can be configured with a run control file, written in ruby. A
-simple example is provided below, more details will be available in
-the [`RunControl` class documentation][run_control_doc].
+  uhwm can be configured with a run control file written in ruby. A
+simple example is provided below, more details are available in the
+[`RunControl` class documentation][run_control_doc].
 
 ``` ruby
 DMENU     = 'dmenu_run -b'.freeze
@@ -77,8 +77,8 @@ BROWSERS  = %w[
 ].freeze
 
 
-modifier :mod1                # This key will be added to the modifier mask for
-                              # *all* key bindings.
+modifier :mod1                # This key is added to the modifier mask for *all*
+                              # key bindings.
 key(:p)     { execute DMENU } # Execute given command in a shell when mod1+shift
                               # is pressed.
 key(:Q)     { quit }          # Quit when mod1+shift+q is pressed (a capitalized
@@ -87,19 +87,19 @@ key(:enter) { execute VT }    # Common key names (`enter') are translated to
                               # their X equivalent (`return').
 
 rule BROWSERS do              # Move windows to the `www' view when their app
-  layout_view_set 'www'       # class matches either /\Aarora/, /\Achromium/… etc
+  layout_view_set 'www'       # class match either /\Aarora/, /\Achromium/… etc
 end
 
 launch do                         # Execute urxvt program twice, synchronously.
   execute! VT                     # `execute!' is a variant of `execute' which
-  execute! VT                     # will only return when a window is mapped.
+  execute! VT                     # return when a window is mapped.
   layout_client_column_set :succ  # Move last mapped window to next column.
 end
 ```
 
   Blocks given to `key`, `rule`, `launch` are executed in a special
 context providing access to methods named "actions", which are
-described in next section.
+described in the following section.
 
 [run_control_doc]: http://www.rubydoc.info/gems/uh-wm/Uh/WM/RunControl
 
@@ -108,10 +108,10 @@ Actions
 -------
 
   The actions DSL implements a few built-in messages, but also acts as
-a proxy to the layout. Any message prefixed with `layout_` will be
-forwarded to the layout, with the prefix stripped. That is, if
+a proxy to the layout. Any message prefixed with `layout_` is
+forwarded to the layout, with its prefix stripped. That is, if
 `layout_view_sel '2'` is evaluated, then the layout will receive the
-`view_sel` message with `"2"` as argument. Up to date information is
+`view_sel` message with `"2"` as argument. Accurate information is
 available in the [`ActionsHandler` class documentation][actions_doc]
 
 | Message       | Arguments | Description

data/lib/uh/wm/actions_handler.rb

@@ -1,15 +1,29 @@
 module Uh
   module WM
+    # Provides a context with helper methods for key bindings
+    # ({RunControl#key}), client rules ({RunControl#rule}) and the {Launcher}
+    # ({RunControl#launch}).
     class ActionsHandler
       include EnvLogging
 
       extend Forwardable
+      # @!method layout
+      #   Returns the layout
+      #   @return [Object] The layout
+      #   @see Env#layout
       def_delegator :@env, :layout
 
+      # @api private
+      # @param env [Env] An environment
+      # @param events [Dispatcher] A dispatcher
       def initialize env, events
         @env, @events = env, events
       end
 
+      # Evaluates action code given as normal argument or block parameter
+      # @api private
+      # @param code [Proc] Action code
+      # @param block [Proc] Action code
       def evaluate code = nil, &block
         if code
           instance_exec &code
@@ -18,11 +32,14 @@ module Uh
         end
       end
 
-      def quit
-        log 'Quit requested'
-        @events.emit :quit
-      end
-
+      # Executes given command. Forks twice, creates a new session and makes
+      # the new process the session leader and process group leader of a new
+      # process group. The new process has no controlling terminal.  Refer to
+      # `fork(2)` and `setsid(2)` for more detail.
+      #
+      # `command` argument is executed with `Kernel#exec`.
+      #
+      # @param command [String, Array] Command to execute
       def execute command
         log "Execute: #{command}"
         pid = fork do
@@ -38,16 +55,22 @@ module Uh
         Process.waitpid pid
       end
 
+      # Kills layout current client (focused) with {Client#kill}
       def kill_current
         return unless layout.current_client
         layout.current_client.kill
       end
 
+      # Logs a separator string, can help during debug
       def log_separator
         log '- ' * 24
       end
 
-      def method_missing(m, *args, &block)
+      # Forwards unhandled messages prefixed with `layout_` to the layout,
+      # without the prefix
+      # @example
+      #   layout_foo # delegates to `layout.foo'
+      def method_missing m, *args, &block
         if respond_to? m
           meth = layout_method m
           log "#{layout.class.name}##{meth} #{args.inspect}"
@@ -61,14 +84,22 @@ module Uh
         end
       end
 
-      def respond_to_missing?(m, *)
+      # Requests the window manager to terminate
+      def quit
+        log 'Quit requested'
+        @events.emit :quit
+      end
+
+      # Checks method existence in layout
+      # @api private
+      def respond_to_missing? m, _
         m.to_s =~ /\Alayout_/ || super
       end
 
 
       private
 
-      def layout_method(m)
+      def layout_method m
         m.to_s.gsub(/\Alayout_/, 'handle_').to_sym
       end
     end

data/lib/uh/wm/run_control.rb

@@ -1,6 +1,8 @@
 module Uh
   module WM
+    # Provides the context and behavior for run control file evaluation.
     class RunControl
+      # Key sym translations for key bindings.
       KEYSYM_TRANSLATIONS = {
         backspace:  :BackSpace,
         enter:      :Return,
@@ -9,6 +11,10 @@ module Uh
       }.freeze
 
       class << self
+        # Builds an instance and evaluates any run control file defined in
+        # the given {Env} instance
+        # @api private
+        # @param env [Env] An environment
         def evaluate env
           rc_path = File.expand_path(env.rc_path)
           rc = new env
@@ -16,24 +22,59 @@ module Uh
         end
       end
 
+      # @api private
+      # @param env [Env] An environment
       def initialize env
         @env = env
       end
 
+      # Evaluates run control code
+      # @api private
+      # @param code [String] The run control file content
+      # @param path [String] The run control file path
       def evaluate code, path
         instance_eval code, path
       rescue ::StandardError, ::ScriptError => e
         raise RunControlEvaluationError, e.message, e.backtrace
       end
 
-      def modifier mod
-        @env.modifier = mod
-      end
-
+      # Registers a key binding
+      # @example Output message on standard output when `modkey+f` is pressed
+      #   key(:f) { puts 'hello world!' }
+      # @example Add `shift` key sym to the modifier mask
+      #   key(:q, :shift) { quit }
+      # @example Convert capitalized key sym `Q` to `shift+q`
+      #   key(:Q) { quit }
+      # @example Convert `enter` to `return` X key sym
+      #   key(:enter) { execute 'xterm' }
+      # @param keysyms [Symbol] X key sym
+      # @param block Code to execute when the key binding is triggered, with
+      #   `self` as an {ActionsHandler} instance
       def key *keysyms, &block
         @env.keybinds[translate_keysym *keysyms] = block
       end
 
+      # Declares code to execute on window manager connection
+      # @example
+      #   launch { execute 'xterm' }
+      # @param block Code to execute when the window manager has connected,
+      #   with `self` as a {Launcher} instance
+      def launch &block
+        @env.launch = block
+      end
+
+      # Defines the layout with either a layout class or an instance with
+      # optional layout options. When given only a hash, configures options for
+      # the default layout and ignores the `options` parameter.
+      # @example
+      #   layout MyLayout
+      #   layout MyLayout, foo: :bar
+      #   layout MyLayout.new
+      #   layout MyLayout.new(foo: :bar)
+      #   layout foo: :bar
+      # @param arg [Class, Object, Hash] A layout class, a layout instance, or
+      #   options for the default layout
+      # @param options [Hash] Layout options
       def layout arg, **options
         case arg
         when Class
@@ -49,16 +90,38 @@ module Uh
         end
       end
 
-      def worker type, **options
-        @env.worker = [type, options]
+      # Defines the modifier key to use for key bindings
+      # @example
+      #   modifier :mod1 # Use `mod1' as modifier
+      # @param keysym [Symbol] X key sym
+      def modifier keysym
+        @env.modifier = keysym
       end
 
+      # Declares a client rule
+      # @example
+      #   rule %w[firefox chrome] do
+      #     log 'moving client to `www\' view!'
+      #     layout_view_set 'www'
+      #   end
+      # @param selectors [String, Array<String>] Substring matched against the
+      #   beginning of clients window application name
+      # @param block Code to execute when the client rule is matched
       def rule selectors = '', &block
         [*selectors].each { |selector| @env.rules[/\A#{selector}/i] = block }
       end
 
-      def launch &block
-        @env.launch = block
+      # Configures the worker
+      # @example Use the blocking worker
+      #   worker :block
+      # @example Use the kqueue worker with 1 second timeout
+      #   worker :kqueue, timeout: 1
+      # @example Use the multiplexing (`select()`) worker with 1 second timeout
+      #   worker :mux, timeout: 1
+      # @param type [Symbol] Worker type: `:block`, `:kqueue` or `:mux`
+      # @param options [Hash] Worker options
+      def worker type, **options
+        @env.worker = [type, options]
       end
 
 

data/lib/uh/wm/version.rb

@@ -1,5 +1,5 @@
 module Uh
   module WM
-    VERSION = '0.0.9'
+    VERSION = '0.0.10'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: uh-wm
 version: !ruby/object:Gem::Version
-  version: 0.0.9
+  version: 0.0.10
 platform: ruby
 authors:
 - Thibault Jouan
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-05-31 00:00:00.000000000 Z
+date: 2015-06-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb-kqueue