Skip to content

Commit

Permalink
1.5.0
Browse files Browse the repository at this point in the history
  • Loading branch information
@Bill-Stewart
Bill-Stewart committed Jun 17, 2021
1 parent 592798e commit 3c74458
Show file tree
Hide file tree
Showing 11 changed files with 1,107 additions and 1,078 deletions.
145 changes: 75 additions & 70 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,34 +1,56 @@
# editenv - Written by Bill Stewart (bstewart at iname.com)
# editenv

This is free software and comes with ABSOLUTELY NO WARRANTY.
# Author

## SYNOPSIS
Bill Stewart - bstewart at iname.com

**editenv** is a Windows console program that lets you interactively edit the value
of an environment variable.
# License

## USAGE
**editenv** is covered by the GNU Public License (GPL). See the file `LICENSE` for details.

## Synopsis

**editenv** is a Windows console program that lets you interactively edit the value of an environment variable.

## Usage

**editenv** [_parameter_ [...]] _variablename_

| Parameter | Abbrev. | Description
| -------------------------- | ----------- | ------------------------------------------------
| **--allowedchars=**... | **-a** ... | Only allows input of specified characters
| **--beginningofline** | **-b** | Starts cursor at beginning of line
| **--disallowchars=**... | **-D** ... | Disallows input of specified characters
| **--disallowquotes** | **-d** | Disallows input of `"` character
| **--emptyinputallowed** | **-e** | Empty input is allowed to remove variable
| **--help** | **-h** | Displays usage information
| **--limitlength=**_n_ | **-l** _n_ | Limits length of typed input to _n_ character(s)
| **--maskinput**[**=**_x_] | **-m** _x_ | Masks input using character _x_ (default=`*`)
| **--overtypemode** | **-o** | Starts line editor in overtype mode
| **--prompt=**... | **-p** ... | Specifies an input prompt
| **--quiet** | **-q** | Suppresses error messages
| **--timeout=**_n_ | **-t** _n_ | Automatically enter input after _n_ second(s)

Parameter names are case-sensitive.

## LINE EDITOR
| Parameter | Abbrev. | Description
| ------------------------- | ---------- | ---------------------------------------------
| **--allowedchars=**... | **-a** ... | Only allows input of specified characters
| **--beginningofline** | **-b** | Starts cursor at beginning of line
| **--disallowchars=**... | **-D** ... | Disallows input of specified characters
| **--disallowquotes** | **-d** | Disallows input of `"` character
| **--emptyinputallowed** | **-e** | Empty input is allowed to remove variable
| **--help** | **-h** | Displays usage information
| **--minlength=**_n_ | **-n** _n_ | Input must be at least _n_ character(s)
| **--maxlength=**_n_ | **-x** _n_ | Input cannot be longer than _n_ character(s)
| **--maskinput**[**=**_x_] | **-m** _x_ | Masks input using character _x_ (default=`*`)
| **--overtypemode** | **-o** | Starts line editor in overtype mode
| **--prompt=**... | **-p** ... | Specifies an input prompt
| **--quiet** | **-q** | Suppresses error messages
| **--timeout=**_n_ | **-t** _n_ | Automatically enter input after _n_ second(s)

### Remarks

* _variablename_ specifies the name of the environment variable you want to edit.

* Parameter names are case-sensitive.

* If the environment variable name or an argument to one of the above parameters contains spaces, enclose it in double quote (`"`) characters.

* The **--maskinput** (**-m**) parameter supports an optional argument (character to use for masking). The full parameter name (**--maskinput**) does not require the mask character, but the abbreviated parameter name (**-m**) requires you to specify a character (that is, `--maskinput` and `-m *` are equivalent). If you want to specify a space for the mask character, specify `--maskinput=" "` or `-m " "`.

* If you specify both **--minlength** (**-n**) and **--maxlength** (**-x**), the minimum length must be smaller than the maximum length.

* You cannot specify the **--minlength** (**-n**) parameter with either the **--emptyinputallowed** (**-e**) or **--timeout** (**-t**) parameters.

* An argument of `0` for **--maxlength** (**-x**) means "no maximum length" (up to maximum allowed length: See **Notes/Limitations** section, below).

* It is recommended to specify parameters at the beginning of the command line (in any order) and the environment variable name at the end of the command line.

## Line Editor

The line editor supports the following keystroke commands:

Expand All @@ -48,61 +70,52 @@ The line editor supports the following keystroke commands:
| `Ctrl+C` | Cancel input
| `Enter` or `Ctrl+M` | Enter input

## EXIT CODES
### Remarks

The `Enter` key does nothing if you use the **--minlength** (**-n**) parameter and the length of the input string is fewer than the number of characters specified by the parameter. (You may want to indicate this in the input prompt.)

| Description | Exit Code
| --------------------------------------------------------- | ---------
| No error | 0
| Empty input and **--emptyinputallowed** not specified | 13
| Command line contains an error | 87
| Environment variable name or value are too long | 122
| Cannot use **--maskinput** parameter when variable exists | 183
| Current and parent process must both be 32-bit or 64-bit | 216
| **--timeout** period elapsed | 258
| `Ctrl+C` pressed to cancel input | 1223
## Exit Codes

* In cmd.exe, you can check the exit code using the `%ERRORLEVEL%` variable or
the `if errorlevel` command.
| Description | Exit Code
| ------------------------------------------------------------------ | ---------
| No error | 0
| Empty input and **--emptyinputallowed** (**-e**) not specified | 13
| Command line contains an error | 87
| Environment variable name or value are too long | 122
| Cannot use **--maskinput** (**-m**) parameter when variable exists | 183
| Current and parent process must both be 32-bit or 64-bit | 216
| **--timeout** (**-t**) period elapsed | 258
| `Ctrl+C` pressed to cancel input | 1223

* In PowerShell, you can check the exit code using the `$LASTEXITCODE`
variable.
### Remarks

## LIMITATIONS
* In cmd.exe, you can check the exit code using the `%ERRORLEVEL%` variable or the `if errorlevel` command.

* In PowerShell, you can check the exit code using the `$LASTEXITCODE` variable.

## Notes/Limitations

* The environment variable's name cannot contain the `=` character.

* The environment variable's name is limited to 127 characters.

* The environment variable's value is limited to 16383 characters.

* The `--timeout` parameter does not use a high-precision timer.
* The **--timeout** (**-t**) parameter does not use a high-precision timer.

* The `--maskinput` parameter is not encrypted or secure.
* The **--maskinput** (**-m**) parameter is not encrypted or secure.

* There is no visual indication of insert vs. overtype mode.

* **editenv** does not work from the PowerShell ISE.

## VERSION HISTORY

1.1.0.0 (2020-07-13)

* Build using FPC 3.2.0.

* Minor documentation corrections.

1.0.0.0 (2020-03-17)

* Initial version.

## EXAMPLES
## Examples

1. Edit the `Path` environment variable for the current console:

editenv Path

When you enter this command, `editenv` lets you interactively edit the
`Path` environment variable for the current console process.
When you enter this command, `editenv` lets you interactively edit the `Path` environment variable for the current console process.

2. cmd.exe shell script (batch file):

Expand All @@ -124,32 +137,27 @@ The line editor supports the following keystroke commands:
:DONE
endlocal

This script prompts you to enter your name and uses the value of the
`%USERNAME%` environment variable as the initial value. If you press
`Ctrl+C`, the script outputs "You canceled". If you pressed `Enter` on an
empty input line, the script outputs "You didn't enter your name" and
repeats the prompt.
This script prompts you to enter your name and uses the value of the `%USERNAME%` environment variable as the initial value. If you press `Ctrl+C`, the script outputs "You canceled". If you pressed `Enter` on an empty input line, the script outputs "You didn't enter your name" and repeats the prompt.

3. cmd.exe shell script:

@echo off
setlocal enableextensions
:REPEAT
set _PIN=
editenv --allowedchars=0123456789 --limitlength=8 --maskinput --prompt="PIN: " --quiet _PIN
editenv --allowedchars=0123456789 --minlength=4 --maxlength=8 --maskinput --prompt="Enter PIN (4-8 digits): " --quiet _PIN
if %ERRORLEVEL% EQU 1223 goto :REPEAT
if %ERRORLEVEL% EQU 13 goto :REPEAT
echo You entered: %_PIN%
endlocal

This script prompts you to enter up to an 8-digit number. Pressing `Ctrl+C`
or pressing `Enter` without entering a value repeats the prompt.
This script prompts you to enter a number from 4 to 8 digits long. Pressing `Ctrl+C` without entering a value repeats the prompt. (The `Enter` key does nothing if the input line has fewer than 4 characters because the command line specifies `--minlength=4`.)

4. PowerShell script:

$env:_ANS = "N"
do {
editenv --prompt="Are you sure? [Y/N] " --allowedchars=NnYy --beginningofline --limitlength=1 --overtype --quiet --timeout=20 _ANS
editenv --prompt="Are you sure? [Y/N] " --allowedchars=NnYy --beginningofline --maxlength=1 --overtype --quiet --timeout=20 _ANS
} until ( $LASTEXITCODE -ne 13 )
if ( $LASTEXITCODE -ne 1223 ) {
if ( $env:_ANS -eq "Y" ) {
Expand All @@ -161,7 +169,4 @@ The line editor supports the following keystroke commands:
}
$env:_ANS = $null

This script presents a timed prompt to enter a `Y` or `N` answer. If you
don't enter anything within 20 seconds, `N` is assumed. Otherwise, you can
enter a `Y` or `N` response. If you enter empty input, the prompt repeats.
Pressing `Ctrl+C` skips the output statements.
This script presents a timed prompt to enter a `Y` or `N` answer. If you don't enter anything within 20 seconds, `N` is assumed. Otherwise, you can enter a `Y` or `N` response. If you enter empty input, the prompt repeats. Pressing `Ctrl+C` skips the output statements.
Loading

0 comments on commit 3c74458

Please sign in to comment.