Skip to content

Java library for generating random, human-readable word slugs (e.g., happy-little-cat). Uses 600+ curated words and can produce ~30 million unique 3-word combinations with the default options.

License

MIT, MIT licenses found

Licenses found

MIT
LICENSE.md
MIT
ORIGINAL_WORK_LICENSE.md
Notifications You must be signed in to change notification settings

XavierCanadas/random-word-slugs-java

Repository files navigation

Random Word Slug Generator - Java

Run Tests

A Java library for generating random, human-readable word combinations with customizable formatting and category filtering. Perfect for creating unique identifiers, usernames, project names, or any scenario requiring memorable random text.

Description

Random Word Slugs generates combinations like "happy-little-cat", "braveBlueElephant", or "Clever Fast Robot" by intelligently combining adjectives and nouns from a curated database of over 600 words across 25+ categories. With the default configuration it can produce almost 30 million unique combinations.

Features

  • 🎲 Random Generation - Generate memorable word combinations
  • πŸ“ Multiple Formats - kebab-case, camelCase, Title Case, lower case, Sentence case
  • 🏷️ Category Filtering - Filter by animals, colors, professions, technology, and more
  • 🎯 Flexible Patterns - Customize word order and parts of speech
  • πŸ“Š Combinatorics - Calculate total possible unique combinations

Installation

Using JitPack

Add the JitPack repository and dependency to your build.gradle.kts:

repositories {
    mavenCentral()
    maven { url = uri("https://jitpack.io") }
}

dependencies {
    implementation("com.github.XavierCanadas:random-word-slugs-java:v1.0.1")
}

Or if using Gradle Groovy (build.gradle):

repositories {
    mavenCentral()
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.XavierCanadas:random-word-slugs-java:v1.0.1'
}

For Maven (pom.xml):

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
<dependency>
    <groupId>com.github.XavierCanadas</groupId>
    <artifactId>random-word-slugs-java</artifactId>
    <version>v1.0.1</version>
</dependency>
</dependencies>

Usage

Basic Usage

import com.github.xaviercanadas.randomwordslugs.generator.SlugGenerator;

public class Main {
    public static void main(String[] args) {
        SlugGenerator generator = new SlugGenerator();

        // Generate with defaults (3 words, adjective-adjective-noun, kebab-case)
        String slug = generator.generate();
        System.out.println(slug);
        // Output: "happy-little-cat"
    }
}

Specify Number of Words

SlugGenerator generator = new SlugGenerator();

String slug2 = generator.generate(2);  // "happy-cat"
String slug4 = generator.generate(4);  // "brave-big-blue-elephant"
String slug5 = generator.generate(5);  // "clever-fast-red-funny-robot"

Custom Formatting

import com.github.xaviercanadas.randomwordslugs.model.Case;
import com.github.xaviercanadas.randomwordslugs.generator.SlugOptions;

SlugGenerator generator = new SlugGenerator();

// camelCase
SlugOptions camelOptions = SlugOptions.builder()
        .format(Case.CAMEL)
        .build();
String camelSlug = generator.generate(3, camelOptions);
// Output: "happyLittleCat"

// Title Case
SlugOptions titleOptions = SlugOptions.builder()
        .format(Case.TITLE)
        .build();
String titleSlug = generator.generate(3, titleOptions);
// Output: "Happy Little Cat"

// Sentence case
SlugOptions sentenceOptions = SlugOptions.builder()
        .format(Case.SENTENCE)
        .build();
String sentenceSlug = generator.generate(3, sentenceOptions);
// Output: "Happy little cat"

// lower case
SlugOptions lowerOptions = SlugOptions.builder()
        .format(Case.LOWER)
        .build();
String lowerSlug = generator.generate(3, lowerOptions);
// Output: "happy little cat"

Category Filtering

import com.github.xaviercanadas.randomwordslugs.model.Category;

SlugGenerator generator = new SlugGenerator();

// Generate animal-themed slugs
SlugOptions animalOptions = SlugOptions.builder()
        .withNounCategories(Category.ANIMALS)
        .withAdjectiveCategories(Category.COLOR, Category.SIZE)
        .build();
String animalSlug = generator.generate(3, animalOptions);
// Output: "blue-big-elephant"

// Technology-themed slugs
SlugOptions techOptions = SlugOptions.builder()
        .withNounCategories(Category.TECHNOLOGY)
        .withAdjectiveCategories(Category.CONDITION)
        .format(Case.CAMEL)
        .build();
String techSlug = generator.generate(3, techOptions);
// Output: "fastPowerfulProcessor"

Available Categories:

  • Nouns: ANIMALS, FOOD, PLACE, PEOPLE, FAMILY, PROFESSION, TECHNOLOGY, TRANSPORTATION, SPORTS, MEDIA, EDUCATION, BUSINESS, HEALTH, RELIGION, SCIENCE, TIME, THING
  • Adjectives: APPEARANCE, PERSONALITY, CONDITION, SIZE, COLOR, SHAPES, QUANTITY, TASTE, TOUCH, SOUNDS, TIME

Custom Word Patterns

import com.github.xaviercanadas.randomwordslugs.model.PartsOfSpeech;

SlugGenerator generator = new SlugGenerator();

// Custom pattern: noun-adjective-noun
SlugOptions customPattern = SlugOptions.builder()
        .partsOfSpeech(PartsOfSpeech.NOUN, PartsOfSpeech.ADJECTIVE, PartsOfSpeech.NOUN)
        .build();
String customSlug = generator.generate(customPattern);
// Output: "cat-happy-dog"

// Another pattern: adjective-adjective-adjective-noun
SlugOptions manyAdjectives = SlugOptions.builder()
        .partsOfSpeech(
                PartsOfSpeech.ADJECTIVE,
                PartsOfSpeech.ADJECTIVE,
                PartsOfSpeech.ADJECTIVE,
                PartsOfSpeech.NOUN
        )
        .build();
String descriptiveSlug = generator.generate(manyAdjectives);
// Output: "brave-clever-fast-robot"

Calculate Possible Combinations

SlugGenerator generator = new SlugGenerator();

// Total possible slugs with default settings
long total = generator.totalUniqueSlugs(3, null);
System.out.println("Total possible 3-word slugs: "+total );

// With category filtering
SlugOptions filtered = SlugOptions.builder()
        .withNounCategories(Category.ANIMALS)
        .withAdjectiveCategories(Category.COLOR)
        .build();
long filteredTotal = generator.totalUniqueSlugs(3, filtered);
System.out.println("Filtered combinations: "+filteredTotal);

Project Structure

random-word-slugs-java/
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ main/
β”‚   β”‚   └── java/com/randomwords/
β”‚   β”‚       β”œβ”€β”€ Main.java                    # Example usage and demos
β”‚   β”‚       β”œβ”€β”€ data/
β”‚   β”‚       β”‚   └── WordDatabase.java        # Word storage (700+ words)
β”‚   β”‚       β”œβ”€β”€ generator/
β”‚   β”‚       β”‚   β”œβ”€β”€ SlugGenerator.java       # Main generator logic
β”‚   β”‚       β”‚   └── SlugOptions.java         # Configuration builder
β”‚   β”‚       β”œβ”€β”€ model/
β”‚   β”‚       β”‚   β”œβ”€β”€ Case.java                # Format types enum
β”‚   β”‚       β”‚   β”œβ”€β”€ Category.java            # Word categories enum
β”‚   β”‚       β”‚   β”œβ”€β”€ PartsOfSpeech.java       # Grammar types enum
β”‚   β”‚       β”‚   └── Word.java                # Word data model
β”‚   β”‚       └── util/
β”‚   β”‚           └── Formatter.java           # Text formatting utilities
β”‚   └── test/
β”‚       └── java/com/randomwords/
β”‚           β”œβ”€β”€ data/
β”‚           β”‚   └── WordDatabaseTest.java
β”‚           β”œβ”€β”€ generator/
β”‚           β”‚   β”œβ”€β”€ SlugGeneratorTest.java
β”‚           β”‚   └── SlugOptionsTest.java
β”‚           β”œβ”€β”€ model/
β”‚           β”‚   └── WordTest.java
β”‚           └── util/
β”‚               └── FormatterTest.java
β”œβ”€β”€ build.gradle.kts                         # Gradle build configuration
β”œβ”€β”€ jitpack.yml                              # JitPack configuration
β”œβ”€β”€ LICENSE                                  # MIT License
└── README.md

Key Components

  • SlugGenerator - Main entry point for generating slugs
  • SlugOptions - Builder pattern for configuring generation options
  • WordDatabase - Contains 300+ nouns and 300+ adjectives across 25+ categories
  • Formatter - Handles text case transformations
  • Word - Immutable data model for words with categories
  • Model Classes - Type-safe enums for categories, formats, and parts of speech

License

This project is licensed under the MIT License - see the LICENSE file for details.

Original Work Attribution

This library is a Java port inspired by the TypeScript random-word-slugs library by Nick Scialli, also licensed under MIT. The original word database and core concept are derived from that project.

Acknowledgments

  • Original Concept: random-word-slugs by Nick Scialli - The TypeScript library that inspired this Java implementation
  • Word Database: Curated word lists adapted from the original project
  • Project Context: Developed as part of a Computer Science final degree project (TFG) at Universitat Pompeu Fabra

Requirements

  • Java: 21 or higher.

About

Java library for generating random, human-readable word slugs (e.g., happy-little-cat). Uses 600+ curated words and can produce ~30 million unique 3-word combinations with the default options.

Topics

Resources

License

MIT, MIT licenses found

Licenses found

MIT
LICENSE.md
MIT
ORIGINAL_WORK_LICENSE.md

Stars

Watchers

Forks

Packages

No packages published

Languages