0
# Command Line Interface
1

2
Complete command-line tool for generating word clouds directly from text files with comprehensive parameter control, input/output redirection support, and all WordCloud customization options.
3

4
## Capabilities
5

6
### Main CLI Entry Point
7

8
Primary function for executing word cloud generation from command line with parsed arguments.
9

10
```python { .api }
11
def main(args, text, imagefile):
12
    """
13
    Generate word cloud from command line arguments.
14

15
    Creates WordCloud instance with provided arguments, generates word cloud from text,
16
    and saves result to specified image file.
17

18
    Parameters:
19
    - args (dict): Parsed command line arguments as WordCloud parameters
20
    - text (str): Input text for word cloud generation  
21
    - imagefile (file-like): Output file object for PNG image
22

23
    Returns:
24
    - None: Saves word cloud directly to imagefile
25
    """
26
```
27

28
### Argument Parsing
29

30
Comprehensive command line argument parsing with validation and type conversion.
31

32
```python { .api }
33
def make_parser():
34
    """
35
    Create argument parser for wordcloud CLI.
36

37
    Builds ArgumentParser with all available WordCloud parameters as command line options,
38
    including input/output handling, styling options, and text processing controls.
39

40
    Returns:
41
    - argparse.ArgumentParser: Configured argument parser
42
    """
43

44
def parse_args(arguments):
45
    """
46
    Parse and validate command line arguments.
47

48
    Processes command line arguments, validates options, handles file I/O,
49
    and converts arguments to WordCloud-compatible format.
50

51
    Parameters:
52
    - arguments (list): Command line argument list (typically sys.argv[1:])
53

54
    Returns:
55
    - tuple: (args_dict, text_string, output_file) ready for main() function
56

57
    Raises:
58
    - ValueError: For incompatible argument combinations
59
    - ArgumentTypeError: For invalid file paths or regexp patterns
60
    """
61
```
62

63
### Module Entry Point
64

65
Entry point function for `python -m wordcloud` execution.
66

67
```python { .api }
68
def main():
69
    """
70
    Entry point for 'python -m wordcloud' command.
71

72
    Parses sys.argv arguments and calls wordcloud_cli_main with results.
73
    This function is registered as the script entry point in setup.py.
74
    """
75
```
76

77
### Utility Classes
78

79
Helper classes for argument parsing and validation.
80

81
```python { .api }
82
class FileType:
83
    def __init__(self, mode='r', bufsize=-1):
84
        """
85
        Factory for creating file object types with Unicode support.
86
        
87
        Parameters:
88
        - mode (str): File open mode (default: 'r')
89
        - bufsize (int): Buffer size (default: -1)
90
        """
91
        
92
    def __call__(self, string):
93
        """
94
        Convert string to file object, handling stdin/stdout redirection.
95
        
96
        Parameters:
97
        - string (str): File path or '-' for stdin/stdout
98
        
99
        Returns:
100
        - file-like: Opened file object with UTF-8 encoding
101
        """
102

103
class RegExpAction:
104
    def __call__(self, parser, namespace, values, option_string=None):
105
        """
106
        Validate regular expression arguments.
107
        
108
        Parameters:
109
        - parser (ArgumentParser): The argument parser
110
        - namespace (Namespace): Parsed arguments namespace
111
        - values (str): Regular expression string to validate
112
        - option_string (str): Option that triggered this action
113
        
114
        Raises:
115
        - ArgumentError: If regular expression is invalid
116
        """
117
```
118

119
## Command Line Options
120

121
The CLI supports all WordCloud parameters through command line flags:
122

123
### Input/Output Options
124
- `--text FILE`: Input text file (default: stdin)
125
- `--imagefile FILE`: Output PNG file (default: stdout) 
126
- `--stopwords FILE`: Custom stopwords file (one word per line)
127

128
### Appearance Options
129
- `--width WIDTH`: Canvas width in pixels (default: 400)
130
- `--height HEIGHT`: Canvas height in pixels (default: 200)
131
- `--background COLOR`: Background color (default: black)
132
- `--colormap COLORMAP`: Matplotlib colormap name (default: viridis)
133
- `--color COLOR`: Single color for all words
134
- `--fontfile PATH`: Custom font file path
135

136
### Layout Options
137
- `--mask FILE`: Image file to use as shape mask
138
- `--contour_width WIDTH`: Mask contour width (default: 0)
139
- `--contour_color COLOR`: Mask contour color (default: black)
140
- `--prefer_horizontal RATIO`: Horizontal vs vertical placement ratio (default: 0.9)
141
- `--scale SCALE`: Scaling factor (default: 1)
142
- `--margin WIDTH`: Spacing around words (default: 2)
143

144
### Text Processing Options
145
- `--regexp PATTERN`: Custom tokenization regular expression
146
- `--no_collocations`: Disable bigram detection
147
- `--include_numbers`: Include numbers in word cloud
148
- `--min_word_length LENGTH`: Minimum word length (default: 0)
149
- `--no_normalize_plurals`: Disable plural normalization
150

151
### Font and Sizing Options
152
- `--max_words N`: Maximum number of words (default: 200)
153
- `--min_font_size SIZE`: Minimum font size (default: 4)
154
- `--max_font_size SIZE`: Maximum font size
155
- `--font_step STEP`: Font size increment (default: 1)
156
- `--relative_scaling RATIO`: Word frequency scaling (default: 0)
157

158
### Rendering Options
159
- `--mode MODE`: Image mode RGB or RGBA (default: RGB)
160
- `--repeat`: Repeat words until max_words reached
161
- `--random_state SEED`: Random seed for reproducibility
162
- `--colormask FILE`: Reference image for color extraction
163

164
## Usage Examples
165

166
### Basic Usage
167

168
```bash
169
# Generate word cloud from text file
170
wordcloud_cli --text input.txt --imagefile output.png
171

172
# Read from stdin, write to stdout
173
cat document.txt | wordcloud_cli > wordcloud.png
174

175
# Using python -m syntax
176
python -m wordcloud --text input.txt --imagefile output.png
177
```
178

179
### Customization Examples
180

181
```bash
182
# Custom size and colors
183
wordcloud_cli --text input.txt --width 1200 --height 800 \
184
              --background white --colormap plasma --imagefile large.png
185

186
# Using mask for custom shape
187
wordcloud_cli --text input.txt --mask shape.png \
188
              --contour_width 2 --contour_color blue --imagefile shaped.png
189

190
# Single color variation
191
wordcloud_cli --text input.txt --color darkblue --imagefile blue.png
192

193
# Custom font and text processing
194
wordcloud_cli --text input.txt --fontfile /path/to/font.ttf \
195
              --stopwords custom_stops.txt --min_word_length 3 \
196
              --imagefile custom.png
197
```
198

199
### Advanced Options
200

201
```bash
202
# Image-based coloring
203
wordcloud_cli --text input.txt --colormask reference.jpg \
204
              --imagefile colored.png
205

206
# Fine-tuned layout
207
wordcloud_cli --text input.txt --max_words 500 --relative_scaling 0.8 \
208
              --prefer_horizontal 0.7 --scale 2 --imagefile detailed.png
209

210
# Custom tokenization
211
wordcloud_cli --text input.txt --regexp "[a-zA-Z]{4,}" \
212
              --no_collocations --include_numbers --imagefile tokens.png
213

214
# Reproducible generation
215
wordcloud_cli --text input.txt --random_state 42 --imagefile consistent.png
216
```
217

218
### Pipeline Usage
219

220
```bash
221
# Process PDF documents
222
pdftotext document.pdf - | wordcloud_cli --imagefile doc_cloud.png
223

224
# Filter and process
225
grep -E "important|critical|urgent" log.txt | \
226
wordcloud_cli --colormap Reds --imagefile alerts.png
227

228
# Multiple files
229
cat *.txt | wordcloud_cli --max_words 1000 --imagefile combined.png
230
```
231

232
### Configuration Files
233

234
```bash
235
# Using custom stopwords
236
echo -e "said\nwould\ncould\nmight" > mystops.txt
237
wordcloud_cli --text input.txt --stopwords mystops.txt --imagefile filtered.png
238

239
# Batch processing with consistent settings
240
for file in *.txt; do
241
    wordcloud_cli --text "$file" --width 800 --height 600 \
242
                  --colormap viridis --imagefile "${file%.txt}.png"
243
done
244
```
245

246
## Error Handling
247

248
The CLI provides comprehensive error handling for:
249

250
- **File I/O errors**: Invalid input/output paths, permission issues
251
- **Image format errors**: Unsupported mask or colormask formats  
252
- **Regular expression errors**: Invalid tokenization patterns
253
- **Color specification errors**: Invalid color names or codes
254
- **Font loading errors**: Missing or invalid font files
255
- **Argument conflicts**: Incompatible option combinations (e.g., --color with --colormask)
256

257
## Help and Version Information
258

259
```bash
260
# Display help message
261
wordcloud_cli --help
262
python -m wordcloud --help
263

264
# Show version
265
wordcloud_cli --version
266
python -m wordcloud --version
267
```