Merge 1e00a2a696 into 3690f58d15

README.md

@@ -10,35 +10,40 @@ access to settings and toggling proxies.
 ## Features
 
 - Switch internet proxy settings for various applications and the system.
-- Manage configurations through a `configs.json` file.
-- Command-line interface with commands like `set`, `unset`, and `save`.
-- System tray icon with options to enable and disable proxies, open settings,
-save configurations, or exit the application.
+- Configuration files stored in `configs/` for better organization and flexibility.
+- CLI commands (`set`, `unset`, `save`, `debug`) for managing proxy settings.
+- System tray icon for fast access to all functionality.
 
 ## Installation
 
-You should download the [latest release](https://github.com/Baipyrus/ProxySwitcher/releases)
-archive, **extract all contents** to a dedicated directory and then simply execute
-the [`.\install.ps1`](./install.ps1) script within a Windows Powershell.
+This project offers two installation methods: via PowerShell or manually. In the
+end, you will always be using the [`.\install.ps1`](./install.ps1) script which will
+automatically download the Project if necessary and adds it to `%PATH%`. All contents
+will then be installed to `%LOCALAPPDATA%/Programs` for a user installation.
 
-Alternatively, you could simply run the following command in a Windows PowerShell:
+### PowerShell Installation
+
+Run the following command in Windows PowerShell:
 
 ```powershell
-# Using 'Invoke-RestMethod' and 'Invoke-Expression'
 irm 'https://raw.githubusercontent.com/Baipyrus/ProxySwitcher/main/install.ps1' | iex
 ```
 
+### Manual Installation
+
+1. Download the [latest release](https://github.com/Baipyrus/ProxySwitcher/releases).
+2. Extract the archive to somewhere accessible to your user.
+3. Run the [`.\install.ps1`](./install.ps1) script within a Windows Powershell instance.
+
 ## Usage
 
-Generally, the [Installation](#installation) step will install both the program,
-its assets, and a shortcut for the Windows Startmenu for your current userprofile.
-Additionally, the program will also be added to the user's `%PATH%` Variable and
-will this be executable from within the command-line. However, you will either need
-to navigate into the program directory (`C:\Users\[Username]\AppData\Local\Programs\ProxySwitcher\`)
+First, you will either need to navigate into the program directory (`C:\Users\[Username]\AppData\Local\Programs\ProxySwitcher\`)
 manually or specify a path to any directory containing configuration files using
 the flag `-c, --configs string   configurations path (default "configs/")`.
 To keep it simple, it is still recommended to use the program in system tray or
-directly via code. This latter option will be explained next:
+directly via code.
+
+In case you want to run the code directly:
 
 - Clone the repository:
 
@@ -51,83 +56,87 @@ directly via code. This latter option will be explained next:
 - **set**: Enable all saved proxies including system proxy.
 
     ```powersell
-    # .\ProxySwitcher.exe set
+    # ProxySwitcher.exe set
     go run . set
     ```
 
 - **unset**: Disable all saved proxies including system proxy.
 
     ```powersell
-    # .\ProxySwitcher.exe unset
+    # ProxySwitcher.exe unset
     go run . unset
     ```
 
 - **save**: Saves a new configuration to set a proxy for.
 
     ```powersell
-    # .\ProxySwitcher.exe save
+    # ProxySwitcher.exe save
     go run . save
     ```
 
 - **debug**: Prints all proxy configurations after generating corresponding commands.
 
     ```powersell
-    # .\ProxySwitcher.exe debug
+    # ProxySwitcher.exe debug
     go run . save
     ```
 
 ### Configuration
 
-The programs for which the proxy settings should be managed are stored in [`configs/`](https://github.com/Baipyrus/ProxySwitcher/tree/main/configs),
-wherein you can then create a JSON file per command group. These files can easily
-be modified directly or generated through the `save` command. For examples,
-please take a look at the [default config](https://github.com/Baipyrus/ProxySwitcher/tree/main/configs)
-or at the following block:
+Proxy configurations are organized within the [`configs/`](https://github.com/Baipyrus/ProxySwitcher/tree/main/configs),
+directory, with each JSON file representing a configuration for a specific command
+group. You can modify or add your own configurations in any JSON file in this directory
+directly, or you could use the `save` command in a CLI to save settings for you.
+For examples configurations, please take a look at the [default config](https://github.com/Baipyrus/ProxySwitcher/tree/main/configs).
 
-```js
-[
+#### Structure
+
+Any of these JSON files are used to build commands that the program can run to `set`
+and `unset` the proxy configuration of other programs. The system proxy will be set
+automatically upon calling the respective commands. The actual proxy address and
+port will be automatically detected from your system settings, if available.
+
+Once in one of these JSON files, you will need to create an object (`{}`) with the
+following properties:
+
+```javascript
 {
-        "name": "test1", // Default CMD Name
-        "cmd": "echo 'Hello, World!'", // Optional
+    // Either "name" or "cmd" or both is required:
+    "name": "npm",
+    // Use a custom '$PRSW_ARG' variable to inject 
+    // arguments into "cmd" at given positions:
+    // "cmd": "npm",
+
     "set": [
         {
             "args": [
-                    "http"
-                ], // Optionally empty
-                "type": "text" // Default; Optional
-                "equator": " " // Default; Optional
-            }, // Writes "echo 'Hello, World!' http ", followed
-               // by your system proxy, to a powershell process.
-            {
-                "args": [
-                    "https"
-                ], // Optionally empty
-                "equator": "=" // Optional
-            }  // Writes "echo 'Hello, World!' https=", followed
-               // by your system proxy, to a powershell process.
-        ], // Optional
-        "unset": []
-        // "unset" has the contents as "set" above
-        // and it is also optional.
-    }, {
-        "name": "test2", // Default CMD Name
-        "cmd": "echo '$PRSW_ARG $PRSW_ARG'", // Optional
-        "set": [
-            {
-                "args": [
-                    "https"
-                ], // Optionally empty
-                "type": "variable" // Optional
-            }  // Writes "echo 'https <Your System Proxy>'"
-               // to a powershell process.
-        ] // Optional
+                "config",
+                "set",
+                "proxy"
+            ],
+            // Optionally specify a separator between the
+            // last argument and the injected proxy string:
+            "equator": "=", // Default: " "
+            // Optionally specify a surrounding character
+            // for injected proxy string:
+            "surround": "\"",
+            // Optionally specify the type of command. If
+            // using '$PRSW_ARG' in "cmd", set to "variable".
+            "type": "variable", // Default: "text"
+            // Optionally choose to skip injecting the
+            // proxy string for pre-config commands.
+            "discard": "true" // Default: "false"
+        }
+    ],
+
+    // Use the same structure as "set":
+    "unset" []
 }
-]
 ```
 
 ### System Tray Icon
 
-Right-click the system tray icon to:
+The system tray icon provides a context menu for all commands:
 
 - **Properties**: View and modify system proxy settings.
 - **Enable Proxy**: Enable all saved proxies including system proxy.
@@ -138,8 +147,17 @@ Right-click the system tray icon to:
 ## Building
 
 1. Clone the repository as seen above in [Usage](#usage)
-2. Run the following command:
+2. If running on Windows Subsystem for Linux:
+    - Set environment variables to build for windows:
+
+    ```bash
+    GOOS=windows
+    GOARCH=amd64 
+    ```
+
+3. Run the following command:
 
     ```powershell
-    GOOS=windows GOARCH=amd64 go build -o build/ -v ./...
+    # Remove-Item -Recurse -Force -ErrorAction SilentlyContinue build/
+    go build -o build/ -v ./...
     ```