Dateline - Comprehensive Date/Time Parser for Go

A powerful Go package that can parse dates and times from strings in over 150+ different formats. Perfect for log analysis, data processing, and any application that needs to extract temporal information from text.

Features

• 150+ Date/Time Formats: Supports ISO 8601, RFC formats, Unix timestamps, relative dates, multilingual months, and more
• Intelligent Detection: Automatically finds and extracts dates from within larger text strings
• Date Removal: Option to remove the detected date from the input string
• Multiple Output Formats: JSON or plain text output
• Timezone Support: Handles various timezone formats and offsets
• Multilingual: Recognizes month names in English, Spanish, French, German, Italian, and Portuguese

Installation

go get github.com/yourusername/dateline

Command Line Usage

Build the CLI tool

go build -o dateline ./cmd/dateline

Basic Usage

# Parse a date from stdin
echo "Meeting on 2024-03-15 at 2:30 PM" | ./dateline

# Output:
# Parsed Date/Time:
#   Time: 2024-03-15 00:00:00 UTC
#   Unix: 1710460800
#   Parsed: '2024-03-15'
#   Position: [11:21]

Command Line Options

• -remove : Remove the parsed date from the input string
• -json : Output results in JSON format
• -all : Find all dates in the input (not just the first)
• -v : Verbose output (show additional details)
• -h : Show help message

Examples

# Remove date from string
echo "File created on March 15, 2024 needs review" | ./dateline -remove
# Output: Without date: 'File created on  needs review'

# JSON output
echo "2024-03-15T14:30:45Z" | ./dateline -json
# Output: {"time":"2024-03-15T14:30:45Z","unix":1710513045,...}

# Find all dates
echo "From 2024-01-01 to 2024-12-31" | ./dateline -all
# Output: Found 2 date(s)...

# Verbose mode
echo "today" | ./dateline -v
# Shows additional details like format type and ISO 8601 representation

Package Usage in Your Code

Basic Example

package main

import (
    "fmt"
    "log"
    "dateline"
)

func main() {
    // Simple parsing
    input := "The meeting is scheduled for March 15, 2024 at 2:30 PM"
    result, err := dateline.Parse(input, false)
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("Found date: %s\n", result.Time.Format("2006-01-02 15:04:05"))
    fmt.Printf("Original text: %s\n", result.OriginalText)
    fmt.Printf("Parsed portion: %s\n", result.ParsedString)
    fmt.Printf("Position: [%d:%d]\n", result.StartIndex, result.EndIndex)
}

Remove Date from String

// Parse and remove the date
input := "Error occurred on 2024-03-15 - please investigate"
result, err := dateline.Parse(input, true) // true = remove date
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Text without date: %s\n", result.StringWithout)
// Output: "Error occurred on  - please investigate"

Find All Dates

input := "Project runs from 2024-01-01 to 2024-12-31"
results, err := dateline.FindAllDates(input)
if err != nil {
    log.Fatal(err)
}

for i, result := range results {
    fmt.Printf("Date %d: %s at position [%d:%d]\n", 
        i+1, result.Time.Format("2006-01-02"), 
        result.StartIndex, result.EndIndex)
}

Parse with Options

import "time"

// Parse with specific timezone
nyLocation, _ := time.LoadLocation("America/New_York")
result, err := dateline.ParseWithOptions(
    "Meeting at 3pm tomorrow",
    dateline.WithLocation(nyLocation),
    dateline.WithDateRemoval(true),
)

Supported Format Categories

✅ Fully Supported (155+ formats)

ISO 8601 & Variants

• 2024-03-15T14:30:45Z
• 2024-03-15T14:30:45+00:00
• 2024-03-15T14:30:45.123456789
• 20240315T143045Z
• 2024-03-15 14:30:45

RFC Formats

• Fri, 15 Mar 2024 14:30:45 GMT (RFC 1123)
• Friday, 15-Mar-24 14:30:45 GMT (RFC 850)
• 2024-03-15T14:30:45Z (RFC 3339)

Common Date Formats

• 03/15/2024 (American)
• 15/03/2024 (European)
• 2024/03/15 (Asian)
• 15.03.2024 (German)
• 15-03-2024 (ISO-like)

Written Dates

• March 15, 2024
• 15 March 2024
• Mar 15, 2024
• 15th March 2024
• March 1st, 2024

Multilingual Support

• 15 mars 2024 (French)
• 15 marzo 2024 (Spanish)
• 15 de marzo de 2024 (Spanish with "de")
• 15. März 2024 (German) *
• Various other European languages

Unix Timestamps

• 1710510645 (seconds)
• 1710510645123 (milliseconds)
• @1710510645 (with @ prefix)

Relative Dates

• today, yesterday, tomorrow
• 2 days ago, in 3 hours
• last Monday, next Friday

Technical Formats

• [15/Mar/2024:14:30:45 +0000] (Log format)
• (2024-03-15T14:30:45Z) (Parentheses wrapped)
• 20240315_143045 (Underscore separated)
• Database formats (Oracle, MySQL, PostgreSQL)

Special Formats

• 2024-W11 (ISO week dates)
• Q1 2024 (Quarter formats)
• Jan 2, 2006 at 3:04pm (MST) (Go reference format)

⚠️ Partially Supported

• Some multilingual formats with special characters
• Complex spelled-out dates

❌ Not Currently Supported (69 formats)

• Asian character formats (年月日, 년월일)
• Arabic/Persian numerals
• Julian dates
• Buddhist/Islamic calendar dates
• Some ordinal day formats (2024-074)
• Duration formats (P3Y6M4D)

Test Results

Current parser performance on comprehensive format test suite:

Testing All Formats from formats.md
=====================================
✓ Passed: 155 / 224
✗ Failed: 69 / 224
Success Rate: 69%

Progress: [████████████████████████████████░░░░░░░░░░░░░░░░] 69%

Performance by Category

Category	Support Level	Examples
ISO 8601	95%	2024-03-15T14:30:45Z
RFC Formats	90%	Fri, 15 Mar 2024 14:30:45 GMT
American Dates	100%	03/15/2024, March 15, 2024
European Dates	85%	15/03/2024, 15.03.2024
Unix Timestamps	100%	1710510645
Relative Dates	100%	today, 2 days ago
Technical/Log	80%	[15/Mar/2024:14:30:45 +0000]
Multilingual	75%	15 marzo 2024
Quarter/Week	60%	Q1 2024, 2024-W11

Running Tests

# Run comprehensive format test
./test-all-formats.sh

# Run basic test suite
./test.sh

# Test specific format
echo "your date string" | ./dateline

API Reference

Types

type ParseResult struct {
    Time          time.Time  // Parsed time value
    Format        string     // Format identifier used
    OriginalText  string     // Original input string
    StartIndex    int        // Start position of date in string
    EndIndex      int        // End position of date in string
    ParsedString  string     // The actual string that was parsed
    StringWithout string     // Input string with date removed
}

Functions

Parse(input string, removeDate bool) (*ParseResult, error)

Parses a date from the input string. If removeDate is true, removes the date from the string.

FindAllDates(input string) ([]*ParseResult, error)

Finds all dates in the input string.

ParseWithOptions(input string, opts ...ParseOption) (*ParseResult, error)

Parses with additional options like timezone and removal settings.

Parse Options

• WithDateRemoval(bool) - Set whether to remove the date from input
• WithLocation(*time.Location) - Set the timezone for parsing

Contributing

Contributions are welcome! Areas for improvement:

• Additional language support for month names
• More Asian date formats
• Historical calendar systems
• Additional timezone abbreviations

License

MIT License - See LICENSE file for details

Acknowledgments

Built to handle the comprehensive date format list from real-world applications, supporting the most commonly encountered formats in logs, databases, and international systems.