CHING(1)

📦 version 1.053, in alpine 3.24

💖 CHING(1) 💖 — like, the manual page, but make it make sense

okay bestie, so this is the Perl-shipped man page for ching — yes, that ching — and it's filed under "User Contributed Perl Documentation" on the shelf, which is exactly where you'd expect a several-thousand-year-old oracle to live. no cap. 🧚

✨ NAME ✨

ching — the Book of Changes. that's it. that's the whole name. iconic behavior honestly. 🎀

🌸 SYNOPSIS 🌸

ching [-n] [-r] [-h] [-p program] [hexagram-lines]

like, that's the whole vibe right there. you either give it lines or you don't. 🦋

💜 DESCRIPTION 💜

The I Ching, aka the Book of Changes, is an ancient Chinese oracle that has been in use for centuries — literal centuries, bestie — as a source of wisdom and advice. main character energy since forever. 👑

The text of the oracle (yes, people call it "the text of the oracle", sometimes) is made of sixty-four hexagrams, and each one is symbolized by a particular arrangement of six straight (---) and broken (- -) lines. six lines, two possible states, sixty-four combos. the math is mathing and it's slaying. 🎀

Each hexagram has two major sections, and you do need to know the difference:

  • The Judgement — this one relates specifically to the matter at hand. for example: "It furthers one to have somewhere to go." like it's literally talking about your exact situation. targeted. 🔥
  • The Image — this one describes the general attributes of the hexagram and how they apply to one's own life: "Thus the superior man makes himself strong and untiring." character development, honestly. ✨

🦋 The Lines 🦋

okay so the lines are associated with numeric values ranging from six through nine. here's the vibe check:

  • even values (6 and 8) → broken lines
  • odd values (7 and 9) → solid lines

and now the spicy part: when the value is six or nine, the line is said to be moving, and for any such line there's an appended judgement that becomes significant. lowkey important. also, the moving lines are inherently unstable and change into their opposites — so a second hexagram pops out (and thus an additional judgement). it's giving plot twist. 😭

to build the numeric value of a hexagram you list the digits corresponding to each of the lines, going from the bottom upward. bottom to top, bestie, don't do it backwards. 💅

🔮 Consulting the Oracle 🔮

Normally you consult the oracle by fixing the desired question firmly in mind and then casting a set of changes (lines) using yarrow-stalks or tossed coins. that's the traditional route. the resulting hexagram will be the answer to the question. 🫶

This oracle is a little different and we love her for it: it simply reads a question from the standard input (up to an "EOF", or a period on a line by itself) and hashes the individual characters in combination with the time of day, process ID and the user's user and group IDs. that resulting value is used as the seed of a random number generator which drives a simulated coin-toss divination. then the answer is formatted and written to the standard output. chaos math into ancient wisdom, we stan. 💖

⭐ OPTIONS ⭐

  • -n — causes *ROFF commands to be piped through nroff(1) for output formatting, exactly like in the original BSD implementation. by default the formatting is done by the ching program itself. retro slay. 🎀
  • -r — causes *ROFF formatting commands to be sent to the standard output. honestly you probably won't find this very useful unless you're debugging the -n switch. it's giving dev tools only. 👑
  • -p program — specifies the command to use to display the output. the default is the value of the environment variable CHING_PAGER, or of PAGER, or none if neither environment variable is set. pick your pager, bestie. 💅
  • -h — can be used to display the line values from a divination cast by the computer. so the computer throws the coins, you get the numbers. 🦋

also, for those who wish to remain steadfast in the old traditions, the oracle will also accept the results of a personal divination using yarrow sticks or coins — to do this, cast the change and then type the resulting line values as an argument. old school and valid. 🌸

(and conversely, -h is the reverse trip: computer casts it, you read the values. cute little symmetry, we love to see it. 🫶)

The Perl code is copyright (c) 1995, 1999 Albert Dvornik <bert@genscan.com>.

The hexagram text and ROFF macros are Copyright (c) 1988 The Regents of the University of California. All rights reserved. This product includes software developed by the University of California, Berkeley and its contributors. legal stuff but make it ✨respectful✨.

🌈 About The Hexagram Text Copyright 🌈

okay so in the original BSD version, the macros and the hexagram text resided in separate files from the program source, and neither of these files contained a copyright notice. the author is working under the assumption that they were intended to be covered by the same copyright as the program source, which is the copyright displayed above. if you have reason to believe otherwise, please let him know — he said it, not me. 🙈

Also, please drop him a line if you know of a freely available I Ching text that's not encumbered by the Obnoxious BSD Advertising Clause. (his words! "Obnoxious" with a capital O! we're being so real about licensing right now. 💀)

🍓 SEE ALSO 🍓

  It furthers one to see the great man.

that's the whole section. the man page is being poetic about it and honestly? respect. it furthers one. go see the great man. 🫶

🌸 DIAGNOSTICS 🌸

  Thus the superior man at nightfall
  Goes indoors for rest and recuperation.

error messages but make them ancient wisdom. take a nap, bestie, the superior man literally did. 😭💜

🐛 BUGS 🐛

The program does not support simulated tossing of yarrow stalks as a way of consulting the oracle. coins only, no stalks. do not come for her about the yarrow stalks, she already knows. 💅

🎀 the cute little sign-off 🎀

this page is perl v5.42.2, dated 2026-02-15, and it lives at the top of the page under the name CHING(1) in the User Contributed Perl Documentation section — so like, that's the whole citation, mwah. 💖✨🌸🦋🎀

periodt. go ask the oracle something. 👑

📦 where this page comes from