Submarine is a lightweight string formatter built in Ruby. It allows the use of placeholder values inside of a string, which can then be formatted during runtime into whatever else you like. It's best summed up with a quick example:
string = "Hello, my name is [[name]]."
formatted_string = Submarine.new(text: string, name: 'Joe').format!
=> "Hello, my name is Joe."
Not completely unlike Handlebars or Mustache or RedCloth, Submarine takes a string and formats it using predefined key value pairs.
When is Submarine useful? Let's say you have a Ruby web app with some admin editable text fields. The admin has a particular text field that allows them to enter a welcome message that's displayed in a users dashboard. The admin would like to include the users name in the message, as a way of personalizing the greeting. Submarine allows the admin to enter text with predefined formatters that will then be magically converted when the user views the message.
Maybe the text copy the admin enters via the web app interface looks like:
// Inside a text field input
Good morning [[name]], welcome back to your dashboard!
This string can now be run through Submarine to turn [[name]] into something useful:
greeting = "Good morning [[name]], welcome back to your dashboard!"
formatted_greeting = Submarine.new(text: greeting, name: user.name).format!
=> "Good morning Joe, welcome back to your dashboard!"
Add the gem the standard Gemfile way:
# Gemfile
gem 'submarine'
As shown above, Submarine takes a string and formats anything surrounded in double square brackets, like [[name]]. Maybe you're formatting an email:
email_body = "Hello [[name]]. You have [[days]] until your trial expires."
sub = Submarine.new(text: email_body, name: user.name, days: user.account.days_until_expires)
sub.format! => "Hello Joe, you have 7 days until your trial expires."
Submarine only requires that you provide it a string and the corresponding replacement values.
Submarine is configurable. Maybe you're not particularly fond of double square brackets and you'd prefer to have your variables surrounded with curly brackets, like {{name}}. Or maybe you prefer something more esoteric like <^name^>. Although Submarine defaults to square brackets, you're free to override them:
# maybe in an initialization file like config/initializers/submarine.rb
Submarine.configure do |config|
config.format_key = :text # Key representing the string to be formatted
config.left_delimiter = '[[' # The left-hand side matcher
config.right_delimiter = ']]' # The right-hand side matcher
config.substitutions = {} # Optional global default substitutions
end
config.substitutions: You can predefine global substitution defaults in the configuration. Maybe you'd always like to match [[contact_email]] with config.substitutions = {contact_email: 'contact@mysite.com'}.
If you'd like to reload the Submarine defaults at any point during runtime you can call reload! on the configuration object:
Submarine.config.reload!
This gem was created for Ruby 2. It's very likely it could work with older versions. You'll have to test to determine compatibility!
Submarine is open and free for all. Please use, fork, update, critique, send pull requests, etc.