cari3s
2.0.0A generator for the i3 status bar.
Table of Contents
System Information
Definition Index
-
CARI3S
- ORG.SHIRAKUMO.CARI3S
No documentation provided.-
EXTERNAL CLASS BATTERY
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 six values: 0. charge-percentage 1. charging-p 2. discharging-p 3. hours-remaining 4. minutes-remaining 5. seconds-remaining See VALUE-GENERATOR
-
EXTERNAL CLASS BLOCK
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
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
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
A generator for the current CPU usage. This value-generator supplies the following value: 0. usage-percentage See VALUE-GENERATOR
-
EXTERNAL CLASS DISK-USAGE
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 ECHO
An event that is sent back over the connection as-is. This event does not reach generators. See event
-
EXTERNAL CLASS EVENT
Superclass for all events that might happen in the system. See PROCESS-EVENT
-
EXTERNAL CLASS EVENT-SERVER
Represents an event exchange server. This server runs a TCP listener on a given port on the localhost. The port defaults to 2424. Once started, the server accepts an arbitrary amount of connections, over which events can be issued. An event should follow the format as specified in SERIALIZE-OBJECT, and should be followed by a single Linefeed. For each event issued, the server will respond with one or more objects. The connection is never closed by the server except for when the underlying stream is closed, or a TCP error occurs and the connection is doomed anyway. The client is allowed to terminate the connection at any time. This class on its own does nothing. In order to start the server listener, START must be called. STOP can be called to end the listener and disconnect all clients. Once started, PROCESS-CONNECTIONS must be called regularly in order to accept new connections, handle incoming events, and to clean up old connections that have disconnected. See PORT See LISTENER See CONNECTIONS See START See STOP See PROCESS-CONNECTIONS
-
EXTERNAL CLASS GENERATE
An event to signal that blocks should be generated immediately. This event does not reach generators. See event
-
EXTERNAL CLASS GENERATOR
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 See INTERVAL See PROCESS-EVENT
-
EXTERNAL CLASS HEADER
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
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
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. When :CACHE is T, memory used by the cache is counted as occupied. When :SWAP is T, swap memory and usage are added to the total. This value-generator supplies the following three values: 0. usage-percentage 1. total-megabytes 2. free-megabytes See VALUE-GENERATOR
-
EXTERNAL CLASS NETWORK-IP
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
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
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
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. It also handles remote client connections through the event-server. See INTERVAL See NEXT-TIME See GENERATORS See OUTPUT See INPUT See CLICK-PAUSE See PRODUCE-OUTPUT See PROCESS See RUN-BAR See EVENT-SERVER
-
EXTERNAL CLASS UPTIME
A generator for the current system uptime. This value-generator supplies the following four values: 0. uptime-days (NIL if zero) 1. uptime-hours 2. uptime-minutes 3. uptime-seconds
-
EXTERNAL CLASS VALUE-GENERATOR
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 CLASS WEATHER
A generator for current weather data. You must specify your darksky.net api-key via the :API-KEY initarg, and your global coordinates in the (LAT . LNG) format via the :LOCATION initarg. This requires an active internet connection to function. This value-generator supplies the following seven values: 0. summary 1. temperature [C] 2. temperature-apparent-p 3. apparent-temperature [C] 4. humidity [%] 5. wind [km/h] 6. pressure [hPa]
-
EXTERNAL FUNCTION LOAD-FROM-FILE
- FILE
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
- CLICK-EVENTS-P
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
Runs a status bar initialised from a file. See LOAD-FROM-FILE See RUN-BAR
-
EXTERNAL FUNCTION TOPLEVEL
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 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 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
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 CONNECTIONS
- OBJECT
The list of connected client sockets. This is not thread-safe to modify. See EVENT-SERVER
-
EXTERNAL GENERIC-FUNCTION (SETF CONNECTIONS)
- NEW-VALUE
- OBJECT
No documentation provided. -
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 FROM-TABLE
- TYPE
- TABLE
Generate an object from a table of basic types. This is intended for json deserialisation. Allowed types are: - hash-table - string - list - vector - number - T - NIL
-
EXTERNAL GENERIC-FUNCTION GENERATE
- 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
-
EXTERNAL GENERIC-FUNCTION (SETF INSTANCE)
- NEW-VALUE
- OBJECT
No documentation provided. -
EXTERNAL GENERIC-FUNCTION INTERVAL
- OBJECT
Accessor to the interval in seconds in which output is generated The default interval is one second for generators, and 0.1 seconds for status-bars. GENERATE is only called on generators if their own interval has expired. They will not be called more frequently than the status-bar's own interval however. See NEXT-TIME See STATUS-BAR See GENERATOR
-
EXTERNAL GENERIC-FUNCTION (SETF INTERVAL)
- NEW-VALUE
- OBJECT
No documentation provided. -
EXTERNAL GENERIC-FUNCTION LISTENER
- OBJECT
The server socket to listen for connections on. This is NIL if the server is not running. This is not thread-safe to modify. See EVENT-SERVER
-
EXTERNAL GENERIC-FUNCTION (SETF LISTENER)
- 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 MESSAGE
- 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 OBJECT-INITARGS
- OBJECT
Returns a list of initargs to reconstruct the given object with make-instance. By default this simply gathers a list of all slots that are bound and that have at least one initarg. This is for the purpose of reconstructing the object after serialisation. You may add methods in case you want more precise control over the reconstruction of the object.
-
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 PARSE-EVENT-OR-LOSE
- STREAM
Attempts to parse an event from the given source, signalling an error on failure. This will return an EVENT instance. See EVENT
-
EXTERNAL GENERIC-FUNCTION PORT
- OBJECT
The port on which the server listens for connections. Defaults to 2424. See EVENT-SERVER
-
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 PROCESS-CONNECTIONS
- SERVER
Processes the event-server connections. This proceeds by listening for new connections and accepting them if there are any. It then listens on each socket in turn, parsing and processing pending events. If a stream or socket error occurs, the connection is removed. If another error occurs during parsing or processing, an error is sent back to the client. See PARSE-EVENT-OR-LOSE See PROCESS-EVENT See SERIALIZE-OBJECT See EVENT-SERVER
-
EXTERNAL GENERIC-FUNCTION PROCESS-EVENT
- EVENT
- PROCESSOR
Causes the given event to be processed by the specified receiver. If the receiver does not understand the event, an error is signalled. In the case of a status-bar, unknown events are passed on to its generators. In the case of a generator, unknown events are ignored. You should add methods to this as necessary in order to interface your object with the general event system. See EVENT
-
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 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 SERIALIZE-OBJECT
- OBJECT
- STREAM
Serialises the object to the given stream in the event protocol format. The event protocol format is an UTF-8 based format: OBJECT ::= "NIL" | "T" | INSTANCE INSTANCE ::= CLASS-NAME INITARG* INITARG ::= keyword VALUE VALUE ::= symbol | string | real | list Programs that intend on parsing events or return values from Cari3s need to be able to parse this format and serialise their respective format to it as well. Restrictions on the encoding of values: - Strings may not contain the Linefeed character. - Symbols must be either unqualified (without the package prefix), or keywords. - Symbol names may not contain the Linefeed character. - Symbol names must be written in all lowercase with the exception of NIL and T which are written all uppercase. - Only proper lists are allowed.
-
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 START
- SERVER
Start the event-server. If it is already started, an error is signalled. See EVENT-SERVER
-
EXTERNAL GENERIC-FUNCTION STOP
- SERVER
Stops the event-server. If it is already stopped, nothing is done. See EVENT-SERVER
-
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 TO-TABLE
- OBJECT
Turn the object into a table of basic types. This is intended for json serialisation. Allowed types are: - hash-table - string - list - vector - number - T - NIL
-
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.