Merge branch 'pr555'

plugins/battery/README.md

@@ -0,0 +1,64 @@
+# Battery Plugin for Oh My Bash
+
+## Overview
+
+This custom plugin for Oh My Bash enhances your terminal experience by providing functions to monitor and display battery status and information.
+
+## Functions
+
+### 1. `ac_adapter_connected`
+
+- **Description:** Checks if the AC adapter is currently connected.
+- **Returns:**
+  - `0` if the adapter is connected.
+  - Non-zero exit status otherwise.
+
+### 2. `ac_adapter_disconnected`
+
+- **Description:** Checks if the AC adapter is currently disconnected.
+- **Returns:**
+  - `0` if the adapter is disconnected.
+  - Non-zero exit status otherwise.
+
+### 3. `battery_percentage`
+
+- **Description:** Retrieves and displays the current battery charge as a percentage of full (100%).
+- **Standard Output:**
+  - Battery percentage as an integer.
+
+### 4. `battery_charge`
+
+- **Description:** Presents a graphical representation of the battery charge using ASCII characters.
+- **Stanard Output:**
+  - Graphical representation of the battery charge.
+
+## Usage
+
+Add the plugin name `battery` in the `plugins` array in `~/.bashrc`.
+
+```shell
+# bashrc
+
+plugins=(... battery)
+```
+
+You can use the functions from the interactive settings with Oh My Bash.
+
+_⚠️ if you want to add only the plugin and not Oh My Bash, you can copy the file
+`battery.plugin.sh` and `lib/utils.sh` to a place you like and source them in
+`~/.basrhc` (for interactive uses) or in a shell script (for a standalone shell
+program).  You may instead copy and paste the functions directly into a script
+file, in which case the plugin will not receive updates and possible errors
+will have to be solved by you_
+
+## Dependencies
+
+This plugin relies on several utilities for retrieving battery information:
+
+- `upower`: Primary tool for battery information retrieval.
+- `acpi`, `pmset`, `ioreg`, `WMIC`: Fallback options for battery information retrieval.
+- `/sys/class/power_supply/`: Fallback option for battery information retrieval.
+
+This plugin file also depends on the following module in Oh My Bash:
+
+- `lib/utils.sh`

plugins/progress/README.md

@@ -0,0 +1,62 @@
+# Using the Progress Bar Script
+
+## Description
+
+This script provides a simple progress bar TUI for the terminal platform. It allows you to visualize the progress of a task being executed in your shell script.
+
+## Usage
+
+You can use the function `progress` from the interactive settings with Oh My
+Bash.  The function handles printing of the progress bar.
+
+1. **Enable plugin:**
+
+  - Add the plugin name `progress` in the `plugins` array in `~/.bashrc`.
+
+  ```shell
+  # bashrc
+
+  plugins=(... progress)
+  ```
+
+2. **Invoke `progress` Function:**
+   - Within a shell function, call the `progress` function whenever you want to display the progress bar.
+   - Pass two parameters to the `progress` function:
+     - `PARAM_PROGRESS`: The progress percentage (0-100) of the task.
+     - `PARAM_STATUS`: Optional. A status message to display alongside the progress bar.
+
+   ```bash
+   # Example usage:
+   progress 25 "Processing data..."  # Displays a 25% progress bar with the status "Processing data..."
+   ```
+
+To change the delay of the progress bar, please overwrite the `delay` function.
+
+```bash
+# Example: change the delay to 0.1 sec
+function delay { sleep 0.1; }
+```
+
+_⚠️ if you want to add only the plugin and not Oh My Bash, you can copy the file
+`progress.plugin.sh` to a place you like and source it in `~/.basrhc` (for
+interactive uses) or in a shell script (for a standalone shell program).  You
+may instead copy and paste the functions directly into a script file, in which
+case the plugin will not receive updates and possible errors will have to be
+solved by you_
+
+
+## Example
+
+```bash
+# bashrc
+
+function example {
+  # Example: Your code for the shell function here:  Invoke the progress
+  # function to display the progress bar as your function progresses.  This
+  # displays a 25% progress bar with the status "Processing data...":
+  progress 25 "Processing data..."
+```
+
+This will visually represent the progress of your function's execution in the
+terminal. Adjust the `progress` function calls according to the progress of
+your task.

plugins/xterm/README.md

@@ -1,3 +1,54 @@
-# Xterm plugin
+# Xterm Plugin
 
-This plugin sets the xterm title for the current directory and the currently running command.
+## Description
+
+This script automatically sets your xterm title with host and location information. It dynamically updates the title to reflect the current user, host, directory, and command being executed.
+
+## Source
+
+You can find the original source of this script [here](https://github.com/Bash-it/bash-it/blob/bf2034d13d/plugins/available/xterm.plugin.bash).
+
+## Variables
+
+- `PROMPT_CHAR` (optional): This variable is shared with powerline.
+- `OMB_PLUGIN_XTERM_SHORT_TERM_LINE` (optional): Controls whether to shorten the directory name in the title.
+- `OMB_PLUGIN_XTERM_SHORT_USER` (optional): Overrides the default user name.
+- `OMB_PLUGIN_XTERM_SHORT_HOSTNAME` (optional): Overrides the default hostname.
+
+## Functions
+
+1. **`set_xterm_title`**
+   - Sets the xterm title with the provided string.
+
+## Usage
+
+1. **Enable plugin:**
+
+  - Add the plugin name `xterm` in the `plugins` array in `~/.bashrc`.
+
+  ```shell
+  # bashrc
+
+  plugins=(... xterm)
+  ```
+
+2. **Customization:**
+
+  - Modify the variables and functions as needed to fit your preferences.
+
+The xterm title will be automatically updated based on your commands and directory changes.
+
+_⚠️ if you want to add only this plugin and not Oh My Bash, you can copy the
+file `xterm.plugin.bash` in a place you like and edit the file to comment out
+the line `_omb_module_require plugin:bash-preexec`.  Then, source
+`xterm.plugin.bash` in `~/.basrhc` (for interactive uses) or in a shell script
+(for a standalone shell program).  To make the xterm title be automatically
+updated, you also need to get a copy of `bash-preexec.sh` (a not up-to-date one
+is found in the repository of Oh My Bash at `tools/bash-preexec.sh`) and source
+it as well.  You may instead copy and paste the functions directly into a
+script file, in which case the plugin will not receive updates and possible
+errors will have to be solved by you_
+
+## Dependencies
+
+This plugin relies on `bash-preexec.sh` for the preexec and precmd hooks.