erb 5.0.2 → 6.0.1

data/_doc/erb_executable.md

@@ -0,0 +1,240 @@
+# \ERB Executable
+
+The `erb` executable gives command-line access to ERB template processing.
+
+The executable is installed with \ERB, which is part of the Ruby installation.
+
+For a quick summary, type:
+
+```bash
+$ erb --help
+```
+
+The format of the command is
+`erb [_options_] [_filepaths_]`,
+where:
+
+- _options_ are zero or more [options][options].
+- _filepaths_ are zero or more paths to files, each containing an plain text
+  that can include \ERB tags.
+
+## Filepaths
+
+With one or more _filepaths_ given, `erb` reads all the given files as a single template;
+that is, `erb` processes multiple files into a single result:
+
+```bash
+$ cat t.erb
+<%= RUBY_VERSION %>
+<%= Time.now %>
+$ cat u.erb
+% Encoding.list.take(4).each do |encoding|
+* <%= encoding %>
+% end
+$ erb t.erb u.erb
+3.4.5
+2025-09-24 00:23:00 +0100
+* ASCII-8BIT
+* UTF-8
+* US-ASCII
+* UTF-16BE
+```
+
+There is a special "filepath", `'-'`, that specifies the standard input:
+
+```bash
+$ echo "<%= RUBY_VERSION %>" | erb u.erb -
+* ASCII-8BIT
+* UTF-8
+* US-ASCII
+* UTF-16BE
+3.4.5
+```
+
+Any filepath, including `'-'`, may be repeated.
+
+With no _filepaths_ given, `erb` reads and processes the standard input:
+
+```bash
+$ echo "<%= RUBY_VERSION %>" | erb # Prints the ERB version string.
+```
+
+## Options
+
+### `-d`, `--debug`: Set $DEBUG
+
+Use option `-d` or `--debug` to turn on debugging output:
+
+```bash
+$ echo "<%= $DEBUG %>" | erb
+"false"
+$echo "<%= $DEBUG %>" | erb --debug
+"true"
+```
+
+### `-E`, `--encoding`: Set Encodings
+
+Use option `-E` or `--encoding` to set the default external encoding to `_ex_`
+and, if `_in_` is given, to set the default internal encoding to `_in_`.
+
+Each encoding, `ex` and `in`, must be the name of an Encoding:
+
+```
+erb  -E ASCII-8BIT:ASCII-8BIT t.erb
+```
+
+### `-h`, `--help`: Print Help
+
+Use option `-h` or `--help` to print `erb` help text:
+
+```bash
+$ erb --help
+```
+
+### `-n`: Print Source with Line Numbers
+
+Use option `-n` with option `-x` to print the output of ERB#src,
+with numbered lines:
+
+```bash
+$ cat t.erb
+<%= RUBY_VERSION %>
+<%= Time.now %>
+$ erb -n -x t.erb
+  1 #coding:UTF-8
+  2 _erbout = +''; _erbout.<<(( RUBY_VERSION ).to_s); _erbout.<< "\n".freeze
+  3 ; _erbout.<<(( Time.now ).to_s); _erbout.<< "\n".freeze
+  4 ; _erbout
+```
+
+Using option `-n` without option `-x` has no effect:
+
+```bash
+$ erb -n t.erb
+3.4.5
+2025-09-23 02:44:57 +0100
+```
+
+### `-P`: Disable Execution Tag Shorthand
+
+By default, `erb` enables [execution tag shorthand][execution tag shorthand]:
+
+```
+$ cat u.erb
+% Encoding.list.take(4).each do |encoding|
+* <%= encoding %>
+% end
+$ erb u.erb
+* ASCII-8BIT
+* UTF-8
+* US-ASCII
+* UTF-16BE
+```
+
+You can use option `-P` to disable the shorthand:
+
+```
+$ erb -P u.erb # Raises NameError: "undefined local variable or method 'encoding'"
+```
+
+### `-r`: Load Library
+
+You can use option `-r` to load a library;
+the option may be given multiple times, to load multiple libraries:
+
+```
+$ erb -r csv -r bigdecimal t.erb
+```
+
+### `-T`: Set Trim Mode
+
+You can use option `-T` to set the trim mode.
+
+The values for the option are:
+
+- `'0'`, meaning `'%'`; enable execution tag shorthand;
+  see [execution tag shorthand][execution tag shorthand].
+- `'1'`, meaning `'%>'`: enable execution tag shorthand and omit newline for each line ending with `'%>'`;
+  see [suppressing unwanted newlines][suppressing unwanted newlines].
+- `'2'`, meaning `'<>'`:  to suppress the trailing newline for each line
+  that both begins with `'<%'` and ends with `'%>'`;
+  see [suppressing unwanted newlines][suppressing unwanted newlines].
+- `'-'`, meaning `'%-'`: enable execution tag shorthand and omit each blank line ending with `'-%>'`.
+  see [execution tag shorthand][execution tag shorthand]
+  and [suppressing unwanted blank lines][suppressing unwanted blank lines].
+
+Example:
+
+```bash
+$ erb -T 0 t.erb
+```
+
+### `-U`: Set Default Encodings to UTF-8
+
+You can use option `-U` to set both external and internal encodings to UTF-8:
+
+```bash
+$ erb -U t.erb
+```
+
+### `-v`: Set $VERBOSE
+
+Use option `-v` to turn on verbose output:
+
+```bash
+$ $ "<%= $VERBOSE %>" | erb
+"false"
+$ echo "<%= $VERBOSE %>" | erb -v
+"true"
+```
+
+### `-v`: Print \ERB Version
+
+Use option `--version` to print the \ERB version string:
+
+```bash
+$ erb --version
+```
+
+### `-x`: Print Source
+
+Use option `-x` to print the output of ERB#src,
+which is the Ruby code that is to be run when ERB#result is called:
+
+```bash
+$ cat t.erb
+<%= RUBY_VERSION %>
+<%= Time.now %>
+$ erb -x t.erb
+#coding:UTF-8
+_erbout = +''; _erbout.<<(( RUBY_VERSION ).to_s); _erbout.<< "\n".freeze
+; _erbout.<<(( Time.now ).to_s); _erbout.<< "\n".freeze
+; _erbout
+```
+
+### `--`: End of Options
+
+You can use option `'--'` to declare the end of options in the `erb` command;
+`erb` treats each word following as a filepath (even if it looks like an option):
+
+```
+erb -- --help # Raises Errno::ENOENT: "No such file or directory @ rb_sysopen - --help"
+```
+
+### `name=value`: Set the Value of a Variable
+
+You can use option `name=value` to set the value of the variable named `name`
+to the given `value`.
+
+The option may be given multiple times to set multiple variables:
+
+```bash
+$ echo "<%= foo %> <%= bar %>" | erb foo=1 bar=2
+"1 2"
+```
+
+[erb.new]: https://docs.ruby-lang.org/en/master/ERB.html#method-c-new.
+[execution tag shorthand]: rdoc-ref:ERB@Shorthand+Format+for+Execution+Tags
+[options]: rdoc-ref:erb_executable.md@Options
+[suppressing unwanted blank lines]: rdoc-ref:ERB@Suppressing+Unwanted+Blank+Lines
+[suppressing unwanted newlines]: rdoc-ref:ERB@Suppressing+Unwanted+Newlines

data/erb.gemspec

@@ -18,6 +18,7 @@ Gem::Specification.new do |spec|
 
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "https://github.com/ruby/erb/blob/v#{spec.version}/NEWS.md"
 
   spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }

data/ext/erb/escape/escape.c

@@ -39,29 +39,41 @@ static VALUE
 optimized_escape_html(VALUE str)
 {
     VALUE vbuf;
-    char *buf = ALLOCV_N(char, vbuf, escaped_length(str));
+    char *buf = NULL;
     const char *cstr = RSTRING_PTR(str);
     const char *end = cstr + RSTRING_LEN(str);
 
-    char *dest = buf;
+    const char *segment_start = cstr;
+    char *dest = NULL;
     while (cstr < end) {
         const unsigned char c = *cstr++;
         uint8_t len = html_escape_table[c].len;
         if (len) {
+            size_t segment_len = cstr - segment_start - 1;
+            if (!buf) {
+                buf = ALLOCV_N(char, vbuf, escaped_length(str));
+                dest = buf;
+            }
+            if (segment_len) {
+                memcpy(dest, segment_start, segment_len);
+                dest += segment_len;
+            }
+            segment_start = cstr;
             memcpy(dest, html_escape_table[c].str, len);
             dest += len;
         }
-        else {
-            *dest++ = c;
-        }
     }
-
     VALUE escaped = str;
-    if (RSTRING_LEN(str) < (dest - buf)) {
+    if (buf) {
+        size_t segment_len = cstr - segment_start;
+        if (segment_len) {
+            memcpy(dest, segment_start, segment_len);
+            dest += segment_len;
+        }
         escaped = rb_str_new(buf, dest - buf);
         preserve_original_state(str, escaped);
+        ALLOCV_END(vbuf);
     }
-    ALLOCV_END(vbuf);
     return escaped;
 }
 

data/lib/erb/compiler.rb

@@ -225,7 +225,7 @@ class ERB::Compiler # :nodoc:
       end
     end
 
-    ERB_STAG = %w(<%= <%# <%)
+    ERB_STAG = %w(<%= <%# <%).freeze
     def is_erb_stag?(s)
       ERB_STAG.member?(s)
     end
@@ -480,7 +480,6 @@ class ERB::Compiler # :nodoc:
     end
   }.new(caller(0)).c
   private_constant :WARNING_UPLEVEL
-  # :startdoc:
 
   def warn_invalid_trim_mode(mode, uplevel:)
     warn "Invalid ERB trim mode: #{mode.inspect} (trim_mode: nil, 0, 1, 2, or String composed of '%' and/or '-', '>', '<>')", uplevel: uplevel + WARNING_UPLEVEL

data/lib/erb/util.rb

@@ -2,14 +2,14 @@
 
 # Load CGI.escapeHTML and CGI.escapeURIComponent.
 # CRuby:
-#   cgi.gem v0.1.0+ (Ruby 2.7-3.4) and Ruby 3.5+ stdlib have 'cgi/escape' and CGI.escapeHTML.
-#   cgi.gem v0.3.3+ (Ruby 3.2-3.4) and Ruby 3.5+ stdlib have CGI.escapeURIComponent.
+#   cgi.gem v0.1.0+ (Ruby 2.7-3.4) and Ruby 4.0+ stdlib have 'cgi/escape' and CGI.escapeHTML.
+#   cgi.gem v0.3.3+ (Ruby 3.2-3.4) and Ruby 4.0+ stdlib have CGI.escapeURIComponent.
 # JRuby: cgi.gem has a Java extension 'cgi/escape'.
 # TruffleRuby: lib/truffle/cgi/escape.rb requires 'cgi/util'.
 require 'cgi/escape'
 
 # Load or define ERB::Escape#html_escape.
-# We don't build the C extention 'cgi/escape' for JRuby, TruffleRuby, and WASM.
+# We don't build the C extension 'cgi/escape' for JRuby, TruffleRuby, and WASM.
 # miniruby (used by CRuby build scripts) also fails to load erb/escape.so.
 begin
   require 'erb/escape'
@@ -19,6 +19,7 @@ rescue LoadError
   # A subset of ERB::Util. Unlike ERB::Util#html_escape, we expect/hope
   # Rails will not monkey-patch ERB::Escape#html_escape.
   module ERB::Escape
+    # :stopdoc:
     def html_escape(s)
       CGI.escapeHTML(s.to_s)
     end
@@ -47,19 +48,19 @@ module ERB::Util
   alias h html_escape
   module_function :h
 
-  #
-  # A utility method for encoding the String _s_ as a URL.
-  #
-  #   require "erb"
-  #   include ERB::Util
-  #
-  #   puts url_encode("Programming Ruby:  The Pragmatic Programmer's Guide")
-  #
-  # _Generates_
-  #
-  #   Programming%20Ruby%3A%20%20The%20Pragmatic%20Programmer%27s%20Guide
-  #
   if CGI.respond_to?(:escapeURIComponent)
+    #
+    # A utility method for encoding the String _s_ as a URL.
+    #
+    #   require "erb"
+    #   include ERB::Util
+    #
+    #   puts url_encode("Programming Ruby:  The Pragmatic Programmer's Guide")
+    #
+    # _Generates_
+    #
+    #   Programming%20Ruby%3A%20%20The%20Pragmatic%20Programmer%27s%20Guide
+    #
     def url_encode(s)
       CGI.escapeURIComponent(s.to_s)
     end

data/lib/erb/version.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
 class ERB
-  VERSION = '5.0.2'
+  # The string \ERB version.
+  VERSION = '6.0.1'
 end