cari3s

About Cari3s

This is an i3 status bar generator library/program.

How To

First make sure Cari3s is available to ASDF by either cloning and registering it, or downloading it via Quicklisp. Then build a standalone binary of Cari3s like this:

sbcl --dynamic-space-size 128MB --eval "(asdf:make :cari3s)"

This should produce a binary called cari3s in the source directory. Copy or symlink it into your PATH.

Next, create a configuration file in ~/.config/i3/cari3s.conf with something like the following:

(cpu-usage)
(mem-usage)
(io-usage)
(network-ip)
(clock)

Then change your ~/.config/i3/config's status bar section and set the status_command to cari3s:

bar {
  status_command cari3s
  ...
}

Once you reload i3, it should display a status bar similar to the following:

In the above example we defined five generators. The following generators are available out of the box:

• battery
• clock
• cpu-usage
• disk-usage
• io-usage
• mem-usage
• network-ip

The look of each of them can be customised through the :text format string, and the :markup pango options, as well as a variety of extra options for blocks.

Defining new Generators

Defining a raw generator is just a matter of subclassing generator and providing a method for generate that, when invoked, returns a list of block instances that should be displayed on the status bar.

There's some helper classes available like the single-generator and the value-generator, as most generators will only produce a single block and produce their text based on some recomputed value every time.

For the value-generator all you need to implement is a method on compute-value and provide a sensible default :text initarg.

None of the existing generators are terribly complicated, so if you're still unsure what to do, have a look at their sources.

System Information

Definition Index

• CARI3S

  • ORG.SHIRAKUMO.CARI3S

  Source

  No documentation provided.

  • EXTERNAL CLASS

    BATTERY

    Source

    A generator for battery status information.
    
    You may supply the name of the battery of interest using the
    :BATTERY initarg. It defaults to the first battery device.
    
    This value-generator supplies the following five values:
      0. charge-percentage
      1. charging-p
      2. hours-remaining
      3. minutes-remaining
      4. seconds-remaining
    
    See VALUE-GENERATOR

  • EXTERNAL CLASS

    BLOCK

    Source

    Class representing a block in the i3 status bar.
    
    A block is a textual container with some styling options.
    See your i3 documentation for more information on blocks and their
    behaviour.
    
    Instances of this class can be serialised using Jonathan.
    
    See TEXT
    See SHORT-TEXT
    See FOREGROUND
    See BACKGROUND
    See BORDER
    See MIN-WIDTH
    See ALIGN
    See NAME
    See INSTANCE
    See URGENT-P
    See SEPARATOR
    See TEXT-FORMAT

  • EXTERNAL CLASS

    CLICK

    Source

    Class representing a click event being fired on a block.
    
    This event comes from i3 itself if the connection was opened with
    a header that has SEND-CLICK-EVENTS-P set to T.
    
    See NAME
    See INSTANCE
    See BUTTON
    See LOCATION
    See RELATIVE-LOCATION
    See BLOCK-SIZE

  • EXTERNAL CLASS

    CLOCK

    Source

    A generator for a current local time clock.
    
    This value-generator supplies the following nine values:
      0. year
      1. month
      2. day-of-month
      3. day-of-week
      4. hour
      5. minute
      6. second
      7. short-day-name
      8. short-month-name
    
    See VALUE-GENERATOR

  • EXTERNAL CLASS

    CPU-USAGE

    Source

    A generator for the current CPU usage.
    
    This value-generator supplies the following value:
      0. usage-percentage
    
    See VALUE-GENERATOR

  • EXTERNAL CLASS

    DISK-USAGE

    Source

    A generator for the current partition capacity usage.
    
    You may specify the path to the partition of interest using
    the :DEVICE initarg.
    
    This value-generator supplies the following value:
      0. usage-percentage
    
    See VALUE-GENERATOR

  • EXTERNAL CLASS

    EVENT

    Source

    Superclass for all events that might trigger a GENERATE.
    
    See TICK
    See CLICK
    See GENERATE

  • EXTERNAL CLASS

    GENERATOR

    Source

    This is the superclass for all block generators.
    
    A generator is responsible for creating one or more blocks
    that are emitted into the status bar.
    
    A concrete class of a generator must supply a primary method
    on GENERATE.
    
    See GENERATE

  • EXTERNAL CLASS

    HEADER

    Source

    Class representing the i3bar protocol header.
    
    Instances of this class can be serialised using Jonathan.
    
    See VERSION
    See STOP-SIGNAL
    See CONTINUE-SIGNAL
    See SEND-CLICK-EVENTS-P

  • EXTERNAL CLASS

    IO-USAGE

    Source

    A generator for the current disk i/o usage.
    
    You may specify whether you're interested in :read, :write, or
    :read-write using the :DIRECTION initarg.
    
    This value-generator supplies the following value:
      0. megabytes-per-second
    
    See VALUE-GENERATOR

  • EXTERNAL CLASS

    MEM-USAGE

    Source

    A generator for the current memory usage.
    
    You may specify whether you're interested in swap and cache
    by using the :SWAP and :CACHE initargs respectively.
    
    This value-generator supplies the following three values:
      0. usage-percentage
      1. total-megabytes
      2. free-megabytes
    
    See VALUE-GENERATOR

  • EXTERNAL CLASS

    NETWORK-IP

    Source

    A generator for the current network IP address.
    
    You may specify which device you're interested in with the
    :DEVICE initarg. It defaults to whichever device is listed
    first that does not bind to localhost.
    
    This value-generator supplies the following two values:
      0. ip-address
      1. device-name
    
    See VALUE-GENERATOR

  • EXTERNAL CLASS

    PANGO-BLOCK

    Source

    Represents a block whose text should be marked up with pango.
    
    Note that neither TEXT nor SHORT-TEXT should contain raw pango
    markup tags themselves, but rather you should use the MARKUP and
    SHORT-MARKUP slots to set the markup regions to be used.
    
    TEXT and SHORT-TEXT will automatically render the textual contents
    with the appropriate markup regions.
    
    Each entry in the MARKUP and SHORT-MARKUP lists should have the
    following structure:
    
      (START END . MARKUP/MARKUP-OPTIONS)
    
    Please see the pango-markup library for more information:
    
      https://shinmera.github.io/pango-markup
    
    See MARKUP
    See SHORT-MARKUP
    See PANGO-MARKUP:MARKUP-REGIONS

  • EXTERNAL CLASS

    SINGLE-GENERATOR

    Source

    Superclass for all block generators that only generate a single block.
    
    As a convenience, this generator also directly inherits from
    PANGO-BLOCK in order to let the user and subclasses customise
    the block's look and feel conveniently.
    
    The primary method of a single-generator's GENERATE does not
    need to return anything useful, as the generator itself is
    always automatically returned from GENERATE in a list.
    
    If no :name is provided on a single-generator instance, the name is
    automatically set to the class-name of the instance's class.
    
    See PANGO-BLOCK
    See GENERATOR
    See GENERATE

  • EXTERNAL CLASS

    STATUS-BAR

    Source

    Class to represent an i3 status bar.
    
    An instance of this class is capable of handling the i3 protocol
    and invoking a number of block generators at the appropriate times.
    
    See INTERVAL
    See NEXT-TIME
    See GENERATORS
    See OUTPUT
    See INPUT
    See CLICK-PAUSE
    See PRODUCE-OUTPUT
    See PROCESS
    See RUN-BAR

  • EXTERNAL CLASS

    TICK

    Source

    Basic class for period update events.

  • EXTERNAL CLASS

    VALUE-GENERATOR

    Source

    Superclass for all block generators that generate their text content based on some computed value.
    
    The TEXT and SHORT-TEXT of a value-generator should be format
    strings that may consume however many values the respective
    generator promises to supply.
    
    Note that the pango markup for both text and short-text is
    applied AFTER the format string has been formatted in order to
    avoid encoding issues with entities in format directives.
    
    A concrete class of a value-generator must supply a primary
    method on COMPUTE-VALUE.
    
    See COMPUTE-VALUE
    See SINGLE-GENERATOR

  • EXTERNAL FUNCTION

    LOAD-FROM-FILE

    • FILE

    Source

    Loads a status bar definition from the given file.
    
    The file should have the following format:
    
      DEFINITION ::= (INITARG|GENERATOR)*
      INITARG    ::= keyword value
      GENERATOR  ::= (NAME INITARG*)
      NAME       --- A symbol naming the class of the generator.
    
    So for instance a simple file for a status bar with a two-second
    interval, a clock generator, and a cpu-usage generator would look as
    follows:
    
      :interval 2
      (clock :text "~4@*~2d:~2,'0d:~2,'0d")
      (cpu-usage)
    
    See GENERATOR
    See STATUS-BAR

  • EXTERNAL FUNCTION

    RUN-BAR

    • BAR
    • &KEY
    • (PAUSE 1/30)
    • (CLICK-EVENTS-P T)

    Source

    Starts the i3bar protocol and continuously processes the status bar.
    
    If click-events-p is T, i3 will send click events to the status bar.
    Pause is the minimal number of seconds between calls to PROCESS.
    
    See PROCESS
    See STATUS-BAR

  • EXTERNAL FUNCTION

    RUN-BAR-FROM-FILE

    • &OPTIONAL
    • (FILE ~/.config/i3/cari3s.conf)

    Source

    Runs a status bar initialised from a file.
    
    See LOAD-FROM-FILE
    See RUN-BAR

  • EXTERNAL FUNCTION

    TOPLEVEL

    Source

    Lisp binary toplevel entry function.
    
    This simply calls RUN-BAR-FROM-FILE, passing along the command line
    options to the binary.

  • EXTERNAL GENERIC-FUNCTION

    ALIGN

    • OBJECT

    Accessor to the text alignment property of the block.
    
    Can be one of: :center :right :left
    Defaults to :left
    
    Note that alignment is only in effect if the min-width has not been
    reached.
    
    See BLOCK

  • EXTERNAL GENERIC-FUNCTION

    (SETF ALIGN)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    BACKGROUND

    • OBJECT

    Accessor to the background colour of the block.
    
    A colour can either be an encoded RGB integer, or a list of R, G, B,
    and optional A elements with each element being an integer between
    0 and 255.
    
    See BLOCK

  • EXTERNAL GENERIC-FUNCTION

    (SETF BACKGROUND)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    BLOCK-SIZE

    • OBJECT

    Accessor to the block's screen dimensions.
    
    The dimensions is a cons of WIDTH and HEIGHT sizes in pixels.
    
    See CLICK

  • EXTERNAL GENERIC-FUNCTION

    (SETF BLOCK-SIZE)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    BORDER

    • OBJECT

    Accessor to the border colour of the block.
    
    A colour can either be an encoded RGB integer, or a list of R, G, B,
    and optional A elements with each element being an integer between
    0 and 255.
    
    See BLOCK

  • EXTERNAL GENERIC-FUNCTION

    (SETF BORDER)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    BUTTON

    • OBJECT

    Accessor to the X11 button ID that was used to perform the click.
    
    By default this should be:
      1 -- left
      2 -- middle
      3 -- right
    
    See CLICK

  • EXTERNAL GENERIC-FUNCTION

    (SETF BUTTON)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    CLICK-PAUSE

    • OBJECT

    Accessor to the number of seconds that the next tick event is delayed to when a click event has come in.
    
    See PROCESS
    See NEXT-TIME
    See STATUS-BAR

  • EXTERNAL GENERIC-FUNCTION

    (SETF CLICK-PAUSE)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    COMPUTE-VALUE

    • VALUE-GENERATOR

    Source

    Computes the values used for the format string in a value-generator's text.
    
    This function is called whenever GENERATE is called on the
    value-generator.
    
    See VALUE-GENERATOR

  • EXTERNAL GENERIC-FUNCTION

    CONTINUE-SIGNAL

    • OBJECT

    The unix signal used to continue bar updates.
    
    Defaults to 18 (SIGCONT)
    
    See HEADER

  • EXTERNAL GENERIC-FUNCTION

    (SETF CONTINUE-SIGNAL)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    FOREGROUND

    • OBJECT

    Accessor to the foreground text colour of the block.
    
    A colour can either be an encoded RGB integer, or a list of R, G, B,
    and optional A elements with each element being an integer between
    0 and 255.
    
    See BLOCK

  • EXTERNAL GENERIC-FUNCTION

    (SETF FOREGROUND)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    GENERATE

    • GENERATOR
    • EVENT

    Source

    Generates a list of blocks to use in the status bar.
    
    The event should be an instance of an EVENT subclass, which
    allows the generator to react to user input such as clicks.
    
    See BLOCK
    See GENERATOR

  • EXTERNAL GENERIC-FUNCTION

    GENERATORS

    • OBJECT

    Accessor to the list of generators that the status-bar invokes to generate its output.
    
    See GENERATOR
    See STATUS-BAR

  • EXTERNAL GENERIC-FUNCTION

    (SETF GENERATORS)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    INPUT

    • OBJECT

    Accessor to the input stream from which the status-bar reads click events.
    
    This defaults to *STANDARD-INPUT*
    
    See PROCESS
    See STATUS-BAR

  • EXTERNAL GENERIC-FUNCTION

    (SETF INPUT)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    INSTANCE

    • OBJECT

    Accessor to the instance name of the block.
    
    See NAME
    See BLOCK
    See CLICK

  • EXTERNAL GENERIC-FUNCTION

    (SETF INSTANCE)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    INTERVAL

    • OBJECT

    Accessor to the interval in seconds in which tick events are fired.
    
    The default interval is one second.
    
    Unless click events are fired and click-pause is set, the status-
    bar's generators are fired with a tick event according to this
    interval.
    
    See NEXT-TIME
    See STATUS-BAR

  • EXTERNAL GENERIC-FUNCTION

    (SETF INTERVAL)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    LOCATION

    • OBJECT

    Accessor to the screen position of the click.
    
    The location is a cons of X and Y coordinates, relative to the top
    left corner of the X11 root window in pixels.
    
    See CLICK

  • EXTERNAL GENERIC-FUNCTION

    (SETF LOCATION)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    MARKUP

    • OBJECT

    Accessor to the list of markup regions for the pango block's text.
    
    See PANGO-BLOCK

  • EXTERNAL GENERIC-FUNCTION

    (SETF MARKUP)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    MIN-WIDTH

    • OBJECT

    Accessor to the minimum pixel width of the block.
    
    From i3docs:
    The minimum width (in pixels) of the block. If the content of the
    text key take less space than the specified min-width, the block
    will be padded to the left and/or the right side, according to the
    align key. This is useful when you want to prevent the whole
    status line to shift when value take more or less space between each
    iteration. The value can also be a string. In this case, the width
    of the text given by min-width determines the minimum width of the
    block. This is useful when you want to set a sensible minimum width
    regardless of which font you are using, and at what particular size.
    
    See BLOCK

  • EXTERNAL GENERIC-FUNCTION

    (SETF MIN-WIDTH)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    NAME

    • OBJECT

    Accessor to the name of the block.
    
    From i3docs:
    Every block should have a unique name (string) entry so that it can
    be easily identified in scripts which process the output. i3bar
    completely ignores the name and instance fields. Make sure to also
    specify an instance (string) entry where appropriate. For example,
    the user can have multiple disk space blocks for multiple mount
    points.
    
    See INSTANCE
    See BLOCK
    See CLICK

  • EXTERNAL GENERIC-FUNCTION

    (SETF NAME)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    NEXT-TIME

    • OBJECT

    Accessor to the next time a tick event should be fired.
    
    This is automatically updated when a tick event has fired or when a
    click event has fired and click-pause is set.
    
    The value is in internal-time-units.
    
    See INTERVAL
    See CLICK-PAUSE
    See STATUS-BAR

  • EXTERNAL GENERIC-FUNCTION

    (SETF NEXT-TIME)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    OUTPUT

    • OBJECT

    Accessor to the output stream to which the status-bar writes its results.
    
    This defaults to *STANDARD-OUTPUT*
    
    See PRODUCE-OUTPUT
    See STATUS-BAR

  • EXTERNAL GENERIC-FUNCTION

    (SETF OUTPUT)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    PROCESS

    • BAR

    Processes the status-bar, causing it to potentially read inputs and generate outputs.
    
    First the input is checked for a new click event. If one is there,
    it is parsed from the stream and output is produced according to
    GENERATE on the generators and the click event. If click-pause is
    set, the next-time is delayed by click-pause number of seconds from
    the current time.
    
    Next the next-time is checked against the current internal real
    time. If the time has passed, output is produced according to
    GENERATE on the generators and a new tick event. The next-time is
    then delayed by interval number of seconds from the current time.
    
    See CLICK
    See TICK
    See NEXT-TIME
    See CLICK-PAUSE
    See INTERVAL
    See GENERATOR
    See GENERATORS
    See STATUS-BAR

  • EXTERNAL GENERIC-FUNCTION

    PRODUCE-OUTPUT

    • BAR
    • PAYLOAD

    Outputs the given payload as JSON to the status-bar's output stream.
    
    See OUTPUT
    See STATUS-BAR

  • EXTERNAL GENERIC-FUNCTION

    RELATIVE-LOCATION

    • OBJECT

    Accessor to the relative position of the click.
    
    The location is a cons of X and Y coordinates, relative to the top
    left corner of the block itself in pixels.
    
    See CLICK

  • EXTERNAL GENERIC-FUNCTION

    (SETF RELATIVE-LOCATION)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    SEND-CLICK-EVENTS-P

    • OBJECT

    Whether i3 should send click updates to the process.
    
    Defaults to NIL
    
    See HEADER

  • EXTERNAL GENERIC-FUNCTION

    (SETF SEND-CLICK-EVENTS-P)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    SEPARATOR

    • OBJECT

    Accessor to the block's separator behaviour.
    
    If set should be either T, or a number of pixels for the width of
    the separator. If T, the default i3 behaviour is to use 9 pixels
    of width for the separator.

  • EXTERNAL GENERIC-FUNCTION

    (SETF SEPARATOR)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    SHORT-MARKUP

    • OBJECT

    Accessor to the list of markup regions for the pango block's short-text.
    
    See PANGO-BLOCK

  • EXTERNAL GENERIC-FUNCTION

    (SETF SHORT-MARKUP)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    SHORT-TEXT

    • OBJECT

    Accessor to the short, alternate text content of the block.
    
    From i3docs:
    Where appropriate, the short-text should also be provided. It
    will be used in case the status line needs to be shortened
    because it uses more space than your screen provides. For
    example, when displaying an IPv6 address, the prefix is
    usually (!) more relevant than the suffix, because the latter
    stays constant when using autoconf, while the prefix changes.
    When displaying the date, the time is more important than the
    date (it is more likely that you know which day it is than
    what time it is).
    
    See BLOCK

  • EXTERNAL GENERIC-FUNCTION

    (SETF SHORT-TEXT)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    STOP-SIGNAL

    • OBJECT

    The unix signal used to pause bar updates.
    
    Defaults to 19 (SIGSTOP)
    
    See HEADER

  • EXTERNAL GENERIC-FUNCTION

    (SETF STOP-SIGNAL)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    TEXT

    • OBJECT

    Accessor to the full textual content of the block.
    
    This field is required to be set.
    
    See BLOCK

  • EXTERNAL GENERIC-FUNCTION

    (SETF TEXT)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    TEXT-FORMAT

    • BLOCK

    Returns the text format used by the block's text content.
    
    Defaults to :none
    
    See BLOCK

  • EXTERNAL GENERIC-FUNCTION

    URGENT-P

    • OBJECT

    Accessor to whether the block is considered urgent or not.
    
    From i3docs:
    A boolean which specifies whether the current value is urgent.
    Examples are battery charge values below 1 percent or no more
    available disk space (for non-root users). The presentation of
    urgency is up to i3bar.
    
    See BLOCK

  • EXTERNAL GENERIC-FUNCTION

    (SETF URGENT-P)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    VERSION

    • OBJECT

    The version integer of the protocol that is used.
    
    Defaults to 1.
    
    See HEADER

  • EXTERNAL GENERIC-FUNCTION

    (SETF VERSION)

    • NEW-VALUE
    • OBJECT

    No documentation provided.