CLDF - Crushlog Data Format for Dart

A Dart implementation of the Crushlog Data Format (CLDF) for climbing data exchange.

Features

• Read and write CLDF archives (.cldf files)
• JSON serialization/deserialization for all CLDF models
• Type-safe Dart models for all CLDF entities
• Archive creation with automatic checksums
• Automatic statistics calculation when writing archives
• Validation support
• Enhanced Media Support (v1.2.3+)
  • Media attachments for routes, locations, sectors, and climbs
  • Semantic media designation (topo, beta, approach, etc.)
  • Support for embedded files and external URLs
  • Captions and timestamps for media items

Platform Support

This package supports all platforms except Web/WASM because CLDF archives require file system access for reading and writing .cldf files. The package works on:

• ✅ Android
• ✅ iOS
• ✅ macOS
• ✅ Windows
• ✅ Linux
• ❌ Web (file I/O not available)

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  cldf: ^1.2.3

Usage

Reading a CLDF archive

import 'package:cldf/cldf.dart';

final reader = CLDFReader();
final archive = await reader.readFile('path/to/file.cldf');

// Access data
print('Locations: ${archive.locations.length}');
print('Routes: ${archive.routes.length}');
print('Climbs: ${archive.climbs.length}');

Writing a CLDF archive

import 'package:cldf/cldf.dart';

final archive = CLDFArchive(
  manifest: Manifest(
    version: '1.0.0',
    format: 'CLDF',
    creationDate: DateTime.now(),
    platform: Platform.iOS,
    appVersion: '1.0.0',
  ),
  locations: [
    Location(
      id: 1,
      name: 'Test Crag',
      country: 'USA',
      isIndoor: false,
    ),
  ],
  routes: [
    Route(
      id: 1,
      locationId: 1,
      name: 'Classic Route',
      routeType: RouteType.route,
      grades: {'french': '6a'},
    ),
  ],
  climbs: [
    Climb(
      id: 1,
      date: '2024-01-15',
      routeName: 'Classic Route',
      type: ClimbType.route,
      finishType: FinishType.redpoint,
      attempts: 2,
    ),
  ],
);

final writer = CLDFWriter();
await writer.writeFile('output.cldf', archive);

Automatic Statistics

When writing an archive, statistics are automatically calculated if not already present in the manifest:

// Stats will be calculated automatically
final archive = CLDFArchive(
  manifest: Manifest(
    version: '1.0.0',
    format: 'CLDF',
    creationDate: DateTime.now(),
    platform: Platform.android,
    appVersion: '1.0.0',
    // No stats provided - will be calculated automatically
  ),
  locations: locations,
  climbs: climbs,
  // ... other data
);

await writer.writeFile('output.cldf', archive);
// The written archive will have stats populated with counts of all entities

Media Support (v1.2.3+)

Attach media to any entity with semantic designation:

final route = Route(
  id: 101,
  locationId: 1,
  name: 'The Dawn Wall',
  routeType: RouteType.route,
  media: Media(
    items: [
      MediaItem(
        type: MediaType.photo,
        path: 'media/dawn_wall_topo.jpg',
        designation: MediaDesignation.topo,
        caption: 'Full route topo with pitch breakdown',
        source: MediaSource.embedded,
      ),
      MediaItem(
        type: MediaType.video,
        path: 'https://youtube.com/watch?v=example',
        designation: MediaDesignation.beta,
        caption: 'Beta video from Tommy Caldwell',
        source: MediaSource.external,
      ),
    ],
    count: 2,
  ),
);

Available Designations:

• topo - Route diagrams
• beta - How-to information
• approach - Access info
• log - Climb documentation
• overview - General views
• conditions - Current state
• gear - Equipment info
• descent - Down-climb info
• other - Unspecified

Working with JSON

All models support JSON serialization:

// Convert to JSON
final climbJson = climb.toJson();

// Parse from JSON
final climb = Climb.fromJson(jsonData);

Models

The package provides models for all CLDF entities:

• Manifest - Archive metadata with automatic statistics calculation
• Location - Climbing locations
• Sector - Sectors within locations
• Route - Routes and boulders
• Climb - Individual climb records
• Session - Climbing sessions
• Tag - Tags for categorization
• MediaItem - Media references (photos/videos)
• Author - Author information for exports
• Stats - Statistics about the archive content

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

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