50

Magic comments in Ruby

 5 years ago
source link: https://www.tuicool.com/articles/zEnmme6
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
neoserver,ios ssh client

In this article, we’re going to explore the following topics:

  • comments vs magic comments
  • specifications
  • existing magic comments

Comments vs magic comments

In Ruby, you have the possibility to annotate and document your code using comments.

To declare a comment we use the # character followed by our comment

Here all the text after the # is not interpreted by Ruby.

It only helps the developer to understand the code.

In another hand, there is some comments that are interpreted by Ruby.

They are known as Magic Comments — or Magic Instructions

Here, the # encoding: big5 is interpreted by Ruby.

When Ruby reads this magic comment then it automatically sets the encoding of any string declared in this file to Encoding:Big5 — we’ll go further with encoding: in the last section of this article.

Now that we know the difference between a comment and a magic comment then let’s have a quick look at magic comments specifications.

Specifications

We’ll see the implicit rules that we need to know to get the best of this feature.

Syntaxes

There is 2 syntaxes to declare a magic comment

# encoding: UTF-8
# -*- encoding: UTF-8 -*-

Both syntaxes will be interpreted similarly by Ruby.

Multiple files

Let’s see what’s the scope of a magic comment

As we can see, the magic comment is only effective in the file where it is declared.

Indeed, the encoding within the world.rb file is the default Ruby encoding: UTF-8 .

So, the magic comment doesn’t have any impact in the required files.

Multiple magic comments

We can declare multiple magic comments in the same file.

For example

Here, Ruby will parse and process both of these 2 magic comments — we’ll detail these magic comments in the next sections.

So they’ll be both effective in this file.

Precendence

As precedence rules are different for each magic comment then I’ll describe these rules under each of the magic comments sections.

Ok.

Now that we’re more familiar with the notion of magic comment, then let’s have a look to the different magic comments that we can play with.

Magic comments

In thi section, we’re going to slightly talk about each of the magic comments.

We wont deep dive each notion.

The goal here is only to present you the magic comments and give you the precedence rules that are applied to them.

I invite you to browse the official documentation for further information — edge cases, etc..

The encoding: magic comment

In Ruby, the default encoding is UTF-8 .

Feel free to read The Evolution of Ruby Strings from 1.8 to 2.5 if you’re not familiar with the notion of codepoint and encoding.

The encoding: magic comment allows us to modify this default encoding in the file where this comment is defined

Here, we can see that our string encoding is Encoding:Big5 — as declared in the magic comment.

Precedence

Here, only the first declared encoding: instruction is processed.

The others are skipped.

Note that we can use encoding: or coding: .

The frozen_string_literal: magic comment

This magic comment is pretty useful when you declare several times a similar string using string literals.

Indeed, it makes an optimisation by only creating one object per string based on content

Here we can see that if we declare two similar strings then only one instance of the String class will be created for both of them.

This mechanism is especially useful when we use strings as identifiers for resource — similarly to a symbol.

Precedence

Here, only the last declared frozen_string_literal: instruction is processed.

The others are skipped.

The warn_indent: magic comment

This comment works the same as the ruby -w warn_indent.rb command line

outputs

$> ruby warn_indent.rb
warn_indent
 .rb:4: warn: mismatched indentations at 'end' with 'def'

Here we can see that if the code isn’t well indented then Ruby raises a warning accordingly.

Precedence

Here, only the last declared warn_indent: instruction is processed.

The others are skipped.

Voilà!


report

Recommend

About Joyk


Aggregate valuable and interesting links.
Joyk means Joy of geeK