README.md

Lit CLI

Shine a light on terminal commands. 🔥

Lit lets you create console logs that are only visible after prefixing a command with lit. You can use flags to filter the types of logs and step through your application at runtime, essentially turning your logs into breakpoints. You can press Enter to continue to the next step or press P to begin a Pry session. Lit was originally created to view the reflections generated by Reflekt via the command line, but can be used in a range of applications.

Usage

Simply start any command with lit. For example a script like ruby script.rb becomes:

lit ruby script.rb

Then run the application and watch the terminal window for Lit messages:

Flags

Lit accepts flags to modify behaviour. They are prefixed with an @ and appended after the lit command:

lit @<flag-name> ruby <script-name>.rb

Flags start with an @ instead of a -- so that they aren't confused with flags for the original command that Lit is firing off.

@step

Step through the code. The terminal will stop at each lit() message, then prompt you to press Enter to continue to the next message or press P to enter a Pry session.

lit @step ruby script.rb

When in a Pry session, enter x to exit Pry or !!! to exit the program (use x; to access a variable called x).

Note: Only files required via require_relative are currently supported for Pry session.
Note: Pry is not available to lit() messages in the first file to require 'lit_cli', so require Lit in your application's entry point / main file if you need this feature.

@status

Filter logs by message status:

lit @status=error ruby script.rb

Multiple statuses are comma separated:

lit @status=fail,error ruby script.rb

@type

Filter logs by message type:

lit @type=cat,dog ruby script.rb

Types are optional and represent the type of data, similar to a class.

@delay

Delay the execution of a message to make fast outputting logs easier to read. The default delay is 0 seconds (no delay) but can be any positive Integer or Float, for example:

lit @delay=1 ruby script.rb

Installation

In Gemfile add:

gem 'lit-cli'

In terminal run:

bundle install

Or:

gem install lit-cli

If an application is currently using Lit then the lit command will already be available in your terminal without any installation required.

API

Instructions for integrating your application with Lit.

Usage

Require lit_cli at the top of your file:

require 'lit_cli'

Include LitCLI in your module or class:

class ExampleClass
  include LitCLI

Then use the lit() instance method:

lit "message"

lit()

lit(message, status = :info, type = nil, context = nil)

• String message - The message to show.
• Symbol status (optional) - The status of the message such as :info, :warn or :error.
• Symbol type (optional) - The type of data this message represents such as :cat or :dog.
• String context (optional) - The current class name or instance ID, anything that gives context.

Available statuses and types can be configured, see lib/config.rb and demo/demo.rb for more info.

Symbols

Special characters convey extra meaning when embedded in the message string.

method()

lit "message method()"

Placing () next to a word will style them as a method.

#number

lit "message #1"

Placing a # next to a number will style them as a number.

>indent

lit "> message"

Placing a > at the start of a message will indent the log in the console. Multiple >>> symbols can be used and for each one, two spaces of indentation will be added. Indentation is not preserved when using @status or @type filters.

^separator

lit "^ message"

Placing a ^ at the start of a message will add a line break above the log in the console. Multiple ^^^ symbols can be used and for each one, one line break will be added. Line breaks are not preserved when using @status or @type filters.

Code as comments

You can use the lit() method in place of comments to help document your code. This:

# Create control for method.
control = Control.new(action, 0, @@reflekt.aggregator)
action.control = control

Becomes this:

lit "Create control for #{method} method"
control = Control.new(action, 0, @@reflekt.aggregator)
action.control = control

Now you've commented your code and your comments double as logs.

Emoji support

You can even use the emoji 🔥() instead of lit() to call the method... cause why not? Climate change is real and we're all going to die anyway. So the final code could be:

🔥 "Create control for #{method} method"
control = Control.new(action, 0, @@reflekt.aggregator)
action.control = control

The lit emoji acts as a nice sectional heading too. These are all just ideas and it's up to you to decide how to write code and save the future of humanity.