From 74e86d266b244ff40c098dfabab239710c6e5143 Mon Sep 17 00:00:00 2001 From: Paul Duncan Date: Wed, 5 Sep 2018 23:19:38 -0400 Subject: ruby: more documentation --- ruby/lib/luigi-template.rb | 280 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 279 insertions(+), 1 deletion(-) (limited to 'ruby/lib') diff --git a/ruby/lib/luigi-template.rb b/ruby/lib/luigi-template.rb index 8b4d476..d1a8ac5 100644 --- a/ruby/lib/luigi-template.rb +++ b/ruby/lib/luigi-template.rb @@ -1,10 +1,288 @@ +# +# = Luigi Template +# +# == Overview +# +# Luigi Template is a string template library. +# +# == Examples +# +# Simple usage example: +# +# # load luigi template +# require 'luigi-template' +# +# # create template +# tmpl = Luigi::Template.new('hello %{name}') +# +# # run template and print result +# puts tmpl.run({ +# name: 'Paul' +# }) +# +# # prints "hello Paul" +# +# You can also filter values in templates, using the pipe symbol: +# +# # create template that converts name to upper-case +# tmpl = Luigi::Template.new('hello %{name | uc}') +# +# # run template and print result +# puts tmpl.run({ +# name: 'Paul' +# }) +# +# # prints "hello PAUL" +# +# Filters can be chained: +# +# # create template that converts name to upper-case and then +# # strips leading and trailing whitespace +# tmpl = Luigi::Template.new('hello %{name | uc | trim}') +# +# # run template and print result +# puts tmpl.run({ +# name: ' Paul ' +# }) +# +# # prints "hello PAUL" +# +# Filters can take arguments: +# +# # create template that converts name to lowercase and then +# # calculates the SHA-1 digest of the result +# tmpl = Luigi::Template.new('hello %{name | lc | hash sha1}') +# +# # run template and print result +# puts tmpl.run({ +# name: 'Paul', +# }) +# +# # prints "hello a027184a55211cd23e3f3094f1fdc728df5e0500" +# +# You can define custom global filters: +# +# # create custom global filter named 'foobarify' +# Luigi::FILTERS[:foobarify] = proc { |s| "foo-#{s}-bar" } +# +# # create template which uses custom "foobarify" filter +# tmpl = Luigi::Template.new('hello %{name | foobarify}') +# +# # run template and print result +# puts tmpl.run({ +# name: 'Paul' +# }) +# +# # prints "hello foo-Paul-bar" +# +# Or define custom filters for a template: +# +# # create template with custom filters rather than global filters +# tmpl = Luigi::Template.new('hello %{name | reverse}', { +# reverse: proc { |s| s.reverse } +# }) +# +# # run template and print result +# puts tmpl.run({ +# name: 'Paul', +# }) +# +# # prints "hello luaP" +# +# Your custom filters can accept arguments, too: +# +# # create custom global filter named 'foobarify' +# Luigi::FILTERS[:wrap] = proc { |s, args| +# case args.length +# when 2 +# '(%s, %s, %s)' % [args[0], s, args[1]] +# when 1 +# '(%s in %s)' % [s, args[0]] +# when 0 +# s +# else +# raise 'invalid argument count' +# end +# } +# +# # create template that uses custom "wrap" filter +# tmpl = Luigi::Template.new('sandwich: %{meat | wrap slice heel}, taco: %{meat | wrap shell}') +# +# # run template and print result +# puts tmpl.run({ +# meat: 'chicken' +# }) +# +# # prints "sandwich: (slice, chicken, heel), taco: (chicken in shell)" +# +# == Filters +# +# The following filters are built-in: +# +# * +uc+: Convert string to upper-case. +# * +lc+: Convert string to lower-case. +# * +h+: HTML-escape string. +# * +u+: URL-escape string. +# * +json+: JSON-encode value. +# * +trim+: Strip leading and trailing whitespace from string. +# * +base64+: Base64-encode value. +# * +hash+: Hash value. Requires hash algorithm parameter (ex: +# "sha1", "md5", etc). +# +# You can add your own global filters, like so: +# +# # create custom global filter named 'foobarify' +# Luigi::FILTERS[:foobarify] = proc { |s| "foo-#{s}-bar" } +# +# # create template which uses custom "foobarify" filter +# tmpl = Luigi::Template.new('hello %{name | foobarify}') +# +# # run template and print result +# puts tmpl.run({ +# name: 'Paul' +# }) +# +# # prints "hello foo-Paul-bar" +# +# == License +# +# Copyright 2007-2018 Paul Duncan ({pabs@pablotron.org}[mailto:pabs@pablotron.org]) +# +# 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. +# + require 'uri' require 'json' require 'openssl' # require 'pp' # -# String templating library. See Luigi::Template for details. +# Top-level Luigi namespace. See Luigi::Template for details. +# +# Example: +# +# # load luigi template +# require 'luigi-template' +# +# # create template +# tmpl = Luigi::Template.new('hello %{name}') +# +# # run template and print result +# puts tmpl.run({ +# name: 'Paul' +# }) +# +# # prints "hello Paul" +# +# You can also filter values in templates, using the pipe symbol: +# +# # create template that converts name to upper-case +# tmpl = Luigi::Template.new('hello %{name | uc}') +# +# # run template and print result +# puts tmpl.run({ +# name: 'Paul' +# }) +# +# # prints "hello PAUL" +# +# Filters can be chained: +# +# # create template that converts name to upper-case and then +# # strips leading and trailing whitespace +# tmpl = Luigi::Template.new('hello %{name | uc | trim}') +# +# # run template and print result +# puts tmpl.run({ +# name: ' Paul ' +# }) +# +# # prints "hello PAUL" +# +# Filters can take arguments: +# +# # create template that converts name to lowercase and then +# # calculates the SHA-1 digest of the result +# tmpl = Luigi::Template.new('hello %{name | lc | hash sha1}') +# +# # run template and print result +# puts tmpl.run({ +# name: 'Paul', +# }) +# +# # prints "hello a027184a55211cd23e3f3094f1fdc728df5e0500" +# +# You can define custom global filters: +# +# # create custom global filter named 'foobarify' +# Luigi::FILTERS[:foobarify] = proc { |s| "foo-#{s}-bar" } +# +# # create template which uses custom "foobarify" filter +# tmpl = Luigi::Template.new('hello %{name | foobarify}') +# +# # run template and print result +# puts tmpl.run({ +# name: 'Paul' +# }) +# +# # prints "hello foo-Paul-bar" +# +# Or define custom filters for a template: +# +# # create template with custom filters rather than global filters +# tmpl = Luigi::Template.new('hello %{name | reverse}', { +# reverse: proc { |s| s.reverse } +# }) +# +# # run template and print result +# puts tmpl.run({ +# name: 'Paul', +# }) +# +# # prints "hello luaP" +# +# Your custom filters can accept arguments, too: +# +# # create custom global filter named 'foobarify' +# Luigi::FILTERS[:wrap] = proc { |s, args| +# case args.length +# when 2 +# '(%s, %s, %s)' % [args[0], s, args[1]] +# when 1 +# '(%s in %s)' % [s, args[0]] +# when 0 +# s +# else +# raise 'invalid argument count' +# end +# } +# +# # create template that uses custom "wrap" filter +# tmpl = Luigi::Template.new('sandwich: %{meat | wrap slice heel}, taco: %{meat | wrap shell}') +# +# # run template and print result +# puts tmpl.run({ +# meat: 'chicken' +# }) +# +# # prints "sandwich: (slice, chicken, heel), taco: (chicken in shell)" # module Luigi # -- cgit v1.2.3