Serenity OS cal 命令详解从 man 手册到源码的终端日历实现全剖析【免费下载链接】serenityThe Serenity Operating System 项目地址: https://gitcode.com/GitHub_Trending/se/serenity本篇以 Serenity OS 的cal命令手册页 Base/usr/share/man/man1/cal.md 为主体结合其完整实现 Userland/Utilities/cal.cpp、日期常量 AK/DateConstants.h 与日历系统设置 Userland/Applications/CalendarSettings/CalendarSettingsWidget.cpp讲清这个终端日历工具的全部选项、输出格式、星期起始日配置来源与当前日高亮机制。读完你可以完整复现cal的三种视图单月、三月并列、整年并理解其布局宽度计算、ANSI 高亮和配置文件的读取链路。命令概述cal是 Serenity OS 用户态工具Userland/Utilities/中的一个终端日历程序其手册页给出的标准用法为$ cal [--starting-day weekday] [--three-month-view] [--year] [[month] year]行为约定来自手册页 Description 一节不带任何参数时显示当前月份且当前日期始终被高亮只传入year不传month时自动切换为整年概览视图月份与年份均以数字表示每周从星期几开始默认跟随Calendar 系统设置中的配置除非显式传入--starting-day。选项全解选项长选项作用-s--starting-day指定一周从星期几开始接受星期名的长/短/两字母缩写或数字索引0 表示周日-3--three-month-view以“上月、当月、下月”三个月并列的方式显示-y--year以网格形式显示整年未指定年份数字时默认当前年三个选项在源码中注册于 Userland/Utilities/cal.cpp 的Core::ArgsParser调用处与手册页一一对应args_parser.add_positional_argument(month, Month, month, Core::ArgsParser::Required::No); args_parser.add_positional_argument(year, Year, year, Core::ArgsParser::Required::No); args_parser.add_option(week_start_day_name, Day that starts the week, starting-day, s, day); args_parser.add_option(year_mode, Show the whole year at once, year, y); args_parser.add_option(three_month_mode, Show the previous and next month beside the current one, three-month-view, 3);两个值得注意的边界规则互斥检查--year与--three-month-view不能同时使用同时给出会打印cal: Cannot specify both --year and --three-month-mode at the same time并以状态码 1 退出见 cal.cpp#L184-L187“单参数视为年”的兼容处理由于两个位置参数都是可选的用户执行cal 2023时该数字最初会被解析进month源码用一个显式的 workaround 将其纠正为年份见 cal.cpp#L195-L199// Hack: workaround one value parsing as a month if (month !year) { year month; month 0; }紧随其后的逻辑是若指定了year而没有month则自动置year_mode true——这正是手册页所述“只传年份即显示整年”的实现依据cal.cpp#L201-L202。三种视图的输出示例完整继承手册页1. 显示当前月# Display the current month $ cal March - 2023 Su Mo Tu We Th Fr Sa 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 312. 显示任意月份cal month year# Display any month $ cal 1 1999 January - 1999 Su Mo Tu We Th Fr Sa 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 313. 三个月并列cal -3 month year# Display three months side-by-side $ cal -3 3 2023 February - 2023 March - 2023 April - 2023 Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa 1 2 3 4 1 2 3 4 1 5 6 7 8 9 10 11 5 6 7 8 9 10 11 2 3 4 5 6 7 8 12 13 14 15 16 17 18 12 13 14 15 16 17 18 9 10 11 12 13 14 15 19 20 21 22 23 24 25 19 20 21 22 23 24 25 16 17 18 19 20 21 22 26 27 28 26 27 28 29 30 31 23 24 25 26 27 28 29注意三月份视图的左右两个月标题带年份February - 2023这与源码中该模式使用Header::MonthAndYear的枚举取值一致cal.cpp#L226-L236。4. 整年视图cal year# Display an entire year $ cal 2023 Year 2023 January February March Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa 1 2 3 4 5 6 7 1 2 3 4 1 2 3 4 8 9 10 11 12 13 14 5 6 7 8 9 10 11 5 6 7 8 9 10 11 15 16 17 18 19 20 21 12 13 14 15 16 17 18 12 13 14 15 16 17 18 22 23 24 25 26 27 28 19 20 21 22 23 24 25 19 20 21 22 23 24 25 29 30 31 26 27 28 26 27 28 29 30 31 April May June Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa 1 1 2 3 4 5 6 1 2 3 2 3 4 5 6 7 8 7 8 9 10 11 12 13 4 5 6 7 8 9 10 9 10 11 12 13 14 15 14 15 16 17 18 19 20 11 12 13 14 15 16 17 16 17 18 19 20 21 22 21 22 23 24 25 26 27 18 19 20 21 22 23 24 23 24 25 26 27 28 29 28 29 30 31 25 26 27 28 29 30 30 July August September Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa 1 1 2 3 4 5 1 2 2 3 4 5 6 7 8 6 7 8 9 10 11 12 3 4 5 6 7 8 9 9 10 11 12 13 14 15 13 14 15 16 17 18 19 10 11 12 13 14 15 16 16 17 18 19 20 21 22 20 21 22 23 24 25 26 17 18 19 20 21 22 23 23 24 25 26 27 28 29 27 28 29 30 31 24 25 26 27 28 29 30 30 31 October November December Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa 1 2 3 4 5 6 7 1 2 3 4 1 2 8 9 10 11 12 13 14 5 6 7 8 9 10 11 3 4 5 6 7 8 9 15 16 17 18 19 20 21 12 13 14 15 16 17 18 10 11 12 13 14 15 16 22 23 24 25 26 27 28 19 20 21 22 23 24 25 17 18 19 20 21 22 23 29 30 31 26 27 28 29 30 24 25 26 27 28 29 30整年视图的布局参数直接体现在源码中每月单元格宽 22 列7 个两位数字加 6 个空格一整行放三个月、月间留 2 列间隔cal.cpp#L24-L26int constexpr month_width 01 02 03 04 05 06 07sv.length(); // 22 int constexpr year_width 3 * month_width 2 * sv.length(); // 70Year 2023大标题即以year_width居中输出月份网格以“左中右”三个月为一行、共 4 行输出且该模式下月份标题不含年份Header::Month详见 cal.cpp#L215-L225。星期起始日从配置到命令行--starting-day接受三类输入解析逻辑集中在weekday_index()cal.cpp#L32-L49按顺序尝试长名Sunday…Saturday短名Sun…Sat两字母名Su…Sa以上均通过AK::StringUtils::equals_ignoring_ascii_case做大小写不敏感匹配若都不匹配再尝试按数字解析0表示周日全部失败则报错Unknown weekday name。三套名称表定义在 AK/DateConstants.h 的long_day_names、short_day_names、mini_day_names中。未传该选项时的默认值并不写死而是读取 Calendar 应用的配置default_weekday_start()打开名为Calendar的应用配置文件取[View] FirstDayOfWeek项缺省为Sundaycal.cpp#L51-L56auto calendar_config TRY(Core::ConfigFile::open_for_app(Calendarsv)); String default_first_day_of_week TRY(String::from_byte_string(calendar_config-read_entry(Viewsv, FirstDayOfWeeksv, Sundaysv)));这份配置由桌面端 CalendarSettings 应用写入CalendarSettingsWidget.cpp 的apply_settings()会把FirstDayOfWeek、FirstDayOfWeekend、WeekendLength、DefaultView四个键写入Calendar配置组且出厂默认值即为Sunday见同文件reset_default_values()CalendarSettingsWidget.cpp#L25-L31。而ConfigFile::open_for_app的取径规则是“用户配置目录 应用名 .ini”Userland/Libraries/LibCore/ConfigFile.cpp#L29-L34因此在 Serenity OS 中实际读取的文件即~/.config/Calendar.ini。这解释了手册页中“周起始日默认跟随 Calendar 系统设置”的表述修改桌面端设置会同步影响终端cal的默认行为。得到start_of_week后表头由weekday_names_header()生成以两字母星期名为基础按(i start_of_week) % 7旋转拼出Su Mo Tu We Th Fr Sa这样的行cal.cpp#L68-L78。当前日高亮与网格填充算法手册页强调“当前日始终高亮”。实现上程序启动时用time()localtime()捕获今天的年/月/日存为三个全局量cal.cpp#L189-L193在逐日填充网格时若“显示的年 当前年 显示的月 当前月 当日 今天”就用 ANSI 反色转义序列包裹该日期cal.cpp#L116-L120#define ANSI_INVERT_OUTPUT \e[7m #define ANSI_RESET_OUTPUT \e[0m ... TRY(days_in_row.try_append(TRY(String::formatted(ANSI_INVERT_OUTPUT {:2} ANSI_RESET_OUTPUT, day))));网格填充的核心是“当月 1 号落在本周第几格”的计算先取Core::DateTime::create(year, month, 1)得到 1 号是星期几及当月总天数再通过weekday 7 - start_of_week并对 7 取模得到在自定义周起始日坐标系下的首列偏移偏移列之前填充两个空格的占位符之后每满 7 列折行cal.cpp#L103-L130。三月份并列视图则由print_months_side_by_side()对三条行序列逐行拼接每列左对齐到month_width、列间留 2 空格月份行数不等时以空串补齐cal.cpp#L135-L144上月/下月的年份进位由go_to_previous_month()/go_to_next_month()处理跨年边界cal.cpp#L146-L162。安全边界最小权限承诺serenity_main入口在解析参数前立即执行Core::System::pledge(stdio rpath cpath)cal.cpp#L164-L166。这是 Serenity OS 的 pledge 机制进程此后只保留标准 I/O 与必要的路径查询/解析能力任何越界的系统调用都会被直接拒绝。也就是说cal在运行时被限制在“读时间、读配置、写输出”这一最小能力集内是理解 Serenity OS 用户态工具安全模型的一个典型样本。小结与延伸阅读cal是一个小而完整的 Serenity OS 用户态程序值得沿以下路径继续阅读手册页行为契约Base/usr/share/man/man1/cal.md完整实现约 245 行单文件Userland/Utilities/cal.cpp星期/月份名称常量表AK/DateConstants.h周起始日的配置来源Userland/Applications/CalendarSettings/CalendarSettingsWidget.cpp、Userland/Libraries/LibCore/ConfigFile.cpp核心要点回顾cal支持单月、三月份并列、整年三种视图-s/--starting-day接受大小写不敏感的星期长/短/两字母名或 0 起始的数字索引未指定周起始日时回落到~/.config/Calendar.ini中 Calendar 应用的FirstDayOfWeek默认 Sunday今天所在日期通过 ANSI 反色序列高亮程序以pledge(stdio rpath cpath)运行在最小权限下。【免费下载链接】serenityThe Serenity Operating System 项目地址: https://gitcode.com/GitHub_Trending/se/serenity创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Serenity OS cal 命令详解：从 man 手册到源码的终端日历实现全剖析
Serenity OS cal 命令详解从 man 手册到源码的终端日历实现全剖析【免费下载链接】serenityThe Serenity Operating System 项目地址: https://gitcode.com/GitHub_Trending/se/serenity本篇以 Serenity OS 的cal命令手册页 Base/usr/share/man/man1/cal.md 为主体结合其完整实现 Userland/Utilities/cal.cpp、日期常量 AK/DateConstants.h 与日历系统设置 Userland/Applications/CalendarSettings/CalendarSettingsWidget.cpp讲清这个终端日历工具的全部选项、输出格式、星期起始日配置来源与当前日高亮机制。读完你可以完整复现cal的三种视图单月、三月并列、整年并理解其布局宽度计算、ANSI 高亮和配置文件的读取链路。命令概述cal是 Serenity OS 用户态工具Userland/Utilities/中的一个终端日历程序其手册页给出的标准用法为$ cal [--starting-day weekday] [--three-month-view] [--year] [[month] year]行为约定来自手册页 Description 一节不带任何参数时显示当前月份且当前日期始终被高亮只传入year不传month时自动切换为整年概览视图月份与年份均以数字表示每周从星期几开始默认跟随Calendar 系统设置中的配置除非显式传入--starting-day。选项全解选项长选项作用-s--starting-day指定一周从星期几开始接受星期名的长/短/两字母缩写或数字索引0 表示周日-3--three-month-view以“上月、当月、下月”三个月并列的方式显示-y--year以网格形式显示整年未指定年份数字时默认当前年三个选项在源码中注册于 Userland/Utilities/cal.cpp 的Core::ArgsParser调用处与手册页一一对应args_parser.add_positional_argument(month, Month, month, Core::ArgsParser::Required::No); args_parser.add_positional_argument(year, Year, year, Core::ArgsParser::Required::No); args_parser.add_option(week_start_day_name, Day that starts the week, starting-day, s, day); args_parser.add_option(year_mode, Show the whole year at once, year, y); args_parser.add_option(three_month_mode, Show the previous and next month beside the current one, three-month-view, 3);两个值得注意的边界规则互斥检查--year与--three-month-view不能同时使用同时给出会打印cal: Cannot specify both --year and --three-month-mode at the same time并以状态码 1 退出见 cal.cpp#L184-L187“单参数视为年”的兼容处理由于两个位置参数都是可选的用户执行cal 2023时该数字最初会被解析进month源码用一个显式的 workaround 将其纠正为年份见 cal.cpp#L195-L199// Hack: workaround one value parsing as a month if (month !year) { year month; month 0; }紧随其后的逻辑是若指定了year而没有month则自动置year_mode true——这正是手册页所述“只传年份即显示整年”的实现依据cal.cpp#L201-L202。三种视图的输出示例完整继承手册页1. 显示当前月# Display the current month $ cal March - 2023 Su Mo Tu We Th Fr Sa 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 312. 显示任意月份cal month year# Display any month $ cal 1 1999 January - 1999 Su Mo Tu We Th Fr Sa 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 313. 三个月并列cal -3 month year# Display three months side-by-side $ cal -3 3 2023 February - 2023 March - 2023 April - 2023 Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa 1 2 3 4 1 2 3 4 1 5 6 7 8 9 10 11 5 6 7 8 9 10 11 2 3 4 5 6 7 8 12 13 14 15 16 17 18 12 13 14 15 16 17 18 9 10 11 12 13 14 15 19 20 21 22 23 24 25 19 20 21 22 23 24 25 16 17 18 19 20 21 22 26 27 28 26 27 28 29 30 31 23 24 25 26 27 28 29注意三月份视图的左右两个月标题带年份February - 2023这与源码中该模式使用Header::MonthAndYear的枚举取值一致cal.cpp#L226-L236。4. 整年视图cal year# Display an entire year $ cal 2023 Year 2023 January February March Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa 1 2 3 4 5 6 7 1 2 3 4 1 2 3 4 8 9 10 11 12 13 14 5 6 7 8 9 10 11 5 6 7 8 9 10 11 15 16 17 18 19 20 21 12 13 14 15 16 17 18 12 13 14 15 16 17 18 22 23 24 25 26 27 28 19 20 21 22 23 24 25 19 20 21 22 23 24 25 29 30 31 26 27 28 26 27 28 29 30 31 April May June Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa 1 1 2 3 4 5 6 1 2 3 2 3 4 5 6 7 8 7 8 9 10 11 12 13 4 5 6 7 8 9 10 9 10 11 12 13 14 15 14 15 16 17 18 19 20 11 12 13 14 15 16 17 16 17 18 19 20 21 22 21 22 23 24 25 26 27 18 19 20 21 22 23 24 23 24 25 26 27 28 29 28 29 30 31 25 26 27 28 29 30 30 July August September Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa 1 1 2 3 4 5 1 2 2 3 4 5 6 7 8 6 7 8 9 10 11 12 3 4 5 6 7 8 9 9 10 11 12 13 14 15 13 14 15 16 17 18 19 10 11 12 13 14 15 16 16 17 18 19 20 21 22 20 21 22 23 24 25 26 17 18 19 20 21 22 23 23 24 25 26 27 28 29 27 28 29 30 31 24 25 26 27 28 29 30 30 31 October November December Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa 1 2 3 4 5 6 7 1 2 3 4 1 2 8 9 10 11 12 13 14 5 6 7 8 9 10 11 3 4 5 6 7 8 9 15 16 17 18 19 20 21 12 13 14 15 16 17 18 10 11 12 13 14 15 16 22 23 24 25 26 27 28 19 20 21 22 23 24 25 17 18 19 20 21 22 23 29 30 31 26 27 28 29 30 24 25 26 27 28 29 30整年视图的布局参数直接体现在源码中每月单元格宽 22 列7 个两位数字加 6 个空格一整行放三个月、月间留 2 列间隔cal.cpp#L24-L26int constexpr month_width 01 02 03 04 05 06 07sv.length(); // 22 int constexpr year_width 3 * month_width 2 * sv.length(); // 70Year 2023大标题即以year_width居中输出月份网格以“左中右”三个月为一行、共 4 行输出且该模式下月份标题不含年份Header::Month详见 cal.cpp#L215-L225。星期起始日从配置到命令行--starting-day接受三类输入解析逻辑集中在weekday_index()cal.cpp#L32-L49按顺序尝试长名Sunday…Saturday短名Sun…Sat两字母名Su…Sa以上均通过AK::StringUtils::equals_ignoring_ascii_case做大小写不敏感匹配若都不匹配再尝试按数字解析0表示周日全部失败则报错Unknown weekday name。三套名称表定义在 AK/DateConstants.h 的long_day_names、short_day_names、mini_day_names中。未传该选项时的默认值并不写死而是读取 Calendar 应用的配置default_weekday_start()打开名为Calendar的应用配置文件取[View] FirstDayOfWeek项缺省为Sundaycal.cpp#L51-L56auto calendar_config TRY(Core::ConfigFile::open_for_app(Calendarsv)); String default_first_day_of_week TRY(String::from_byte_string(calendar_config-read_entry(Viewsv, FirstDayOfWeeksv, Sundaysv)));这份配置由桌面端 CalendarSettings 应用写入CalendarSettingsWidget.cpp 的apply_settings()会把FirstDayOfWeek、FirstDayOfWeekend、WeekendLength、DefaultView四个键写入Calendar配置组且出厂默认值即为Sunday见同文件reset_default_values()CalendarSettingsWidget.cpp#L25-L31。而ConfigFile::open_for_app的取径规则是“用户配置目录 应用名 .ini”Userland/Libraries/LibCore/ConfigFile.cpp#L29-L34因此在 Serenity OS 中实际读取的文件即~/.config/Calendar.ini。这解释了手册页中“周起始日默认跟随 Calendar 系统设置”的表述修改桌面端设置会同步影响终端cal的默认行为。得到start_of_week后表头由weekday_names_header()生成以两字母星期名为基础按(i start_of_week) % 7旋转拼出Su Mo Tu We Th Fr Sa这样的行cal.cpp#L68-L78。当前日高亮与网格填充算法手册页强调“当前日始终高亮”。实现上程序启动时用time()localtime()捕获今天的年/月/日存为三个全局量cal.cpp#L189-L193在逐日填充网格时若“显示的年 当前年 显示的月 当前月 当日 今天”就用 ANSI 反色转义序列包裹该日期cal.cpp#L116-L120#define ANSI_INVERT_OUTPUT \e[7m #define ANSI_RESET_OUTPUT \e[0m ... TRY(days_in_row.try_append(TRY(String::formatted(ANSI_INVERT_OUTPUT {:2} ANSI_RESET_OUTPUT, day))));网格填充的核心是“当月 1 号落在本周第几格”的计算先取Core::DateTime::create(year, month, 1)得到 1 号是星期几及当月总天数再通过weekday 7 - start_of_week并对 7 取模得到在自定义周起始日坐标系下的首列偏移偏移列之前填充两个空格的占位符之后每满 7 列折行cal.cpp#L103-L130。三月份并列视图则由print_months_side_by_side()对三条行序列逐行拼接每列左对齐到month_width、列间留 2 空格月份行数不等时以空串补齐cal.cpp#L135-L144上月/下月的年份进位由go_to_previous_month()/go_to_next_month()处理跨年边界cal.cpp#L146-L162。安全边界最小权限承诺serenity_main入口在解析参数前立即执行Core::System::pledge(stdio rpath cpath)cal.cpp#L164-L166。这是 Serenity OS 的 pledge 机制进程此后只保留标准 I/O 与必要的路径查询/解析能力任何越界的系统调用都会被直接拒绝。也就是说cal在运行时被限制在“读时间、读配置、写输出”这一最小能力集内是理解 Serenity OS 用户态工具安全模型的一个典型样本。小结与延伸阅读cal是一个小而完整的 Serenity OS 用户态程序值得沿以下路径继续阅读手册页行为契约Base/usr/share/man/man1/cal.md完整实现约 245 行单文件Userland/Utilities/cal.cpp星期/月份名称常量表AK/DateConstants.h周起始日的配置来源Userland/Applications/CalendarSettings/CalendarSettingsWidget.cpp、Userland/Libraries/LibCore/ConfigFile.cpp核心要点回顾cal支持单月、三月份并列、整年三种视图-s/--starting-day接受大小写不敏感的星期长/短/两字母名或 0 起始的数字索引未指定周起始日时回落到~/.config/Calendar.ini中 Calendar 应用的FirstDayOfWeek默认 Sunday今天所在日期通过 ANSI 反色序列高亮程序以pledge(stdio rpath cpath)运行在最小权限下。【免费下载链接】serenityThe Serenity Operating System 项目地址: https://gitcode.com/GitHub_Trending/se/serenity创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考