# Module `awful.rules`

### Info:

- Copyright: 2009 Julien Danjou
- Release: v3.5.4
- Author: Julien Danjou <julien@danjou.info>

## Functions

match (c, rule) | Check if a client matches a rule.
match_any (c, rule) | Check if a client matches any part of a rule.
matching_rules (c, rule) | Get list of matching rules for a client.
does_match (c, rule) | Check if a client matches a given set of rules.
apply (c) | Apply awful.rules.rules to a client.
execute (c, props, callbacks) | Apply properties and callbacks to a client.

## Tables

rules | This is the global rules table.

## Functions

match (c, rule)
  Check if a client matches a rule.

  ### Parameters:

  - c The client.
  - rule The rule to check.

  ### Returns:

  True if it matches, false otherwise.
match_any (c, rule)
  Check if a client matches any part of a rule.

  ### Parameters:

  - c The client.
  - rule The rule to check.

  ### Returns:

  True if at least one rule is matched, false otherwise.
matching_rules (c, rule)
  Get list of matching rules for a client.

  ### Parameters:

  - c The client.
  - rule The rules to check. List with "rule", "rule_any", "except" and "except_any" keys.

  ### Returns:

  The list of matched rules.
does_match (c, rule)
  Check if a client matches a given set of rules.

  ### Parameters:

  - c The client.
  - rule The rules to check. List with "rule", "rule_any", "except" and "except_any" keys.

  ### Returns:

  True if at least one rule is matched, false otherwise.
apply (c)
  Apply awful.rules.rules to a client.

  ### Parameters:

  - c The client.
execute (c, props, callbacks)
  Apply properties and callbacks to a client.

  ### Parameters:

  - c The client.
  - props Properties to apply.
  - callbacks Callbacks to apply.

## Tables

rules
  This is the global rules table.

  You should fill this table with your rule and properties to apply. For example, if you want to set xterm maximized at startup, you can add:
  `{ rule = { class = "xterm" }, properties = { maximized_vertical = true, maximized_horizontal = true } }`

  If you want to set mplayer floating at startup, you can add:
  `{ rule = { name = "MPlayer" }, properties = { floating = true } }`

  If you want to put Firefox on a specific tag at startup, you can add:
  `{ rule = { instance = "firefox" }, properties = { tag = mytagobject } }`

  If you want to put Emacs on a specific tag at startup, and immediately switch to that tag you can add:
  `{ rule = { class = "Emacs" }, properties = { tag = mytagobject, switchtotag = true } }`

  If you want to apply a custom callback to execute when a rule matched, for example to pause playing music from mpd when you start dosbox, you can add:
  `{ rule = { class = "dosbox" }, callback = function(c) awful.util.spawn('mpc pause') end }`

  Note that all "rule" entries need to match. If any of the entry does not match, the rule won't be applied.

  If a client matches multiple rules, their applied in the order they are put in this global rules table. If the value of a rule is a string, then the match function is used to determine if the client matches the rule.

  If the value of a property is a function, that function gets called and function's return value is used for the property.

  To match multiple clients to a rule one need to use slightly different syntax:
  `{ rule_any = { class = { "MPlayer", "Nitrogen" }, instance = { "xterm" } }, properties = { floating = true } }`

  To match multiple clients with an exception one can couple 'except' or 'except_any' with the rules:
  `{ rule = { class = "Firefox" }, except = { instance = "Navigator" }, properties = {floating = true}, },`
  `{ rule_any = { class = { "Pidgin", "Xchat" } }, except_any = { role = { "conversation" } }, properties = { tag = tags[1][1] } }
  `{ rule = {}, except_any = { class = { "Firefox", "Vim" } }, properties = { floating = true } }``

generated by LDoc 1.4.2