RichText

This gem is intended to simplify the handling of formatted text. Out of the box there is no support for any actual format, but that is intentional. The RichText::Document class is primarily ment to be subclassed and extended, and only includes functionality that is (potentially) useful to any format.

See Usage below for more details on how to work with and extend the gem.

Installation

Add this line to your application's Gemfile:

gem 'richtext'

And then execute:

$ bundle

Or install it yourself as:

$ gem install richtext

Usage

# Create a new RichText document
rt = RichText::Document.new 'hello '

# Or use the more convenient method
rt = RichText 'hello '

# Format the text using attributes
entry = rt.append('world', bold: true, my_attribute: '.')

# Some common styling attributes are supported directly
# This line is equivalent to entry[:italic] = true
entry.italic = true
# Under the covers the attributes are stored as
# key-value pairs, so any attribute is valid
entry[:my_attribute] = '!'

# Render the text without any formatting
puts rt.to_s # => 'hello world'

# Or style the text yourself
html = rt.to_s do |e, string|
  # Access the attributes from the entry and format the
  # string accordingly
  string += e[:my_attribute] if e[:my_attribute]
  string = "<b>#{string}</b>" if e.bold?

  # Return the formatted string at the end of the block
  string
end

puts html # => 'hello <b>world!</b>'

Implementing new formats is easy. Just extend the RichText::Document class and implement the class methods .parse and .render. The following snippet describes a document type that only renders words with more than 6 letters.

class MyFormat < RichText::Document
  def should_parse?
    true
  end

  def self.parse(base, string)
    # Format specific implementation to parse a string. Here
    # each word is represented by its own entry. Entries are
    # given a random visibility attribute.
    string.split(' ').each do |word|
      base.append_child word, visible: (word.length > 6)
    end
  end

  def self.render(base)
    # Format specific implementation to render the document
    str = base.to_s do |entry, string|
      next string unless entry.leaf?
      entry[:visible] ? string + ' ' : ''
    end

    str.rstrip
  end
end

doc = MyFormat.new 'Format specific implementation to parse a string'
puts doc.to_s # => 'specific implementation'

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/seblindberg/richtext.

License

The gem is available as open source under the terms of the MIT License.