tcx 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d01c5e7b68db327c2799dedc1bae6129d7e15611fc6150f0e579370e6e88f03
-  data.tar.gz: 91be5cd3892f53f44624ee133e0a19fb9bab5d81199529dfacc33a2310d02c79
+  metadata.gz: 2a22d167ca20a21779421b65e48f939affd43b7983bda56f22da9e5013d6af6c
+  data.tar.gz: 7d526b593d253b3e6c4dcb64aea2ca7df4fa255d457871608d3677a16768b216
 SHA512:
-  metadata.gz: 5ce16d273b98f168852ae1544b913ee8ac92fc7fda6db73a34c181a1787d1056c8b4883aecb74ce3ebb78ccfeaa3ab518a8ec9fe0a8696368267046bb4bc8113
-  data.tar.gz: e1666d5a681fb5e95ccdb59f97a2fb34c64a4b561a68d7e2c47bf2273c718a99bca0bb18480f380dd31ff1396dec742091c75c4036c1161db6a5b76aed5713bd
+  metadata.gz: f2f772cb32f27738b1683c0087e13ca7a82987350846d875ae202d245a21bca3f0fafc5d0ed0cc8793c558adc585f29af080495feadf70dbee95c1baf8f45788
+  data.tar.gz: 625852f7eb80fe4c1123ba2d4187934aa28da3c1dd65de21ffc5a504b1c74c9c506c49fabd71df50e6a668273758907885429362ac91c9c87d66ac1e96bb6994

data/CHANGELOG.md

@@ -1,3 +1,15 @@
-### 0.1.0 (Next)
+### 0.3.0 (2025-10-24)
 
-* Initial public release - [@dblock](https://github.com/dblock).
+* Added reading and writing multisport activity folders - [@dblock](https://github.com/dblock).
+* Added reading and writing workouts - [@dblock](https://github.com/dblock).
+* Write required namespaces dynamically - [@dblock](https://github.com/dblock).
+* Added reading and writing courses - [@dblock](https://github.com/dblock).
+* Added writing multiple extension attributes - [@dblock](https://github.com/dblock).
+
+### 0.2.0 (2025-10-24)
+
+* Added support for writing TCX files - [@dblock](https://github.com/dblock).
+
+### 0.1.0 (2025-10-23)
+
+* Initial public release, generic TCX reader - [@dblock](https://github.com/dblock).

data/README.md

@@ -3,7 +3,9 @@
 [![Gem Version](https://badge.fury.io/rb/tcx.svg)](https://badge.fury.io/rb/tcx)
 [![Test](https://github.com/dblock/tcx/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/dblock/tcx/actions/workflows/test.yml)
 
-A Garmin Training Center XML (TCX) reader (and future writer). Unlike prior art such as [tcx_rb](https://github.com/keithdoggett/tcx_rb) or [tcxread](https://github.com/firefly-cpp/tcxread), aims to provide a more coherent API by implementing the complete read/write [TCX schema](https://www8.garmin.com/xmlschemas/TrainingCenterDatabasev2.xsd) in a more structured way.
+A Garmin Training Center XML (.TCX) reader and writer.
+
+Unlike other libraries such as [tcx_rb](https://github.com/keithdoggett/tcx_rb) or [tcxread](https://github.com/firefly-cpp/tcxread), provides a more idiomatic API, implements both read and write, and supports the entire [TCX schema](https://www8.garmin.com/xmlschemas/TrainingCenterDatabasev2.xsd), including extensions.
 
 ## Installation
 
@@ -17,16 +19,41 @@ Run `bundle install`.
 
 ## Usage
 
+### Working with Files
+
+Read and write TCX files using `Tcx#load_file` and `dump`. 
+
 ```ruby
 require 'tcx'
 
-tcx = Tcx.load_file('examples/multiple_running_activities.tcx') # => Tcx::Database
+tcx = Tcx.load_file('activities.tcx') # => Tcx::Database
+
+tcx.activities # => [Tcx::Activity], array of Tcx::Activity
+tcx.workouts # => [Tcx::Workout]
+tcx.courses # => [Tcx::Course]
+
+tcx.dump # overwrites activities.tcx
+
+tcx.dump('activities2.tcx') # writes to activities2.tcx
+```
+
+### Working with XML Data
+
+Directly manipulate TCX data without creating files.
+
+```ruby
+data = File.read('activities.tcx') # String
 
-tcx.activities # => [Tcx::Activity]
-...
+tcx = Tcx.load(data) # => Tcx::Database
+
+tcx.to_xml # => XML string
+
+tcx.dump('activities2.tcx') # writes to activities2.tcx
 ```
 
-See [examples/multiple_running_activities.rb](examples/multiple_running_activities.rb) for a detailed example.
+### Examples
+
+See [examples](examples) for a complete set of working samples.
 
 ## Upgrading
 

data/lib/tcx/extensions/activity_extension/v2/activity_lap.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Tcx
+  module Extensions
+    module ActivityExtension
+      module V2
+        # LX
+        class ActivityLap < Base
+          property 'avg_speed', from: 'AvgSpeed', transform_with: lambda(&:to_f)
+          property 'max_bike_cadence', from: 'MaxBikeCadence', transform_with: lambda(&:to_i)
+          property 'avg_run_cadence', from: 'AvgRunCadence', transform_with: lambda(&:to_i)
+          property 'max_run_cadence', from: 'MaxRunCadence', transform_with: lambda(&:to_i)
+          property 'steps', from: 'Steps', transform_with: lambda(&:to_i)
+          property 'avg_watts', from: 'AvgWatts', transform_with: lambda(&:to_i)
+          property 'max_watts', from: 'MaxWatts', transform_with: lambda(&:to_i)
+          property 'extensions', from: 'Extensions', transform_with: ->(v) { ExtensionsList.parse(v) }
+        end
+      end
+    end
+  end
+end

data/lib/tcx/extensions/activity_extension/v2/activity_trackpoint.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Tcx
+  module Extensions
+    module ActivityExtension
+      module V2
+        # TPX
+        class ActivityTrackpoint < Base
+          property 'speed', from: 'Speed', transform_with: lambda(&:to_f)
+          property 'run_cadence', from: 'RunCadence', transform_with: lambda(&:to_i)
+          property 'watts', from: 'Watts', transform_with: lambda(&:to_i)
+          property 'extensions', from: 'Extensions', transform_with: ->(v) { ExtensionsList.parse(v) }
+          property 'cadence_sensor', from: 'CadenceSensor', transform_with: ->(v) { CadenceSensorType.parse(v) }
+
+          def self.attributes
+            ['cadence_sensor']
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tcx/extensions/activity_extension/v2/base.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Tcx
+  module Extensions
+    module ActivityExtension
+      module V2
+        # LX
+        class Base < Tcx::Base
+          def self.namespace
+            'http://www.garmin.com/xmlschemas/ActivityExtension/v2'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tcx/extensions/activity_extension/v2/cadence_sensor_type.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Tcx
+  module Extensions
+    module ActivityExtension
+      module V2
+        class CadenceSensorType
+          include Ruby::Enum
+
+          define :footpod, 'Footpod'
+          define :bike, 'Bike'
+        end
+      end
+    end
+  end
+end

data/lib/tcx/extensions/activity_extension/v2.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'v2/base'
+require_relative 'v2/cadence_sensor_type'
+require_relative 'v2/activity_lap'
+require_relative 'v2/activity_trackpoint'

data/lib/tcx/extensions.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'extensions/activity_extension/v2'

data/lib/tcx/file.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Tcx
+  class File
+    extend Forwardable
+
+    attr_accessor :file_path
+
+    def_delegators :database, :folders, :activities, :workouts, :courses, :author, :to_xml
+
+    def initialize(file_path = nil)
+      @file_path = file_path
+    end
+
+    def database
+      @database ||= if file_path
+                      ::File.open(file_path) do |file|
+                        xml = Nokogiri::XML(file)
+                        Tcx::Database.parse(xml.root)
+                      end
+                    else
+                      Tcx::Database.new
+                    end
+    end
+
+    def dump(target_path = nil)
+      database.dump(target_path)
+    end
+  end
+end

data/lib/tcx/types/abstract_source.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Tcx
+  class AbstractSource < Base
+    property 'name', from: 'Name'
+  end
+end

data/lib/tcx/{models → types}/activity.rb

@@ -6,6 +6,12 @@ module Tcx
     property 'id', from: 'Id'
     property 'laps', from: 'Lap', transform_with: ->(v) { to_array(v).map { |el| Lap.parse(el) } }
     property 'notes', from: 'Notes'
+    property 'training', from: 'Training', transform_with: ->(v) { to_array(v).map { |el| Training.parse(el) } }
     property 'creator', from: 'Creator', transform_with: ->(v) { AbstractSource.parse(v) }
+    property 'extensions', from: 'Extensions', transform_with: ->(v) { ExtensionsList.parse(v) }
+
+    def self.attributes
+      ['sport']
+    end
   end
 end

data/lib/tcx/types/activity_list.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Tcx
+  class ActivityList < Base
+    property 'activities', from: 'Activities', transform_with: ->(v) { v.map { |el| Activity.parse(el) } }
+    property 'multisport_sessions', from: 'MultisportSession', transform_with: ->(v) { v.map { |el| MultisportSession.parse(el) } }
+
+    def_delegators :activities, :each, :count
+
+    def self.parse(list)
+      ActivityList.new(
+        'Activities' => list.xpath('xmlns:Activity'),
+        'MultisportSession' => list.xpath('xmlns:MultiSportSession')
+      )
+    end
+
+    def build_xml(builder, namespace = nil)
+      activities.each do |activity|
+        builder.Activity(activity.attributes) do |activity_builder|
+          activity.build_xml(activity_builder, namespace)
+        end
+      end
+    end
+  end
+end

data/lib/tcx/types/activity_reference.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Tcx
+  class ActivityReference < Base
+    property 'id', from: 'Id', transform_with: ->(v) { ::Time.parse(v) }
+  end
+end

data/lib/tcx/types/application.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Tcx
+  class Application < AbstractSource
+    property 'build', from: 'Build', transform_with: ->(v) { Build.parse(v) }
+    property 'lang_id', from: 'LangID'
+    property 'part_number', from: 'PartNumber'
+
+    def attributes
+      super.merge('xsi:type' => 'Application_t')
+    end
+  end
+end

data/lib/tcx/types/base.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Tcx
+  class Base < Hashie::Trash
+    include Hashie::Extensions::IgnoreUndeclared
+    extend Forwardable
+
+    DEFAULT_NAMESPACE = 'http://www.garmin.com/xmlschemas/TrainingCenterDatabase/v2'
+
+    # TODO: dynamically register additional namespaces to support custom extensions
+    DEFAULT_NAMESPACE_DEFINITIONS = {
+      'xsi:schemaLocation' => 'http://www.garmin.com/xmlschemas/TrainingCenterDatabase/v2 http://www.garmin.com/xmlschemas/TrainingCenterDatabasev2.xsd',
+      'xmlns' => 'http://www.garmin.com/xmlschemas/TrainingCenterDatabase/v2',
+      'xmlns:xsi' => 'http://www.w3.org/2001/XMLSchema-instance',
+      'xmlns:ns2' => 'http://www.garmin.com/xmlschemas/UserProfile/v2',
+      'xmlns:ns3' => 'http://www.garmin.com/xmlschemas/ActivityExtension/v2',
+      'xmlns:ns4' => 'http://www.garmin.com/xmlschemas/ProfileExtension/v1',
+      'xmlns:ns5' => 'http://www.garmin.com/xmlschemas/ActivityGoals/v1'
+    }.freeze
+
+    INVERTED_DEFAULT_NAMESPACE_DEFINITIONS = DEFAULT_NAMESPACE_DEFINITIONS.invert.freeze
+
+    class << self
+      def parse(xml)
+        klass = to_class(xml['xsi:type'])
+        return klass.parse(xml) if klass
+
+        attributes = xml.attributes.to_h
+
+        xml.children.each do |child|
+          next unless child.is_a?(Nokogiri::XML::Element)
+
+          attributes[child.name] = if attributes.key?(child.name)
+                                     to_array(attributes[child.name]) + [child]
+                                   elsif child.children.one? && child.children.first.is_a?(Nokogiri::XML::Text)
+                                     child.text
+                                   else
+                                     child
+                                   end
+        end
+
+        new attributes
+      end
+
+      # Transform an XmlElement into [XmlElement], cannot be used with Array or causes a coercion error
+      def to_array(value)
+        value.is_a?(Array) ? value : [value]
+      end
+
+      def to_class(xsi_type)
+        return unless xsi_type
+
+        # TODO: not all extension types are Type_t
+        klass = Tcx.const_get(xsi_type.gsub(/_t$/, ''))
+        self == klass ? nil : klass
+      rescue NameError # extension not implemented
+        nil
+      end
+
+      def attributes
+        []
+      end
+
+      def namespace
+        DEFAULT_NAMESPACE
+      end
+    end
+
+    def attributes
+      self.class.attributes.map do |attribute|
+        value = self[attribute]
+        next unless value
+
+        property_name = self.class.inverse_translations.fetch(attribute, attribute)
+        [property_name, build_value(value)]
+      end.compact.to_h
+    end
+
+    def build_xml(builder, namespace = nil)
+      (self.class.properties - self.class.attributes).each do |property|
+        value = self[property]
+        next unless value
+
+        property_name = self.class.inverse_translations.fetch(property, property)
+
+        case value
+        when Base
+          build_el(builder, property_name, value)
+        when Array
+          value.each do |element|
+            build_el(builder, property_name, element)
+          end
+        else
+          builder = builder[namespace] if namespace
+          builder.send(property_name, build_value(value))
+        end
+      end
+    end
+
+    def namespace_definitions
+      DEFAULT_NAMESPACE_DEFINITIONS
+    end
+
+    def inverted_namespace_definitions
+      @inverted_namespace_definitions ||= if namespace_definitions == DEFAULT_NAMESPACE_DEFINITIONS
+                                            INVERTED_DEFAULT_NAMESPACE_DEFINITIONS
+                                          else
+                                            namespace_definitions.invert
+                                          end
+    end
+
+    private
+
+    def build_el(builder, property_name, element)
+      attributes = element.attributes if element.is_a?(Base)
+      namespace = inverted_namespace_definitions[element.class.namespace]&.split(':')&.[](1) if element.is_a?(Base)
+      builder = builder[namespace] if namespace
+
+      builder.send(property_name, attributes) do |property_builder|
+        element.build_xml(property_builder, namespace)
+      end
+    end
+
+    def build_value(value)
+      case value
+      when Nokogiri::XML::Element
+        # empty node
+      when ::Time
+        value.iso8601
+      else
+        value
+      end
+    end
+  end
+end

data/lib/tcx/types/boolean_type.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Tcx
+  class BooleanType
+    include Ruby::Enum
+
+    define :true, 'true' # rubocop:disable Lint/BooleanSymbol
+    define :false, 'false' # rubocop:disable Lint/BooleanSymbol
+  end
+end

data/lib/tcx/types/build.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Tcx
+  class Build < Base
+    property 'version', from: 'Version', transform_with: ->(v) { Version.parse(v) }
+    property 'type', from: 'Type', transform_with: ->(v) { BuildType.parse(v) }
+    property 'time', from: 'Time', transform_with: ->(v) { ::Time.parse(v) }
+    property 'builder', from: 'Builder'
+  end
+end

data/lib/tcx/types/build_type.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Tcx
+  class BuildType
+    include Ruby::Enum
+
+    define :internal, 'Internal'
+    define :alpha, 'Alpha'
+    define :beta, 'Beta'
+    define :release, 'Release'
+  end
+end

data/lib/tcx/types/cadence.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Tcx
+  class Cadence < Base
+    property 'value', from: 'Value', transform_with: lambda(&:to_i)
+
+    def_delegators :value, :to_i, :==
+  end
+end

data/lib/tcx/types/cadence_target.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Tcx
+  class CadenceTarget < Target
+    property 'low', from: 'Low', transform_with: lambda(&:to_f)
+    property 'high', from: 'High', transform_with: lambda(&:to_f)
+  end
+end

data/lib/tcx/types/calories_burned.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Tcx
+  class CaloriesBurned < Duration
+    property 'calories', from: 'Calories', transform_with: lambda(&:to_i)
+  end
+end

data/lib/tcx/{models → types}/course_folder.rb

@@ -5,5 +5,10 @@ module Tcx
     property 'folders', from: 'Folder', transform_with: ->(v) { to_array(v).map { |el| CourseFolder.parse(el) } }
     property 'course_references', from: 'CourseNameRef', transform_with: ->(v) { to_array(v).map { |el| NameKeyReference.parse(el) } }
     property 'notes', from: 'Notes'
+    property 'name', from: 'Name'
+
+    def self.attributes
+      ['name']
+    end
   end
 end

data/lib/tcx/types/course_list.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Tcx
+  class CourseList < Base
+    property 'courses', from: 'Courses', transform_with: ->(v) { v.map { |el| Course.parse(el) } }
+
+    def_delegators :courses, :each, :to_a
+
+    def self.parse(list)
+      CourseList.new('Courses' => list.xpath('xmlns:Course'))
+    end
+
+    def build_xml(builder, namespace = nil)
+      courses.each do |course|
+        builder.Course(course.attributes) do |course_builder|
+          course.build_xml(course_builder, namespace)
+        end
+      end
+    end
+  end
+end

data/lib/tcx/{models → types}/course_point.rb

@@ -3,7 +3,7 @@
 module Tcx
   class CoursePoint < Base
     property 'name', from: 'Name'
-    property 'time', from: 'Time', transform_with: ->(v) { Time.parse(v) }
+    property 'time', from: 'Time', transform_with: ->(v) { ::Time.parse(v) }
     property 'position', from: 'Position', transform_with: ->(v) { Position.parse(v) }
     property 'altitude_meters', from: 'AltitudeMeters', transform_with: lambda(&:to_f)
     property 'point_type', from: 'PointType', transform_with: ->(v) { CoursePointType.parse(v) }

data/lib/tcx/types/custom_speed_zone.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Tcx
+  class CustomSpeedZone < Zone
+    property 'view_as', from: 'ViewAs', transform_with: ->(v) { SpeedType.parse(v) }
+    property 'low_in_meters_per_second', from: 'LowInMetersPerSecond', transform_with: lambda(&:to_f)
+    property 'high_in_meters_per_second', from: 'HighInMetersPerSecond', transform_with: lambda(&:to_f)
+  end
+end

data/lib/tcx/types/database.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Tcx
+  class Database < Base
+    property 'folders', from: 'Folders', transform_with: ->(arr) { Folders.parse(arr) }
+    property 'activities', from: 'Activities', transform_with: ->(arr) { ActivityList.parse(arr) }
+    property 'workouts', from: 'Workouts', transform_with: ->(arr) { WorkoutList.parse(arr) }
+    property 'courses', from: 'Courses', transform_with: ->(arr) { CourseList.parse(arr) }
+    property 'author', from: 'Author', transform_with: ->(el) { AbstractSource.parse(el) }
+
+    attr_accessor :namespace_definitions
+
+    class << self
+      def load(data)
+        xml = Nokogiri::XML(data)
+        parse(xml.root)
+      end
+
+      def parse(xml)
+        instance = super
+        instance.namespace_definitions = {
+          'xsi:schemaLocation' => xml['xsi:schemaLocation']
+        }.merge(xml.namespace_definitions.to_h do |ns|
+          [['xmlns', ns.prefix].compact.join(':'), ns.href]
+        end)
+        instance
+      end
+    end
+
+    def dump(target_path)
+      ::File.write(target_path, to_xml)
+    end
+
+    def to_xml
+      to_xml_builder.to_xml
+    end
+
+    private
+
+    def to_xml_builder
+      Nokogiri::XML::Builder.new(encoding: 'UTF-8') do |xml|
+        xml.TrainingCenterDatabase(namespace_definitions) do |xml|
+          build_xml(xml)
+        end
+      end
+    end
+  end
+end

data/lib/tcx/{models/abstract_source.rb → types/device.rb}

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
 module Tcx
-  class AbstractSource < Base
-    property 'name', from: 'Name'
+  class Device < AbstractSource
     property 'unit_id', from: 'UnitId'
     property 'product_id', from: 'ProductID'
     property 'version', from: 'Version', transform_with: ->(v) { Version.parse(v) }
+
+    def attributes
+      super.merge('xsi:type' => 'Device_t')
+    end
   end
 end

data/lib/tcx/types/distance.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Tcx
+  class Distance < Duration
+    property 'meters', from: 'Meters', transform_with: lambda(&:to_i)
+  end
+end

data/lib/tcx/types/duration.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Tcx
+  class Duration < Base
+    property 'seconds', from: 'Seconds', transform_with: lambda(&:to_i)
+    property 'meters', from: 'Meters', transform_with: lambda(&:to_i)
+    property 'heart_rate', from: 'HeartRate', transform_with: ->(v) { HeartRateValue.parse(v) }
+    property 'calories', from: 'Calories', transform_with: lambda(&:to_i)
+  end
+end

data/lib/tcx/types/extensions_list.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Tcx
+  class ExtensionsList < Base
+    # TODO: forward all extension properties up
+    property 'TPX', transform_with: ->(v) { Tcx::Extensions::ActivityExtension::V2::ActivityTrackpoint.parse(v) }
+    property 'LX', transform_with: ->(v) { Tcx::Extensions::ActivityExtension::V2::ActivityLap.parse(v) }
+  end
+end

data/lib/tcx/types/first_sport.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Tcx
+  class FirstSport < Base
+    property 'activity', from: 'Activity', transform_with: ->(v) { Activity.parse(v) }
+  end
+end

data/lib/tcx/types/folders.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Tcx
+  class Folders < Base
+    property 'history', from: 'History', transform_with: ->(v) { to_array(v).map { |el| History.parse(el) } }
+    property 'courses', from: 'Courses', transform_with: ->(v) { to_array(v).map { |el| Courses.parse(el) } }
+    property 'workouts', from: 'Workouts', transform_with: ->(v) { to_array(v).map { |el| Workouts.parse(el) } }
+  end
+end