読み込み中...

Rubyにおけるヒアドキュメントを使ったスクリプトの書き方5選

Rubyのヒアドキュメント Ruby
2024.05.05
この記事は約12分で読めます。

【サイト内のコードはご自由に個人利用・商用利用いただけます】

この記事では、プログラムの基礎知識を前提に話を進めています。

説明のためのコードや、サンプルコードもありますので、もちろん初心者でも理解できるように表現してあります。

本記事のサンプルコードを活用して機能追加、目的を達成できるように作ってありますので、是非ご活用ください。

※この記事は、一般的にプロフェッショナルの指標とされる『実務経験10,000時間以上』を満たす現役のプログラマチームによって監修されています。

※Japanシーモアは、常に解説内容のわかりやすさや記事の品質に注力しております。不具合、分かりにくい説明や不適切な表現、動かないコードなど気になることがございましたら、記事の品質向上の為にお問い合わせフォームにてご共有いただけますと幸いです。
(送信された情報は、プライバシーポリシーのもと、厳正に取扱い、処分させていただきます。)

●ヒアドキュメントとは？

Rubyには、ヒアドキュメントという強力な機能があります。

ヒアドキュメントを使うと、複数行にわたる長い文字列を簡潔に記述できるんです。

コードの可読性が高まり、メンテナンスもしやすくなります。

でも、ヒアドキュメントってどんなものなのでしょうか？

簡単に解説していきますので、一緒に理解を深めていきましょう。

○ヒアドキュメントの基本構文

ヒアドキュメントは、次のような構文で記述します。

<<識別子
  複数行の
  文字列を
  ここに書く
識別子

ポイントは、始まりと終わりに同じ識別子を使うことです。

これにより、その間に書かれた文字列が、まとめて1つの文字列として扱われるんですね。

例えば、次のように使えます。

message = <<MSG
  こんにちは。
  今日の天気は晴れです。
  良い1日を！
MSG

puts message

実行結果

  こんにちは。
  今日の天気は晴れです。
  良い1日を！

ヒアドキュメントを使うと、複数行の文字列をスッキリと書けるのがわかりますね。

エスケープシーケンスを多用せずに、そのまま文字列を記述できるのが嬉しいポイントです。

●ヒアドキュメントの5つの使い方

さて、ヒアドキュメントの基本は理解できたと思います。

でも、実際の開発現場でどう活用すればいいのかまだイメージしにくいですよね。

そこで、ヒアドキュメントの具体的な使い方を5つのサンプルコードとともに紹介していきます。

○サンプルコード1：複数行の文字列の定義

ヒアドキュメントの最も基本的な使い方は、複数行の文字列を定義することです。

先ほどの例でも見たように、ヒアドキュメントを使えば、複数行にわたる長い文字列をスッキリと書けます。

例えば、ユーザーへの長めの案内メッセージを表示する場合などに便利です。

message = <<~MSG
  こんにちは、#{user_name}さん。
  本日は、弊社のサービスをご利用いただきありがとうございます。
  ご不明な点がありましたら、いつでもサポートまでご連絡ください。
  引き続き、よろしくお願いいたします。
MSG

puts message

実行結果

こんにちは、田中さん。
本日は、弊社のサービスをご利用いただきありがとうございます。
ご不明な点がありましたら、いつでもサポートまでご連絡ください。
引き続き、よろしくお願いいたします。

ポイントは、ヒアドキュメントの開始行に<<~を使っていることです。

これによって、ヒアドキュメント内の各行の先頭にあるスペースが自動的に削除されます。

インデントを揃えて見やすくできるのがメリットです。

また、#{user_name}のように式展開を使えば、変数の値をヒアドキュメント内に埋め込むこともできます。

とても柔軟で強力な機能なので、ぜひ覚えておきましょう。

○サンプルコード2：テンプレートの作成

次に、ヒアドキュメントを使ってテンプレートを作成する方法を見ていきます。

HTMLやSQLなどの長めのテンプレートを、コード内に直接記述する際に役立ちますよ。

例えば、HTMLメールのテンプレートをヒアドキュメントで用意して、必要な情報を埋め込むなんてこともできます。

def generate_html_mail(name, url)
  <<~HTML
    <!DOCTYPE html>
    <html>
      <head>
        <meta charset="UTF-8">
        <title>ようこそ！</title>
      </head>
      <body>
        <h1>#{name}さん、こんにちは！</h1>
        <p>以下のURLから会員登録を完了してください。</p>
        <a href="#{url}">#{url}</a>
      </body>
    </html>
  HTML
end

puts generate_html_mail("田中", "https://example.com/register")

実行結果

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <title>ようこそ！</title>
  </head>
  <body>
    <h1>田中さん、こんにちは！</h1>
    <p>以下のURLから会員登録を完了してください。</p>
    <a href="https://example.com/register">https://example.com/register</a>
  </body>
</html>

HTMLをヒアドキュメントで記述することで、コードとテンプレートを分離できるのがポイントです。

可読性が高まり、メンテナンスもしやすくなりますよね。

また、SQLクエリのテンプレートを用意しておくのにもヒアドキュメントは最適です。

条件に応じてクエリを組み立てる際に、とても便利に使えますよ。

○サンプルコード3：ファイルへの書き込み

ヒアドキュメントは、ファイルへのテキスト書き込みにも活用できます。

File.writeメソッドと組み合わせることで、簡単にファイルを生成できるんです。

例えば、設定ファイルのテンプレートをヒアドキュメントで用意しておいて、必要な情報を埋め込んでファイルに書き出すなんてこともできます。

config_template = <<~CONFIG
  [database]
  host = #{database_host}
  port = #{database_port}
  name = #{database_name}

  [api]
  endpoint = #{api_endpoint}
  key = #{api_key}
CONFIG

File.write("config.ini", config_template)

こんな感じで、ヒアドキュメントとファイル操作を組み合わせれば、設定ファイルの生成をコード内で完結できます。

テンプレートとしてヒアドキュメントを使うことで、設定ファイルの構造が一目瞭然になります。

○サンプルコード4：シェルコマンドの実行

ちょっと意外かもしれませんが、ヒアドキュメントはシェルコマンドの実行にも使えます。

systemメソッドや%x記法と一緒に使うことで、複数行のシェルコマンドをスッキリと書けます。

例えば、gitコマンドでのコミットメッセージをヒアドキュメントで用意して、そのままシェルで実行なんてことができてしまいます。

commit_message = <<~MSG
  機能追加：ユーザー登録機能の実装

  - 登録フォームの作成
  - バリデーションの追加
  - メール送信処理の実装
MSG

system(<<~COMMAND)
  git add .
  git commit -m "#{commit_message}"
  git push origin master
COMMAND

ヒアドキュメントを使えば、複数行のコミットメッセージを変数に格納しつつ、そのままシェルコマンドに渡せるのが便利ですよね。

コマンドの可読性が高まり、メンテナンスもしやすくなります。

○サンプルコード5：ドキュメントの生成

最後に、ヒアドキュメントを使ってドキュメントを生成する方法を紹介します。

READMEやCHANGELOGなどの長めのドキュメントを、コード内で管理したい場合に便利です。

例えば、Ruby GemのREADMEをヒアドキュメントで用意しておいて、バージョン番号などの情報を埋め込んで出力する、なんてことができます。

def generate_readme(version)
  <<~README
    # My Awesome Gem

    This is a sample gem.

    ## Installation

    Add this line to your application's Gemfile:

    ```ruby
    gem 'my_awesome_gem', '~> #{version}'
    ```

    And then execute:

        $ bundle install

    ## Usage

    TODO: Write usage instructions here.

    ## License

    The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
  README
end

puts generate_readme("1.0.0")

実行結果

# My Awesome Gem

This is a sample gem.

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'my_awesome_gem', '~> 1.0.0'
```

And then execute:

    $ bundle install

## Usage

TODO: Write usage instructions here.

## License

The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

バージョン番号などの変数をヒアドキュメント内に埋め込むことで、ドキュメントの生成を自動化できるのがポイントです。

コード内でドキュメントを一元管理できるので、とても便利です。

●ヒアドキュメントを使う際の注意点

ヒアドキュメントは本当に便利な機能ですが、使い方を間違えると思わぬバグに遭遇することがあるんです。

初心者の方はもちろん、経験者の方も注意が必要ですよ。

そこで、ヒアドキュメントを使う際の注意点を3つ紹介します。

後述するポイントを押さえておけば、ヒアドキュメントをより安全に活用できるはずです。

○インデントに気をつける

ヒアドキュメントを使うときは、インデントには十分気をつけましょう。

特に、ヒアドキュメントの開始行と終了行のインデントが揃っていないと、構文エラーになってしまうんです。

例えば、次のようなコードはエラーになります。

def some_method
  <<~HEREDOC
    This is a heredoc.
    It spans multiple lines.
  HEREDOC
end

エラーメッセージ

`some_method': unexpected token at '<<' (SyntaxError)

ヒアドキュメントの開始行と終了行のインデントがずれているため、構文エラーが発生しているのがわかりますね。

正しくは、次のようにインデントを揃える必要があります。

def some_method
  <<~HEREDOC
    This is a heredoc.
    It spans multiple lines.
  HEREDOC
end

このように、ヒアドキュメントを使うときは、インデントに十分注意を払いましょう。

コードのレイアウトを崩さないよう、慎重に記述することが大切ですよ。

○終了識別子の位置に注意

ヒアドキュメントの終了識別子は、必ず行頭に置く必要があります。終了識別子の前に空白やタブがあると、正しく動作しないので注意しましょう。

例えば、次のようなコードは期待通りに動きません。

puts <<~HEREDOC
  This is a heredoc.
  It spans multiple lines.
  HEREDOC

出力結果

This is a heredoc.
It spans multiple lines.
HEREDOC

終了識別子の前にスペースがあるため、ヒアドキュメントが正しく終了していないのがわかりますね。

正しくは、次のように終了識別子を行頭に置く必要があります。

puts <<~HEREDOC
  This is a heredoc.
  It spans multiple lines.
HEREDOC

出力結果

This is a heredoc.
It spans multiple lines.

このように、ヒアドキュメントの終了識別子は、必ず行頭に置くことを忘れないでくださいね。

些細なミスが思わぬバグを引き起こすこともあるので、慎重に記述しましょう。

○ヒアドキュメント内での変数展開

ヒアドキュメント内では、式展開を使って変数の値を埋め込むことができます。

ただし、式展開を使うときは、ヒアドキュメントの区切り文字に注意が必要です。

デフォルトの区切り文字である"（ダブルクォート）を使った場合、式展開が有効になります。

一方、'（シングルクォート）を使った場合は、式展開が無効になるんです。

例えば、次のようなコードを見てみましょう。

name = "Alice"
puts <<~HEREDOC
  Hello, #{name}!
  This is a heredoc.
HEREDOC

出力結果

Hello, Alice!
This is a heredoc.

ダブルクォートを使っているため、#{name}が式展開され、Aliceに置き換わっているのがわかりますね。

一方、次のようにシングルクォートを使った場合は、式展開が無効になります。

name = "Alice"
puts <<~'HEREDOC'
  Hello, #{name}!
  This is a heredoc.
HEREDOC

出力結果

Hello, #{name}!
This is a heredoc.

#{name}がそのまま出力されており、式展開が行われていないことがわかります。

まとめ

本記事では、ヒアドキュメントの基本的な使い方から、実践的な活用例まで詳しく解説してきました。

ヒアドキュメントを使いこなすことで、コードの可読性が高まり、メンテナンス性も向上します。

テンプレートやドキュメントの生成にも活用できるので、開発の生産性アップにも繋がるはずです。

ただし、ヒアドキュメントを使う際は、インデントや終了識別子の位置、変数展開の区切り文字など、いくつか注意点があることを忘れないでくださいね。

慣れないうちは、細心の注意を払って記述することが大切です。

最後まで読んでいただき、ありがとうございました。

本記事が、あなたのRubyプログラミングの助けになれば幸いです。

ヒアドキュメントを活用して、より良いコードを書いていきましょう！