red_cap 0.12.1 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd9606811238e9bdb1b1631958b96015870257419b4c83165631028ddbf2fdd2
-  data.tar.gz: a2604ed8e68436afbdcc4a7be836d827c9331a2610a8d245fdd04c000ff04aa7
+  metadata.gz: 48644d7de607c9ccde5f8314ec0ed2565924d2f83f266b7dccd03b200d0eec0b
+  data.tar.gz: 0afddb777531a00b7d4fbc687f38f392974262a8edb2f4a603d48022501bc043
 SHA512:
-  metadata.gz: 701a73e5cb940b753e4bfdf618d0667fa5a2a67a5267c4fafdadb6a5213805e83971a08c333c96f46cb1ebeb76e8f308939697f4a6b184a4dd15666d0ba9253b
-  data.tar.gz: c95e08ea6752e3c403c9abe84351cf1adb92bdfe20b249311e069c696b64266232f45a7b9276764e215e37cacc6bfb49f32c8c400971e1644aee4ad8619575a2
+  metadata.gz: 16463efe4a464d37ad171101b596afa9b958419e2452d08269d87f0e227de6e5e528420b9e3749570724798dab6971cef234f36ced87fb94c44f7d67129f1777
+  data.tar.gz: 07eff14d151bd692e8a12375aeac8191e291e7c95fcc31ed92aeed02353cd117e33423a84fa5f9b2c13144b811523b3b9cdc479f0ca097e38395372be09855f9

data/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ['3.2', '3.3', '3.4']
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Ruby ${{ matrix.ruby }}
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true
+
+    - name: Run tests
+      run: bundle exec rake spec
+
+    - name: Upload coverage to Codecov
+      if: matrix.ruby == '3.3'
+      uses: codecov/codecov-action@v5
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+        file: ./coverage/coverage.xml
+        fail_ci_if_error: false

data/README.md

@@ -1,28 +1,144 @@
 # REDCap
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/red_cap`. To experiment with that code, run `bin/console` for an interactive prompt.
+![CI](https://github.com/botandrose/red_cap/workflows/CI/badge.svg)
+![Coverage](https://codecov.io/gh/botandrose/red_cap/branch/master/graph/badge.svg)
 
-TODO: Delete this and the text above, and describe your gem
+A Ruby client library for connecting to REDCap (Research Electronic Data Capture) and parsing forms and data. REDCap is a secure web application for building and managing online surveys and databases, particularly for research studies.
 
-## Installation
+## Features
 
-Add this line to your application's Gemfile:
+- **REDCap API Integration**: Full client for REDCap's API endpoints
+- **Form Parsing**: Dynamic form handling with Ruby-friendly field access
+- **Field Type Support**: Comprehensive support for REDCap field types (text, radio buttons, checkboxes, dropdowns, etc.)
+- **Caching**: Optional response caching for improved performance
+- **Batch Operations**: Efficient handling of large datasets with pagination
+- **File Handling**: Support for file uploads and downloads
+
+## Configuration
+
+Configure the gem globally:
 
 ```ruby
-gem 'red_cap'
+REDCap.configure do |config|
+  config.url = "https://your-redcap-instance.org/api/"
+  config.token = "your_api_token_here"
+  config.per_page = 100  # optional, defaults to 100
+  config.cache = true    # optional, defaults to nil (no caching)
+end
 ```
 
-And then execute:
+Or create instances with specific configurations:
 
-    $ bundle
+```ruby
+client = REDCap.new(
+  url: "https://your-redcap-instance.org/api/",
+  token: "your_api_token_here",
+  per_page: 50
+)
+```
 
-Or install it yourself as:
+## Usage
 
-    $ gem install red_cap
+### Basic Data Operations
 
-## Usage
+```ruby
+# Find a specific record
+record = client.find("study_id_001")
+
+# Get all records (with block for memory efficiency)
+client.all do |record|
+  puts record["study_id"]
+end
+
+# Get all records as array
+records = client.all
+
+# Filter records
+client.where(status: 1, age: 25) do |record|
+  puts record["name"]
+end
+
+# Update a record
+client.update("study_id_001", { name: "John Doe", age: 30 })
+
+# Delete a record
+client.delete("study_id_001")
+```
+
+### Working with Forms
+
+```ruby
+# Access the form structure
+form = client.form
+
+# Access field values with dynamic methods
+form.responses = record_data
+puts form.participant_name  # accesses field "participant_name"
+puts form.age               # accesses field "age"
+puts form.consent_date      # accesses field "consent_date"
+
+# Check field types
+field = form.fields.find { |f| f.field_name == "gender" }
+puts field.radio?          # true if radio button field
+puts field.checkbox?       # true if checkbox field
+puts field.field_type      # "radio", "checkbox", etc.
+```
+
+### Field Types
+
+The gem supports various REDCap field types with appropriate Ruby representations:
+
+- **Text fields**: Return string values
+- **Yes/No fields**: Return boolean values
+- **Radio buttons**: Return selected option text
+- **Checkboxes**: Return array of selected options
+- **Dropdowns**: Return selected option text
+- **Files**: Return field name if file exists
+
+### Advanced Field Access
+
+```ruby
+# Override field type interpretation
+form.my_field(as: :radio_buttons)
+
+# Access with options
+form.checkbox_field(default: false)
+```
+
+### File Handling
+
+```ruby
+# Download a file
+file = client.client.file("record_id", "file_field_name")
+puts file.filename
+puts file.type
+# file.data contains the file content
+```
+
+### Caching
+
+Enable caching to improve performance for repeated API calls:
+
+```ruby
+REDCap.configure do |config|
+  config.cache = true
+end
+
+# Clear cache when needed
+REDCap::Cache.clear
+```
+
+## Field Types Reference
 
-TODO: Write usage instructions here
+| REDCap Type   | Ruby Class          | Return Value               |
+| ------------- | ------------------- | -------------------------- |
+| text          | Text                | String                     |
+| notes         | Notes               | String                     |
+| yesno         | Yesno               | Boolean                    |
+| radio         | RadioButtons        | String (selected option)   |
+| dropdown      | Dropdown            | String (selected option)   |
+| checkbox      | CheckboxesWithOther | Array of strings           |
+| file          | File                | String (field name) or nil |
 
 ## Development
 
@@ -32,7 +148,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/red_cap.
+Bug reports and pull requests are welcome on GitHub at https://github.com/botandrose/red_cap.
 
 ## License
 

data/lib/red_cap/cache.rb

@@ -18,6 +18,11 @@ class REDCap
         raw
       end
     end
+
+    def self.clear
+      dir = "tmp/redcap_cache"
+      FileUtils.rm_rf dir if ::File.exist?(dir)
+    end
   end
 end
 

data/lib/red_cap/client.rb

@@ -55,8 +55,6 @@ class REDCap
 
     File = Struct.new(:data, :type, :filename)
 
-    private
-
     def fetch_study_ids filter=nil
       json_api_request({
         content: "record",
@@ -66,17 +64,21 @@ class REDCap
     end
 
     require "active_support/core_ext/object/to_query"
-    def json_api_request options
-      full_url = @url + "?" + options.to_query
-      json = Cache.fetch(full_url) do
-        response = base_request(options.reverse_merge({
-          format: "json",
-        }))
-        response.body
+    def json_api_request options, cache: false
+      request_options = options.reverse_merge(format: "json")
+      json = if cache
+        full_url = @url + "?" + options.to_query
+        Cache.fetch(full_url) do
+          base_request(request_options).body
+        end
+      else
+        base_request(request_options).body
       end
       JSON.load(json)
     end
 
+    private
+
     def base_request options
       connection = Faraday.new(url: @url)
       connection.options.open_timeout = 300

data/lib/red_cap/form/fields.rb

@@ -164,7 +164,7 @@ class REDCap
           end
         end
 
-        if selected_options.keys.include?("501")
+        if selected_options(responses).keys.include?("501")
           right[-1] = [other_text_field("501")&.value(responses)]
         end
 

data/lib/red_cap/form.rb

@@ -3,8 +3,9 @@ require "active_support/core_ext/string/inflections"
 
 class REDCap
   class Form
-    def initialize data_dictionary
+    def initialize data_dictionary, responses=nil
       @data_dictionary = data_dictionary
+      @responses = responses
     end
 
     attr_accessor :data_dictionary, :responses
@@ -27,7 +28,7 @@ class REDCap
     def find_field key, field_class, options
       field = fields.find { |field| field.field_name == key }
       field = field_class.new(field.attributes) if field_class
-      field.options = options
+      field.options = options if field
       field
     end
 

data/lib/red_cap/instrument_table.rb

@@ -0,0 +1,58 @@
+class REDCap
+  class InstrumentTable < ActiveRecord::Base
+    self.table_name = :redcap_instrument_tables
+
+    class_attribute :config
+    def self.pulls_from config
+      self.config = config.reverse_merge({
+        key: :study_id,
+        repeating: false,
+      })
+
+      config[:fields].each do |field|
+        define_method field do
+          value = form.send(field)
+          value.define_singleton_method :var do
+            "#{config[:instrument_name]}.#{field}"
+          end
+          value
+        end
+      end
+    end
+
+    def self.pull client, filter={}
+      filter.reverse_merge!({
+        content: "record",
+        events: Array(config[:events] || config[:event]).join(","),
+        fields: [config[:key]] + config[:fields],
+      })
+
+      metadata = client.json_api_request({
+        content: "metadata",
+        fields: config[:fields],
+      }, cache: true)
+
+      client.json_api_request(filter).map do |response|
+        if config[:repeating]
+          next unless response["redcap_repeat_instrument"] == config[:instrument_name]
+          repeat_instance = response["redcap_repeat_instance"]
+        end
+        record = where({
+          instrument_name: config[:instrument_name],
+          repeat_instance: repeat_instance,
+          event: response.fetch("redcap_event_name"),
+          key: response.fetch(config[:key].to_s),
+        }).first_or_initialize
+        record.update!({
+          fields: response,
+          metadata: metadata,
+        })
+        record
+      end.compact
+    end
+
+    def form
+      @form ||= REDCap::Form.new(metadata, fields)
+    end
+  end
+end

data/lib/red_cap/version.rb

@@ -1,3 +1,3 @@
 class REDCap
-  VERSION = "0.12.1"
+  VERSION = "0.13.0"
 end

data/lib/red_cap.rb

@@ -3,6 +3,8 @@ require "red_cap/client"
 require "red_cap/form"
 
 class REDCap
+  autoload :InstrumentTable, "red_cap/instrument_table"
+
   class << self
     def configure
       yield self

data/red_cap.gemspec

@@ -27,4 +27,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec"
+  spec.add_development_dependency "simplecov"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: red_cap
 version: !ruby/object:Gem::Version
-  version: 0.12.1
+  version: 0.13.0
 platform: ruby
 authors:
 - Micah Geisel
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-04-22 00:00:00.000000000 Z
+date: 2025-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -80,6 +79,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Library for connecting to REDCap and parsing forms and data
 email:
 - micah@botandrose.com
@@ -87,6 +100,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/ci.yml"
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
@@ -101,13 +115,13 @@ files:
 - lib/red_cap/client.rb
 - lib/red_cap/form.rb
 - lib/red_cap/form/fields.rb
+- lib/red_cap/instrument_table.rb
 - lib/red_cap/version.rb
 - red_cap.gemspec
 homepage: https://github.com/botandrose/red_cap
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -122,8 +136,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.32
-signing_key: 
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Library for connecting to REDCap and parsing forms and data
 test_files: []