My Dot-Files

Table of Contents

• Summary
• TODO
  • Dot-files
  • Scripts
  • Other repository files
• Shell Functions
  • Print
  • Shell Functions
  • Predicates
  • Queries
  • Arrays
  • Command
  • Math
  • Internet
  • Multimedia
• Appendix

Summary

My core configuration (dot) files, shell functions and utility scripts.

• ZSH is the leading shell.

• Bash configs exist for rare cases in which zsh is not availlable, they are not regularly maintained and usually outdated.

• If not clearly ZSH related, all alias, function, etc. files should be Bash compatible (but not always POSIX compliant).

• All files use the " \{\{\{( .*)?$" (or {{{ }}} in short) folding comment pattern (use e.g. emacs, VS Code, eclipse)

TODO

• Review functions.zsh and aliases (update ancient code, remove obsolete code, maybe modularize)

• Include additional shell and python scripts

Dot-files

File / Folder	App	Description
.zshenv	ZSH	Common ZSH login shell environment (variables).
.zlogout	ZSH	Common ZSH logout cleanup
.zshrc	ZSH	Common ZSH config
.zsh.d/zshrc-freebsd.zsh .zsh.d/zshrc-motoko.zsh .zsh.d/zshrc-puppet.zsh .zsh.d/zshrc-saito.zsh .zsh.d/zshrc-11001001_org.zsh	ZSH	OS, distirbution, and/or host specific ZSH configs.
.zsh.d/aliases.zsh	SH	Common aliases
.zsh.d/aliases-freebsd.zsh .zsh.d/aliases-linux.zsh	SH	OS, distirbution, and/or host specific specific aliases.
.zsh.d/functions.zsh	SH	Common shell functions.
.zsh.d/functions-freebsd.zsh	SH	OS, distirbution, and/or host specific shell aliases.
.bash.d/bashrc	Bash	Common Bash config (rarely maintained).
.profile		Currently only loaded from insicede .xsession to prepare the enviroment (variables) without a login shell. It’s basically a copy of .zshenv though the latter can contain zsh specific stuff.
.xsession	X, Wayland	Used by the display manager. Currently only loades .profile and .xinitrc.
.xinitrc	X, Wayland	Loaded from inside .xsession or when starting xinit.
.xession/common .xession/default .xession/saito	X, Wayland	Common, default and host specific xsession initialization scripts loaded from inside .xinitrc. The common script is always loaded, the host specific script .xsession.d/{hostname} (e.g. .xsession.d/saito) is loaded if existing, else the fallback default is loaded .xsession.d/default.
.Xresources .Xresources.d/saito	X, Wayland	Common and host specific X Resources. The .Xresources file is loaded from inside .xsession.d/common. If a host specific Xresources .Xresources.d/{hostname} (e.g. Xresources.d/saito) exists, it is merged into the common resources.
.imwheelrc	IMWheel	General and app specific mouse button/wheel mappings.
.vimrc	VIM	VIM configuration
.config/mpv/config .config/mpv/input.conf	mpv	MPV configuration and key bindings.
.mplayer/config .mplayer/input.conf	MPlayer	Old MPlayer configuration and key bindings (switched to mpv).

ip=(192 168 100 18) printf "ip: %s\n" $(join_by . $ip) exp=$(join_by + $(seq 1 10)) printf "%s = %s\n" $exp $exp

Host / OS specific zsh files

Custom host / OS specific ZSH configurtaions, aliases, functions, xsessions and xresources can be created and they are dynamically loaded in case of a match. This provides a conveniant way to enrich the envoronment in case of a spicific host / os without messing around with the core files.

This is the sequence in which zshrc’s, aleases and functions are loaded from within .zshrc:

 # top of zshrc (always loaded)
 .zsh.d/functions.zsh
 .zsh.d/aliases.zsh

 # bottom of zshrc (loaded in given sequence if host/os matches)
 .zsh.d/functions-${OS}.zsh
 .zsh.d/functions-${HOST}.zsh
 .zsh.d/functions-${HOST}-${OS}.zsh
 .zsh.d/functions-${HOST}-${OS}_wsl.zsh

 .zsh.d/aliases-${OS}.zsh
 .zsh.d/aliases-${HOST}.zsh
 .zsh.d/aliases-${HOST}-${OS}.zsh
 .zsh.d/aliases-${HOST}-${OS}_wsl.zsh

 .zsh.d/zshrc-${OS}.zsh
 .zsh.d/zshrc-${HOST}.zsh
 .zsh.d/zshrc-${HOST}-${OS}.zsh
 .zsh.d/zshrc-${HOST}-${OS}_wsl.zsh

The special suffix _wsl is used on Windows Subsystem Linux, this allows the -linux files to be loaded in addition to (followed by) a WSL specific -linux_wsl file.

Some examples can be seen in the Dot-files list above.

Scripts

File	Description
bin/media-keys.sh	Script to be used from within X (e.g. media key mappings) for media player control (play/pause, perv/next song) and pulse audio volume control (+/-5% and toggle mute) optionally showing an OSD.

Other repository files

File	Description
link.sh	Link all dotfile repo files (except for loacl scripts and documentation) to the user’s home directory. Missing directories are created in the process. It currently moves existing files / links, that would be overwritten in the process, to a backup location inside the home directory.
permissions.sh	Updates the dotfile repo file permissions.
README.adoc	This file

Shell Functions

Some of the shell functions contained in .zsh.d/functions.zsh will be described in the following chapters.

Print

Function	Description
p_usg USAGE..	Print a Usage text.
p_msg MSG..	Print an info message.
p_war MSG..	Print a warning message.
p_err MSG..	Print an error message (stderr).
p_dbg DBG_LVL SHOW_AT_LVL MSG..	Print a debug msg if the given debug level is reached. A global debug level can be set via the DBG_LVL variable, in this case p_dbg will use the higher level max(arg-level, global-level), meaning whichever is larger. As a result the global level can be used to globally raise, but never to lower the locally used debug level. So simply set the DBG_LVL argument to 0 if only the global level should be considered.
p_yes p_no	Print yes in green and no in red color.
py_print [-i import] PY_CODE..	Route the given code through the python3 print function. Use -i to import additional packages.

Colors

Function	Description
p_colortable	Print 256 ansi color table.
tputs STYLE..	Execute multiple tput commands in sequence. Exapmle:
tp STYLE..	Set one or more tput colors and text effects by (short) name. All values are looked up from a map (no need to run an external process).

Shell Functions

Function	Description
func_name	Returns the current function’s name: ${FUNCNAME[0]} on bash, ${funcstack[1]} on zsh.
func_caller	Returns the function’s caller name (if caller is a function): ${FUNCNAME[1]} on bash, ${funcstack[2]} on zsh.

Predicates

Function	Description
is_zsh	true if zsh session, else: false
is_bash	true if bash session, else: false
is_su	true if root (super user) session, else: false
is_sudo	true if in sudo mode, else: false
is_sudo_cached	true if sudo has cached credentials, else: false
is_ssh	true if ssh session, else: false
is_int NUMBER..	true if all given numbers are integers (only digits), else: false. Ignores leading/trailing spaces, accepts leading +/- sign.
is_decimal NUMBER..	true if all given numbers are decimals (only digits, MUST contain decimal separator '.'), else: false. Ignores leading/trailing spaces, accepts leading +/- sign.
is_number NUMBER..	true if all given numbers a either integers or decimals (only digits, CAN contain decimal separator '.'), else: false. Ignores leading/trailing spaces, accepts leading +/- sign.
is_positive NUMBER..	true if all numbers do NOT start with a -, else: false. Ignores leading/trailing spaces. Note: This doesn’t check if the arguments are numbers (it simply checks for a leading -, should always be used in combination with is_int/decimal/number).

Queries

Function	Description
q_yesno QUESTION	Print the QUESTION and asks for (y)es/(n)o input. Returns true if answer is yes, else: false.
q_overwrite FILE	Checks if the given file exists, if so asks wether to overwrite it via (y)es/(n)o input. Returns true only if FILE exists AND if answer is yes, else: false.

Arrays

Function	Description
join_by DELIMITER ARRAY..	Join array / arguments using the given delimiter. On ZSH consider using ${(j:del:)array}. Note that on zsh the same can be achived via ${(j:.:)ip}.

Command

Function	Description
cmd_delay DELAY COMMAND..	Execute a command with a delay (using sleep format, e.g. 3m for 3 minutes). Sleep timer example: cmd_delay 45m systemctl suspend.
while_read COMMAND..	Monitor input (read lines) and execute command in foreground using input as command argument. Example: while_read wget to download all entered urls.
while_read_bg COMMAND..	Monitor input (read lines) and execute command in background (job) using input as command argument. Example: while_read_bg wget to download all entered urls.
while_read_xclip [OPTION..] COMMAND..	Monitor X clipboard and execute command using clipboard content as command argument. Example: while_read_xclip -b -m '^https?://.*' tee -a links.txt "<<<'{}'" | wget -nv -c -i - to append all http(s) URLs read vom clipboard to a file named links.txt and download them using wget.

Math

Function	Description
calc EXPR..	A simple wrapper for dc. Set the decimal scale using the -s option (default: 0).
py_calc PY_CODE..	Routes PY_CODE through python3’s print function with from math import *. Apart from this additional import it’s basically the same as py_print so this is also possible (even without the math. prefix):

Internet

Function	Description
ytp URL..	Download media files using youtube-dl and aria2c (4 concurrent downloads, 4 threads per host) using the same output file names provide by youtube-dl using the following pattern: %(title)s [%(id)s].%(ext)s. Note that this is basically the same as the alias yt but using aria2c for parallel download instead of the integrated, single threaded downloader. When multiple formats are available, all yt* commands will favor free codecs starting with the highest quality streams _(rough codec/format priority: vp9/opus/vp8/vorbis/webm/ogg/*).
ytap URL..	The same as ytp above, but downloads audio stream only preferably to a ogg(opus/vorbis) file. Note that this is basically the same as the alias yta but using aria2c for parallel download.

Multimedia

Function	Description
mpv_find DIR [OPTION..] [-a MPV-ARG..]	Find any media file (default: .avi,.mkv,.mp4,.webm, regex match can be changed) and play them using mpv. Allows sorting, fs tree recursion, list-only (stdout, no playback), 'resuming' (from a given index), and passing additional arguments to mpv. Example: mpv_find -r -s -R -a --no-resume-playback will play all videos in the current, and all subfolders, in random order, ignoring mpv’s remsue-playback function.
to_mp3 INFILE [BITRATE [OUTFILE]]	Convert the given INFILE to mp3 using ffmpeg (INFILE may be any media file containing an audio stream processable by ffmpeg). A bitrate of 160k and default output file name {infilename}-audio.mp3 ise used if no specific options are provided.
to_opus [-b BITRATE] INFILE [OPUSENC_ARG..]	Convert the given INFILE to opus using opusenc (infile may be any media file containing audio readable by opusenc). If no arguments are provided it uses the default opusenc vbr bitrate of "64kbps per mono stream, 96kbps per coupled pair". The output file is {infilename}.opus _(currently not changeable).
ff_concat OUTFILE INFILE..	Concatenates all INFILEs into OUTFILE using ffmpeg.
ff_crop INFILE CROP [OUTFILE]	Crop INFILE video using the given ffmpeg crop format (e.g. 640:352:0:64) to the default outfil {infilename}_CROP.{infileext}. Requires imagemagick’s identify.

Images

Function	Description
gif_delay FILE	Returns all frame indexes of a gif FILE with their respective delays (speed). It is optionally possible to only list the delays --delay-only or to print only the (rounded) average 1/100 sec delay --average of all frames. In the --help examples are provided on how to change the speed of a gif file using imagemagick’s convert. Requires imagemagick’s identify.
image_concat FILE..	Concatenate images. TODO: Needs further improvement.
image_dimensions FILE..	Returns dimensions given images in format: {file-name}|{w}|{h}|{w}x{h}|{w*x}|{min(w,h)}|{max(w,h)} (width, height, pixels, shortest/longest edge, etc.). The delimiter | can be changed. Requires imagemagick’s identify.

Appendix

Icon pack by Icons8