CAL(1)

💖 NAME 💖

ccal — displays a calendar. That's it, that's the whole vibe. This is the page for CAL(1), and the program itself is called ccal, bestie. No cap. 🗓️✨

✨ SYNOPSIS ✨

ccal [ options ] [ [ num_month ] year ]
ccal [ options ] [ word_month ] [ year ]

🌸 DESCRIPTION 🌸

okay so by default, ccal shows you a calendar for the current month, and it marks the current day so you know exactly where you are in time. Iconic behavior honestly. But if you hand it certain arguments, it will serve you a whole entire year, or a specific month plus year. Main character energy. 👑

The transition from the Julian to the Gregorian calendar is assumed to have occurred in 1752 on the 3rd of September. Ten days following that date were eliminated by the reformation, so the calendar for that month is a bit unusual. Yeah. It's giving glitch in the timeline. That's just how it is. 🫠

If you're displaying in the single-month format, ccal will go looking for a date file. If it finds one, it reads that file, hunting for special date descriptions for that month, and those get displayed to the right of the calendar. By default, up to 24 appointments may be displayed per month. And if the current date happens to land on one of these special dates, it gets flagged by an asterisk. ⭐ If there's room, appointments for the next month may also be displayed — but with some limitations (currently, special dates such as the 3rd Thursday of will not be calculated for next month).

ccal can also optionally use colors when displaying the calendar. But — important — it will not display colors any time the calendar is not directly displaying on the console. This is generally the desired behavior when you're redirecting cal's output to another program or a file. She knows when to dress up and when to stay lowkey. 💅

🦋 ARGUMENTS 🦋

A verbally-specified month may be entered without specifying a year in the argument list; however, a single numerical argument will be interpreted as a year. Only the first 3 characters of the month name are significant for a verbally-specified month. So the command cal 10 refers to 10 AD, not October, and not 1910. Yeah fr fr, read that one again. 💀

The available options are:

• --3[months] — Display previous/current/next month together. This option will be ignored when displaying a full year.
• --a[ppts] — Maximum number of appointments to display. Minimum is 8, maximum is 50, default is 24.
• --col[or-file]=filename — Read color definitions from filename (default color filename depends on operating system).
• --con[tinue]=n — Display the next n successive months starting with the month specified.
• --d[ata-file]=filename — Read appointments from filename (default appointment data filename depends on operating system). You may use -d up to 8 times in a commandline to specify multiple data file names.
• --e[urope] — Use European format (first weekday is Monday).
• --a[merican] — Use North American format (first weekday is Sunday), this is the default.
• --f[uture] — If current month is displayed, then show only future appointments from the date file, not appointments that are past. This allows room for other descriptions with future dates to be displayed. As time progresses through the month, old descriptions are discarded and newer ones are used. The --future switch affects only the display for the current month, and not other months.
• --j[ulian] — Display Julian dates (days one-based, numbered from January 1).
• --m[onday] — Display Monday as the first day of the week (same as --europe).
• --noc[olor] — Inhibit the use of colors.
• --nod[ata] — Do not try to read any appointment data file.
• --p[ause] — Pause before exiting and prompt for a keystroke.
• --th[ismonth] — Disable display of next month appointments; show only current month's.
• --to[day] — Show only today's appointments.
• --u[se-color] — Allow the use of colors.
• --y[ear] — Display a calendar for the current year.

There's an optional environment variable that ccal can use if it finds it. If CALOPT is set, then ccal will read it and use any valid command line options found there. This lets you set commonly used switches in your environment and have them always used (e.g. --europe). But heads up: ccal will produce its usage screen when run if any invalid options are set in this variable. 🚨

---

🎀 COMMAND EXAMPLES 🎀

• ccal --f --d=my_dates — display the current month and future appointments defined in file my_dates
• ccal 1996 — display the entire year of 1996
• ccal 9 1752 — display the month of September 1752
• ccal sep 1752 — same as above
• ccal January — display January of the current year
• ccal help — help message displayed for unrecognized arguments

🍓 DATE FILES 🍓

ccal will search for a date file called cal.dat in the directory it was executed from. If not found, it will search in the user's $HOME directory for a file called .cal.dat. If still not found, it will look for a global cal.dat in a system wide directory. To find out where this location is, you can run ccal --help which will display the location. 🔍

The special date descriptions specified in the date file are single lines, formatted as follows:

 YYYY MM DD NW xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

where

• YYYY — is the year,
• MM — is the month (01 - 12),
• DD — is the day (00 if the NW field is used),
• NW — is the weekday-of-month code (00 if the DD field is used)
• xxxx — is the description; it will be truncated as necessary to fit

The data MUST occupy the character fields as shown. This is not a suggestion, bestie. 🙈

If YYYY is specified as -999, the month and day are assumed to be annual events such as holidays, and the description will be displayed for any year. If MM is specified as -9, the day is assumed to be a monthly event for the specified year. In the weekday-of-month code NW, N signifies on which weekday W the special date occurs. For example, 31 indicates the third sunday. Values of W range from 1 to 7, for Sunday to Saturday, respectively. A value of 9 for N indicates "last" — as in 95 for "last thursday." 🗓️

If ALL of the fields contain a positive number and the year is at least 1970, then the description is assumed to be periodic, starting at the given date, with the period in days specified in NW (e.g. 1995 01 06 14 will display the description every 2nd Friday using 6 January 1995 as the base date). The base date does not get displayed. Lowkey a whole recurring-event engine in there. 🔥

You can display birthdays and anniversaries by putting the year of birth (or other special event) inside brackets or braces, in the description. This number is converted to the number of years since the year you indicate, and the brackets or braces are removed from the output. If braces {} are used, the number will have an ordinal suffix, as in 21st, 32nd, 43rd, 54th, etc. If the number in brackets or braces is greater than the current year, the number will be displayed unchanged. Example: "Alex's {1961} birthday" will display as "Alex's 34th birthday" (if the current year is 1995). If you need to include brackets or braces in your output then you can escape them by prefixing it with a '\'. Example: "Alex's \{1961\} birthday" will be displayed as "Alex's {1961} birthday". 🎂

NOTE: If ccal is invoked with the --europe or --monday switch, then the W values 1-7 denote Monday(1) to Sunday(7) rather than Sunday(1) to Saturday(7). Don't get caught slippin'. ⚠️

A line in cal.dat must start with -999 or a 4-digit number to be considered as data. The data lines may be in any order. All these appointments will be displayed in chronological order, regardless of the ordering in the appointment data file. ✨

If ccal was compiled with the reminder support, then ccal will also search for the files dates and .dates in the same places as for the cal.dat equivalents. The dates file is used by the reminder(1) program and is an alternate, less-powerful format for specifying descriptions. A file in this format cannot be specified with the --data-file= option.

The reminder format consists of text lines of length < screen width in the following format:

  DDDDDDDD:N:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx:yyyyyy:S

where

• DDDDDDDD — is the date in one of the following formats:
  • M/D/Y — an event occurring on a specific day (year can be two or four digits, but must be two for backward compatibility with reminder)
  • M/D — an event occurring every year
  • D — an event occurring every month
  • DDD — an event occurring every week (day of the week is 'Sun', 'Mon', etc.)
• N — is the number of days notice of the event to give the user (ignored by ccal)
• xxxxx — the event description
• yyyyy — an optional receptor of the event (e.g. Mr. Jones)
• S — status flag, either N for normal event or D for a deleted (not displayed) event

Blank lines are ignored. A line otherwise not in the above format is assumed to specify a file name from which to read more events. The file is searched for in the usual places. 🫶

🌈 LOCALISATION 🌈

ccal will also use the user's locale definitions to determine which day to use as the starting weekday. This is overridden if the -europe or the -american command line switches are used.

If you do not set the -europe or -american switch, your locale is properly defined, and you see a different start weekday different from what you would expect, then either ccal or your libc definitions are to blame. If you think this is a bug in ccal please report it. 👀

🎨 COLOR ATTRIBUTES 🎨

okay so bestie, you can absolutely customise the vibes here. ccal goes on a lil scavenger hunt for a color definition file called cal.col, and it checks these places in order:

1. the directory it was executed from — it looks for cal.col right there
2. if that's a no-show, it peeks in your $HOME directory for a file called .cal.col
3. if it's still not found, it goes looking for a global system-wide /etc/cal.col

you can confirm exactly where the system-wide definition lives by running ccal --help — it'll show you the location. 💅

and yes, users may override the default colors used when displaying calendars. how? by creating a color definition file in their home directory. easy.

---

🌈 example of a color definition file 🌈

 15 02   video colors for month name
 01 03   video colors for weekday header
 07 01   video colors for normal calendar days
 13 01   video colors for sundays
 14 02   video colors for current day
 07 06   bkgd for yearly calendar (space between months)
 11 00   video colors for special day descriptions
 12 08   video colors for * indicating descr.=today

see that FG BG vibe up top? that's the whole layout, bestie.

the rules, no cap:

• color definitions must appear exactly as above — a two-character field for the foreground color, then a space, then a two-character field for the background color
• the color definitions must start on the first line, and must not contain blank lines 🙈
• comments may appear after the second field, as long as the total line length does not exceed 80 characters

---

🎀 possible colors 🎀

  black           0
  blue            1
  green           2
  cyan            3
  red             4
  violet          5
  orange          6
  light gray      7

  dark gray       8
  bright blue     9
  bright green    10
  bright cyan     11
  bright red      12
  bright violet   13
  yellow          14
  white           15

⚠️ heads up bestie: specifying a background color from 8 to 15 will result in a background color of 0 to 7, with flashing text. not a drill. 💀

---

📁 FILES 📁

here's the whole roster of files this thing messes with:

• cal.dat — Date file
• cal.col — Color definition file
• $HOME/.cal.dat — User's local date file
• $HOME/.cal.col — User's local color file
• /etc/cal.dat — System wide definition for dates
• /etc/cal.dat — System wide definition for colors
• ~/.dates — Date file used with UNIX reminder program and can be used with cal.

(and yes, /etc/cal.dat is listed twice up there with two different descriptions — that's literally how it's written, iykyk 🫶)

---

👑 AUTHOR 👑

     Alex Matulich  -  alex@unicorn.us.com

     ...with enhancements and modifications by other
     contributors.

     (c) 1993-2001 by Unicorn Research Corporation
http://unicorn.us.com.
     Inspired by an Amiga program by Gary L. Brant.

shoutout to Alex, shoutout to the mystery contributors, shoutout to Gary L. Brant and his Amiga program. iconic lineage fr fr ✨

---

🔍 SEE ALSO 🔍

date(1), reminder(1),

---

and that's a wrap on the whole page, bestie! 🦋 this version is the one dated 28 January 2004, and it's page CAL(1) — go forth and make your terminal calendar cute. slay, periodt. 💖