rux 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 29ba86ed38eae6295a1f2f3a68df1b371589c72c24ef4827541e238bdc288f5d
+  data.tar.gz: 4db5f89366ba6bb85ef4939f33e55e71aed68baa9cc437d347f4888e1bb2e772
+SHA512:
+  metadata.gz: b94c6b6b4b9a4d802c32135b6f47f12186428b54a3d94c74a4eb72e858c077f4f4a8548615cd07e58c1b4a20340bcaba8412789e22f0387819850f0026f41eec
+  data.tar.gz: 5f37c06fe42d57e38dafa661f9f22c7a0dd180375afe36d4c4d98ed38f01d29c9668b1bf2e81fec19b05278bbabf081871c448944456cfe1f6045716e9d12ff9

data/Gemfile

@@ -0,0 +1,9 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :development, :test do
+  gem 'pry-byebug'
+  gem 'rake'
+  gem 'rspec'
+end

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Cameron Dutro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+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.

data/README.md

@@ -0,0 +1,310 @@
+## rux [![Build Status](https://travis-ci.com/camertron/rux.svg?branch=master)](https://travis-ci.com/camertron/rux)
+
+Rux is a JSX-inspired way to write HTML tags in your Ruby code. It can be used to render view components in Rails via the [rux-rails gem](https://github.com/camertron/rux-rails). This repo however contains only the rux parser itself.
+
+## Introduction
+
+A bit of background before we dive into how to use rux.
+
+### React and JSX
+
+React mainstreamed the idea of composing websites from a series of components. To make it conceptually easier to transition from HTML templates to Javascript components, React also introduced an HTML-based syntax called JSX that allows developers to embed HTML into their Javascript code.
+
+### Rails View Components
+
+For a long time, Rails didn't really have any support for components, preferring to rely on HTML template languages like ERB and HAML. The fine folks at Github however decided components could work well in Rails and released their [view_component framework](https://github.com/github/view_component). There was even some talk about merging view_component into Rails core as `ActionView::Component`, but unfortunately it looks like that won't be happening.
+
+**NOTE**: I'm going to be focusing on Rails examples here using the view_component gem, but rendering views from a series of components is a framework-agnostic idea.
+
+### View Component Example
+
+A view component is just a class. The actual view portion is usually stored in a secondary template file that the component renders in the context of an instance of that class. For example, here's a very basic view component that displays a person's name on the page:
+
+```ruby
+# app/components/name_component.rb
+class NameComponent < ViewComponent::Base
+  def initialize(first_name:, last_name:)
+    @first_name = first_name
+    @last_name = last_name
+  end
+end
+```
+
+```html+erb
+<%# app/components/name_component.html.erb %>
+<span><%= @first_name %> <%= last_name %></span>
+```
+
+View components have a number of very nice properties. Read about them on [viewcomponent.org](https://viewcomponent.org/) or watch Joel Hawksley's excellent 2019 [Railsconf talk](https://www.youtube.com/watch?v=y5Z5a6QdA-M).
+
+## HTML in Your Ruby
+
+Rux does one thing: it lets you write HTML in your Ruby code. Here's the name component example from earlier rewritten in rux (sorry about the syntax highlighting, Github doesn't know about rux yet).
+
+```ruby
+# app/components/name_component.rux
+class NameComponent < ViewComponent::Base
+  def initialize(first_name:, last_name:)
+    @first_name = first_name
+    @last_name = last_name
+  end
+
+  def call
+    <span>
+      {@first_name} {@last_name}
+    </span>
+  end
+end
+```
+
+**NOTE**: The example above takes advantage of a feature of the view_component gem that lets you define a `call` method instead of creating a separate template file.
+
+Next, we'll run the `ruxc` tool to translate the rux code into Ruby code, eg. `ruxc app/components/name_component.rux`. Here's the result:
+
+```ruby
+class NameComponent < ViewComponent::Base
+  def initialize(first_name:, last_name:)
+    @first_name = first_name
+    @last_name = last_name
+  end
+
+  def call
+    Rux.tag("span") {
+      Rux.create_buffer.tap { |_rux_buf_,|
+        _rux_buf_ << @first_name
+        _rux_buf_ << " "
+        _rux_buf_ << @last_name
+      }.to_s
+    }
+  end
+end
+```
+
+As you can see, the span tag was converted to a `Rux.tag` call. The instance variables containing the first and last names are concatenated together and rendered inside the span.
+
+## Composing Components
+
+Things get even more interesting when it comes to rendering components inside other components. Let's create a greeting component that makes use of the name component:
+
+```ruby
+# app/components/greeting_component.rux
+class GreetingComponent < ViewComponent::Base
+  def call
+    <div>
+      Hey there <NameComponent first-name="Homer" last-name="Simpson" />!
+    </div>
+  end
+end
+```
+
+The `ruxc` tool produces:
+
+```ruby
+class GreetingComponent < ViewComponent::Base
+  def call
+    Rux.tag("div") {
+      Rux.create_buffer.tap { |_rux_buf_,|
+        _rux_buf_ << " Hey there "
+        _rux_buf_ << render(NameComponent.new(first_name: "Homer", last_name: "Simpson"))
+        _rux_buf_ << "! "
+      }.to_s
+    }
+  end
+end
+```
+
+The `<NameComponent>` tag was translated into an instance of the `NameComponent` class and the attributes into its keyword arguments.
+
+**NOTE**: The `render` method is provided by `ViewComponent::Base`.
+
+## Embedding Ruby
+
+Since rux code is translated into Ruby code, anything goes. You're free to put any valid Ruby statements inside the curly braces.
+
+For example, let's say we want to change our greeting component to greet a variable number of people:
+
+```ruby
+# app/components/greeting_component.rux
+class GreetingComponent < ViewComponent::Base
+  def initialize(people:)
+    # people is an array of hashes containing :first_name and :last_name keys
+    @people = people
+  end
+
+  def call
+    <div>
+      {@people.map do |person|
+        <NameComponent
+          first-name={person[:first_name]}
+          last-name={person[:last_name]}
+        />
+      end}
+    </div>
+  end
+end
+```
+
+Notice we were able to embed Ruby within rux within Ruby within rux. Within Ruby. The rux parser supports unlimited levels of nesting, although you'll probably not want to go _too_ crazy.
+
+## Keyword Arguments Only
+
+Any view component that will be rendered by rux must _only_ accept keyword arguments in its constructor. For example:
+
+```ruby
+class MyComponent < ViewComponent::Base
+  # GOOD
+  def initialize(first_name:, last_name:)
+  end
+
+  # BAD
+  def initialize(first_name, last_name)
+  end
+
+  # BAD
+  def initialize(first_name, last_name = 'Simpson')
+  end
+end
+```
+
+In other words, positional arguments are not allowed. This is because there's no such thing as a positional HTML attribute - all HTML attributes are key/value pairs. So, in order to match up with HTML, rux components are written with keyword arguments.
+
+Note also that the rux parser will replace dashes with underscores in rux tag attributes to adhere to both HTML and Ruby syntax conventions, since HTML attributes use dashes while Ruby keyword arguments use underscores. For example, here's how to write a rux tag for `MyComponent` above:
+
+```ruby
+<MyComponent first-name="Homer" last-name="Simpson" />
+```
+
+Notice that the rux attribute "first-name" is passed to `MyComponent#initialize` as "first_name".
+
+## How it Works
+
+Translating rux code (Ruby + HTML tags) into Ruby code happens in three phases: lexing, parsing, and emitting. The lexer phase is implemented as a wrapper around the lexer from the [Parser gem](https://github.com/whitequark/parser) that looks for specific patterns in the token stream. When it finds an opening HTML tag, it hands off lexing to the rux lexer. When the tag ends, the lexer continues emitting Ruby tokens, and so on.
+
+In the parsing phase, the token stream is transformed into an intermediate representation of the code known as an abstract syntax tree, or AST. It's the parser's job to work out which tags are children of other tags, associate attributes with tags, etc.
+
+Finally it's time to generate Ruby code in the emitting phase. The rux gem makes use of the visitor pattern to walk over all the nodes in the AST and generate a big string of Ruby code. This big string is the final product that can be written to a file and executed by the Ruby interpreter.
+
+## Transpiling Rux to Ruby
+
+While the `ruxc` tool is a convenient way to transpile rux to Ruby via the command line, it's also possible to do so programmatically.
+
+### Transpiling Strings
+
+Let's say you have a string containing a bunch of rux code. You can transpile it to Ruby like so:
+
+```ruby
+require 'rux'
+
+str = 'some rux code'
+Rux.to_ruby(str)
+```
+
+**NOTE**: The `to_ruby` method accepts a visitor instance as its second argument (see below for more information about creating custom visitors). It uses the default visitor if no second argument is provided.
+
+### Transpiling Files
+
+Rux comes with a handy `File` class to make transpiling files easier:
+
+```ruby
+require 'rux'
+
+f = Rux::File.new('path/to/some/file.rux')
+
+# get result as a string, same as calling Rux.to_ruby
+f.to_ruby
+
+# write result to path/to/some/file.rb
+f.write
+
+# write result to the given file
+f.write('somewhere/else/file.rb')
+
+# the default file the result will be written, i.e. the location
+# #write will write to
+f.default_outfile
+```
+
+## Custom Visitors
+
+Rux comes with a default visitor capable of emitting Ruby code that is mostly compatible with the view_component gem discussed earlier. A little bit of extra work is required to render rux components in Rails, which is why the rux-rails gem uses a modified version of the default visitor to emit Ruby code that will render correctly in Rails views. It's likely other frameworks that want to render rux components will need a custom visitor as well.
+
+Visitors should inherit from the `Rux::Visitor` class and implement the various methods. See lib/rux/visitor.rb for details. If you're looking to tweak the default visitor, inherit from `Rux::DefaultVisitor` instead, and see lib/rux/default_visitor.rb for details.
+
+## Custom Tag Builders
+
+The `Rux.tag` method emits HTML tags via the configured tag builder. You can configure a custom tag builder by setting `Rux.tag_builder` to any object that responds to the `call` method (and accepts three arguments). For example:
+
+```ruby
+class MyTagBuilder
+  def call(tag_name, attributes = {}, &block)
+    # Should return a string, eg. '<div foo="bar"></div>'.
+    # When called, the block should return the tag's body contents.
+  end
+end
+
+Rux.tag_builder = MyTagBuilder.new
+```
+
+Or, since the only requirement is that the tag builder respond to `#call`, you could pass a lambda:
+
+```ruby
+Rux.tag_builder = -> (tag_name, attributes = {}, &block) do
+  # Should return a string, eg. '<div foo="bar"></div>'.
+  # When called, the block should return the tag's body contents.
+end
+```
+
+## Custom Buffers
+
+You may have noticed calls to `Rux.create_buffer` in the code examples above. Rux comes with a default buffer implementation, but you can configure a custom one as well. The rux-rails gem for example configures rux to use `ActiveSupport::SafeBuffer` in order to be compatible with Rails view rendering. Buffer implementations only need to define two methods: `#>>` and `#to_s`:
+
+```ruby
+class MyBuffer
+  def initialize
+    @buffer = ''
+  end
+
+  def <<(thing)
+    # it's important to handle nils here
+    @buffer << (thing || '')
+  end
+
+  def to_s
+    @buffer
+  end
+end
+
+Rux.buffer = MyBuffer
+```
+
+## The Library Path
+
+It is my hope that, in the future, Ruby and Rails devs will publish collections of view components in gem form that other devs can use in their own projects. Maybe some of those view component libraries will even be written in rux. Accordingly, I wanted a way of adding rux components to Rails' eager load system, but without actually depending on Rails.
+
+The rux library path is a way for libraries written in rux to register themselves. The rux-rails gem automatically appends every entry in the library path to the Rails eager load and autoload paths so .rux files are automatically reloaded in development mode. Hopefully the library path enables other frameworks to do something similar.
+
+Adding a path is done like so:
+
+```ruby
+Rux.library_paths << 'path/to/dir/with/rux/files'
+```
+
+## Editor Support
+
+Sublime Text: [https://github.com/camertron/rux-SublimeText](https://github.com/camertron/rux-SublimeText)
+
+Atom: [https://github.com/camertron/rux-atom](https://github.com/camertron/rux-atom)
+
+VSCode: [https://github.com/camertron/rux-vscode](https://github.com/camertron/rux-vscode)
+
+## Running Tests
+
+`bundle exec rspec` should do the trick.
+
+## License
+
+Licensed under the MIT license. See LICENSE for details.
+
+## Authors
+
+* Cameron C. Dutro: http://github.com/camertron

data/Rakefile

@@ -0,0 +1,14 @@
+require 'bundler'
+require 'rspec/core/rake_task'
+require 'rubygems/package_task'
+
+require 'rux'
+
+Bundler::GemHelper.install_tasks
+
+task default: :spec
+
+desc 'Run specs'
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = './spec/**/*_spec.rb'
+end

data/bin/ruxc

@@ -0,0 +1,96 @@
+#! /usr/bin/env ruby
+
+$:.push(File.expand_path('./lib'))
+
+require 'pathname'
+require 'optparse'
+require 'rux'
+
+class RuxCLI
+  def self.parse(argv)
+    if argv.empty?
+      puts 'Please pass a file or directory to transpile'
+      exit 1
+    end
+
+    options = {
+      recursive: false,
+      pretty: true
+    }
+
+    if argv.first != '-h' && argv.first != '--help'
+      options[:in_path] = argv.shift
+    end
+
+    parser = OptionParser.new do |opts|
+      opts.banner = "Usage: ruxc path [options]"
+
+      oneline(<<~DESC).tap do |desc|
+        Prettify generated Ruby code (default: #{options[:pretty]}).
+      DESC
+        opts.on('-p', '--[no-]pretty', desc) do |pretty|
+          options[:pretty] = pretty
+        end
+      end
+
+      opts.on('-h', '--help', 'Prints this help info') do
+        puts opts
+        exit
+      end
+    end
+
+    parser.parse(argv)
+    new(options)
+  end
+
+  def self.oneline(str)
+    str.split("\n").join(' ')
+  end
+
+  def initialize(options)
+    @options = options
+  end
+
+  def validate
+    unless File.exist?(in_path)
+      puts "Could not find file at '#{in_path}'"
+      exit 1
+    end
+  end
+
+  def each_file(&block)
+    files = if in_path.directory?
+      in_path.glob(File.join('**', '*.rux'))
+    else
+      [in_path]
+    end
+
+    files.each do |file|
+      ruby_file = file.sub_ext('.rb')
+      yield file, ruby_file
+    end
+  end
+
+  def in_path
+    @in_path ||= Pathname(@options[:in_path]).expand_path
+  end
+
+  def pretty?
+    @options[:pretty]
+  end
+
+  private
+
+  def directory?
+    File.directory?(in_path)
+  end
+end
+
+cli = RuxCLI.parse(ARGV)
+cli.validate
+
+cli.each_file do |in_file, out_file, rbi_file|
+  rux_file = Rux::File.new(in_file)
+  rux_file.write(out_file, pretty: cli.pretty?)
+  puts "Wrote #{out_file}"
+end