ta_lib_ffi 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bce4e063a54d75d182df869d35da723b37949710c6f1c5044c6973cbc96d3004
-  data.tar.gz: f74f344e265e98f8d080c0044a2fb95bac0060d8a664ff6e9930266be850712a
+  metadata.gz: 92ebfb652f8812db1420b8e8722f9df5e32850da14ca18c3df847dde134518b4
+  data.tar.gz: cbdeb52af3442827979b03523b58b6bcbf84484ec8fbd7a5a7265d5218401ce6
 SHA512:
-  metadata.gz: 896f41210adc293d7fe65dc4c7331916780b9e616587315a9671c2bfc76ad4a364492d26db5051efa8f18077a6dfa5535a4fd29cda2664c6e5fcc00452b1b7cb
-  data.tar.gz: 1d3c9ff3389f34cd93822e9136a87aaf5c61f0dfa015b4d5c715b5219898cf87a04f221bd1346f90f7339fda7b93fcd6d39a8a07ad79bb5b1558c321f983f511
+  metadata.gz: c07c6bb3ed6337582246a299df71eacf041f1c562180eea98d7f044cad285b971f7c56ebd8e949d73e303bce25dd1b2d1627e5add1dc9eb494a78f0effd901ae
+  data.tar.gz: 90d78b4fee669a0a5cd8f4d4f90501002bfd2006ef16af5541c7416f5dcfe5f6abf1d831059b302528df5eb7b328b595fe582048d16e8d301d1b3d3de92352f3

data/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2025-02-23
+
+### Added
+- Auto-generated YARD documentation
+- GitHub Actions PR Agent workflow
+- Cross-platform test support (Ubuntu, macOS, Windows)
+
+### Changed
+- Optimized function documentation generator
+- Improved error handling and validation
+- Updated development dependencies
+
+### Fixed
+- Fixed prices handling in multiple technical analysis functions
+
 ## [0.2.0] - 2025-01-21
 
 ### Added
@@ -15,7 +30,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Renamed main file from `lib/ta_lib.rb` to `lib/ta_lib_ffi.rb`
 - Updated require statements in specs and gemspec
 
-## [0.1.0] - 2024-01-21
+## [0.1.0] - 2025-01-21
 
 ### Added
 - Initial release of ta_lib_ffi
@@ -39,5 +54,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Security
 - N/A
 
-[0.2.0]: https://github.com/Youngv/ta_lib_ffi/compare/v0.1.0...v0.2.0
-[0.1.0]: https://github.com/Youngv/ta_lib_ffi/releases/tag/v0.1.0
+[0.3.0]: https://github.com/TA-Lib/ta-lib-ruby/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/TA-Lib/ta-lib-ruby/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/TA-Lib/ta-lib-ruby/releases/tag/v0.1.0

data/README.md

@@ -1,14 +1,15 @@
 # TALibFFI
 
-![Tests](https://github.com/Youngv/ta_lib_ffi/actions/workflows/main.yml/badge.svg)
+![Tests](https://github.com/TA-Lib/ta-lib-ruby/actions/workflows/main.yml/badge.svg)
+[![Gem Version](https://badge.fury.io/rb/ta_lib_ffi.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/ta_lib_ffi)
 
 ## Introduction
 
-TALibFFI is a Ruby binding for [TA-Lib](https://ta-lib.org/) (Technical Analysis Library) using FFI (Foreign Function Interface). It provides a comprehensive set of functions for technical analysis of financial market data.
+TALibFFI is a Ruby binding for [TA-Lib](https://ta-lib.org/) (Technical Analysis Library) using FFI (Foreign Function Interface). It provides a comprehensive set of functions for technical analysis of financial market data. This gem is based on the [TA-Lib C headers](https://github.com/TA-Lib/ta-lib/blob/6a07e4ca1877c5ab4b08b81015858bfcbf2ef832/include/ta_abstract.h#L45), providing a Ruby-friendly interface to the underlying C library.
 
 ## Requirements
 
-- Ruby >= 3.0.0
+- Ruby >= 3.1.0
 - TA-Lib >= 0.6.4
 
 ## Installation
@@ -38,7 +39,7 @@ wget https://github.com/ta-lib/ta-lib/releases/download/v0.6.4/ta-lib_0.6.4_i386
 sudo dpkg -i ta-lib_0.6.4_i386.deb
 ```
 
-### Installing the Ruby Gem
+### [Installing the Ruby Gem](https://rubygems.org/gems/ta_lib_ffi)
 
 Add this to your application's Gemfile:
 
@@ -65,8 +66,20 @@ prices = [10.0, 11.0, 12.0, 11.0, 10.0, 9.0, 8.0, 7.0, 6.0, 5.0, 4.0]
 # Calculate SMA
 puts TALibFFI.sma(prices, time_period: 3)
 # => [11.0, 11.333333333333334, 11.0, 10.0, 9.0, 8.0, 7.0, 6.0, 5.0]
+
+# Average True Range (ATR) Example
+high = [82.15, 81.89, 83.03, 83.30, 83.85, 83.90, 83.33, 84.30, 84.84, 85.00, 85.90, 86.58, 86.98, 88.00, 87.87]
+low  = [81.29, 80.64, 81.31, 82.65, 83.07, 83.11, 82.49, 82.30, 84.15, 84.11, 84.03, 85.39, 85.76, 87.17, 87.01]
+close = [81.59, 81.06, 82.87, 83.00, 83.61, 83.15, 82.84, 83.99, 84.55, 84.36, 85.53, 86.54, 86.89, 87.77, 87.29]
+
+# Calculate ATR with period = 5
+result = TALibFFI.atr([high, low, close], time_period: 5)
+# => [1.101999999999998, 1.0495999999999992, 1.2396799999999994, 1.1617440000000012, 1.1073952000000011, ...]
 ```
 
+## Documentation
+- [API Documentation](https://www.rubydoc.info/github/TA-Lib/ta-lib-ruby/main) - Detailed documentation of all available methods and classes
+
 ## TODO
 - [ ] Add RDoc documentation for Ruby methods
 - [ ] Create detailed function examples with input/output samples
@@ -83,7 +96,7 @@ puts TALibFFI.sma(prices, time_period: 3)
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/Youngv/ta_lib_ffi
+Bug reports and pull requests are welcome on GitHub at https://github.com/TA-Lib/ta-lib-ruby
 
 ## License
 

data/Rakefile

@@ -2,6 +2,7 @@
 
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+require "yard"
 
 RSpec::Core::RakeTask.new(:spec)
 
@@ -10,3 +11,14 @@ require "rubocop/rake_task"
 RuboCop::RakeTask.new
 
 task default: %i[spec rubocop]
+
+YARD::Rake::YardocTask.new do |t|
+  require_relative "lib/ta_lib_ffi"
+  require_relative "lib/ta_lib_ffi/doc"
+  TALibFFI::Doc.insert
+
+  t.files = ["lib/**/*.rb"]
+  t.options = ["--exclude", "lib/ta_lib_ffi/doc.rb"]
+  t.stats_options = ["--list-undoc"]
+  # t.after = -> { TALibFFI::Doc.remove }
+end

data/lib/ta_lib_ffi/doc.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module TALibFFI
+  # Generates documentation for a TA-Lib function
+  #
+  # This module provides methods to generate documentation for TA-Lib functions.
+  # It includes methods to collect input, optional input, and output information,
+  # and to generate documentation for each function.
+  module Doc
+    module_function
+
+    def insert
+      puts "Inserting documentation"
+      file_path = File.expand_path("../ta_lib_ffi.rb", __dir__)
+      content = File.read(file_path)
+
+      new_content = content.sub(
+        /### GENERATED DOCUMENTATION START ###.*### GENERATED DOCUMENTATION END ###/m,
+        "### GENERATED DOCUMENTATION START ###\n#{generate}\n    ### GENERATED DOCUMENTATION END ###"
+      )
+
+      File.write(file_path, new_content)
+    end
+
+    def remove
+      puts "Removing documentation"
+      file_path = File.expand_path("../ta_lib_ffi.rb", __dir__)
+      content = File.read(file_path)
+
+      new_content = content.sub(
+        /### GENERATED DOCUMENTATION START ###.*### GENERATED DOCUMENTATION END ###/m,
+        "### GENERATED DOCUMENTATION START ###\n    ### GENERATED DOCUMENTATION END ###"
+      )
+
+      File.write(file_path, new_content)
+    end
+
+    def generate
+      docs = []
+      TALibFFI.function_info_map.each_value do |h|
+        docs << generate_function_documentation(h[:info], h[:inputs], h[:opt_inputs], h[:outputs])
+      end
+      docs.join("\n")
+    end
+
+    def generate_function_documentation(func_info, inputs, opt_inputs, outputs)
+      [
+        generate_function_description(func_info, inputs, opt_inputs),
+        generate_input_documentation(inputs),
+        generate_optional_input_documentation(opt_inputs),
+        generate_output_documentation(outputs),
+        generate_error_documentation
+      ].flatten.compact.join("\n")
+    end
+
+    def generate_function_description(func_info, inputs, opt_inputs) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+      args = []
+      inputs.map do |input|
+        args << TALibFFI.normalize_parameter_name(input["paramName"].to_s)
+      end
+
+      opt_inputs.map do |opt_input|
+        param_name = TALibFFI.normalize_parameter_name(opt_input["paramName"].to_s)
+        args << "#{param_name}: #{opt_input["defaultValue"]}"
+      end
+
+      [
+        "    # @!method #{func_info["name"].to_s.downcase}(#{args.join(", ")})",
+        "    # #{func_info["hint"].to_s.strip}",
+        "    #"
+      ]
+    end
+
+    def generate_input_documentation(inputs) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+      inputs.map do |input| # rubocop:disable Metrics/BlockLength
+        param_name = TALibFFI.normalize_parameter_name(input["paramName"].to_s)
+        flags = TALibFFI.extract_flags(input["flags"], :TA_InputFlags)
+
+        type = case input["type"]
+               when TALibFFI::TA_PARAM_TYPE[:TA_Input_Price]
+                 array_types = Array.new(flags.length, "Array<Float>")
+                 "Array(#{array_types.join(", ")})"
+               when TALibFFI::TA_PARAM_TYPE[:TA_Input_Real]
+                 "Array<Float>"
+               when TALibFFI::TA_PARAM_TYPE[:TA_Input_Integer]
+                 "Array<Integer>"
+               end
+
+        description = if input["type"] == TALibFFI::TA_PARAM_TYPE[:TA_Input_Price]
+                        arrays = flags.map do |flag|
+                          {
+                            TA_IN_PRICE_OPEN: "open",
+                            TA_IN_PRICE_HIGH: "high",
+                            TA_IN_PRICE_LOW: "low",
+                            TA_IN_PRICE_CLOSE: "close",
+                            TA_IN_PRICE_VOLUME: "volume",
+                            TA_IN_PRICE_OPENINTEREST: "open interest",
+                            TA_IN_PRICE_TIMESTAMP: "timestamp"
+                          }[flag]
+                        end
+                        "Required price arrays: #{arrays.join(", ")}"
+                      else
+                        "Input values"
+                      end
+
+        "    # @param #{param_name} [#{type}]  #{description}"
+      end
+    end
+
+    def generate_optional_input_documentation(opt_inputs)
+      opt_inputs.map do |opt_input|
+        param_name = TALibFFI.normalize_parameter_name(opt_input["paramName"].to_s)
+        type = opt_input["type"] == TALibFFI::TA_PARAM_TYPE[:TA_OptInput_RealRange] ? "Float" : "Integer"
+        "    # @param #{param_name} [#{type}]  #{opt_input["hint"]} (default: #{opt_input["defaultValue"]})"
+      end
+    end
+
+    def generate_output_documentation(outputs) # rubocop:disable Metrics/MethodLength
+      if outputs.length == 1
+        type = outputs.first["type"] == TALibFFI::TA_PARAM_TYPE[:TA_Output_Real] ? "Float" : "Integer"
+        ["    # @return [Array<#{type}>]"]
+      else
+        [
+          "    # @return [Hash]  Hash containing the following arrays:",
+          *outputs.map do |output|
+            param_name = TALibFFI.normalize_parameter_name(output["paramName"].to_s)
+            type = output["type"] == TALibFFI::TA_PARAM_TYPE[:TA_Output_Real] ? "Float" : "Integer"
+            "    # @option result [Array<#{type}>] :#{param_name}  Output values"
+          end
+        ]
+      end
+    end
+
+    def generate_error_documentation
+      "    # @raise [TALibError]  If there is an error in function execution\n"
+    end
+  end
+end