Admiral

Executes multiple programs concurrently to generate output for bars

Table of Contents

Introduction

If you just want to get Admiral running, skip to the next section.

Programs like lemonbar and i3bar have become popular in recent years, and with good reason. For those of you who are unfamiliar with them, these programs read from standard input and then output what they receive on a bar. For the most part, their output is identical to their input, but they accept some format strings which allow the user to specify things like colors, justification, and clickable areas.

The advantage of this system is that it is very powerful. The disadvantage is that it can be rather difficult to configure.

A typical bar script looks something like this: a shell script, probably bash, is used to collect and format the output of various commands. This is done in an infinite loop, probably ending with sleep 0.1 or something similar. The output of this script is then piped into the bar program, which receives a new line (which may be identical to its previous line) ten times per second.

The main problem with this method is that it's rather difficult to handle timing correctly. A counter showing the number of outdated programs on the system can be updated less frequently than a clock.

Actually, a previous bar script I had contained both of the aforementioned items. One day, I noticed the clock on my bar had stopped working. The cause? The internet had died. This prevented the package counter command (checkupdates | wc -l) from ever finishing, which caused the entire bar to stop working.

Another major problem is that shell scripts of these types are bug-prone and tend to become very bloated. Admiral has a declarative style which allows you to configure your bar with ease and avoid pesky bugs.

What Admiral Does

Admiral runs programs specified by the user and prints their output. It allows for a clear separation of different sections, which simplifies configuration.

The best part? Each program is run in its own thread. This means that each section is updated independently of the other sections. It also means that if something fails, it fails independently of the other sections. That example where the clock stopped? This would never happen with Admiral. Sure, checkupdates would still hang indefinitely and prevent that number from changing. But the clock (and the rest of the bar) would be unaffected.

Admiral also limits its output. Whenever one of its programs updates, it checks to see if anything has actually changed since it last printed a message. If nothing has changed, Admiral prints nothing—this limits the amount of refreshing that your bar program has to do.

Getting Started

Prerequisites

  • rustc — the Rust compiler

  • cargo — the Rust package manager

  • git (optional but recommended)

These can probably be installed via your distribution's package manager. If the Rust compiler and Cargo are not packaged for your distro, you can download them here.

Installation

  1. Clone this repository with git clone https://github.com/sector-f/admiral.git
    • Alternatively, a .zip file of the master branch can be downloaded here
  2. cd into the newly-created admiral/ directory
  3. Run cargo build --release

This will create an admiral excutable in the ./target/release/ directory. You may want to copy this to somewhere in your $PATH, like /usr/local/bin/ or ~/.local/bin/

You may then copy the provided admiral.d/ directory to ~/.config/ (or your $XDG_CONFIG_HOME directory, if you have that environment variable set).

Configuration

Configuration is done with an admiral.toml file. This file is looked for in ~/.config/admiral.d/ (Or $XDG_CONFIG_HOME/admiral.d/, if that environment variable is set). Alternatively, a configuration file may be specified with the -c flag, e.g. admiral -c /path/to/file.toml.

An example admiral.d/ (complete with the admiral.toml) is included in this repository.

[admiral]

[admiral] is the section where Admiral's output is configured. It has one required entry: items. Here is an example [admiral] section:

[admiral]
items = ["music", "workspaces", "clock"]

Each entry in the items table specifies a section of the config file that will be run. Note that the order specified here is the order that Admiral will use for the scripts' output.

Sections of the admiral.toml

Each section of the admiral.toml contains a command that produces some output; you can use shell scripts, python scripts, executable binaries, etc.

Here is an example script section:

[clock]
path = "date '+%I:%M %p'"
reload = 1

path

path is the only required entry for a script. The specified command is executed by a shell running in the same directory as the admiral.toml. So, path = "./mpd.sh" will run the mpd.sh in the same directory as the admiral.toml, and path = "echo 'Hello, world!'" will output "Hello, world!" using your shell. Note that the shell is determined via the $SHELL environment variable.

shell

shell is an optional variable that specifies an alternate shell to execute commands with. The default shell is your $SHELL environment variable. Using an alternate shell may be useful if you wish to leverage features of a specific shell for a certain command. An example use is shell = "/usr/bin/fish".

reload

The reload value is the optional duration in seconds between each execution of the script. It may be either an integer such as 10 or a float such as 0.5.

If no reload value is specified, and static is not set to true, this indicates that the script should never exit. It will be run, and each line it outputs will be used separately. This is for commands such as xtitle -s, which handle polling themselves and output new information on a new line. If the process is killed, it will automatically be restarted.

static

static is an optional boolean variable. It is set to false by default. It is for scripts that only need to be run once. Here is an example:

[center]
path = "echo '%{c}'"
static = true

This script is used to add a format sequence for lemonbar. It only needs to be run once, and its output will never change.

Newlines

Bars expect newline characters to be used only at the end of each full line of input; Admiral tries to respect this by trimming newline characters from the output of scripts. Users should be aware of how this is handled:

  • Both \r and \n characters are removed from the start and end of a script's output

  • If no reload value is specified and static is false, Admiral uses each line produced by the script. This means that each line meant to be displayed must end in either \n or \r\n. However, these characters will still be stripped from Admiral's output so as to keep its complete output on a single line.

Example

An example admiral.d/ directory is included with admiral. The example is designed for use with bspwm, and also relies on xtitle to get the window title. Its output is designed to be piped to lemonbar. The command admiral | lemonbar -g x30 | sh should work for a demonstration, although a greater number of clickable areas may need to be specified with lemonbar -a if you have more than 8 desktops.

The example bar has three sections: BSPWM workspace information, the current window title, and the current time. The workspace section uses the letters f, o, and u to represent free (empty), occupied, and urgent desktops, respectively. Lowercase letters represent unfocused desktops, and an uppercase letter represents the focused desktop.

This workspace section is clickable. Left-clicking on a letter will switch to the corresponding desktop. Scrolling up with the mouse wheel while the cursor is over the workspace section will switch to the previous desktop, and scrolling down with the mouse wheel will switch to the next desktop.

This directory contains two files: an admiral.toml file and bspwm_workspaces.sh. Let's look at the example admiral.toml:

[admiral]

This is the provided [admiral] section:

[admiral]
items = ["left", "workspaces",
         "center", "title",
         "right", "clock"]

Six scripts are listed. Three are used to provide information, and the other three are used for formatting the output.

Scripts

These are the first three scripts listed in the example admiral.toml file:

[workspaces]
path = "./bspwm_workspaces.sh"

[title]
path = "xtitle -s -t 100"

[clock]
path = "date '+%-I:%M %p  '"
reload = 1

bspwm_workspaces.sh is a Bash script that parses the output of bspc subscribe report and converts it into a clickable, human-readable format for lemonbar. Because bspc subscribe report (and therefore bspwm_workspaces.sh) never exits, no reload value is specified.

Formatting

These are the last three scripts:

[left]
path = "echo '%{l}'"
static = true

[center]
path = "echo '%{c}'"
static = true

[right]
path = "echo '%{r}'"
static = true

These output format strings to be interpreted by lemonbar. As their output only needs to be captured once, static is set to true. Remember that admiral removes trailing newline characters; this means that using echo rather than echo -n will still work here.

Keeping the format strings outside of the main scripts allows for quicker, easier formatting.

Bugs

  • Specifying a toml file in the current directory as admiral -c admiral.toml causes scripts with relative paths to fail.
    • Workaround: Give the "directory name" as well, i.e. admiral -c ./admiral.toml

Any bugs that are found should be reported here.



Admiral

同时执行多个程序以生成条形输出

目录

简介

如果您只想获得海军上将,请跳到下一节

程序,如 lemonbar i3bar 近年来颇受欢迎, 并有很好的理由。对于那些不熟悉他们的人, 这些程序从标准输入读取,然后输出他们在酒吧上收到的内容。 在大多数情况下,他们的输出与他们的输入是相同的,但他们接受 一些格式字符串,允许用户指定颜色, 理由和可点击的区域。

这个系统的优点是它非常强大。缺点是 这可能很难配置。

一个典型的bar脚本看起来像这样:一个shell脚本,可能是bash, 用于收集和格式化各种命令的输出。这完成了 一个无限循环,可能以 sleep 0.1 或类似的东西结束。 此脚本的输出然后被管道输入到bar程序,它接收一个新的 行(可能与之前的行相同)每秒十次。

这个方法的主要问题在于它是相当困难的 正确处理时间一个柜台显示的数量 系统上过时的程序可以比时钟更频繁地更新。

实际上,以前的酒吧剧本包含了上述两个 物品。有一天,我注意到我的酒吧的时钟停止了工作。 原因?互联网已经死了。这样就阻止了package counter命令 ( checkupdates | wc -l <​​/ code>)从未完成,导致整个 酒吧停止工作。

另一个主要问题是这些类型的shell脚本容易出错 往往会变得很blo肿。 海军上将有一个声明式的风格,让您轻松配置您的酒吧 并避免恶作剧。

什么上将不

海军上将运行用户指定的程序并打印输出。它允许 为了明确分离不同的部分,这简化了配置 最好的部分? 每个程序都在自己的线程中运行。 这意味着每个部分都是独立于其他部分进行更新的。 这也意味着如果某些事情失败,它将独立地失败 部分。 时钟停止的例子海军上将永远不会发生。 当然, checkupdates 仍然会无限期地挂起,并阻止这种情况 数字来自变化。但时钟(和酒吧的其余部分)将不受影响。

海军上将也限制其输出。每当其中一个程序更新时,它会检查 如果自上次打印邮件以来,任何事情实际上发生了变化如果没有 改变了,海军上将打印没有 - 这限制了你的酒吧刷新的数量 程序必须做。

入门指南

前提条件

  • rustc - Rust编译器

  • 货物 - Rust包管理器

  • git (可选但推荐)

这些可能通过您的发行版的软件包管理器进行安装。 如果Rust编译器和货物没有为您的发行版打包, 您可以下载此处

安装

  1. Clone this repository with git clone https://github.com/sector-f/admiral.git
    • Alternatively, a .zip file of the master branch can be downloaded here
  2. cd into the newly-created admiral/ directory
  3. Run cargo build –release

这将在 ./ target / release / 目录中创建一个 admiral 。 您可能想将其复制到您的 $ PATH 中的某个位置, 像 / usr / local / bin / 〜/ .local / bin /

然后,您可以将提供的 admiral.d / 目录复制到〜/ .config / (或您的 $ XDG_CONFIG_HOME 目录,如果您设置了该环境变量)。

配置

使用 admiral.toml 文件完成配置。此文件被查找 〜/ .config / admiral.d / (或 $ XDG_CONFIG_HOME / admiral.d / ,如果那个环境 变量设置)。或者,可以指定配置文件 -c 标志,例如 admiral -c /path/to/file.toml

一个示例 admiral.d / (完整的 admiral.toml )包含在这个 存储库。

[admiral]

[admiral] 是配置海军上将的输出部分。 它有一个必需条目: items 。这是一个例子 [admiral] 部分:

[admiral]
items = ["music", "workspaces", "clock"]

items 表中的每个条目指定将要运行的配置文件的一部分。 请注意,这里指定的顺序是海军上将使用的顺序 脚本的输出。

admiral.toml

的部分

admiral.toml 的每个部分都包含一个生成一些输出的命令; 您可以使用shell脚本,python脚本,可执行二进制文件等。

这是脚本示例部分:

[clock]
path = "date '+%I:%M %p'"
reload = 1

path

path 是脚本唯一必需的条目。执行指定的命令 由shell运行在与 admiral.toml 相同的目录中。 所以, path =./mpd.sh将在同一目录中运行 mpd.sh admiral.toml path =echo’Hello,world!’将输出Hello,world!使用 你的外壳。请注意,shell通过 $ SHELL 环境变量确定。

shell

shell 是一个可选变量,指定执行命令的备用shell 与。默认shell是您的 $ SHELL 环境变量。使用备用 如果您希望利用特定shell的功能,shell可能很有用 命令。一个例子是 shell =/ usr / bin / fish

reload

reload 值是以秒为单位的可选持续时间 每个执行脚本。它可以是整数,例如 10 或浮动如 0.5

如果没有指定 reload 值,并且 static 未设置为 true ,则表示 脚本不应该退出。它将运行,它输出的每一行将是 单独使用。这是用于处理轮询的命令,例如 xtitle -s 并在新的一行输出新的信息。如果这个过程被杀死,它会的 自动重启。

static

static 是一个可选的布尔变量。默认设置为false。是为了 只需要运行一次的脚本。这是一个例子:

[center]
path = "echo '%{c}'"
static = true

此脚本用于添加 lemonbar 的格式序列。它只需要 运行一次,其输出将永远不变。

新线

酒吧预计换行符只能在每条完整的输入行结尾使用; 海军上将尝试通过从输出中修剪换行符来尊重这一点 的脚本。用户应该知道如何处理:

  • Both \r and \n characters are removed from the start and end of a script's output

  • If no reload value is specified and static is false, Admiral uses each line produced by the script. This means that each line meant to be displayed must end in either \n or \r\n. However, these characters will still be stripped from Admiral's output so as to keep its complete output on a single line.

示例

海军上将包括一个示例 admiral.d / 目录。这个例子是为了设计的 与 bspwm 一起使用,并且还依赖于 xtitle 获取窗口标题。它的 输出设计为管道传输到 lemonbar 。 命令 admiral | lemonbar -g x30 | sh 应该用于演示,虽然 可能需要使用 lemonbar -a 指定更多的可点击区域 如果您有超过8个桌面。

示例栏有三个部分:BSPWM工作区信息,当前窗口 标题和当前时间。工作区部分使用 字母 f o u 表示空闲(空),占用和紧急桌面, 分别。小写字母表示未聚焦的桌面和大写字母 字母表示重点桌面。

此工作区可点击。左键单击一个字母将切换到 相应的桌面。光标结束时,用鼠标滚轮向上滚动 工作区将切换到上一个桌面,然后滚动 下来,鼠标滚轮将切换到下一个桌面。

此目录包含两个文件:一个 admiral.toml 文件和 bspwm_workspaces.sh 。 我们来看看例子 admiral.toml

[admiral]

这是提供的 [admiral] 部分:

[admiral]
items = ["left", "workspaces",
         "center", "title",
         "right", "clock"]

列出了六个脚本。三个用于提供信息,另一个 三个用于格式化输出。

脚本

这些是示例 admiral.toml 文件中列出的前三个脚本:

[workspaces]
path = "./bspwm_workspaces.sh"

[title] path = "xtitle -s -t 100"

[clock] path = "date '+%-I:%M %p '" reload = 1

bspwm_workspaces.sh 是一个Bash脚本,用于解析 bspc subscribe report 的输出 并将其转换为 lemonbar 的可点击,可读的格式。因为 bspc subscribe report (因此 bspwm_workspaces.sh )永远不会退出,没有重新加载 值被指定。

格式化

这些是最后三个脚本:

[left]
path = "echo '%{l}'"
static = true

[center] path = "echo '%{c}'" static = true

[right] path = "echo '%{r}'" static = true

这些输出格式字符串由 lemonbar 解释。作为他们的输出 需要被捕获一次, static 设置为 true 。 请记住, admiral 删除尾随的换行符;这意味着 使用 echo 而不是 echo -n 仍然可以在这里工作。

将格式字符串保留在主脚本之外可以更快,更简单 格式化。

错误

  • 在当前目录中指定一个toml文件为 admiral -c admiral.toml 导致具有相对路径的脚本失败。
    • 解决方法:提供目录名称,即 admiral -c ./admiral.toml
应该报告发现的任何错误 此处




相关问题推荐