herb 0.0.1 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 5c394bc2c2281a98fffdbd20598cf1b8fb14c710
-  data.tar.gz: a3179a63d031f7599274f144ef7d846518a0bd96
+SHA256:
+  metadata.gz: 65973631dd5b45bb927fb6a60a84eb46f649054c07f14883ead07975a28c0de0
+  data.tar.gz: e01a0da35101184f8c38ab4fbf38d1d0fc9c54fe2ce690a462bacca2e86c207d
 SHA512:
-  metadata.gz: 02bd3e967c8d5433d141d4c4fb6c84c6610c2ca280413016def1280a7b4b77520289e582c070d030455f3a66b714cab34f292c46c7de94199e95ab8356d90b40
-  data.tar.gz: d2c7bfbd62d6188b5bbf7741b90113ffef0945ae7724f2e92ae98efc2d099a75496a3b4215836dc09bdd3a688776f547e46962a8457605eb219025bd34511c90
+  metadata.gz: d17d15332dd4b2fe81cf9a0c209efbc14ed94988e033221ec8be9c9c51e744cac0efd2bdb8d1187dca8cc555f03d5892dc7194a0765cff7fee7031226314b60c
+  data.tar.gz: 2a662061b9127b5976593d7a19fc1b255ed693abaeaa5b567a8273d33589941bc97a264d7d52045496f2372af9b37e0a36862394c86787a30bb0b26ff6fbf1e7

data/{LICENSE → LICENSE.txt}

@@ -1,5 +1,6 @@
-Copyright (c)      2016 Francesco Rodriguez
-Copyright (c) 2011-2016 Michel Martens
+The MIT License (MIT)
+
+Copyright (c) 2024 Marco Roth
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -17,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+THE SOFTWARE.

data/Makefile

@@ -0,0 +1,121 @@
+exec = herb
+test_exec = run_herb_tests
+
+sources = $(wildcard src/*.c) $(wildcard src/**/*.c)
+headers = $(wildcard src/*.h) $(wildcard src/**/*.h)
+objects = $(sources:.c=.o)
+
+extension_sources = $(wildcard ext/**/*.c)
+extension_headers = $(wildcard ext/**/*.h)
+extension_objects = $(extension_sources:.o)
+
+prism_objects = $(filter-out src/main.c, $(sources))
+
+project_files = $(sources) $(headers)
+extension_files = $(extension_sources) $(extension_headers)
+nodejs_extension_files = $(wildcard node/**/*.cpp) $(wildcard node/**/*.h) $(wildcard node/**/*.hpp)
+project_and_extension_files = $(project_files) $(extension_files) $(nodejs_extension_files)
+
+test_sources = $(wildcard test/**/*.c)
+test_objects = $(test_sources:.c=.o)
+non_main_objects = $(filter-out src/main.o, $(objects))
+
+soext ?= $(shell ruby -e 'puts RbConfig::CONFIG["DLEXT"]')
+lib_name = $(build_dir)/lib$(exec).$(soext)
+static_lib_name = $(build_dir)/lib$(exec).a
+ruby_extension = ext/herb/$(lib_name)
+
+build_dir = build
+$(shell mkdir -p $(build_dir))
+
+os := $(shell uname -s)
+
+prism_path = $(shell bundle show prism)
+prism_include = $(prism_path)/include
+prism_build = $(prism_path)/build
+
+prism_flags = -I$(prism_include)
+prism_ldflags = $(prism_build)/libprism.a
+
+# Enable strict warnings
+warning_flags = -Wall -Wextra -Werror -pedantic
+
+# Debug build (no optimizations, debug symbols)
+debug_flags = -g -O0 -Wno-unused-parameter
+
+# Production build (optimized)
+production_flags = $(warning_flags) -O3 -march=native -flto
+
+# Shared library flags (only for `.so`/`.dylib`/`.bundle`)
+shared_library_flags = -fPIC
+
+# Default build mode (change this as needed)
+flags = $(warning_flags) $(debug_flags) $(prism_flags) -std=c99
+
+# Separate test compilation flags
+test_flags = $(debug_flags) $(prism_flags) -std=gnu99
+
+# Shared library build (if needed)
+shared_flags = $(production_flags) $(shared_library_flags) $(prism_flags)
+
+ifeq ($(os),Linux)
+  test_cflags = $(test_flags) -I/usr/include/check
+  test_ldflags = -L/usr/lib/x86_64-linux-gnu -lcheck -lm -lsubunit $(prism_ldflags)
+  cc = clang-19
+  clang_format = clang-format-19
+  clang_tidy = clang-tidy-19
+endif
+
+ifeq ($(os),Darwin)
+  brew_prefix := $(shell brew --prefix check)
+  test_cflags = $(test_flags) -I$(brew_prefix)/include
+  test_ldflags = -L$(brew_prefix)/lib -lcheck -lm $(prism_ldflags)
+  llvm_path = $(shell brew --prefix llvm@19)
+  cc = $(llvm_path)/bin/clang
+  clang_format = $(llvm_path)/bin/clang-format
+  clang_tidy = $(llvm_path)/bin/clang-tidy
+endif
+
+all: prism $(exec) $(lib_name) $(static_lib_name) test wasm
+
+$(exec): $(objects)
+	$(cc) $(objects) $(flags) $(ldflags) $(prism_ldflags) -o $(exec)
+
+$(lib_name): $(objects)
+	$(cc) -shared $(objects) $(shared_flags) $(ldflags) $(prism_ldflags) -o $(lib_name)
+	# cp $(lib_name) $(ruby_extension)
+
+$(static_lib_name): $(objects)
+	ar rcs $(static_lib_name) $(objects)
+
+src/%.o: src/%.c
+	$(cc) -c $(flags) -fPIC $< -o $@
+
+test/%.o: test/%.c
+	$(cc) -c $(test_cflags) $(test_flags) $(prism_flags) $< -o $@
+
+test: $(test_objects) $(non_main_objects)
+	$(cc) $(test_objects) $(non_main_objects) $(test_cflags) $(test_ldflags) -o $(test_exec)
+
+clean:
+	rm -f $(exec) $(test_exec) $(lib_name) $(shared_lib_name) $(ruby_extension)
+	rm -rf $(objects) $(test_objects) $(extension_objects) lib/herb/*.bundle tmp
+	rm -rf $(prism_path)
+
+bundle_install:
+	bundle install
+
+prism: bundle_install
+	cd $(prism_path) && ruby templates/template.rb && make static && cd -
+
+format:
+	$(clang_format) -i $(project_and_extension_files)
+
+lint:
+	$(clang_format) --dry-run --Werror $(project_and_extension_files)
+
+tidy:
+	$(clang_tidy) $(project_files) -- $(flags)
+
+wasm:
+	cd wasm && make

data/README.md

@@ -1,171 +1,170 @@
-herb [![Build Status](https://travis-ci.org/frodsan/herb.svg)](https://travis-ci.org/frodsan/herb)
-====
+<div align="center">
+  <img alt="Herb HTML+ERB parser" height="256px" src="https://github.com/user-attachments/assets/d0714ee1-ca33-4aa4-aaa9-d632ba79d54a">
+</div>
 
-Minimal template engine with default escaping.
+<h2 align="center">Herb</h2>
 
-Description
------------
+<h4 align="center">HTML + ERB (HTML Embedded Ruby)</h4>
 
-Herb is a fork of [Mote] that uses a [ERB]-like style syntax and auto-escape HTML special characters by default.
+<div align="center">Powerful and seamless HTML-aware ERB parsing and tooling.</div>
 
-Installation
-------------
+## Contributing
 
-Add this line to your application's Gemfile:
+This project builds the Herb program and its associated unit tests using a Makefile for automation. The Makefile provides several useful commands for compiling, running tests, and cleaning the project.
 
-```ruby
-gem "herb"
-```
+### Requirements
+
+- [**Check**](https://libcheck.github.io/check/): For unit testing.
+- [**Clang 19**](https://clang.llvm.org): The compiler used to build this project.
+- [**Clang Format 19**](https://clang.llvm.org/docs/ClangFormat.html): For formatting the project.
+- [**Clang Tidy 19**](https://clang.llvm.org/extra/clang-tidy/): For linting the project.
+- [**Prism Ruby Parser v1.4.0**](https://github.com/ruby/prism/releases/tag/v1.4.0): We use Prism for Parsing the Ruby Source Code in the HTML+ERB files.
+- [**Ruby**](https://www.ruby-lang.org/en/): We need Ruby as a dependency for `bundler`.
+- [**Bundler**](https://bundler.io): We are using `bundler` to build [`prism`](https://github.com/ruby/prism) from source so we can build `herb` against it.
+- [**Emscripten**](https://emscripten.org): For the WebAssembly build of `libherb` so it can be used in the browser using the [`@herb-tools/browser`](https://github.com/marcoroth/herb/blob/main/javascript/packages/browser) package.
+- [**Doxygen**](https://www.doxygen.nl): For building the C-Reference documentation pages.
 
-And then execute:
+##### For Linux
 
+```bash
+xargs sudo apt-get install < Aptfile
 ```
-$ bundle
+or:
+
+```bash
+sudo apt-get install check clang-19 clang-tidy-19 clang-format-19 emscripten doxygen
 ```
 
-Or install it yourself as:
+##### For macOS (using Homebrew)
 
+```bash
+brew bundle
 ```
-$ gem install herb
+or:
+
+```bash
+brew install check llvm@19 emscripten doxygen
 ```
 
-Basic Usage
------------
+### Building
 
-This is a basic example:
+#### Clone the Repo
 
-```ruby
-require "herb"
+Clone the Git Repository:
 
-template = Herb.parse("your template goes here!")
-template.call
-# => "your template goes here!"
+```
+git clone https://github.com/marcoroth/herb && cd herb/
 ```
 
-Herb recognizes two tags to evaluate Ruby code: `<% %>`, and `<%= %>`. The difference between them is that while the `<% %>` tags only evaluate the code, the `<%= %>` tags also prints the result to the template.
+#### Build Herb
 
-Imagine that your template looks like this:
+We can now compile all source files in `src/` and generate the `herb` executable.
 
-```erb
-<% # single line code %>
-<% gems = ["rack", "cuba", "herb"] %>
+```bash
+make all
+```
 
-<%
-  # multi-line code
-  sorted = gems.sort
-%>
+> [!NOTE]
+For any consecutive builds you can just run `make`/`make all`.
 
-<ul>
-<% sorted.each do |name| %>
-  <li><%= name %></li>
-<% end %>
-</ul>
-```
+### Run
 
-The generated result will be like:
+The `herb` executable exposes a few commands for interacting with `.html.erb` files:
 
-```html
-<ul>
-  <li>cuba</li>
-  <li>herb</li>
-  <li>rack</li>
-</ul>
 ```
+❯ ./herb
+./herb [command] [options]
 
-Parameters
-----------
-
-The values passed to the template are available as local variables:
+Herb 🌿 Powerful and seamless HTML-aware ERB parsing and tooling.
 
-```ruby
-template = Herb.parse("Hello {{ name }}", [:name])
-template.call(name: "Ruby")
-# => Hello Ruby
+./herb lex [file]      -  Lex a file
+./herb lex_json [file] -  Lex a file and return the result as json.
+./herb parse [file]    -  Parse a file
+./herb ruby [file]     -  Extract Ruby from a file
+./herb html [file]     -  Extract HTML from a file
+./herb prism [file]    -  Extract Ruby from a file and parse the Ruby source with Prism
 ```
 
-You can also use the `params` local variable to access the given parameters:
+Running the executable shows a pretty-printed output for the respective command and the time it took to execute:
 
-```ruby
-template = Herb.parse("Hello {{ params[:name] }}")
-template.call(name: "Ruby")
-# => Hello Ruby
 ```
+❯ ./herb lex examples/simple_erb.html.erb
 
-Auto-escaping
--------------
+#<Herb::Token type="TOKEN_ERB_START" value="<%" range=[0, 2] start=(1:0) end=(1:2)>
+#<Herb::Token type="TOKEN_ERB_CONTENT" value=" title " range=[2, 9] start=(1:2) end=(1:9)>
+#<Herb::Token type="TOKEN_ERB_END" value="%>" range=[9, 11] start=(1:9) end=(1:11)>
+#<Herb::Token type="TOKEN_NEWLINE" value="\n" range=[11, 12] start=(1:0) end=(2:1)>
+#<Herb::Token type="TOKEN_EOF" value="" range=[12, 12] start=(2:1) end=(2:1)>
 
-By default, Herb escapes HTML special characters to prevent [XSS][xss] attacks. You can start the expression with an exclamation mark to disable escaping for that expression:
+Finished lexing in:
 
-```ruby
-template = Herb.parse("Hello {{ name }}", [:name])
-template.call(name: "<b>World</b>")
-# => Hello &lt;b&gt;World&lt;b&gt;
-
-template = Herb.parse("Hello {{! name }}", [:name])
-template.call(name: "<b>World</b>")
-# => Hello <b>World</b>
+        12 µs
+     0.012 ms
+  0.000012  s
 ```
 
-Herb::Helpers
---------------
+### Building the Ruby extension
 
-There's a helper available in the `Herb::Helpers` module, and you are
-free to include it in your code. To do it, just type:
+We use `rake` and `rake-compiler` to compile the Ruby extension. Running rake will generate the needed templates, run make, build the needed artifacts, and run the Ruby tests.
 
-```ruby
-include Herb::Helpers
+```bash
+rake
 ```
 
-### Using the `herb` helper
+If `rake` was successful you can use `bundle console` to interact with `Herb`:
+
+```bash
+bundle console
+```
 
-The `herb` helper receives a file name and a hash and returns the rendered version of its content. The compiled template is cached for subsequent calls.
+```
+irb(main):001> Herb.parse("<div></div>")
 
-```ruby
-herb("test/basic.erb", n: 3)
-# => "***\n"
+# => #<Herb::ParseResult:0x0000000 ... >
 ```
 
-### Template caching
+### Test
 
-When the `herb` helper is first called with a template name, the file is read and parsed, and a proc is created and stored in the current thread. The parameters passed are defined as local variables in the template. If you want to provide more parameters once the template was cached, you won't be able to access the values as local variables, but you can always access the `params` hash.
+Builds the test suite from files in `test/` and creates the `run_herb_tests` executable to run the tests:
 
-For example:
+#### For the C Tests
 
-```ruby
-# First call
-herb("foo.erb", a: 1, b: 2)
+```bash
+make test && ./run_herb_tests
 ```
 
-Contributing
-------------
-
-Fork the project with:
+#### For the Ruby Tests
 
-```
-$ git clone git@github.com:frodsan/herb.git
+```bash
+rake test
 ```
 
-To install dependencies, use:
+### Clean
 
+Removes the `herb`, `run_herb_tests`, `prism` installation, and all `.o` files.
+
+```bash
+make clean
 ```
-$ bundle install
-```
 
-To run the test suite, do:
+### Local Integration Testing
+
+The `bin/integration` script allows for quick local iteration. On every run it cleans the directory, builds the source from scratch and runs all checks, including the C-Tests, Ruby Tests, Linters, and examples in succession.
 
+```bash
+bin/integration
 ```
-$ rake test
+
+The integration was successful if you see:
+
 ```
+❯ bin/integration
 
-For bug reports and pull requests use [GitHub][issues].
+[...]
 
-License
--------
+Integration successful!
+```
 
-Herb is released under the [MIT License][mit].
+## License
 
-[erb]: http://ruby-doc.org/stdlib-2.3.1/libdoc/erb/rdoc/ERB.html
-[issues]: https://github.com/frodsan/herb/issues
-[mit]: http://www.opensource.org/licenses/MIT
-[mote]: https://github.com/soveran/mote
-[xss]: http://en.wikipedia.org/wiki/Cross-Site_Scripting
+This project is licensed under the MIT License - see the [LICENSE](LICENSE.txt) file for details.

data/Rakefile

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "English"
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task "make" do
+  puts "Running make..."
+  IO.popen("make") do |output|
+    output.each_line do |line|
+      puts line
+    end
+  end
+end
+
+begin
+  require "rake/extensiontask"
+
+  PLATFORMS = %w[
+    aarch64-linux-gnu
+    aarch64-linux-musl
+    arm-linux-gnu
+    arm-linux-musl
+    arm64-darwin
+    x86_64-darwin
+    x86_64-linux-gnu
+    x86_64-linux-musl
+    x86-linux-gnu
+    x86-linux-musl
+  ].freeze
+
+  exttask = Rake::ExtensionTask.new do |ext|
+    ext.name = "herb"
+    ext.source_pattern = "*.{c,h}"
+    ext.ext_dir = "ext/herb"
+    ext.lib_dir = "lib/herb"
+    ext.gem_spec = Gem::Specification.load("herb.gemspec")
+    ext.cross_compile = true
+    ext.cross_platform = PLATFORMS
+  end
+
+  Rake::Task[:compile].enhance do
+    raise "src/* could not be compiled #{$CHILD_STATUS.exitstatus}" if $CHILD_STATUS.exitstatus != 0
+  end
+
+  Rake::Task[:clean].enhance do
+    IO.popen("make clean") do |output|
+      output.each_line do |line|
+        puts line
+      end
+    end
+  end
+
+  task "gem:native" do
+    require "rake_compiler_dock"
+    # sh "bundle config set cache_all true"
+
+    PLATFORMS.each do |platform|
+      RakeCompilerDock.sh "bundle && rake native:#{platform} gem", platform: platform
+    end
+
+    RakeCompilerDock.sh "bundle && rake java gem", rubyvm: :jruby
+  rescue LoadError
+    abort "rake_compiler_dock is required to build native gems"
+  end
+
+  namespace "gem" do
+    task "prepare" do
+      require "rake_compiler_dock"
+      require "io/console"
+
+      # sh "bundle config set cache_all true"
+      sh "cp ~/.gem/gem-*.pem build/gem/ || true"
+
+      gemspec_path = File.expand_path("./herb.gemspec", __dir__)
+      spec = eval(File.read(gemspec_path), binding, gemspec_path)
+
+      RakeCompilerDock.set_ruby_cc_version(spec.required_ruby_version.as_list)
+
+      # ENV["GEM_PRIVATE_KEY_PASSPHRASE"] = STDIN.getpass("Enter passphrase of gem signature key: ")
+    rescue LoadError
+      abort "rake_compiler_dock is required for this task"
+    end
+
+    exttask.cross_platform.each do |platform|
+      desc "Build all native binary gems in parallel"
+      multitask "native" => platform
+
+      desc "Build the native gem for #{platform}"
+      task platform => "prepare" do
+        RakeCompilerDock.sh(
+          "bundle && rake native:#{platform} gem RUBY_CC_VERSION='#{ENV.fetch("RUBY_CC_VERSION", nil)}'",
+          platform: platform
+        )
+      end
+    end
+  end
+rescue LoadError => e
+  desc "Compile task not available (rake-compiler not installed)"
+  task :compile do
+    puts e
+    abort <<~MESSAGE
+
+      "rake-compiler is required for this task.
+
+      Are you running `rake` using `bundle exec rake`?
+
+      Otherwise
+        * try to run bundle install
+        * add it to your Gemfile
+        * or install it with: gem install rake-compiler
+    MESSAGE
+  end
+end
+
+desc "Render out template files"
+task :templates do
+  require_relative "templates/template"
+
+  Dir.glob("#{__dir__}/templates/**/*.erb").each do |template|
+    Herb::Template.render(template)
+  end
+end
+
+namespace :templates do
+  desc "Watch template files and regenerate on changes"
+  task :watch do
+    require "listen"
+
+    Rake::Task[:templates].execute
+
+    puts
+    puts "Watching config.yml and templates/**/*.erb for changes..."
+
+    ignore = Dir.glob("*/").map { |dir| Regexp.escape(dir.chomp("/")) }.map { |dir| %r{^#{dir}/} }
+
+    config_listener = Listen.to(".", only: /config\.yml$/, ignore: ignore) do
+      puts
+      puts "#{Time.now.strftime("[%Y-%m-%d %H:%M:%S]")} config.yml changed, regenerating all templates ..."
+      puts
+
+      Rake::Task[:templates].execute
+    end
+
+    template_listener = Listen.to("templates", only: /\.erb$/) do |modified, added, removed|
+      puts
+      (added + modified).each do |template|
+        template_file = template.delete_prefix("#{__dir__}/")
+
+        puts "#{Time.now.strftime("[%Y-%m-%d %H:%M:%S]")} Detected change, regenerating #{template_file} ..."
+        Herb::Template.render(template_file)
+      end
+
+      removed.each do |template|
+        puts
+        puts "#{template} was removed. Make sure to also remove the generated file."
+      end
+    end
+
+    config_listener.start
+    template_listener.start
+
+    sleep
+  rescue LoadError
+    abort "listen gem is required for this task. Add it to your Gemfile or install it with: gem install listen"
+  end
+end
+
+namespace :parse do
+  desc "Parse ERB files in a project directory"
+  task :project, [:path, :output_file] do |_t, args|
+    require_relative "lib/herb"
+
+    Herb::Project.new(args[:path], output_file: args[:output_file]).parse!
+  end
+end
+
+task default: [:templates, :make, :compile, :test]

data/exe/herb

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/herb"
+Herb::CLI.new(ARGV).call