Say gives you the API and the output style you already know and love from ActiveRecord::Migration#say... anywhere! Plus a few extra goodies for long-running processes like incremental progress indicators and remaining time estimation.
Add this line to your application's Gemfile:
gem"say",github: "pdobb/say"# Not published to RubyGems.And then execute:
bundleTested MRI Ruby Versions:
- 3.1
- 3.2
- 3.3
- 3.4
- 4.0
For Ruby 2.7 support, install say gem version 0.5.2.
gem"say",github: "pdobb/say",tag: "v0.5.2"# Not published to RubyGems.Say has no other dependencies.
Typical usage is to just call Say.<method> directly, though it is possible to include Say if you prefer. (See below.)
When called with a block, say will output both Start and Finish banners, then return the result of the block to the caller.
When called without a block, say will output a string of the specified type (defaults to :success).
require"say"classDirectAccessProcessordefrunSay.("DirectAccessProcessor"){Say.("Successfully did the thing!")Say.()# Or: Say.callSay.("Debug details about this ...",:debug)Say.("Info about stuff ...",:info)Say.("Maybe look into this thing ...",:warn)Say.("Failed to do a thing ...",:error)"The Result!"}endendresult=DirectAccessProcessor.new.run=DirectAccessProcessor ========================================================
->Successfullydidthe thing!
...
>> Debugdetailsaboutthis ...
-- Infoaboutstuff ...
!¡Maybelookintothisthing ...
** Failedtodoathing ...
=Done(0.0001s) ===============================================================
# => "The Result!"Use include Say to gain access to the instance-level say methods.
require"say"classIncludeProcessorincludeSaydefrunsay("IncludeProcessor"){say("Successfully did the thing!")saysay("Debug details about this ...",:debug)say("Info about stuff ...",:info)say("Maybe look into this thing ...",:warn)say("Failed to do a thing ...",:error)"The Result!"}endendresult=IncludeProcessor.new.run=IncludeProcessor =============================================================
-> Successfullydidthe thing!
...
>> Debugdetailsaboutthis ...
-- Infoaboutstuff ...
!¡Maybelookintothisthing ...
** Failedtodoathing ...
=Done(0.0001s) ===============================================================
# => "The Result!"When using Say.(<message>, <type>), the available types and output representations are:
| Type | Output Prefix |
|---|---|
:debug | " >> " |
:error | " ** " |
:info | " -- " |
:success | " -> " |
:warn | " !¡ " |
Say.debug("TEST")# => " >> TEST"Say.error("TEST")# => " ** TEST"Say.info("TEST")# => " -- TEST"Say.success("TEST")# => " -> TEST"Say.warn("TEST")# => " !¡ TEST"The default type if call is used is :success.
Say.call("TEST")# => " -> TEST"Say.("TEST")# => " -> TEST"The include Say alternatives for each of the <type> calls in the previous section are:
Say.("TEST",:debug)# => " >> TEST"Say.("TEST",:error)# => " ** TEST"Say.("TEST",:info)# => " -- TEST"Say.("TEST",:success)# => " -> TEST"Say.("TEST",:warn)# => " !¡ TEST"Use Say.hr for thin, 1-line separators + padding on top/bottom.
Say.info("Before")Say.hrSay.("After")
-- Before
--------------------------------------------------------------------------------
->AfterThe fill line, template, and length can all be customized:
Say.info("Before")Say.hr("-*",template: "%s",columns: 20)# `template` defaults to: `"\n%s\n"Say.("After")
-- Before
-*-*-*-*-*-*-*-*-*-*
->AfterTemplate can also include book-ends:
Say.hr("-*",template: "|%s|")
|-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*|Use Say.section for 3-line banners to really visually split up your output into major sections.
Say.section
================================================================================
================================================================================
================================================================================
Say.section("TEST")
================================================================================
=TEST =========================================================================
================================================================================
Say.section("TEST",columns: 0)
========
=TEST=
========The various banner-producing methods also support left/center/right justification. Just pass in e.g. justify: :left, justify: :center, or justify: :right. The default, if nothing is supplied, is justify: :left.
# BlockSay.("Hello, World!"){Say.("Huzzah!")}=Hello,World! ================================================================
-> Huzzah!=Done(0.0000s) ===============================================================
Say.("Hello, World!",justify: :left){Say.("Huzzah!")}=Hello,World! ================================================================
-> Huzzah!=Done(0.0000s) ===============================================================
Say.("Hello, World!",justify: :center){Say.("Huzzah!")}
================================= Hello,World!================================
-> Huzzah!
================================ Done(0.0000s) ================================
Say.("Hello, World!",justify: :right){Say.("Huzzah!")}================================================================ Hello,World!=-> Huzzah!
=============================================================== Done(0.0000s)=# BannerSay.banner("TEST")=TEST =========================================================================Say.banner("TEST",justify: :left)=TEST =========================================================================Say.banner("TEST",justify: :center)
=====================================TEST =====================================Say.banner("TEST",justify: :right)
=========================================================================TEST=# HeaderSay.header("TEST")=TEST =========================================================================Say.header("TEST",justify: :left)=TEST =========================================================================Say.header("TEST",justify: :center)
=====================================TEST =====================================Say.header("TEST",justify: :right)
=========================================================================TEST=# FooterSay.footer=Done =========================================================================Say.footer(justify: :left)=Done =========================================================================Say.footer(justify: :center)
=====================================Done =====================================Say.footer(justify: :right)
=========================================================================Done=# SectionSay.section("TEST")
================================================================================
=TEST =========================================================================
================================================================================
Say.section("TEST",justify: :left)
================================================================================
=TEST =========================================================================
================================================================================
Say.section("TEST",justify: :center)
================================================================================
=====================================TEST =====================================
================================================================================
Say.section("TEST",justify: :right)
================================================================================
=========================================================================TEST=
================================================================================NOTE: The "line" methods will ignore justification attempts as there is no built in concept of columns for these.
Say.("TEST",justify: :right)# `justify: :right` is ignored.->TESTAll of the above examples are using the default interpolation template accessed via the Say.<method> methods. For advanced usage, one may access the Say::InterpolationTemplate directly and either use the predefined templates or specify their own.
# :double_lineinterpolation_template=Say::InterpolationTemplate::Builder.double_lineinterpolation_template.inspect# => "['=', ...]{}['=', ...]"interpolation_template.interpolate# => "=="interpolation_template.left_justify(length: 20)# => "===================="# :title (the default template, if none is specified)interpolation_template=Say::InterpolationTemplate::Builder.titleinterpolation_template.inspect# => ['=', ...] {} ['=', ...]interpolation_template.interpolate("TEST")# => "= TEST ="interpolation_template.left_justify("TEST",length: 20)# => "= TEST ============="interpolation_template.center_justify("TEST",length: 20)# => "======= TEST ======="interpolation_template.right_justify("TEST",length: 20)# => "============= TEST ="# :wtfinterpolation_template=Say::InterpolationTemplate::Builder.wtfinterpolation_template.inspect# => "['?', ...] {} ['?', ...]"interpolation_template.interpolate("TEST")# => "? TEST ?"interpolation_template.left_justify("TEST",length: 20)# => "? TEST ?????????????"interpolation_template.center_justify("TEST",length: 20)# => "??????? TEST ???????"interpolation_template.right_justify("TEST",length: 20)# => "????????????? TEST ?"# Example 1interpolation_template=Say::InterpolationTemplate.new(left_bookend: "╰(⇀︿⇀)つ-]═",left_fill: "-",right_fill: "-")interpolation_template.inspect# => "╰(⇀︿⇀)つ-]═['-', ...]{}['-', ...]"interpolation_template.interpolate("TEST")# => "╰(⇀︿⇀)つ-]═-TEST-"interpolation_template.left_justify("TEST",length: 40)# => "╰(⇀︿⇀)つ-]═-TEST-------------------------"interpolation_template.center_justify("TEST",length: 40)# => "╰(⇀︿⇀)つ-]═--------TEST------------------"interpolation_template.right_justify("TEST",length: 40)# => "╰(⇀︿⇀)つ-]═-------------------------TEST-"# Example 2interpolation_template=Say::InterpolationTemplate.new(left_bookend: "( •_•)O*¯",left_fill: "`·.·´",right_fill: "`·.·´",right_bookend: "¯°Q(•_• )")interpolation_template.inspect# => "( •_•)O*¯['`·.·´', ...]{}['`·.·´', ...]¯°Q(•_• )"interpolation_template.interpolate("TEST")# => "( •_•)O*¯`·.·´TEST`·.·´¯°Q(•_• )"interpolation_template.left_justify("TEST")# => "( •_•)O*¯`·.·´TEST`·.·´`·.·´`·.·´`·.·´`·.·´`·.·´`·.·´`·.·´`·.·´`·.·´`·.¯°Q(•_• )"interpolation_template.center_justify("TEST")# => "( •_•)O*¯`·.·´`·.·´`·.·´`·.·´`·.·`·.·´TEST`·.·´`·.·´`·.·´`·.·´`·.·´`·.·¯°Q(•_• )"interpolation_template.right_justify("TEST")# => "( •_•)O*¯`·.·´`·.·´`·.·´`·.·´`·.·´`·.·´`·.·´`·.·´`·.·´`·.`·.·´TEST`·.·´¯°Q(•_• )"Use Say.progress to track long-running processing loops on a given interval. Set the interval to receive say updates only during on-interval ticks through the loop. The default interval is 1, meaning every loop is considered on-interval.
# The default interval is 1.Say.progressdo |interval|
3.timesdo# Increment the interval's internal index by 1.interval.updateinterval.say("Test",:debug)endend=[20230604151646]Start(i=0) =================================================[20230604151646] >> Test(i=1)[20230604151646] >> Test(i=2)[20230604151646] >> Test(i=3)=Done(0.0000s) ===============================================================Say.progress("Progress Tracking Test",interval: 3)do |interval|
0.upto(6)do |index|
# Set the interval's internal index to the current index. This may be safer.interval.update(index)# Only "say" for on-interval ticks through the loop.interval.say("Before Update Interval.",:debug)# Optionally use a block to time a segment.interval.say("Progress Interval Block.")dosleep(0.025)# Do the work here.# Always "say", regardless of interval, in the usual way: with `Say.call`.Say.("Interval-Agnostic Update. Index: #{index}",:info)endinterval.say("After Update Interval.",:debug)endend=[20230604151646]ProgressTrackingTest(i=0) ================================
-- Interval-AgnosticUpdate.Index: 0
-- Interval-AgnosticUpdate.Index: 1
-- Interval-AgnosticUpdate.Index: 2[20230604151646] >> BeforeUpdateInterval.(i=3)=[20230604151646]ProgressIntervalBlock.(i=3) ==============================
-- Interval-AgnosticUpdate.Index: 3=Done(0.0261s) ===============================================================
[20230604151646] >> AfterUpdateInterval.(i=3)
-- Interval-AgnosticUpdate.Index: 4
-- Interval-AgnosticUpdate.Index: 5[20230604151647] >> BeforeUpdateInterval.(i=6)=[20230604151647]ProgressIntervalBlock.(i=6) ==============================
-- Interval-AgnosticUpdate.Index: 6=Done(0.0261s) ===============================================================
[20230604151647] >> AfterUpdateInterval.(i=6)=Done(0.1828s) ===============================================================Internally, calling say on a Say::Progress::Interval object uses Say.progress_line to output the given message and index indicator. You may do the same even without an Interval object.
# Given a message. (The default Type is :info.)Say.progress_line("TEST",index: 3)# => [20230604151647] -- TEST (i=3)Say.progress_line("TEST",:success,index: 3)# => [20230604151647] -> TEST (i=3)# Given no message.Say.progress_line(index: 3)# => [20230604151647] ... (i=3)If you choose to include Say then your class will gain the following instance methods:
saysay_bannersay_footersay_headersay_linesay_progresssay_progress_linesay_sectionsay_with_block
... though you probably really only need say, and sometimes: say_progress and/or say_progress_line.
classWithIncludeincludeSayendclassWithoutIncludeendadded_class_methods=WithInclude.methods - WithoutInclude.methodsSay.("Class methods added by `include Say`: #{added_class_methods}")
-- Classmethodsaddedby`include Say`: []added_instance_methods=(WithInclude.new.methods - WithoutInclude.new.methods).sort!Say.("Instance methods added by `include Say`: #{added_instance_methods}")->Instancemethodsaddedby`include Say`: [:say,:say_banner,:say_footer,:say_header,:say_line,:say_progress,:say_progress_line,:say_section,:say_with_block]The standardized nature of Say's logging methods lends itself well to highlighting output types using iTerm2's Text Highlighting Triggers. To set this up, go to Settings for iTerm2 -> Profiles -> Advanced -> Triggers section: "Edit" Button.
For more help, see iTerm's documentation on Triggers.
The regular expressions and HEX codes used in the screenshot are:
(?<=^ )->(?= )# Text HEX: #0ae400 Background HEX: transparent(?<=^ )>>(?= )# Text HEX: #ff6500 Background HEX: transparent(?<=^ )--(?= )# Text HEX: #ffffff Background HEX: #666666(?<=^ )!¡(?= )# Text HEX: #ffff00 Background HEX: transparent.*\*{2,}.* # Text HEX: #ffffff Background HEX: #ff0000After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. Or, run rake to run the tests plus linters as well as yard (to confirm proper YARD documentation practices). 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 test this gem:
rakerubocop
reek
npx prettier . --check
npx prettier . --writeTo release a new version of this gem to RubyGems:
- Update the version number in
version.rb - Update
CHANGELOG.md - Run
bundleto update Gemfile.lock with the latest version info - Commit the changes. e.g.
Bump to vX.Y.Z - Run
rake release, which will create a git tag for the version, push git commits and the created tag, and then attempt to push the.gemfile to rubygems.org.
- NOTE: This will fail, as there is already a
saygem and this one is not it. This gem must be installed form github source.
YARD documentation can be generated and viewed live:
- Install YARD:
gem install yard - Run the YARD server:
yard server --reload - Open the live documentation site:
open http://localhost:8808
While the YARD server is running, documentation in the live site will be auto-updated on source code save (and site reload).
Bug reports and pull requests are welcome on GitHub at https://github.com/pdobb/say. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the Say project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.