Black Bytes
Share this post!

An Object That Behaves Like a File?

If you are looking for an object that behaves like an IO object (files, sockets, etc), but that you can control like a string, then StringIO is for you.

Let me show you some examples & things to watch out for!

Basic Examples

To create a StringIO object you can do this:

Then you can read from this object using methods like gets, read & each_line.

I made a handy table for you with the most useful methods:

Method Description
gets Read one line of input
read Read a specific amount of bytes (all by default)
each_line Given a block, iterate over each line
each_char Given a block, iterate over each character
<< Append data
rewind Reset the internal position pointer

Notice that StringIO has a position pointer. This pointer keeps track of how many bytes you have read, just like a file object does.

So every time you call a method like gets or read it will give you that amount of data & advance the pointer.

Even Enumerable methods like map or each_line will advance the position pointer, so keep that in mind.

You can reset the position pointer to the beginning using the rewind method:

That’s it for the basics. I’m going to show you some practical uses for StringIO, but first let me show you something else.

What About StringScanner?

Now you have seen what StringIO can do, but the Ruby Standard Library includes another string-related class.

That class is StringScanner.

It can be confusing since they have similar names & methods, but let me help you see the difference.

The main thing is this:

A StringIO object can replace another IO object (like a File or a Socket), but StringScanner is meant for doing things like parsing (making sense of some text by breaking it into a set of tokens).

These two classes still share something, besides having “String” in their name, they both use an internal position pointer.

Replacing Standard Input & Output

Let’s say you are writing a command-line application that ask user for output using the Kernel#gets method…

…if you want to test this code you are going to have to input something by hand every time.

So is automated testing out of the picture?

No, it isn’t!

This is where StringIO comes to the rescue. You can initialize a StringIO object with your test input & then replace the standard input object pointed by $stdin (this where Ruby looks for user input when you call gets).

This technique can also be used to capture output from methods like puts.

Display methods print to the default output device, known as ‘standard output’. In Ruby this is represented by an IO object which you can replace with your StringIO object.

Example:

This is more involved than the input version, because we want to make sure to restore the original STDOUT object & to rewind our StringIO so we can read the output.

Notice that most testing frameworks include a method to do this for you (assert_output for Minitest & the output matcher in RSpec), but it’s always great to know what’s going on behind the scenes 🙂

Summary

You learned about the StringIO class, which emulates a real IO object so it can act as a replacement for that kind of object.

This can be useful for testing classes that write output to the screen or require user input via the terminal.

If you know about some interesting uses for StringIO let us know in the comments & don’t forget to share this article so more people can enjoy it!

Leave a Comment:

2 comments
Fredrik Svärd says last month

First, thanks for an awesome site and very nice examples!

A flaw in this post

‘…You wrote ‘Let’s say you are writing a command-line application that ask user for output using the…’

I think you mean:

‘…Let’s say you are writing a command-line application that ask user for input using the…’

Reply
    Jesus Castello says last month

    Thanks for reading 🙂

    Reply
Add Your Reply