0
# Yosay
1

2
Yosay creates ASCII art speech bubbles with the Yeoman mascot character for command-line interfaces. Like cowsay but less cow, it provides a JavaScript API and CLI tool for displaying messages in a distinctive, branded format that has become iconic in the JavaScript development ecosystem.
3

4
## Package Information
5

6
- **Package Name**: yosay
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES modules)
9
- **Installation**: `npm install yosay`
10
- **Node.js Version**: >=18
11

12
## Core Imports
13

14
```javascript
15
import yosay from "yosay";
16
```
17

18
For global CLI installation:
19

20
```bash
21
npm install --global yosay
22
```
23

24
## Basic Usage
25

26
```javascript
27
import yosay from "yosay";
28

29
// Simple message
30
console.log(yosay('Hello, world!'));
31

32
// With custom line length
33
console.log(yosay('Hello, world!', { maxLength: 10 }));
34

35
// With ANSI styling (using chalk)
36
import chalk from 'chalk';
37
console.log(yosay(chalk.red('Error: ') + 'Something went wrong!'));
38
```
39

40
## CLI Usage
41

42
```bash
43
# Basic usage
44
$ yosay "Hello, world!"
45

46
# With custom line length
47
$ yosay "Hello, world!" --maxLength 10
48

49
# From stdin
50
$ echo "Hello, world!" | yosay
51
```
52

53
## Capabilities
54

55
### Speech Bubble Generation
56

57
Creates ASCII art speech bubbles with the Yeoman mascot character.
58

59
```javascript { .api }
60
/**
61
 * Creates ASCII art speech bubbles with Yeoman mascot character
62
 * @param message - Text to display in speech bubble (optional, defaults to welcome message)
63
 * @param options - Configuration options (optional)
64
 * @returns String containing ASCII art with Yeoman character and formatted speech bubble
65
 */
66
function yosay(message?: string, options?: YosayOptions): string;
67

68
interface YosayOptions {
69
  /** Maximum line length for word wrapping */
70
  maxLength?: number;
71
}
72
```
73

74
**Features:**
75
- Automatic word wrapping with configurable line length
76
- ANSI styling support with proper escape sequence handling
77
- Fullwidth character support (e.g., Chinese, Japanese characters)
78
- Automatic vertical centering for long messages
79
- Speech bubble overflow handling for very long messages
80
- Default Yeoman mascot greeting when no message provided
81

82
**Usage Examples:**
83

84
```javascript
85
import yosay from "yosay";
86
import chalk from "chalk";
87

88
// Default message
89
console.log(yosay());
90
// Displays: "Welcome to Yeoman, ladies and gentlemen!"
91

92
// Custom message
93
console.log(yosay('Sindre is a horse'));
94

95
// With line length customization
96
console.log(yosay('This is a long message that will wrap', { maxLength: 8 }));
97

98
// With ANSI styling
99
console.log(yosay(chalk.red('Error: ') + chalk.yellow('Build failed!')));
100

101
// Mixed styling across multiple lines
102
console.log(yosay(
103
  chalk.red('Hi') + ' there, sir! ' + 
104
  chalk.bgBlue.white('you are looking') + ' swell today!'
105
));
106

107
// Handling newlines
108
console.log(yosay('first line\nsecond line\n\nfourth line'));
109

110
// Fullwidth characters
111
console.log(yosay('项目可以更新了'));
112
```
113

114
### Command Line Interface
115

116
Command-line interface for yosay functionality.
117

118
```bash { .api }
119
# Usage patterns
120
yosay <string>
121
yosay <string> --maxLength <number>
122
echo <string> | yosay
123

124
# Options
125
--maxLength    Set maximum line length for word wrapping
126
```
127

128
**CLI Examples:**
129

130
```bash
131
# Basic message
132
$ yosay 'Sindre is a horse'
133

134
# Custom line length
135
$ yosay 'Hello world' --maxLength 8
136

137
# From stdin
138
$ echo 'Hello from pipe' | yosay
139

140
# Help
141
$ yosay --help
142
```
143

144
## Architecture
145

146
Yosay is built around several key components:
147

148
- **Message Processing**: Handles ANSI escape sequences and preserves styling during word wrapping
149
- **ASCII Art Rendering**: Uses Unicode box drawing characters for speech bubble frames
150
- **Text Layout Engine**: Manages word wrapping, padding, and vertical alignment
151
- **ANSI Preservation**: Complex algorithm to maintain color and styling across line breaks
152

153
## Types
154

155
```javascript { .api }
156
interface YosayOptions {
157
  /** 
158
   * Maximum line length for word wrapping
159
   * If provided but smaller than the longest word, automatically adjusts to fit
160
   */
161
  maxLength?: number;
162
}
163
```
164

165
## Dependencies
166

167
- **chalk**: Terminal text styling (used internally for Yeoman character colors)
168
- **ansi-regex**: ANSI escape sequence detection  
169
- **ansi-styles**: ANSI styling utilities
170
- **cli-boxes**: Unicode box drawing characters
171
- **meow**: CLI helper (CLI only)
172
- **pad-component**: Text padding utility
173
- **string-width**: String width calculation with Unicode support
174
- **strip-ansi**: Remove ANSI escape sequences
175
- **wrap-ansi**: Word wrapping with ANSI support
176

177
## Error Handling
178

179
The function handles various edge cases gracefully:
180

181
- **Null/undefined message**: Uses default Yeoman welcome message
182
- **Empty string**: Creates empty speech bubble
183
- **Very long words**: Automatically adjusts maxLength to accommodate
184
- **Mixed ANSI sequences**: Preserves styling across line wraps
185
- **Unicode characters**: Proper width calculation for fullwidth characters