Combining Files with Require

Until now, we’ve been putting all of our code into one source file, which works well for small examples. When code size grows and you need multiple classes, though, you’ll want to split your code over several files. You can combine these into one file with require, which takes the following format:

Here, path is the file-path to the file (or files) you want to include. When the compiler sees a require, it searches the file(s) on that path and copies in their contents in the present file. In this way, all source files are combined into one big file. This is only done once: a subsequent require of a previously required file will have no effect.

There are several forms of this command, which can make it a bit confusing at first. We’ll illustrate them one by one.

In this demonstration, each required file prints out a statement that says where it’s located. The code download contains everything, but this is what the folder and file structure look like:

• fileA.cr
• dirA
  • dirB.cr
  • fileA.cr
  • fileA2.cr
  • fileA3.cr
  • dirB
    • dirB.cr
    • fileB.cr
  • dirC
    • fileC1.cr
    • fileC2.cr

Looking in the Current Folder

The require "./part" form searches for part.cr or, if this wasn’t found, part/part.cr (here part/ is a subfolder) in the current folder. Here are some examples:

To make it easy to see the difference, you can explicitly use require "./part.cr" when a file is intended.

Looking in the Parent Folder

Adding an extra period to make it require "../part" works like the previous form, except that now the compiler looks in the parent folder.

You can go up several levels as well, as in require "../../part".

Looking Several Levels Down

Nested forms also work, as you see here:

Wildcards for Files or Subfolders

Using wildcard *: require "./dirA/*" looks for all .cr files in the dirA folder but not in subfolders.

If you also want to look in subfolders with a wildcard, you can use require "./dirA/**". This looks for all .cr files in the dirA folder, and also in subfolders, like dirC.

Using Crystal’s Folder Structures

You can also bring in files using Crystal’s require path with require "file".

This looks up file.cr or file/file.cr in the require path, which consists of two parts.

The first is the location of the standard library, which in Linux is at /opt/crystal/src. You won’t put anything here, but the compiler needs it to locate all Crystal source files.

The second is a lib folder relative to the current working folder. As you build larger projects, the reliable structure this approach offers will be appealing. You’ll use this form to include external libraries in a project. In the next chapter, you’ll see how the default project structure uses these rules.

Prelude
	Ever wondered why you don’t need to require code for working with Booleans, chars, strings, arrays, and all such common types and modules? That’s because they’re all required in the prelude script, which you can often find on Linux at /opt/crystal/src/prelude.cr, or wherever your Crystal installer put it. You can also find the latest version of prelude.cr in the GitHub repository.[35]