US Baby Names — CLI Ranker (bn)

A lightweight Bash utility that reports the popularity rank of a given first name in a specific year using the U.S. Social Security baby‑name dataset (subset included: 1880–1908).

Language: Bash (POSIX shell compatible)
Dataset: us_baby_names/yobYYYY.txt (CSV lines: Name,Gender,Count)
OS: macOS / Linux
Dependencies: GNU grep (ggrep) with PCRE support (-P), coreutils

---

Repository Structure

mahadhsn-us-baby-names/
├── README.md
├── bn                       # main executable (Bash)
└── us_baby_names/           # SSA data subset (1880–1908)
    ├── yob1880.txt
    ├── yob1881.txt
    └── ...

Data format per line:

<name>,<gender>,<count>
Mary,F,7065
John,M,9655

---

Installation

# macOS (Homebrew): ensure GNU grep is available as `ggrep`
brew install grep

# make bn executable
chmod +x bn

If ggrep is not on your PATH after installation, add it:

echo 'export PATH="/opt/homebrew/opt/grep/libexec/gnubin:$PATH"' >> ~/.zshrc
exec zsh -l

The script uses ggrep -P (PCRE). On Linux, grep -P may work; if so, replace ggrep with grep.

---

Usage

bn <year> <assigned gender: f|F|m|M|b|B>
<names>

• year: 4‑digit (e.g., 1901) — must exist in us_baby_names/
• gender: f|F female, m|M male, b|B both
• names: one or more names provided via stdin (interactive or piped)

Examples

Interactive (single name):

$ ./bn 1901 m
John
1901: John ranked 1 out of 1219 male names.

Pipe multiple names:

$ printf "John\nMary\nMahad\n" | ./bn 1888 b
1888: John ranked 1 out of 1015 male names.
1888: Mary ranked 1 out of 793 female names.
1888: Mahad not found among male names.
1888: Mahad not found among female names.

Help & usage:

./bn --help
./bn         # prints usage and exits with code 1

---

Behavior & Output

• For gender = m|M or f|F, prints one line with rank and population size (or "not found").
• For gender = b|B, prints up to two lines: one for male and one for female.
• Ranks are case‑insensitive (-i flag) and match whole tokens using PCRE word boundaries (\bname\b).

---

Exit Codes

• 0 — success
• 1 — invalid number of arguments (also prints usage)
• 2 — badly formatted year or gender
• 3 — badly formatted name (stdin token not alphabetic)
• 4 — no data for the given year

The script validates arguments before reading names from stdin when possible, and validates each name as it’s processed.

---

Implementation Notes

• Ranking logic:
  • Total names per gender computed via ggrep -iP '^.+,G,.+$' | wc -l
  • The rank is the line number of the first match in the gender‑filtered list:
    ggrep -inP "\b<name>\b,G,.+$" | ggrep -oP '^[0-9]+'
  • Uses PCRE for word boundaries and case‑insensitivity.
• Batch mode: Reads stdin line‑by‑line and splits on whitespace, enabling flexible input (one or multiple names per line).
• Portability: Script assumes ggrep (GNU grep) for -P PCRE; macOS’s BSD grep lacks -P.

---

Performance

• Operations are linear in file length; each query filters the year file twice (once per gender when needed).
• For larger datasets (post‑1908), consider pre‑computing maps or using awk to stream once per gender.

---

Testing Ideas

• Happy paths: known top names by year/gender; mixed‑case input.
• Error cases: invalid year (19ab), invalid gender (x), invalid name (John3), missing year file.
• Both‑gender mode: name present in one gender only.

---

Limitations

• Dataset in this repo covers 1880–1908 only. Add more yobYYYY.txt files for later years.
• Names with punctuation/hyphens are treated as invalid (alphabetic only).

---

License

MIT