Skip to content
Tutorials Center
My learning

Topics

Lesson 80 of 134 · Standard Library

YAML and CSV

Learn YAML and CSV in Ruby - YAML.dump and safe loading, permitted classes, CSV.parse with headers and converters, CSV.generate, quoting rules, malformed data errors and the CSV bundled gem.

Two other text formats show up constantly in everyday programs. YAML is a human-friendly format for configuration files (Rails, Docker Compose, CI pipelines and this very website's lesson front matter use it). CSV (comma-separated values) is the lowest common denominator of tabular data: spreadsheets, database exports and bank statements. Ruby handles both in its standard distribution: yaml (a wrapper around the Psych library) and csv.

A quick note on packaging. yaml is a default library that ships inside Ruby. csv is a bundled gem: since Ruby 3.4 it is installed with Ruby but is no longer loaded by default, and in a real project that uses Bundler you must list it in your Gemfile (gem "csv") or require 'csv' fails under bundle exec. The runner on this page has it installed, so the examples run here. It was a core part of Ruby for 20 years, so you will see it in older code with no Gemfile entry. This lesson builds on JSON, hashes and exceptions.

Writing YAML

Ruby YAML.dump and to_yaml

Press Run (or Ctrl + Enter) to see the result here.

Program input · what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

The output starts with ---, the document marker. Hashes become key: value lines, arrays become - item lines, and indentation shows nesting. Notice that symbols are written with a leading colon (:three, :name:). That is a Ruby-specific YAML tag, not something other languages understand, which matters for the next section.

Reading YAML safely

Ruby YAML.load, safe_load and permitted classes

Press Run (or Ctrl + Enter) to see the result here.

Program input · what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

The sample shows YAML's famous type guessing. debug: no and enabled: yes become false and true in the YAML 1.1 rules Psych follows, version: 1.10 becomes the float 1.1 (the trailing zero is lost), an empty value becomes nil, and quoting "01234" keeps a string. When a value must stay text (versions, zip codes, phone numbers, country codes like no for Norway) always quote it.

Never feed untrusted text to a loader that can build arbitrary Ruby objects. In old versions of Ruby, YAML.load could instantiate any class from tags in the document, which led to serious remote code execution bugs in web applications. Modern Psych (version 4 and later) makes YAML.load safe by default and refuses arbitrary classes, but the clear, intention-revealing choice is still YAML.safe_load with permitted_classes: for exactly the classes you expect.

Files and your own classes

Reading and writing files uses YAML.load_file(path) (or safe_load_file) and File.write(path, data.to_yaml). Here is a round trip through a temporary file, and what happens with an object of your own class:

Ruby Files and objects in YAML

Press Run (or Ctrl + Enter) to see the result here.

Program input · what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Dumping your own objects writes Ruby-specific tags (!ruby/struct:Point), which ties the file to your code. Loading it back needs permission for the class and for Symbol, because a struct stores its member names as symbols: with only [Point] you get Psych::DisallowedClass: Tried to load unspecified class: Symbol. For configuration that humans edit or other programs read, convert to plain hashes, arrays and scalars first. Look at the last output line: the key y is written as "y": 2 with quotes, because in YAML 1.1 a bare y means true, so the dumper protects it. Call YAML.unsafe_load only on data you wrote yourself and fully trust.

CSV: reading rows

Remember require 'csv' (bundled gem, see the introduction). CSV text is lines of fields separated by commas; fields with commas or quotes inside are wrapped in double quotes, and a quote inside a field is doubled.

Ruby CSV.parse with and without headers

Press Run (or Ctrl + Enter) to see the result here.

Program input · what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Without headers: true, you get an array of arrays, and every value is a string ("4", not 4). With headers, you get a CSV::Table of CSV::Row objects that you can index by column name. An empty field between commas becomes nil, while an empty quoted field "" becomes the empty string. Reading row['qty'] on a missing cell gives nil, so a blank quantity needs handling, which the next example does with converters.

Converters and symbol headers

Ruby converters and header_converters

Press Run (or Ctrl + Enter) to see the result here.

Program input · what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

converters: :numeric turns fields that look like numbers into Integer or Float; :integer, :float and :date exist too. header_converters: :symbol lowercases headers and replaces spaces with underscores, so Unit Price becomes :unit_price. Converters run on every field, so be careful with identifiers: a zip code 01234 would become the integer 1234. Leave such columns alone with a custom converter that checks the header (the info argument has info.header).

Writing CSV

Ruby CSV.generate, generate_line and quoting

Press Run (or Ctrl + Enter) to see the result here.

Program input · what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

CSV.generate gives you a writer; << appends a row. The library quotes only when needed: fields with commas, quotes or newlines are wrapped, quotes are doubled, and nil becomes an empty field. Writing to a file works the same way: CSV.open("out.csv", "w") { |csv| csv << [...] }.

Errors and messy data

Ruby CSV::MalformedCSVError (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input · what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

The run ends with CSV::MalformedCSVError, whose message is Unclosed quoted field in line 2. here, because a quoted field never ends. Rescue it at the boundary and report the line number. Real-world CSV is messy, so a few options help:

Ruby Handling messy files

Press Run (or Ctrl + Enter) to see the result here.

Program input · what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

The first header in the BOM example looks like "id" but is really "id" (an invisible character in front), so row["id"] would return nil; stripping the BOM first, or opening the file with encoding: "bom|utf-8", fixes it. Use col_sep: for semicolon- or tab-separated files (many European spreadsheets use semicolons), skip_blanks: true to ignore empty lines, strip: true to trim spaces, and liberal_parsing: true as a last resort for badly quoted input. For large files, never read everything into an array: CSV.foreach("big.csv", headers: true) { |row| ... } processes one row at a time using constant memory.

Choosing a format

Need Choose
Configuration edited by people, with comments YAML
Data exchanged with web APIs and JavaScript JSON
Flat tables, spreadsheets, bulk exports CSV
Fast, internal, same-version Ruby only Marshal (never untrusted data)

YAML supports comments (# note), which JSON does not. CSV has no types, no nesting and no standard for the delimiter, so document the format you expect. Whichever you choose, validate the content after reading.

Check your understanding

Quick check · 5 questions

of 5 answered You scored / 5 · perfect!

  1. 1. Why is YAML.safe_load preferred over loading arbitrary documents with an unsafe loader?

    Unsafe YAML loading could instantiate any class named in the document, a known path to remote code execution. safe_load allows basic types and the classes you list in permitted_classes.
  2. 2. What does YAML (Psych) make of the unquoted value no in a config file?

    YAML 1.1 treats no, off and false as booleans, which is why values like country codes must be quoted.
  3. 3. After CSV.parse(text) without any options, what type are the field values?

    CSV has no types. Every field is a String, and an empty unquoted field is nil, unless you pass converters.
  4. 4. Why does the csv library need a Gemfile entry in newer Ruby versions?

    Since Ruby 3.4 csv is a bundled gem. A project using Bundler should declare gem "csv" so require 'csv' works.
  5. 5. What is the memory-friendly way to process a huge CSV file?

    CSV.foreach yields one row at a time, so memory use stays constant, while read and parse build the whole table in memory.

Summary

  • yaml is a default library: to_yaml / YAML.dump write, YAML.safe_load (and safe_load_file) read; permit extra classes such as Symbol explicitly.
  • YAML guesses types (no is false, 1.10 is 1.1, empty is nil): quote strings that must stay text. Prefer plain hashes over dumping your own objects.
  • csv is a bundled gem: add it to your Gemfile in real projects. Fields are strings until you add converters:.
  • Use headers: true for CSV::Row access, header_converters: :symbol for symbol keys, CSV.generate to write, and CSV.foreach for big files.
  • Rescue Psych::SyntaxError and CSV::MalformedCSVError where data enters your program.

Next: Set, OpenStruct and Friends