HEREDOC и его использование в Ruby
Что такое HEREDOC и для чего его используют? Основная цель - написание больших блоков текста (документации) в коде, а также его передача в переменные. HEREDOC - сокращение от "here document".
Чтобы передать HEREDOC переменной, можно использовать привычный синтаксис присваивания:
a = <<HEREDOC Текст документа в переменной HEREDOC puts a
Результат:
Текст документа в переменной
Для более подробного ознакомления с "heredoc" создадим пустой *.rb файл и запишeм в него следующую конструкцию:
def test_heredoc <<HEREDOC Тут у нас будет первая строка документа. А тут вторая. И третья. HEREDOC end
Результат:
Тут у нас будет первая строка документа. А тут вторая. И третья.
В данном примере документация начинается после строки "<< HEREDOC" и заканчивается перед "HEREDOC".
Стоит отметить, что "HEREDOC" вовсе не обязательно писать в верхнем регистре.
Также вместо ключевого слова "HEREDOC" можно использовать любое угодное. "HEREDOC" используется чаще всего программистами, что дает ясно понять, что описывается внутри этой конструкции.
def some_method
<<-something
Это документация, которая использует "something" вместо "HEREDOC".
:)
something
end
puts some_methodРезультат запуска 'heredoc.rb':
Это моя документация, которая использует "something" вместо "HEREDOC".
:)Если посмотреть на пример кода метода test_heredoc, показанный в самом начале этой страницы - можно заметить, что не хватает табуляции (отступов на строках, которыми открывается и закрывается "heredoc"). В следующем методе some_method - табуляция присутствует.
Это связано с тем, что конструкция из первого примера "<<" чувствительна к форматированию. Во втором примере конструкция "<<−" (с знаком 'минус' в конце) позволяет форматировать наш код.
"<<−" делает так, что идентификатор конструкции "heredoc" читается так, как если бы он начинался в самом начале строки. Код содержащийся внутри идентификатора читается буквально - и покажет отступы при выводе в терминале.
Чтобы отформатировать текст и избавиться от лишних отступов в начале строк при печати в терминал - нужно использовать символ лямбды "~" после "<<".
Называется эта конструкция - "squiggly".
def some_squiggly_method
<<~something
Это документация, которая имеет отступы у идентификатора "heredoc".
Отступы в начале документации также обрезаются.
something
end
puts some_squiggly_methodРезультат:
Это документация, которая имеет отступы у идентификатора "heredoc". Отступы в начале документации также обрезаются.
Обратите внимание, что "squiggly" не просто удаляет все отступы в начале строк, а принимает самый короткий отступ в качестве эталона. Все более длинные отступы будут обрезаны ровно по него. Этот функционал позволяет форматировать документацию и исключать ненужные отступы.
Пример:
def some_squiggly_method
<<~something
Это документация, которая имеет отступы у идентификатора "heredoc".
Отступы в начале документации также обрезаются.
Все отступы обрезаются по эту строку.
something
end
puts some_squiggly_methodВывод программы:
Это документация, которая имеет отступы у идентификатора "heredoc". Отступы в начале документации также обрезаются. Все отступы обрезаются по эту строку.
Пустые строки и строки, состоящие исключительно из буквальных табуляций и пробелов, будут игнорироваться для определения отступов, но экранированные табуляции и пробелы считаются не отступными символами.
"HEREDOC" позволяет нам использовать Ruby-код внутри себя, что позволяет делать документацию динамической:
@rand_number = rand(10)
def some_method
<<~something
Случайное число #{@rand_number} + 1 = #{@rand_number + 1}
something
end
puts some_methodЗапустим код:
Случайное число 9 + 1 = 10
Если нам необходимо интерполировать Ruby-код в документации - мы просто возьмем идентификатор нашего "heredoc" в одинарные кавычки:
@rand_number = rand(10)
def some_method
<<~'something'
Случайное число #{@rand_number} + 1 = #{@rand_number + 1}
something
end
puts some_methodРезультат:
Случайное число #{@rand_number} + 1 = #{@rand_number + 1}Обратите внимание, что двойные кавычки можно использовать в конструкции, но они дают такой же результат, как и их полное отсутствие.
Существует способ комбинирования "heredoc", который выглядит так:
def some_method
puts(<<~first, <<~second)
Текст первого хирдока
first
Текст второго хирдока
second
end
some_methodРезультат:
Текст первого хирдока Текст второго хирдока
Ссылки: RubyDoc