Version Go Version Go Reference License

A Go implementation for parsing iCalendar format (.ics) files and converting them into structured JSON format. This library simplifies working with calendar data by providing both a command-line interface and a Go library for iCalendar processing.

iCalendar is a standard format for exchanging calendar and scheduling information. This tool streamlines the process of converting iCalendar data to JSON format by:

• Parsing standard iCalendar files (.ics format) with full RFC 5545 compliance
• Converting to clean JSON structure with organized event data
• Preserving all calendar metadata including timezones, locations, and descriptions
• Handling complex event properties like geographic coordinates and recurring events
• Providing both CLI and library interfaces for different use cases

This project provides both a command-line interface and a Go library for working with iCalendar data.

• ✅ iCalendar Parsing: Full RFC 5545 compliant .ics file parsing
• ✅ JSON Conversion: Clean, structured JSON output format
• ✅ Timezone Support: Proper handling of timezone information
• ✅ Event Properties: Complete support for all standard event properties
• ✅ Geographic Data: Parse and convert GEO coordinates
• ✅ CLI & Library: Both command-line tool and Go library interfaces
• ✅ Cross-platform: Works on Linux, macOS, and Windows

• Go 1.24 or later
• Nix 2.25.4 or later (optional but recommended)
• PowerShell v7.5.1 or later (for building)

1. Clone the repository:

git clone https://github.com/beyondcivic/icaljson.git
cd icaljson

2. Build the application:

go build -o icaljson .

1. Clone the repository:

git clone https://github.com/beyondcivic/icaljson.git
cd icaljson

2. Prepare the environment using Nix flakes:

nix develop

3. Build the application:

./build.ps1

go install github.com/beyondcivic/icaljson@latest

The icaljson tool provides commands for converting iCalendar files to JSON:

# Convert iCalendar to JSON
icaljson generate calendar.ics -o calendar.json
# Show version information
icaljson version

package main
import (
	"fmt"
	"log"
	"github.com/beyondcivic/icaljson/pkg/icaljson"
)
func main() {
	// Convert iCalendar to JSON
	calendar, err := icaljson.Generate("calendar.ics", "calendar.json")
	if err != nil {
		log.Fatalf("Error converting calendar: %v", err)
	}
	fmt.Printf("Converted calendar with %d events\n", len(calendar.Events))
	// Access event data
	for _, event := range calendar.Events {
		fmt.Printf("Event: %s at %s\n", event.Summary, event.Location)
	}
}

Convert an iCalendar (.ics) file to structured JSON format.

icaljson generate [ICS_FILE] [OPTIONS]

Options:

• -o, --output: Output file path (default: [filename].json)

Examples:

# Basic conversion
icaljson generate events.ics
# With custom output path
icaljson generate events.ics -o my-events.json

Display version, build information, and system details.

icaljson version

The tool converts iCalendar data to a clean JSON structure:

{
 "prodid": "-//Calendar Producer//Calendar Product//EN",
 "version": "2.0",
 "calscale": "GREGORIAN",
 "events": [
 {
 "uid": "unique-event-id",
 "start": "2025年10月04日T09:00:00Z",
 "end": "2025年10月04日T10:00:00Z",
 "summary": "Meeting Title",
 "description": "Event description",
 "location": "Meeting Room A",
 "url": "https://example.com/event",
 "geo": {
 "latitude": 47.378177,
 "longitude": 8.540192
 },
 "comment": "Additional notes"
 }
 ]
}

The parser supports standard iCalendar properties:

# Convert a simple calendar file
$ icaljson generate my-calendar.ics -o calendar.json
Generating JSON file for 'my-calendar.ics'...
✓ JSON file generated successfully and saved to: calendar.json

Given an iCalendar file with multiple events, the tool will create a JSON array containing all events with their properties properly converted and formatted.

Converts an iCalendar file to JSON format.

Parameters:

• icsPath: Path to the input .ics file
• outputPath: Path for the output JSON file

Returns:

• *Calendar: Parsed calendar structure
• error: Any error that occurred during processing

Represents the complete calendar structure:

type Calendar struct {
 Prodid string `json:"prodid"`
 Version string `json:"version"`
 Calscale string `json:"calscale"`
 Events []Event `json:"events"`
}

Represents an individual calendar event:

type Event struct {
 UID string `json:"uid"`
 Start string `json:"start"`
 End string `json:"end"`
 Summary string `json:"summary"`
 Description string `json:"description,omitempty"`
 Location string `json:"location,omitempty"`
 URL string `json:"url,omitempty"`
 Geo *GeoPoint `json:"geo,omitempty"`
 Comment string `json:"comment,omitempty"`
}

Represents geographic coordinates:

type GeoPoint struct {
 Latitude float64 `json:"latitude"`
 Longitude float64 `json:"longitude"`
}

The library is organized into several key components:

• Parsing: iCalendar file parsing and validation
• Conversion: iCalendar to JSON structure conversion
• Data Types: Calendar and event data structures
• Utilities: Helper functions for file handling and validation

• Cobra-based CLI with subcommands for each major function
• Comprehensive help system with detailed usage examples
• Flexible output options and error handling

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-feature
3. Make your changes and add tests
4. Ensure all tests pass: go test ./...
5. Commit your changes: git commit -am 'Add new feature'
6. Push to the branch: git push origin feature/new-feature
7. Submit a pull request

Run the test suite:

go test ./...

Run tests with coverage:

go test -cover ./...

Use Nix flakes to set up the build environment:

nix develop

Check the build arguments in build.ps1:

# Build static binary with version information
$env:CGO_ENABLED = "1"
$env:GOOS = "linux"
$env:GOARCH = "amd64"

Then run:

./build.ps1

Or build manually:

go build -o icaljson .

This project is licensed under the MIT License - see the LICENSE file for details.