Skip to content

Commit b00c791

Browse files
tatanustatanus
authored
Merge pull request #4 from tatanus/fix/proc-docs-and-style
docs(proc-docs): Add proc-doc blocks to all non-trivial functions
2 parents ffdc7df + ed3e9fb commit b00c791

9 files changed

Lines changed: 403 additions & 108 deletions

File tree

‎dotfiles/bash.aliases.sh‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
#!/usr/bin/env bash
22
# shellcheck disable=SC2154 # BASH_DIR, PROXY are set by parent shell environment
33
set -uo pipefail
4+
IFS=$'\n\t'
45

56
# =============================================================================
67
# NAME : bash.aliases.sh

‎dotfiles/bash.env.sh‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
#!/usr/bin/env bash
22
set -uo pipefail
3+
IFS=$'\n\t'
34

45
# =============================================================================
56
# NAME : bash.env.sh
@@ -36,7 +37,15 @@ if [[ -z "${BASH_ENV_SH_LOADED:-}" ]]; then
3637
# define colors for Linux
3738
export LS_COLORS="di=34:ln=35:so=32:pi=33:ex=31:bd=34:cd=34:su=0;41:sg=0;46:tw=0;42:ow=33"
3839

39-
# Helper function: Check command availability
40+
###############################################################################
41+
# _check_command
42+
#------------------------------------------------------------------------------
43+
# Purpose : Check if a command is available in PATH
44+
# Usage : _check_command <command>
45+
# Arguments:
46+
# $1 : command - Name of the command to check
47+
# Returns : 0 if available, 1 if not found
48+
###############################################################################
4049
function _check_command() {
4150
if ! command -v "$1" &> /dev/null; then
4251
echo "$1 is not installed or not functional. Some functionality may not work."

‎dotfiles/capture_traffic.sh‎

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
#!/usr/bin/env bash
22
set -uo pipefail
3+
IFS=$'\n\t'
34

45
# =============================================================================
56
# NAME : capture_traffic.sh
@@ -30,15 +31,32 @@ if [[ -z "${CAPTURETRAFFIC_SH_LOADED:-}" ]]; then
3031
# Helper Functions
3132
# =============================================================================
3233

33-
# Check if tshark is available
34+
###############################################################################
35+
# check_tshark
36+
#------------------------------------------------------------------------------
37+
# Purpose : Verify tshark is installed and available in PATH
38+
# Usage : check_tshark
39+
# Returns : Exits with 1 if tshark not found
40+
###############################################################################
3441
check_tshark() {
3542
if [[ -z "${TSHARK_CMD}" ]]; then
3643
fail "tshark is not installed or not in PATH." >&2
3744
exit 1
3845
fi
3946
}
4047

41-
# Validate and parse arguments
48+
###############################################################################
49+
# parse_capture_args
50+
#------------------------------------------------------------------------------
51+
# Purpose : Parse and validate capture_traffic command line arguments
52+
# Usage : parse_capture_args <src_ip> <dst_ip> <src_port> <dst_port> [opts]
53+
# Arguments:
54+
# $1 : src_ip - Source IP address
55+
# $2 : dst_ip - Destination IP address
56+
# $3 : src_port - Source port
57+
# $4 : dst_port - Destination port
58+
# Returns : Sets global variables; exits on error
59+
###############################################################################
4260
parse_capture_args() {
4361
if [[ $# -lt 4 ]]; then
4462
info "Usage: $0 <src_ip> <dst_ip> <src_port> <dst_port> [-t <seconds>] [-m <messages>] [--interface <iface>]" >&2
@@ -91,6 +109,18 @@ if [[ -z "${CAPTURETRAFFIC_SH_LOADED:-}" ]]; then
91109
# Main Function
92110
# =============================================================================
93111

112+
###############################################################################
113+
# capture_traffic
114+
#------------------------------------------------------------------------------
115+
# Purpose : Capture network traffic between two IP:port pairs using tshark
116+
# Usage : capture_traffic <src_ip> <dst_ip> <src_port> <dst_port> [options]
117+
# Arguments:
118+
# $1 : src_ip - Source IP address
119+
# $2 : dst_ip - Destination IP address
120+
# $3 : src_port - Source port
121+
# $4 : dst_port - Destination port
122+
# Returns : 0 on success, 1 on failure
123+
###############################################################################
94124
capture_traffic() {
95125
# Parse arguments
96126
parse_capture_args "$@"

‎dotfiles/combined.history.sh‎

Lines changed: 32 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
#!/usr/bin/env bash
22
# shellcheck disable=SC2154 # pipestatus is zsh-specific, set by the shell
33
# shellcheck disable=SC2034 # Test function variables used for validation patterns
4+
set -uo pipefail
5+
IFS=$'\n\t'
46
# =============================================================================
57
# NAME : combined.history.sh
68
# DESCRIPTION : Logs commands in Bash and Zsh interactive shells.
@@ -111,11 +113,11 @@ fi
111113
# =============================================================================
112114
# Fallback logging if logger not provided
113115
# =============================================================================
114-
if ! declare -f info > /dev/null; then function info() { printf '[* INFO ] %s\n' "${1}"; }; fi
115-
if ! declare -f warn > /dev/null; then function warn() { printf '[! WARN ] %s\n' "${1}" >&2; }; fi
116+
if ! declare -f info > /dev/null; then function info() { printf '[* INFO ] %s\n' "${1}"; }; fi
117+
if ! declare -f warn > /dev/null; then function warn() { printf '[! WARN ] %s\n' "${1}" >&2; }; fi
116118
if ! declare -f error > /dev/null; then function error() { printf '[- ERROR ] %s\n' "${1}" >&2; }; fi
117-
if ! declare -f pass > /dev/null; then function pass() { printf '[+ PASS ] %s\n' "${1}"; }; fi
118-
if ! declare -f fail > /dev/null; then function fail() { printf '[! FAIL ] %s\n' "${1}" >&2; }; fi
119+
if ! declare -f pass > /dev/null; then function pass() { printf '[+ PASS ] %s\n' "${1}"; }; fi
120+
if ! declare -f fail > /dev/null; then function fail() { printf '[! FAIL ] %s\n' "${1}" >&2; }; fi
119121
if ! declare -f debug > /dev/null; then function debug() { printf '[# DEBUG ] %s\n' "${1}"; }; fi
120122

121123
# =============================================================================
@@ -483,13 +485,13 @@ EOF
483485
bash)
484486
# Use parameter expansion instead of sed for better performance
485487
command="$(history 1)"
486-
command="${command#"${command%%[![:space:]]*}"}" # ltrim
487-
command="${command#*[0-9] }" # Remove leading number
488-
command="${command#*] }" # Remove timestamp if present
488+
command="${command#"${command%%[![:space:]]*}"}" # ltrim
489+
command="${command#*[0-9] }" # Remove leading number
490+
command="${command#*] }" # Remove timestamp if present
489491
;;
490492
zsh)
491493
command="$(fc -ln -1)"
492-
command="${command#"${command%%[![:space:]]*}"}" # ltrim
494+
command="${command#"${command%%[![:space:]]*}"}" # ltrim
493495
;;
494496
*)
495497
command=""
@@ -537,13 +539,13 @@ EOF
537539

538540
# Escape dangerous characters to prevent command injection
539541
# Using tr to remove control chars, then parameter expansion for safety
540-
local cleaned="${raw//\\/\\\\}" # escape backslashes
541-
cleaned="${cleaned//\"/\\\"}" # escape double quotes
542-
cleaned="${cleaned//\'/\\\'}" # escape single quotes
543-
cleaned="${cleaned//${bt}/\\${bt}}" # escape backticks (using hex var)
544-
cleaned="${cleaned//\$/\\\$}" # escape $ to prevent expansion
545-
cleaned="${cleaned//\(/\\\(}" # escape opening parenthesis
546-
cleaned="${cleaned//\)/\\\)}" # escape closing parenthesis
542+
local cleaned="${raw//\\/\\\\}" # escape backslashes
543+
cleaned="${cleaned//\"/\\\"}" # escape double quotes
544+
cleaned="${cleaned//\'/\\\'}" # escape single quotes
545+
cleaned="${cleaned//${bt}/\\${bt}}" # escape backticks (using hex var)
546+
cleaned="${cleaned//\$/\\\$}" # escape $ to prevent expansion
547+
cleaned="${cleaned//\(/\\\(}" # escape opening parenthesis
548+
cleaned="${cleaned//\)/\\\)}" # escape closing parenthesis
547549

548550
# Strip control characters
549551
cleaned="$(printf '%s' "${cleaned}" | tr -d '[:cntrl:]')"
@@ -633,21 +635,16 @@ EOF
633635
write_log_entry "${log_line}"
634636
}
635637

636-
# =============================================================================
638+
###############################################################################
637639
# trace_run
638-
#==============================
639-
# Runs a script under tracing (set -x), logging each executed command
640-
# to the main log and an optional per-run trace log.
641-
#
642-
# Usage:
643-
# trace_run <script_path> [args...]
644-
#
645-
# Return Values:
646-
# 0 = success
647-
# 1 = invalid arguments
648-
# 2 = script not executable
649-
# 3 = failed permissions on log file
650-
# =============================================================================
640+
#------------------------------------------------------------------------------
641+
# Purpose : Run a script under tracing (set -x), logging each command
642+
# Usage : trace_run <script_path> [args...]
643+
# Arguments:
644+
# $1 : script_path - Path to script to trace
645+
# $@ : args - Optional arguments to pass to script
646+
# Returns : 0 success, 1 invalid args, 2 not executable, 3 log permissions
647+
###############################################################################
651648
function trace_run() {
652649
local target_script shell_type timestamp per_run_log session_info rc
653650
local interpreter first_line
@@ -758,16 +755,13 @@ EOF
758755
return "${rc}"
759756
}
760757

761-
# =============================================================================
758+
###############################################################################
762759
# test_logging_setup
763-
# ------------------
764-
# Test mode to validate that:
765-
# - log file is writable
766-
# - flock is available
767-
# - syslog is working (if enabled)
768-
# - logrotate config exists (if enabled)
769-
# - log entries can be written
770-
# =============================================================================
760+
#------------------------------------------------------------------------------
761+
# Purpose : Validate logging setup (file, flock, syslog, logrotate)
762+
# Usage : test_logging_setup
763+
# Returns : 0 if all tests pass, 1 on failure
764+
###############################################################################
771765
function test_logging_setup() {
772766
local test_message logrotate_file test_line test_random
773767

‎dotfiles/screen.aliases.sh‎

Lines changed: 64 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
#!/usr/bin/env bash
22
set -uo pipefail
3+
IFS=$'\n\t'
34

45
# =============================================================================
56
# NAME : screen.aliases.sh
@@ -30,6 +31,15 @@ if [[ -z "${SCREEN_ALIAS_AH_LOADED:-}" ]]; then
3031
#####
3132
# ------------------------------------------- #
3233

34+
###############################################################################
35+
# screen
36+
#------------------------------------------------------------------------------
37+
# Purpose : Wrapper for GNU screen with logging support
38+
# Usage : screen [-S session_name] [options]
39+
# Arguments:
40+
# -S : session_name - Name for the screen session
41+
# Returns : 0 on success
42+
###############################################################################
3343
function screen() {
3444
# Initialize variables
3545
local session_name=""
@@ -71,6 +81,15 @@ if [[ -z "${SCREEN_ALIAS_AH_LOADED:-}" ]]; then
7181
screen -ls | grep tached | awk '{ print $1 }'
7282
}
7383

84+
###############################################################################
85+
# does_screen_session_exist
86+
#------------------------------------------------------------------------------
87+
# Purpose : Check if a given screen session exists
88+
# Usage : does_screen_session_exist <session_name>
89+
# Arguments:
90+
# $1 : session_name - Name of the screen session to check
91+
# Returns : 0 if session exists, 1 if not found or error
92+
###############################################################################
7493
function does_screen_session_exist() {
7594
# This function checks if a given screen session exists.
7695
# It takes one argument:
@@ -92,6 +111,16 @@ if [[ -z "${SCREEN_ALIAS_AH_LOADED:-}" ]]; then
92111
return 1 # Session does not exist
93112
}
94113

114+
###############################################################################
115+
# exec_cmd_in_screen_session
116+
#------------------------------------------------------------------------------
117+
# Purpose : Execute a command in a specific screen session
118+
# Usage : exec_cmd_in_screen_session <session> <cmd>
119+
# Arguments:
120+
# $1 : session - Name of the screen session
121+
# $2 : cmd - Command to execute
122+
# Returns : 0 on success
123+
###############################################################################
95124
function exec_cmd_in_screen_session() {
96125
# This function executes a command on a given screen session.
97126
# It takes two arguments:
@@ -111,6 +140,15 @@ if [[ -z "${SCREEN_ALIAS_AH_LOADED:-}" ]]; then
111140
fi
112141
}
113142

143+
###############################################################################
144+
# exec_on_all_screen_sessions
145+
#------------------------------------------------------------------------------
146+
# Purpose : Execute a command on all active screen sessions
147+
# Usage : exec_on_all_screen_sessions <cmd>
148+
# Arguments:
149+
# $1 : cmd - Command to execute on all sessions
150+
# Returns : 0 on completion
151+
###############################################################################
114152
function exec_on_all_screen_sessions() {
115153
# This function executes a specified command on all active screen sessions.
116154
# It takes one argument:
@@ -138,7 +176,15 @@ if [[ -z "${SCREEN_ALIAS_AH_LOADED:-}" ]]; then
138176
local window_index=0
139177
local commands=()
140178

141-
# Recursive function to find the leaf processes and capture their commands
179+
###############################################################################
180+
# find_leaves
181+
#------------------------------------------------------------------------------
182+
# Purpose : Recursively find leaf processes and capture their commands
183+
# Usage : find_leaves <pid>
184+
# Arguments:
185+
# $1 : pid - Process ID to start from
186+
# Returns : Populates commands array with leaf process commands
187+
###############################################################################
142188
function find_leaves() {
143189
local p="$1"
144190
local children=()
@@ -183,7 +229,16 @@ if [[ -z "${SCREEN_ALIAS_AH_LOADED:-}" ]]; then
183229
# Export the get_commands function for use in subshells
184230
export -f _get_pid_commands
185231

186-
# Function to truncate a string to a specified maximum length (default: 63)
232+
###############################################################################
233+
# truncate_string
234+
#------------------------------------------------------------------------------
235+
# Purpose : Truncate a string to a specified maximum length
236+
# Usage : truncate_string <string> [max_length]
237+
# Arguments:
238+
# $1 : string - The string to truncate
239+
# $2 : max_length - Maximum length (default: 63)
240+
# Returns : Prints truncated string to stdout
241+
###############################################################################
187242
function truncate_string() {
188243
local str="$1"
189244
local max="${2:-63}"
@@ -196,7 +251,13 @@ if [[ -z "${SCREEN_ALIAS_AH_LOADED:-}" ]]; then
196251
fi
197252
}
198253

199-
# Function to display the current command running in all screen sessions
254+
###############################################################################
255+
# show_all_screen_commands_and_select
256+
#------------------------------------------------------------------------------
257+
# Purpose : Display commands in all screen sessions and allow selection
258+
# Usage : show_all_screen_commands_and_select
259+
# Returns : 0 on success, 1 if no sessions found
260+
###############################################################################
200261
function show_all_screen_commands_and_select() {
201262
# Capture the list of active screen sessions
202263
IFS=$'\n' read -r -d '' -a session_list < <(get_screen_session_list && printf '\0')

‎dotfiles/ssh.aliases.sh‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
#!/usr/bin/env bash
22
set -uo pipefail
3+
IFS=$'\n\t'
34

45
# =============================================================================
56
# NAME : ssh.aliases.sh
@@ -23,6 +24,15 @@ if [[ -z "${SSH_ALIASES_SH_LOADED:-}" ]]; then
2324
return $?
2425
}
2526

27+
###############################################################################
28+
# sshfs_mount
29+
#------------------------------------------------------------------------------
30+
# Purpose : Mount a remote filesystem via SSHFS
31+
# Usage : sshfs_mount <target_system>
32+
# Arguments:
33+
# $1 : target_system - Name of the remote system to mount
34+
# Returns : 0 on success, 1 on failure
35+
###############################################################################
2636
function sshfs_mount() {
2737
local TARGET_SYSTEM="$1"
2838

@@ -68,6 +78,15 @@ if [[ -z "${SSH_ALIASES_SH_LOADED:-}" ]]; then
6878
fi
6979
}
7080

81+
###############################################################################
82+
# sshfs_unmount
83+
#------------------------------------------------------------------------------
84+
# Purpose : Unmount an SSHFS-mounted remote filesystem
85+
# Usage : sshfs_unmount <target_system>
86+
# Arguments:
87+
# $1 : target_system - Name of the remote system to unmount
88+
# Returns : 0 on success, 1 on failure
89+
###############################################################################
7190
function sshfs_unmount() {
7291
local TARGET_SYSTEM="$1"
7392

0 commit comments

Comments
 (0)