Configuration

Configuration is written in YAML and resides by default in ~/.amazing.yml. This behavior can be altered with the -c or --config switch, as in amazing --config /path/to/config.yml.

1. Values
2. Example
3. Widget configuration
4. Format configuration
5. Notes

h2. Values

include:
  - <path/to/program.rb>
widgets:
  <screen>: 
    <identifier>:
      type: <WidgetName>
      every: <seconds>
      format: <ruby code>
      <custom option>: <value>

h2. Example

include:
  - .amazing/widgets.rb
widgets:
  0:
    pb_bat:
      type: Battery
      every: 10
    tb_time:
      type: Clock
      every: 1
      time_format: %T
    tb_mail:
      type: Maildir
      format: '"#@count new message#{@count != 1 : "s" : ""}"'
      directories:
        - Mail/**/new
        - Mail/inbox/cur

h2. Widget configuration

Each widget type has its own options and “fields”. Fields are variables that can be used in the format option to customize what is displayed in the widget. These options and fields can be found out by issuing amazing with the -w or --list-widgets switch, which will output something like this:

Battery : Remaining battery power in percentage
            battery: <Battery number> || 1
            @percentage = <Power percentage> || 0

Raggle  : Unread posts in raggle
            require 'pstore' # Ruby standard library
            feed_list_path: <Path to feeds list> || ".raggle/feeds.yaml"
            feed_cache_path: <Path to feeds cache> || ".raggle/feed_cache.store"
            @count = <Ammount of unread posts> || 0

ALSA    : Various data for the ALSA mixer
            mixer: <ALSA mixer name> || "Master"
            @volume = <Volume in percentage> || 0

Memory  : Various memory related data
            @cached = <> || 0
            @usage = <Percentage of used memory> || 0
            @total = <Total kilobytes of memory> || 0
            @free = <Free kilobytes of memory> || 0
            @buffers = <> || 0

Maildir : Mail count in maildirs
            directories: <Globs of maildirs> || nil
            @count = <Ammount of mail in searched directories> || 0

Clock   : Displays date and time
            time_format: <Time format as described in DATE(1)> || "%R"
            @time = <Formatted time> || nil

Each section describes a widget type. require describes a dependency, a Ruby library which must be installed for the widget to function. Items followed by a colon describes an option, and items preceded by an at-sign describe a field. The || syntax describes the default value of the option/field.

Note: the output of --list-widgets will likely change as it is currently cryptic.

h2. Format configuration

The format option is actually a Ruby program ran within an instance of the widget type. What this means is you have the full power of Ruby, but don’t have to make it more complex than you want to. Here are some examples:

A simple string

format: '"#@field1 / #@field2"'

Without the single quotes, the double quotes are interpreted by the YAML parser as enforcing the string type.

Conditioning

format: if @free > 1024 then "#{@free / 1024} GB" else "#@free MB" end

format: @free > 1024 ? "#{@free / 1024} GB" : "#@free MB"

Multi line

format: |
  if @free > 1024
    "#{@free / 1024} GB"
  else
    "#@free MB"
  end

h2. Notes

Be wary that the configuration layout will likely change.

• Scripts will be included automatically from ~/.amazing/*.rb, rendering the include list less of a necessity
  • How this should be configured needs to be decided