### Create a Basic Ruby Progress Bar

Source: https://github.com/jfelchner/ruby-progressbar/wiki/Basic-Usage

Demonstrates how to initialize a default progress bar. It starts at 0 with a maximum capacity of 100 and begins automatically. No external dependencies are required beyond the gem itself.

```ruby
progressbar = ProgressBar.create
```

--------------------------------

### Install ruby-progressbar Gem

Source: https://github.com/jfelchner/ruby-progressbar/wiki/Installation

Instructions for installing the ruby-progressbar gem using various methods, including gem install, Gemfile, and IRB.

```ruby
gem install ruby-progressbar
```

```ruby
require 'ruby-progressbar'
```

```ruby
gem 'ruby-progressbar'
```

```ruby
irb -r 'ruby-progressbar'
```

--------------------------------

### Basic Ruby Progress Bar Formatting

Source: https://github.com/jfelchner/ruby-progressbar/wiki/Example

Demonstrates creating a progress bar with elapsed time on the left and percentage complete with title on the right. This is a fundamental way to display progress.

```ruby
ProgressBar.create(:format => '%a %B %p%% %t')
```

```ruby
ProgressBar.create(:format => '%a <%B> %p%% %t')
```

```ruby
ProgressBar.create(:format => '%a |%b>>%i| %p%% %t', :starting_at => 10)
```

```ruby
ProgressBar.create format: "%a %e %P% Processed: %c from %C"
```

--------------------------------

### PAC-MAN Ruby Progress Bar

Source: https://github.com/jfelchner/ruby-progressbar/wiki/Example

Shows how to create a unique PAC-MAN themed progress bar by customizing the progress mark and remainder mark. This example highlights the flexibility in visual representation.

```ruby
ProgressBar.create( :format         => "%a %b\u{15E7}%i %p%% %t",
                    :progress_mark  => ' ',
                    :remainder_mark => "\u{FF65}",
                    :starting_at    => 10)
```

--------------------------------

### Securely Install ruby-progressbar Gem with Gem Signing

Source: https://github.com/jfelchner/ruby-progressbar/wiki/Installation

Steps to securely install the ruby-progressbar gem by adding the public key and using a high-security trust profile. This mitigates risks associated with gem replacement vulnerabilities.

```bash
gem cert --add <(curl -Ls https://raw.github.com/jfelchner/ruby-progressbar/master/certs/jfelchner.pem)
```

```bash
gem install ruby-progressbar -P HighSecurity
```

--------------------------------

### Create Basic and Customized Progress Bars in Ruby

Source: https://context7.com/jfelchner/ruby-progressbar/llms.txt

Demonstrates how to create a basic progress bar with default settings and a customized one with specific title, starting position, total count, format, and length. It also shows how to use custom marks for the progress and remainder.

```ruby
require 'ruby-progressbar'

# Basic progress bar with defaults
progressbar = ProgressBar.create
# Output: Progress: |                                                                       |

# Customized progress bar
progressbar = ProgressBar.create(
  :title       => "Downloading",
  :starting_at => 20,
  :total       => 200,
  :format      => "%t: |%B| %p%% %e",
  :length      => 80
)
# Output: Downloading: |=======                                        | 10% ETA: 00:01:30

# Progress bar with custom marks
progressbar = ProgressBar.create(
  :title          => "Processing",
  :progress_mark  => '#',
  :remainder_mark => '-',
  :total          => 50
)
# Output: Processing: |#####------------------------------------------------|

```

--------------------------------

### Create Customized Ruby Progress Bar

Source: https://github.com/jfelchner/ruby-progressbar/wiki/Options

Demonstrates how to create a customized progress bar in Ruby by passing options such as title, starting progress, and total items. This allows for tailored progress visualization.

```ruby
ProgressBar.create(:title => "Items", :starting_at => 20, :total => 200)
```

--------------------------------

### Increment Progress Bar in Ruby

Source: https://github.com/jfelchner/ruby-progressbar/wiki/Basic-Usage

Shows how to advance the progress bar by one unit. This method is called repeatedly to reflect task completion. The output is a visual representation of the progress.

```ruby
50.times { progressbar.increment }
```

--------------------------------

### Projectors for Smoothed Time Estimation - Ruby

Source: https://context7.com/jfelchner/ruby-progressbar/llms.txt

Illustrates configuring different 'smoothed' projectors to stabilize the Estimated Time Remaining (ETA) calculation, especially for workloads with variable item processing times. It shows examples of default smoothing, higher smoothing, and no smoothing.

```ruby
require 'ruby-progressbar'

# Default smoothed projector (strength 0.1)
progressbar = ProgressBar.create(
  :total     => 100,
  :format    => "%t: |%B| ETA: %e",
  :projector => {
    :type     => 'smoothed',
    :strength => 0.1
  }
)

# Higher smoothing for highly variable workloads
progressbar = ProgressBar.create(
  :total     => 100,
  :format    => "%t: |%B| ETA: %e",
  :projector => {
    :type     => 'smoothed',
    :strength => 0.5  # More smoothing (0.0-1.0 range)
  }
)

# No smoothing (classic linear estimation)
progressbar = ProgressBar.create(
  :total     => 100,
  :format    => "%t: |%B| ETA: %e",
  :projector => {
    :type     => 'smoothed',
    :strength => 0.0  # No smoothing
  }
)

# Simulate variable workload
100.times do |i|
  progressbar.increment
  sleep_time = i % 10 == 0 ? 0.5 : 0.05  # Every 10th item takes longer
  sleep sleep_time
end
```

--------------------------------

### Create Custom Output Stream for Ruby ProgressBar

Source: https://github.com/jfelchner/ruby-progressbar/wiki/Custom-Output-Classes

Defines a custom output class `MyOutput` that inherits from `ProgressBar::Output` and overrides methods to direct output to a specific stream, such as `$stdout`. This example shows how to customize log messages, update strings, and formats, and explicitly defines the `stream` method to return `$stdout`.

```ruby
class MyOutput < ProgressBar::Output
  alias refresh_with_format_change with_refresh

  # This is REQUIRED for the custom output class to work properly
  def stream
    $stdout
  end

  def clear
    stream.print clear_string
    stream.print "\r"
  end

  def log(message)
    clear
    stream.puts "This is a log statement \/ \/ \/"
    stream.puts message

    refresh(:force => true) unless bar.stopped?
  end

  def bar_update_string
    bar.to_s + ' ' + Time.now.iso8601
  end

  def default_format
    'This is some custom stuff %w%i'
  end

  def resolve_format(_format)
    default_format
  end

  def eol
    "\n"
  end
end
```

--------------------------------

### Get ProgressBar Data as Hash (Ruby)

Source: https://github.com/jfelchner/ruby-progressbar/wiki/Output-as-Hash

Retrieves all current data from a ProgressBar instance as a Hash. This is useful for logging, metrics, or custom display logic without rendering the progress bar. It requires an initialized ProgressBar object.

```ruby
progressbar = ProgressBar::Base.new(:output         => output,
                                    :total          => 33,
                                    :title          => 'My Title',
                                    :progress_mark  => 'x',
                                    :remainder_mark => '-',
                                    :length         => 92,
                                    :rate_scale     => lambda { |rate| rate * 200 },
                                    :throttle_rate  => 12.3)

# Make some progress updates over a period of time

progressbar.to_h
```

```ruby
{
  'output_stream'                       => #<StringIO:0x007fdf2d056928>,
  'length'                              => 92,
  'title'                               => 'My Title',
  'progress_mark'                       => 'x',
  'remainder_mark'                      => '-',
  'progress'                            => 22,
  'total'                               => 33,
  'percentage'                          => 66.66,
  'elapsed_time_in_seconds'             => 599.99994701264,
  'estimated_time_remaining_in_seconds' => 400,
  'base_rate_of_change'                 => 0.03672787979966611,
  'scaled_rate_of_change'               => 7.345575959933222,
  'unknown_progress_animation_steps'    => ['=---', '-=--', '--=-', '---='],
  'throttle_rate'                       => 12.3,
  'started?'                            => 2012-07-26 12:50:00 -0500,
  'stopped?'                            => false,
  'finished?'                           => false
}
```

--------------------------------

### Basic Progress Bar Creation in Ruby

Source: https://github.com/jfelchner/ruby-progressbar/wiki/_Sidebar

Demonstrates how to create and initialize a basic progress bar using the ruby-progressbar gem. This is the fundamental step for displaying progress in Ruby applications. No external dependencies beyond the gem itself are required for this basic usage.

```ruby
require 'progressbar'

bar = ProgressBar.new('Processing', 100)

# ... later in your code ...

bar.increment
bar.finish
```

--------------------------------

### Handling Unknown Progress in Ruby

Source: https://github.com/jfelchner/ruby-progressbar/wiki/_Sidebar

Explains how to use the ruby-progressbar gem for tasks where the total number of steps is unknown beforehand. This involves using a different progress bar initialization and updating it as work progresses. It's useful for streaming data or indefinite processes.

```ruby
require 'progressbar'

bar = ProgressBar.new('Processing Data')
bar.file_mode = false

# Simulate receiving data chunks
10.times do |i|
  sleep(0.5)
  bar.increment
  bar.log("Received chunk #{i+1}")
end

bar.finish
```

--------------------------------

### Manage Progress Bar Lifecycle (Finish, Stop, Pause, Reset) in Ruby

Source: https://context7.com/jfelchner/ruby-progressbar/llms.txt

Explains how to manage the progress bar's state using methods like `finish`, `stop`, `pause`, `resume`, and `reset`. Covers auto-finishing behavior, manual completion, stopping at the current progress, pausing and resuming to preserve elapsed time, and resetting the bar to its initial state.

```ruby
require 'ruby-progressbar'

# Auto-finish (default behavior)
progressbar = ProgressBar.create(:starting_at => 99, :total => 100)
progressbar.increment
progressbar.finished?  # => true

# Disable auto-finish
progressbar = ProgressBar.create(:starting_at => 99, :total => 100, :autofinish => false)
progressbar.increment
progressbar.finished?  # => false
progressbar.finish     # Manually complete - jumps to 100%

# Stop without completing
progressbar = ProgressBar.create(:total => 100)
50.times { progressbar.increment }
progressbar.stop       # Stops at current position (50%)
progressbar.stopped?   # => true

# Pause and resume (preserves elapsed time)
progressbar = ProgressBar.create(:total => 100)
30.times { progressbar.increment }
progressbar.pause
# ... do other work ...
progressbar.resume     # Continue from 30%

# Reset to initial state
progressbar = ProgressBar.create(:starting_at => 10, :total => 100)
50.times { progressbar.increment }
progressbar.reset      # Returns to starting_at (10)

```

--------------------------------

### Create Progress Bar with Integrated Percentage (Ruby)

Source: https://context7.com/jfelchner/ruby-progressbar/llms.txt

Illustrates creating a progress bar that shows the percentage completion integrated within the bar itself, using the `%W` token in the `:format` string.

```ruby
require 'ruby-progressbar'

progressbar = ProgressBar.create(
  :format => "%t: |%W|",
  :total  => 100
)
50.times { progressbar.increment }
```

--------------------------------

### Direct Usage with Times and Custom Format - Ruby

Source: https://context7.com/jfelchner/ruby-progressbar/llms.txt

Demonstrates direct usage of the progress bar by iterating a range of numbers and applying a custom format string. This method is useful for simple progress tracking during iterative processes.

```ruby
10.times.with_progressbar(:format => "%t: |%B| %c/%C") do |i|
  # Process item i
  sleep 0.1
end
```

--------------------------------

### Colorize Only the Bar of Progressbar with Blue using ANSI Codes (Ruby)

Source: https://github.com/jfelchner/ruby-progressbar/wiki/Colorizing-Your-Bar

This example shows how to colorize only the bar portion of a ruby-progressbar while keeping the text elements in the default color. It achieves this by embedding the ANSI blue color code (`\e[0;34m`) only around the '%B' format specifier, which represents the progress bar itself. The length of the progressbar is explicitly set to 80 characters.

```ruby
progressbar = ProgressBar.create(format: "%t: |\e[0;34m%B\e[0m|", length: 80)

100.times { progressbar.increment; sleep 0.1 }
```

--------------------------------

### Enumerable Extension for Progress Bars in Ruby

Source: https://github.com/jfelchner/ruby-progressbar/wiki/_Sidebar

Shows how to use the Enumerable extension provided by the ruby-progressbar gem. This allows you to easily wrap iterators with a progress bar, automatically handling increments and completion. It simplifies progress tracking for collection processing.

```ruby
require 'progressbar/ TTY'

items = (1..100).to_a

bar = ProgressBar::TTY.new('Processing Items', items.size)

items.each do |item|
  # Simulate work
  sleep(0.05)
  bar.log("Processed item: #{item}") if item % 10 == 0
end.with_progressbar(bar)
```

--------------------------------

### Use Enumerator Refinement with Progress Bar (Ruby)

Source: https://context7.com/jfelchner/ruby-progressbar/llms.txt

Demonstrates using the `Enumerator` refinement `with_progressbar` to automatically track progress when iterating over collections. This method accepts most `ProgressBar.create` options.

```ruby
require 'ruby-progressbar'

class DataProcessor
  using ProgressBar::Refinements::Enumerator

  def self.process(items)
    results = []

    items.each.with_progressbar(:title => "Processing", :progress_mark => '+') do |item|
      results << transform(item)
      sleep 0.1  # Simulate work
    end

    results
  end

  def self.transform(item)
    item.to_s.upcase
  end
end

# Usage
data = %w[apple banana cherry date elderberry fig grape]
processed = DataProcessor.process(data)
```

--------------------------------

### Create Progress Bar with Custom Format (Ruby)

Source: https://context7.com/jfelchner/ruby-progressbar/llms.txt

Demonstrates creating a progress bar with a custom format string that includes the current/total count and elapsed time. The `ProgressBar.create` method is used with a `:format` option.

```ruby
require 'ruby-progressbar'

progressbar = ProgressBar.create(
  :format => "%t: %c of %C |%w%i| Elapsed: %a",
  :total  => 500
)
125.times { progressbar.increment }
```

--------------------------------

### Customize Progress Bar Format Strings in Ruby

Source: https://context7.com/jfelchner/ruby-progressbar/llms.txt

Details how to customize the visual appearance of the progress bar using format strings. Explains the default format and demonstrates how to include various flags like title (`%t`), bar (`%B`), percentage (`%p`), ETA (`%e`), elapsed time (`%a`), current/total count (`%c/%C`), and rate (`%r`).

```ruby
require 'ruby-progressbar'

# Default format: "%t: |%B|"
progressbar = ProgressBar.create(:total => 100)
# Output: Progress: |                                                                       |

# Show percentage and ETA
progressbar = ProgressBar.create(
  :format => "%t: |%B| %p%% Complete, ETA: %e",
  :total  => 100
)
40.times { progressbar.increment }
# Output: Progress: |=========================                        | 40% Complete, ETA: 00:00:30

```

--------------------------------

### Customizing Progress Bar Formatting in Ruby

Source: https://github.com/jfelchner/ruby-progressbar/wiki/_Sidebar

Demonstrates how to customize the appearance of the progress bar using format strings. This allows for flexible display of information like percentage, elapsed time, and estimated time remaining. The `format` option controls the output string.

```ruby
require 'progressbar'

bar = ProgressBar.new('Custom Format', 100, :bar, :percentage, :eta, :elapsed)
bar.format_with("%a %b %c %e")

100.times do |i|
  sleep(0.05)
  bar.increment
end
```

--------------------------------

### Use Custom Null Output with Ruby ProgressBar

Source: https://github.com/jfelchner/ruby-progressbar/wiki/Custom-Output-Classes

Demonstrates how to instantiate a `ProgressBar` with the custom `MyNullOutput` class. By passing an instance of `MyNullOutput` to the `output` option during creation, the progress bar will effectively be silenced.

```ruby
progressbar = ProgressBar.create(output: MyNullOutput.new)
```

--------------------------------

### Increment, Decrement, and Set Progress in Ruby

Source: https://context7.com/jfelchner/ruby-progressbar/llms.txt

Illustrates methods for controlling the progress bar's position. Includes incrementing by one, decrementing by one, setting the progress to a specific value, and using += / -= for relative adjustments.

```ruby
require 'ruby-progressbar'

progressbar = ProgressBar.create(:total => 100)

# Increment by 1
50.times { progressbar.increment }
# Output: Progress: |===================================                                    |

# Decrement by 1
10.times { progressbar.decrement }
# Output: Progress: |============================                                           |

# Set progress directly
progressbar.progress = 75
# Output: Progress: |====================================================                   |

# Increment/decrement by amount
progressbar.progress += 10
progressbar.progress -= 5
# Output: Progress: |========================================================               |

```

--------------------------------

### Real-time Customization of Progress Bar (Ruby)

Source: https://context7.com/jfelchner/ruby-progressbar/llms.txt

Shows how to dynamically change the progress bar's appearance in real-time using setter methods like `title=`, `progress_mark=`, `remainder_mark=`, and `format=`. These changes update the bar immediately.

```ruby
require 'ruby-progressbar'

progressbar = ProgressBar.create(
  :title          => "Downloading",
  :progress_mark  => '=',
  :remainder_mark => ' ',
  :total          => 100
)

100.times do |i|
  progressbar.increment

  # Update title based on progress
  case i
  when 30
    progressbar.title = "Processing"
  when 60
    progressbar.title = "Finishing"
    progressbar.progress_mark = '#'
  when 90
    progressbar.title = "Complete"
    progressbar.format = "%t: |%B| %p%% Done!"
  end

  sleep 0.03
end
```

--------------------------------

### Ruby ProgressBar: Default Autofinish Behavior

Source: https://github.com/jfelchner/ruby-progressbar/wiki/Finishing

Demonstrates the default autofinish behavior of the Ruby ProgressBar. When the current value reaches the total, the `finished?` method returns true. No external dependencies are required beyond the gem itself.

```ruby
progressbar = ProgressBar.create(:starting_at => 9, :total => 10)
progressbar.increment

progressbar.finished? # => true
```

--------------------------------

### Create Progress Bar with Rate of Change Display (Ruby)

Source: https://context7.com/jfelchner/ruby-progressbar/llms.txt

Shows how to create a progress bar that displays the rate of items processed per second. This is achieved using the `%R` token in the `:format` string.

```ruby
require 'ruby-progressbar'

progressbar = ProgressBar.create(
  :format => "%t: |%B| %R items/sec",
  :total  => 1000
)
```

--------------------------------

### Throttling Progress Bar Updates in Ruby

Source: https://github.com/jfelchner/ruby-progressbar/wiki/_Sidebar

Explains how to implement throttling for progress bar updates to avoid excessive screen flickering or performance overhead. This is particularly useful when updates occur very rapidly. The `throttle_rate` option can be used.

```ruby
require 'progressbar'

bar = ProgressBar.new('Throttled Updates', 1000)
bar.throttle_rate = 0.1 # Update at most every 0.1 seconds

1000.times do |i|
  # Simulate very frequent updates
  bar.increment
end

bar.finish
```

--------------------------------

### Suppress ProgressBar Output with Null Output (Ruby)

Source: https://github.com/jfelchner/ruby-progressbar/wiki/Null-(Blackhole)-Output

Demonstrates how to initialize a ProgressBar with `ProgressBar::Outputs::Null` to prevent any output. This method is useful when you only need to access the final state of the progress bar and want to avoid displaying intermediate updates. It requires the `ruby-progressbar` gem and specifically the `ruby-progressbar/outputs/null` file.

```ruby
require 'ruby-progressbar/outputs/null'

progressbar = ProgressBar.create(output: ProgressBar::Outputs::Null)

progressbar.increment
progressbar.reset
progressbar.clear
progressbar.progress += 20
progressbar.finish

# No output will be visible for the above operations.
```

--------------------------------

### Accessing Progress Data as Hash - Ruby

Source: https://context7.com/jfelchner/ruby-progressbar/llms.txt

Shows how to retrieve all progress bar data, including current progress, total, percentage, elapsed time, ETA, and status flags, as a Hash using the `to_h` method. This is valuable for logging, metrics, or custom display implementations.

```ruby
require 'ruby-progressbar'

progressbar = ProgressBar.create(
  :title          => "Processing",
  :total          => 100,
  :progress_mark  => 'x',
  :remainder_mark => '-',
  :length         => 80,
  :throttle_rate  => 0.1
)

50.times { progressbar.increment; sleep 0.02 }

data = progressbar.to_h
# Returns a hash with progress data

# Example: Log metrics to file
File.write('progress_log.txt', "Completed #{data['percentage']}% in #{data['elapsed_time_in_seconds']}s")
```

--------------------------------

### Null Output for Silent Progress Tracking - Ruby

Source: https://context7.com/jfelchner/ruby-progressbar/llms.txt

Demonstrates using `ProgressBar::Outputs::Null` to create a progress bar that tracks progress internally without producing any console output. This is useful for CLI applications that manage their own UI or when only internal data access is needed.

```ruby
require 'ruby-progressbar'
require 'ruby-progressbar/outputs/null'

# Silent progress bar - no output
progressbar = ProgressBar.create(
  :output => ProgressBar::Outputs::Null,
  :total  => 100
)

# All operations work, just no display
50.times { progressbar.increment }
progressbar.progress  # => 50
progressbar.to_s      # => "Progress: |===================================                                    |"

# Access data for custom rendering
data = progressbar.to_h
puts "Progress: #{data['percentage']}%"

progressbar.finish
progressbar.finished?  # => true
```

--------------------------------

### Verify Checksums for ruby-progressbar Releases

Source: https://github.com/jfelchner/ruby-progressbar/wiki/Installation

How to retrieve and verify checksums for ruby-progressbar gem releases using curl. Supports SHA512, SHA256, and MD5 algorithms.

```bash
curl --silent https://raw.githubusercontent.com/jfelchner/ruby-progressbar/master/checksum/ruby-progressbar-1.8.0.gem.sha256
=> 78020988fc8603843747e316edb8fc50481c6842583eab5749e29fbbc9660f54
```

--------------------------------

### Create Indeterminate Progress Bar (Ruby)

Source: https://context7.com/jfelchner/ruby-progressbar/llms.txt

Demonstrates creating an indeterminate progress bar when the total number of items is unknown by setting `:total => nil`. The bar animates until the total is known and set.

```ruby
require 'ruby-progressbar'

# Start with unknown total
progressbar = ProgressBar.create(:starting_at => 20, :total => nil)

# Each increment animates the unknown pattern
progressbar.increment
progressbar.increment

# Custom animation steps
progressbar = ProgressBar.create(
  :total => nil,
  :unknown_progress_animation_steps => ['|    ', ' |   ', '  |  ', '   | ', '    |']
)

# Set the total when discovered - bar transforms to normal mode
progressbar.total = 100
```

--------------------------------

### Marking Progress in Ruby

Source: https://github.com/jfelchner/ruby-progressbar/wiki/_Sidebar

Illustrates how to update the progress bar to reflect completed work. This involves incrementing the bar's value as tasks are finished. It's essential for providing visual feedback to the user about the ongoing process.

```ruby
require 'progressbar'

bar = ProgressBar.new('Downloading', 50)

50.times do |i|
  # Simulate work
  sleep(0.1)
  bar.increment
end

bar.finish
```

--------------------------------

### Progress Bar Manipulation Methods

Source: https://github.com/jfelchner/ruby-progressbar/wiki/Changing-Progress

This section covers the core methods for manipulating the progress bar's state, such as incrementing, decrementing, and setting the progress value.

```APIDOC
## Progress Bar Manipulation Methods

### Description
These methods allow you to directly control the progress and total count of the progress bar.

### Method
`#increment`

### Endpoint
N/A (Instance Method)

### Parameters
None

### Request Example
```ruby
progressbar.increment
```

### Response
#### Success Response (N/A)
Advances the progress bar by 1 unit.

### Method
`#decrement`

### Endpoint
N/A (Instance Method)

### Parameters
None

### Request Example
```ruby
progressbar.decrement
```

### Response
#### Success Response (N/A)
Retracts the progress bar by 1 unit.

### Method
`#progress+=`

### Endpoint
N/A (Instance Method)

### Parameters
- **amount** (Integer) - Required - The relative amount to increment the progress by.

### Request Example
```ruby
progressbar.progress += 5
```

### Response
#### Success Response (N/A)
Increments the progress bar by the specified relative amount.

### Method
`#progress-=`

### Endpoint
N/A (Instance Method)

### Parameters
- **amount** (Integer) - Required - The relative amount to decrement the progress by.

### Request Example
```ruby
progressbar.progress -= 2
```

### Response
#### Success Response (N/A)
Decrements the progress bar by the specified relative amount.

### Method
`#progress=`

### Endpoint
N/A (Instance Method)

### Parameters
- **value** (Integer) - Required - The absolute value to set the progress to.

### Request Example
```ruby
progressbar.progress = 50
```

### Response
#### Success Response (N/A)
Sets the progress bar to the specified absolute value. Note: This may affect time estimations.

### Method
`#total=`

### Endpoint
N/A (Instance Method)

### Parameters
- **value** (Integer or nil) - Required - The new total number of items to process. Cannot be less than the current progress.

### Request Example
```ruby
progressbar.total = 100
```

### Response
#### Success Response (N/A)
Changes the total number of items the progress bar is tracking. The new total cannot be less than the current accumulated progress.
```

--------------------------------

### Initialize Ruby ProgressBar with Unknown Total

Source: https://github.com/jfelchner/ruby-progressbar/wiki/Unknown-Progress

Initializes a ProgressBar in Ruby with an unknown total. This is useful when the number of items to process is not known beforehand. The bar will display an 'unknown' animation.

```ruby
progressbar = ProgressBar.create(:starting_at => 20, :total => nil)
```

--------------------------------

### Colorizing Progress Bars in Ruby

Source: https://github.com/jfelchner/ruby-progressbar/wiki/_Sidebar

Shows how to add color to the progress bar output using ANSI escape codes. This enhances readability and visual appeal. The gem supports colorization through specific format specifiers or by directly embedding color codes.

```ruby
require 'progressbar'

bar = ProgressBar.new('Colored Bar', 100)
bar.format_with("%{\e[32m"}%.1f%% %b %e%{color_reset}")

100.times do |i|
  sleep(0.05)
  bar.increment
end
```

--------------------------------

### Log Output with Ruby Progress Bar

Source: https://github.com/jfelchner/ruby-progressbar/wiki/Logging

Demonstrates the correct way to log messages while a progress bar is active. Uses the `#log` method to ensure the message is displayed correctly and the progress bar is redrawn afterwards. This avoids the overwriting issue seen with standard `puts` statements.

```ruby
require 'ruby-progressbar'

progressbar = ProgressBar.create
progressbar.progress = 20
progressbar.log 'hello'
```

--------------------------------

### Progressbar Customization API

Source: https://github.com/jfelchner/ruby-progressbar/wiki/Realtime-Customization

This section covers methods for customizing the visual representation and format of the progress bar.

```APIDOC
## Progressbar Customization API

### Description
This API allows you to customize the appearance and format of the progress bar. Changes made to these attributes will result in an immediate refresh of the progress bar.

### Method
Various setter methods and a formatting method are available.

### Endpoints
N/A (These are object methods, not REST endpoints)

### Parameters
#### `#progress_mark=`
- **progress_mark** (String) - Required - Sets the string used to represent progress along the bar.

#### `#remainder_mark=`
- **remainder_mark** (String) - Required - Sets the string used to represent the empty part of the bar.

#### `#title=`
- **title** (String) - Required - Sets the string to represent the items the bar is tracking or any other descriptive text.

#### `#format(format_string)`
- **format_string** (String) - Required - A string defining the custom format for the progress bar rendering. See [Formatting](https://github.com/jfelchner/ruby-progressbar/wiki/Formatting) for details.

### Request Example
```ruby
bar = ProgressBar.new
bar.progress_mark = "#"
bar.remainder_mark = "-"
bar.title = "Processing items:"
bar.format("%t |%b| %p%% %e")
```

### Response
#### Success Response (N/A)
These methods modify the state of the progress bar object directly and do not return specific values in the context of an API response.

#### Response Example
N/A
```

--------------------------------

### Customize Unknown Progress Animation in Ruby

Source: https://github.com/jfelchner/ruby-progressbar/wiki/Custom-Unknown-Progress-Animations

This snippet shows how to initialize a Ruby progress bar with custom animation steps for unknown progress. It takes an array of strings, where each string represents a frame of the animation. The specific frame displayed depends on the current progress value.

```ruby
progressbar = ProgressBar.create(:total => nil, :unknown_progress_animation_steps => ['==>', '>==', '=>='])
```

--------------------------------

### Ruby ProgressBar: Disabling Autofinish

Source: https://github.com/jfelchner/ruby-progressbar/wiki/Finishing

Illustrates how to disable the autofinish feature in Ruby ProgressBar. By setting `:autofinish => false`, the `finished?` method will return false even if the current value equals the total, allowing for manual control over completion. This requires the ProgressBar gem.

```ruby
progressbar = ProgressBar.create(:starting_at => 9, :total => 10, :autofinish => false)
progressbar.increment

progressbar.finished? # => false
```

--------------------------------

### Create Null Output for Ruby ProgressBar

Source: https://github.com/jfelchner/ruby-progressbar/wiki/Custom-Output-Classes

Defines a custom output class `MyNullOutput` that inherits from `ProgressBar::Output` and overrides methods to perform no action. This is useful for scenarios where the progress bar should not be displayed, such as in CLI tools that only need the progress bar's string representation.

```ruby
require 'ruby-progressbar/output'

class MyNullOutput < ProgressBar::Output
  alias refresh_with_format_change with_refresh

  def clear;        end
  def log(_string); end
  def refresh(*);   end

  def clear_string
    ''
  end

  def bar_update_string
    ''
  end

  def default_format
    ''
  end

  def resolve_format(_format)
    ''
  end

  def eol
    ''
  end
end
```

--------------------------------

### Configure Smoothed Projector in Ruby Progress Bar

Source: https://github.com/jfelchner/ruby-progressbar/wiki/Projectors

This snippet demonstrates how to configure the 'smoothed' projector when creating a ProgressBar instance in Ruby. It specifies the projector type and its strength for exponential smoothing. The 'strength' option controls the degree of smoothing, with 0.0 being no smoothing and 1.0 being maximum smoothing. The default strength is 0.1.

```ruby
ProgressBar.create(
  :projector => {
    :type     => 'smoothed',
    :strength => 0.1
  }
)
```

--------------------------------

### Customize Progress Bar Rate Display in Ruby

Source: https://github.com/jfelchner/ruby-progressbar/wiki/Rate-Scaling

This snippet shows how to customize the progress bar's rate display to show kilobytes per second. It utilizes the `:format` option to include the desired units and the `:rate_scale` option with a lambda function to perform the conversion from bytes to kilobytes. This is useful for representing transfer speeds more intuitively.

```ruby
ProgressBar.create(:format     => '%a %B %p%% %r KB/sec',
                   :rate_scale => lambda { |rate| rate / 1024 })

```

--------------------------------

### Use Enumerator Refinement for Progress Bar in Ruby

Source: https://github.com/jfelchner/ruby-progressbar/wiki/Using-Enumerators

This Ruby code snippet demonstrates how to use the `ProgressBar::Refinements::Enumerator` refinement to add progress bar functionality to an Enumerator. It allows for automatic progress bar creation and incrementing for each item processed. The `total` and `starting_at` options are automatically managed.

```ruby
class Fibonacci
  using ProgressBar::Refinements::Enumerator

  def self.generate(quantity = 10)
    sequence = []

    quantity.times.with_progressbar(progress_mark: '+') do |index|
      sequence << fibonacci(index)
    end

    sequence
  end

  private

  def self.fibonacci(position)
    return position if ( 0..1 ).include?(position)

    fibonacci(position - 1) + fibonacci(position - 2)
  end
end
```

--------------------------------

### Throttle ProgressBar Output in Ruby

Source: https://github.com/jfelchner/ruby-progressbar/wiki/Throttling

This snippet demonstrates how to configure a ProgressBar to throttle its console output using the `:throttle_rate` option. This is useful for very fast operations where progress bar output might otherwise be too frequent. The rate is specified in seconds, with a lower number indicating more frequent updates. The default rate is 0.01 seconds (100 updates per second).

```ruby
ProgressBar.create(:throttle_rate => 0.1)
```

--------------------------------

### Log Messages Without Disrupting Progress Bar (Ruby)

Source: https://context7.com/jfelchner/ruby-progressbar/llms.txt

Explains and demonstrates the `log` method for printing messages while a progress bar is active. Unlike `puts`, `log` clears the bar, prints the message, and redraws the bar.

```ruby
require 'ruby-progressbar'

progressbar = ProgressBar.create(:total => 100)

100.times do |i|
  progressbar.increment

  # Log a message every 25 items
  if (i + 1) % 25 == 0
    progressbar.log "Processed #{i + 1} items"
  end

  sleep 0.02
end
```