Skip to content

Add clock mode that displays current system time (#2)#6

Merged
sarsolot merged 12 commits intomasterfrom
feature/clock-mode-issue-2
Aug 30, 2025
Merged

Add clock mode that displays current system time (#2)#6
sarsolot merged 12 commits intomasterfrom
feature/clock-mode-issue-2

Conversation

@sarsolot
Copy link
Owner

Add Clock Mode Feature

🎯 Overview

This PR implements a new clock mode for µTimer that displays the current system time in real-time. The clock mode provides accurate timekeeping by reading the system time every second and displaying it in a clean, readable format.

📋 Changes Summary

🕒 New Clock Mode Feature

  • New option: Added --clock (long) and -k (short) command-line options
  • Time display: Shows current time in clean HH:MM:SS format (e.g., 14:23:45)
  • Real-time updates: Updates every second using system time for maximum accuracy
  • System integration: Handles daylight saving time, NTP synchronization, and manual time changes
  • User control: Can be stopped using 'Q' key, similar to stopwatch mode

🔧 Technical Implementation

  • Timer mode integration: Added TIMER_MODE_CLOCK to existing timer framework
  • Clock-specific functions:
    • clock_get_diff(): Reads current system time using GDateTime
    • clock_new_timer(): Creates clock timer instance
    • timer_sec_msec_to_clock_string(): Formats time for clean display
  • Conflict detection: Integrated with existing option conflict checking
  • Clean architecture: Follows existing code patterns and conventions

📚 Documentation Updates

  • README.md: Updated feature list and usage examples to include clock mode
  • Manual page (utimer.1): Added clock mode documentation with usage examples
  • Help system: Updated command-line help text and descriptions
  • ChangeLog: Added detailed feature description and implementation notes

🔧 Code Quality Improvements

  • Whitespace cleanup: Fixed trailing whitespace issues in source files
  • Version bump: Updated version from 0.5-1 to 0.5-2 for new feature release
  • Code consistency: Maintained existing code style and patterns

🚀 Usage Examples

Basic clock mode:

# Show current time (updates every second)
utimer --clock
utimer -k

Example output:

Current Time: 14:23:45 

Integration with existing features:

# Conflict detection works as expected
utimer --clock --timer=5s  # ❌ Shows error about conflicting options
utimer --help              # ✅ Shows new clock option in help

🧪 Testing

  • ✅ Clock displays accurate current time in HH:MM:SS format
  • ✅ Updates every second with system time
  • ✅ Handles time zone changes and system clock adjustments
  • ✅ Proper conflict detection with other modes (timer, countdown, stopwatch)
  • ✅ Can be stopped with 'Q' key
  • ✅ Both short (-k) and long (--clock) options work
  • ✅ Help system shows new option correctly
  • ✅ All existing modes continue to work unchanged
  • ✅ Clean compilation without warnings

📊 Impact

New Capabilities

  • µTimer now supports 4 modes: timer, countdown, stopwatch, and clock
  • Provides accurate system time display for users who need a CLI clock
  • Maintains consistency with existing µTimer interface patterns

Backward Compatibility

  • ✅ All existing functionality preserved
  • ✅ No breaking changes to existing command-line options
  • ✅ Existing scripts and usage patterns continue to work

Performance

  • Minimal overhead: one system call per second for time reading
  • No impact on other timer modes
  • Efficient time formatting for display

🔗 Related Issues

Resolves #2 - Clock mode that shows current time

📝 Notes for Maintainers

  • Version bumped to 0.5-2 to reflect new feature
  • All source files follow existing code style
  • Documentation comprehensively updated
  • Ready for release and packaging

- Add new --clock/-k option to display current system time
- Shows time in clean HH:MM:SS format, updating every second
- Implemented using system time for accuracy (handles DST, NTP sync)
- Integrated with existing conflict detection and help system
- Updated README and manual page with clock mode documentation
- Updated ChangeLog with feature details
- Bump version to 0.5-2
- Fixed trailing whitespace in source files

Resolves #2
Keep clock mode as pure feature implementation.
Version bump will be handled in separate PR after feature merge.
FEATURE:
- Added --milliseconds (-m) flag to show milliseconds in clock mode
- Clock mode without -m: shows HH:MM:SS (e.g., 10:21:00)
- Clock mode with -m: shows HH:MM:SS.mmm (e.g., 10:21:09.405)
- Preserves existing millisecond display for timer/countdown/stopwatch modes
- Synced with master to get build system fixes

IMPLEMENTATION:
- Added show_milliseconds flag to Config structure
- Modified timer_print() to conditionally format clock output
- Fixed GOption variable declarations (gboolean, not gboolean*)
- All tests pass, backward compatibility maintained

DOCUMENTATION:
- Updated README.md with usage examples
- Enhanced manual page (utimer.1) with detailed option description
- Added comprehensive ChangeLog entry

TESTING VERIFIED:
✓ Clock mode: -k shows HH:MM:SS, -k -m shows HH:MM:SS.mmm
✓ Other modes: -m flag has no effect (already show milliseconds)
✓ Conflict detection works for incompatible mode combinations
✓ All utility options (--help, --version, --limits) work correctly
✓ Full test suite passes
✓ Out-of-tree build (build.sh) works correctly
…ck mode clarity

- Added enhanced development workflow and build system documentation
- Added detailed development section with minimal source approach explanation
- Included release tarball creation and proper test instructions
- Clarified clock mode description: 'clock (with optional milliseconds)'
- Maintained scripting support mention as key differentiating feature
- Enhanced documentation for contributors and maintainers
- Removed unused 'guint total_sec = sec;' variable to eliminate compiler warning
- Function logic unchanged, still works correctly for clock display
- Clean compilation without warnings
- Replaced timer_sec_msec_to_clock_string() and timer_sec_msec_to_clock_string_with_ms()
- With single timer_sec_msec_to_clock_string(sec, msec, show_milliseconds) function
- Eliminates code duplication in time calculation logic
- Cleaner API with conditional formatting based on boolean parameter
- More maintainable - changes only need one location
- Consistent with existing conditional logic patterns
- Changed help text from '(--clock)' to '(only affects --clock)'
- Makes it crystal clear that -m flag only works with clock mode
- Eliminates potential user confusion about option scope
- Keeps CLI help perfectly in sync with man page documentation
- Add test for basic clock format validation (--clock help output)
- Add test for milliseconds format validation (--clock --milliseconds help output)
- Add test for conflict detection (--clock with timer mode)
- All tests use help output validation for reliable cross-platform testing
- Tests integrated with autotools build system via 'make check'
- Replace raw wait status check with g_spawn_check_wait_status()
- Ensures accurate cross-platform exit code validation
- Eliminates deprecation warning from g_spawn_check_exit_status()
- Test still correctly validates that conflicting flags exit with error
- Add test_clock_formatter_values() to test timer_sec_msec_to_clock_string() directly
- Test edge cases: 00:00:00, 23:59:59, 24h+ wraparound, milliseconds formatting
- Fast deterministic tests without process spawning
- Validates formatter logic independently of CLI integration
- Now includes both CLI smoke tests and direct unit tests for comprehensive coverage
- Rename timer_sec_msec_to_clock_string() to timer_clock_string_from_sec_msec()
- New name better reflects that it creates a clock string from seconds/milliseconds
- Clarifies that the function can return both HH:MM:SS and HH:MM:SS.mmm formats
- Updates function documentation to reflect optional millisecond formatting
- More intuitive API naming for future maintainers
@sarsolot sarsolot merged commit a853942 into master Aug 30, 2025
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Clock mode

1 participant