How to use the command 'alex' (with examples)

The ‘alex’ command serves as a powerful tool designed to identify and flag potentially insensitive or inconsiderate language within text. This includes phrasing that may be gender-biased, racially insensitive, religiously inconsiderate, or otherwise exclusive. By using ‘alex’, writers can ensure that their content is inclusive and respectful to all audiences. This open-source tool, available on GitHub, is ideal for those who wish to avoid unequal phrasing and strive for expression clarity and inclusivity.

Use case 1: Analyze text from stdin

Code:

echo "His network looks good" | alex --stdin

Motivation:

There are scenarios when you may want to analyze a specific line or paragraph of text quickly without saving it into a file. This is where stdin comes in handy. For example, when you’re writing or editing content and want to check for inclusivity and sensitivity on-the-fly, using the command line directly can save time and increase productivity by immediately highlighting any potential issues in your phrasing.

Explanation:

• echo "His network looks good": This part of the command sends the string “His network looks good” to the standard input. The echo command is used to display a line of text, which, in this context, serves as input for the alex command.
• |: This is a pipe operator, which takes the output from the command on its left, echo, and uses it as input to the command on its right, alex.
• alex --stdin: The --stdin argument tells alex to expect input from the standard input stream rather than from a file or set of files. This is particularly useful for quick checks.

Example output:

   1: `"His"` may be insensitive, use `Their`, `Theirs` instead

This output immediately points out the potential insensitivity in using a gender-specific pronoun and suggests more inclusive alternatives.

Use case 2: Analyze all files in the current directory

Code:

alex

Motivation:

When working on a project involving multiple text files, it can be crucial to ensure that all documentation is free of biased or exclusionary language. By checking all files in the current directory at once, you can maintain consistency and sensitivity across your entire project without needing to manually check each file individually.

Explanation:

• alex: Running this command without any additional arguments tells alex to analyze all appropriate files (typically text or Markdown files) in the current directory. It does a bulk scan that saves time and ensures comprehensive coverage.

Example output:

path/to/first-file.md
   5: `"Master"` may be insensitive, use `Primary`, `Main` instead

path/to/second-file.md
  12: `"Blacklist"` may be insensitive, use `Blocklist`, `Denylist` instead

This output shows the file paths, line numbers, flagged words, and suggested alternatives.

Use case 3: Analyze a specific file

Code:

alex path/to/file.md

Motivation:

Sometimes, you might only need to analyze a single file, perhaps the one you are currently editing or suspect might contain insensitive language. This use case is ideal when you want to focus efforts on a specific document without sifting through all files in a directory, making it an efficient choice during the editing process.

Explanation:

• alex path/to/file.md: Here, path/to/file.md specifies the path to the specific file the user wishes to analyze. This tells alex to limit its parsing and checking operations strictly to the mentioned file, thus providing concise feedback targeted where it’s needed most.

Example output:

path/to/file.md
   3: `"Guys"` may be insensitive, use `Folks`, `People` instead

This example output highlights words that could be seen as less inclusive and proposes more neutral options.

Use case 4: Analyze all Markdown files except example.md

Code:

alex *.md !example.md

Motivation:

In a situation where a workspace contains numerous Markdown files, you may want to exclude certain files from being analyzed. For instance, if example.md is a template or an archived document that doesn’t require scrutiny, you might wish to exclude it from the batch of files being checked. This functionality allows for selective targeting of files, enhancing efficiency and precision in code analysis.

Explanation:

• alex *.md: The *.md part signifies that alex should analyze all files in the directory with a .md extension, which typically denotes Markdown files. This ensures that all content within Markdown documents is checked for sensitive language.
• !example.md: The exclamation mark ! followed by a file name indicates that alex should exclude this specific file from its analysis. This command line pattern modification permits tailored scans, focusing on relevant content while disregarding predefined exceptions.

Example output:

path/to/another-file.md
   7: `"Whitelisted"` may be insensitive, use `Allowed`, `Permitted` instead

This output indicates analyses done for markdown files other than example.md.

Conclusion:

The ‘alex’ command is a versatile and robust tool designed to promote inclusivity and sensitivity in written works. Through its various use cases, users can analyze sections of text quickly, scrutinize multiple files in a directory, focus on specific documents, or apply these checks selectively across file types. Implementing these practices can help writers ensure that their content is considerate, inclusive, and free of bias, strengthening their message and widening their audience reach.