|
| 1 | +# Usage Guide |
| 2 | + |
| 3 | +## Command Line Usage |
| 4 | + |
| 5 | +### Basic Usage |
| 6 | + |
| 7 | +Convert a single file: |
| 8 | + |
| 9 | +```bash |
| 10 | +uwotm8 example.txt |
| 11 | +``` |
| 12 | + |
| 13 | +Convert multiple files: |
| 14 | + |
| 15 | +```bash |
| 16 | +uwotm8 file1.txt file2.md file3.py |
| 17 | +``` |
| 18 | + |
| 19 | +Process an entire directory: |
| 20 | + |
| 21 | +```bash |
| 22 | +uwotm8 ./my_project/ |
| 23 | +``` |
| 24 | + |
| 25 | +Read from stdin and write to stdout: |
| 26 | + |
| 27 | +```bash |
| 28 | +echo "I love the color gray and my favorite food is filet mignon." | uwotm8 |
| 29 | +# Output: "I love the colour grey and my favourite food is filet mignon." |
| 30 | +``` |
| 31 | + |
| 32 | +### Command Line Options |
| 33 | + |
| 34 | +``` |
| 35 | +usage: uwotm8 [-h] [--check] [--strict] [--include INCLUDE [INCLUDE ...]] [--exclude EXCLUDE [EXCLUDE ...]] [-o OUTPUT] [--version] [src ...] |
| 36 | +
|
| 37 | +Convert American English spelling to British English spelling. |
| 38 | +
|
| 39 | +positional arguments: |
| 40 | + src Files or directories to convert. If not provided, reads from stdin. |
| 41 | +
|
| 42 | +options: |
| 43 | + -h, --help show this help message and exit |
| 44 | + --check Don't write the files back, just return status. Return code 0 means nothing would change. Return code 1 means some files would be reformatted. |
| 45 | + --strict Raise an exception if a word cannot be converted. |
| 46 | + --include INCLUDE [INCLUDE ...] |
| 47 | + File extensions to include when processing directories. Default: .py .txt .md |
| 48 | + --exclude EXCLUDE [EXCLUDE ...] |
| 49 | + Paths to exclude when processing directories. |
| 50 | + -o OUTPUT, --output OUTPUT |
| 51 | + Output file (when processing a single file). If not provided, content is written back to source file. |
| 52 | + --version show program's version number and exit |
| 53 | +``` |
| 54 | + |
| 55 | +### Examples |
| 56 | + |
| 57 | +Check which files would be changed without modifying them: |
| 58 | + |
| 59 | +```bash |
| 60 | +uwotm8 --check myproject/ |
| 61 | +``` |
| 62 | + |
| 63 | +Convert a file and write the output to a different file: |
| 64 | + |
| 65 | +```bash |
| 66 | +uwotm8 american.txt -o british.txt |
| 67 | +``` |
| 68 | + |
| 69 | +Only convert specific file types in a directory: |
| 70 | + |
| 71 | +```bash |
| 72 | +uwotm8 myproject/ --include .md .rst |
| 73 | +``` |
| 74 | + |
| 75 | +Exclude specific paths: |
| 76 | + |
| 77 | +```bash |
| 78 | +uwotm8 myproject/ --exclude myproject/vendor/ myproject/generated/ |
| 79 | +``` |
| 80 | + |
| 81 | +## Python API Usage |
| 82 | + |
| 83 | +For more fine-grained control, you can use the Python API: |
| 84 | + |
| 85 | +### Convert a String |
| 86 | + |
| 87 | +```python |
| 88 | +from uwotm8 import convert_american_to_british_spelling |
| 89 | + |
| 90 | +# Basic usage |
| 91 | +text = "The color of the theater is gray." |
| 92 | +result = convert_american_to_british_spelling(text) |
| 93 | +print(result) # "The colour of the theatre is grey." |
| 94 | + |
| 95 | +# With strict mode |
| 96 | +try: |
| 97 | + result = convert_american_to_british_spelling(text, strict=True) |
| 98 | +except Exception as e: |
| 99 | + print(f"Conversion error: {e}") |
| 100 | +``` |
| 101 | + |
| 102 | +### Convert a File |
| 103 | + |
| 104 | +```python |
| 105 | +from uwotm8 import convert_file |
| 106 | + |
| 107 | +# Convert a file in-place |
| 108 | +convert_file("document.txt") |
| 109 | + |
| 110 | +# Convert a file and write to a new file |
| 111 | +convert_file("document.txt", "document_gb.txt") |
| 112 | + |
| 113 | +# Check if changes would be made without modifying the file |
| 114 | +would_change = convert_file("document.txt", check=True) |
| 115 | +if would_change: |
| 116 | + print("File would be modified") |
| 117 | +else: |
| 118 | + print("No changes needed") |
| 119 | +``` |
| 120 | + |
| 121 | +### Process Multiple Files |
| 122 | + |
| 123 | +```python |
| 124 | +from uwotm8 import process_paths |
| 125 | + |
| 126 | +# Process multiple files and directories |
| 127 | +total, modified = process_paths(["file1.txt", "directory/"]) |
| 128 | +print(f"Processed {total} files, modified {modified}") |
| 129 | + |
| 130 | +# Check mode |
| 131 | +total, modified = process_paths(["file1.txt", "directory/"], check=True) |
| 132 | +print(f"Would modify {modified} of {total} files") |
| 133 | +``` |
| 134 | + |
| 135 | +### Stream Processing |
| 136 | + |
| 137 | +```python |
| 138 | +from uwotm8 import convert_stream |
| 139 | + |
| 140 | +# Process a stream of lines |
| 141 | +with open("input.txt", "r") as f: |
| 142 | + for converted_line in convert_stream(f): |
| 143 | + print(converted_line, end="") |
| 144 | +``` |
| 145 | + |
| 146 | +## Special Cases and Context Handling |
| 147 | + |
| 148 | +uwotm8 includes intelligent handling of various text contexts: |
| 149 | + |
| 150 | +### Hyphenated Terms |
| 151 | + |
| 152 | +Words that are part of hyphenated terms are preserved in their original form. For example: |
| 153 | + |
| 154 | +```bash |
| 155 | +echo "The colors are red and blue, but a 3-color system is used." | uwotm8 |
| 156 | +# Output: "The colours are red and blue, but a 3-color system is used." |
| 157 | +``` |
| 158 | + |
| 159 | +This is useful for preserving technical terminology and compound adjectives where conversion might be inappropriate. |
| 160 | + |
| 161 | +### Code Blocks |
| 162 | + |
| 163 | +Words within code blocks (surrounded by backticks) are not converted: |
| 164 | + |
| 165 | +```bash |
| 166 | +echo "The `setColor(color)` function sets the color." | uwotm8 |
| 167 | +# Output: "The `setColor(color)` function sets the colour." |
| 168 | +``` |
| 169 | + |
| 170 | +### URLs and URIs |
| 171 | + |
| 172 | +Words that appear in lines containing URLs or URIs are not converted: |
| 173 | + |
| 174 | +```bash |
| 175 | +echo "Visit http://example.com/color-picker to select a color." | uwotm8 |
| 176 | +# Output: "Visit http://example.com/color-picker to select a colour." |
| 177 | +``` |
| 178 | + |
| 179 | +### Technical Terms Blacklist |
| 180 | + |
| 181 | +A blacklist of technical terms that shouldn't be converted is maintained: |
| 182 | + |
| 183 | +```bash |
| 184 | +echo "This program uses an analog signal processor." | uwotm8 |
| 185 | +# Output: "This program uses an analog signal processor." |
| 186 | +``` |
| 187 | + |
| 188 | +Common blacklisted terms include: |
| 189 | + |
| 190 | +- "program" (vs "programme") in computing contexts |
| 191 | +- "disk" (vs "disc") in computing contexts |
| 192 | +- "analog" (vs "analogue") in technical contexts |
| 193 | +- "filet" (vs "fillet") in culinary contexts |
0 commit comments