Forem: Lazarus Lazaridis

stup - a shell tool for daily notes

Lazarus Lazaridis — Thu, 30 Apr 2020 20:11:21 +0000

Over the past few years I've been participating in Stand-up meetings and it took me some time to find a convenient and effective way for keeping notes about what I was doing every day.

I needed to be able to:

keep categorized notes on the issues I worked on, the meetings I participated in and stuff that blocked my work etc
easily access these notes based on their date
have an overview of what I did for example the last week
all of the above:
- from inside a terminal
- with the notes strictly bound to the date they are taken
- without having to manually structure and update a single document
- without having to manually create a document for each day

stup

I made this tool which actually is a bash script and I named it stup from the term stand-up.

You can find the project on GitHub here.

Usage examples

Below are some examples showing the most important features of stup.

Adding notes

# Adding a note to the default category at current date
stup add -n "Worked on issue #ABC123"

# Adding a note to the default category setting the current date explicitly
stup add today -n "Worked on issue #ABC123"

# Adding a note to the meetings category
stup add today -c "meetings" -n "2 hours with @phoebe for the project kick off"

# Adding a note to the blocking category for April 10th, 2020
stup add @ 2020-04-10 -c "blocking" -n "connectivity issues"

Showing notes

# Showing yesterday's notes
$ stup

# Showing yesterday's notes explicitly setting the date
$ stup yesterday

# Showing today's notes
$ stup today

# Showing notes on a specific date
$ stup show @ 2020-04-18

# Showing notes on a specific date for the meetings category
$ stup show @ 2020-04-18 -c "meetings"

Retrieving all notes for a period of time

# List current week's notes
stup log week

# List current week's notes skipping command's literal
stup week

# List previous week's notes
stup log previous-week

# List notes between January 20th, 2020 and March 2nd, 2020
stup log --from 2020-01-20 --to 2020-03-02

# List meeting notes between January 20th, 2020 and March 2nd, 2020
stup log --from 2020-01-20 --to 2020-03-02 -c "meetings"

Behind the scenes

Notes are organized in categories.

When a new note is added, stup creates a markdown file and places it under the category's directory in a sub-directory with a path based on the date.

CATEGORIES_ROOT_DIRECTORY/CATEGORY/YEAR/MONTH/YYYY-MM-DD.md

# For example, the notes of a category named "programming" April 18th, 2020 are saved under
CATEGORIES_ROOT_DIRECTORY/programming/2020/04/2020-04-18.md

This allows users to retrieve any notes added on a specific date or in a specific period for a specific or for all categories.

# Fetch notes for all categories
$ stup show @ 2020-04-18

# Fetch notes for a specific category for previous week
$ stup log previous-week -c programming

# Fetch notes for all categories for a specific period
$ stup log --from 2020-04-01 --to 2020-04-15

You can find the full documentation with usage examples on the project's repository and more information about features to be added in the project's GitHub issues page.

Creating a chat application from scratch using Rails and WebSockets

Lazarus Lazaridis — Fri, 11 Oct 2019 08:37:04 +0000

Introduction

In this tutorial we are going to create a chat web application from scratch using Rails and WebSockets.

You can find the code of this tutorial on GitHub.

What are WebSockets

WebSocket is actually a protocol that enables bidirectional communication between the client and the server of a web application over a single long living TCP connection.

The WebSocket protocol enables interaction between a web browser (or other client application) and a web server with lower overheads, facilitating real-time data transfer from and to the server.

This is made possible by providing a standardized way for the server to send content to the client without being first requested by the client, and allowing messages to be passed back and forth while keeping the connection open. In this way, a two-way ongoing conversation can take place between the client and the server.

The communications are done over TCP port number 80 (or 443 in the case of TLS-encrypted connections), which is of benefit for those environments which block non-web Internet connections using a firewall. Similar two-way browser-server communications have been achieved in non-standardized ways using stopgap technologies such as Comet.
-- WebSocket @ Wikipedia

Why WebSockets

Suppose you have to create a web page that shows the statuses of running processes.
Without WebSockets you would have to either:

Use AJAX with Javascript intervals to request and render the latest state of the processes or
Automatically reload the page every x seconds (<meta http-equiv="refresh" content="x">) or
Add a message on the page "The statuses are not updated automatically ¯\_(ツ)_/¯ Press here to reload the page."

All of these methods would request the process statuses from the server even if nothing has changed.

WebSockets are here to allow this communication to take place on demand. The cost is having to keep alive TCP connections between the server and all its clients (each for every open browser tab).

Building the application

We are going to build the web application using:

Ruby: version 2.6.2
Rails: version 5.2.3

Setting up the environment

We are going to install the proper ruby and rails versions.

Install ruby

I use rvm to manage the Ruby versions installed on my system. To install the desired ruby version use:

rvm install ruby 2.6.2

Install rails

Create a directory in your system with the name rails-chat-tutorial.

Navigate to that directory and create the following two files:

.ruby-version

ruby-2.6.2

.ruby-gemset

rails-chat-tutorial

With these file we are letting rvm know that when working on this directory, we want to use the specific ruby version (.ruby-version) and the gems from the specific gemset (.ruby-gemset)

Now, re-entering in the directory you should see something like this:

$ cd .

ruby-2.6.2 - #gemset created /home/iridakos/.rvm/gems/ruby-2.6.2@rails-chat-tutorial
ruby-2.6.2 - #generating rails-chat-tutorial wrappers...........

Install the desired rails version with:

gem install rails -v 5.2.3

Create the rails application

We are ready to create our new rails application:

rails new .

Note: We didn't define a name for the application and rails will resolve it using the directory name: rails-chat-tutorial.

Rails will create all the application's files and install the required gems.

Let's start the application to make sure that everything if fine.

rails server

You should see something like:

=> Booting Puma
=> Rails 5.2.3 application starting in development
=> Run `rails server -h` for more startup options
Puma starting in single mode...
* Version 3.12.1 (ruby 2.6.2-p47), codename: Llamas in Pajamas
* Min threads: 5, max threads: 5
* Environment: development
* Listening on tcp://localhost:3000
Use Ctrl-C to stop

Open a browser and visit http://localhost:3000, if you see this we are good to go.

Users and devise

We are going to use the awesome devise solution for authentication.

Append the following gem requirement at the bottom of the Gemfile file located at the root of the application's directory.

gem 'devise'

On your terminal, install the new gem by executing:

bundle

Finish integration with devise using:

rails generate devise:install

We will create the model representing our uses using the devise generators.

On your terminal, execute:

rails generate devise User username:string

Note: we have added an extra attribute username to our model (besides the defaults generated by devise) so that we have something more friendly to present when displaying users instead of their email.

Open the generated migration which you will find under db/migrate/<datetime>_devise_create_users.rb and append the username's unique index definition with^[4]:

  add_index :users,  :username,             unique: true

Find the line in the file that defines the username column and change it to:

t.string :username, null: false

to make the attribute required.

Then in the User model which is located at app/models/user.rb add the validation rule for uniqueness and presence:

  validates :username, uniqueness: true, presence: true

Finally, apply the database migration using:

rails db:migrate

Rooms and messages

Each chat message is going to take place in the context of a room.

Let's build them all.

Use the following command to create the Room:

rails generate resource Room name:string:uniq

and the following command to create the RoomMessage:

rails generate resource RoomMessage room:references user:references message:text

We are now going to define the appropriate relations^[7].

Open app/models/room.rb and add the relation inside the class:

has_many :room_messages, dependent: :destroy,
                         inverse_of: :room

Open app/models/room_message.rb and add the relations inside the class:

belongs_to :user
belongs_to :room, inverse_of: :room_messages

Migrate the database with:

rails db:migrate

We can now setup our routes so that the root request is served by the RoomsController#index action.

Open your config/routes.rb file and change its contents to:

Rails.application.routes.draw do
  devise_for :users

  root controller: :rooms, action: :index

  resources :room_messages
  resources :rooms
end

Restart the server and try to navigate to the application's root url.

You should see an error message, no worries:

We have to create the index action in the RoomsController. Open the controller app/controllers/rooms_controller.rb and change its contents to the following:

class RoomsController < ApplicationController
  def index
  end
end

Then create the file app/views/rooms/index.html.erb and for now just add the following:

<h1>Rooms index</h1>

Reload and voilà.

Adding authentication

We want all users to be authenticated before start chatting, so we are going to add the following line in the ApplicationController located at app/controllers/application_controller.rb:

  before_action :authenticate_user!

If we navigate to http://localhost:3000 now we should be redirected to the sign in page ^[10].

Before continuing with the good stuff, let's gear up the application with some good features.

Add bootstrap

We are going to use Bootstrap and we will integrate it in the application using the bootstrap-rubygem gem.

Following the instructions of the gem, append the dependencies in your Gemfile.

gem 'bootstrap', '~> 4.3.1'
gem 'jquery-rails'

and execute bundle to fetch and install it.

Change the app/assets/stylesheets/application.css files extension to scss and replace its contents with:

@import "bootstrap";

Add the following lines to the app/assets/javascript/application.js just before the //= require_tree . line^[9]:

//= require jquery3
//= require popper
//= require bootstrap-sprockets

Add simple_form

We are going to use this great gem to generate forms easily.

Append the gem dependency in your Gemfile and bundle to install it.

gem 'simple_form'

Then complete the integration using:

rails generate simple_form:install --bootstrap

Note: We used the --bootstrap directive since that's the framework we are using.

Devise views with bootstrap and simple form

Devise uses its own views for sign in, register etc. But we do have a way to customize these views and now that we have ended up using bootstrap and simple forms, we can generate these views in a way that our choices are respected.

In your terminal:

rails generate devise:views

The view for signing in is under app/views/devise/sessions/new.html.erb and for signing up is under app/views/devise/registrations/new.html.erb. Open these two files and change the submit button's class by replacing the following line^[6]:

<%= f.button :submit, "Sign up" %>

with

<%= f.button :submit, "Sign up", class: 'btn btn-success' %>

to render the buttons bootstrap style.

Before viewing our changes, let's do one last thing in our default layout.

Open app/views/layouts/application.html.erb and replace its contents with:

<!DOCTYPE html>
<html>
  <head>
    <title>RailsChatTutorial</title>
    <%= csrf_meta_tags %>
    <%= csp_meta_tag %>

    <%= stylesheet_link_tag    'application', media: 'all', 'data-turbolinks-track': 'reload' %>
    <%= javascript_include_tag 'application', 'data-turbolinks-track': 'reload' %>
  </head>

  <body>
    <div class="container">
      <div class="row">
        <div class="col-12">
          <%= yield %>
        </div>
      </div>
    </div>
  </body>
</html>

This last one was to use Bootstrap's grid in our views.

Navigate to http://localhost:3000 and view what we have created.

Let's try to sign up following the Sign up link of the form:

As you can see, there is no field to fill in the username. For that to work we have to:

Add the field in the sign up form
Configure devise to accept the new attribute (username) or else the ApplicationController will ignore it once submitted from the form.

To add the field in the sign up form, open app/views/devise/registrations/new.html.erb and add these lines between the email and password fields.

  <%= f.input :username,
              required: true %>

Then, open the app/controllers/application_controller.rb file to configure the new attribute. Change the contents to:

class ApplicationController < ActionController::Base
  before_action :authenticate_user!

  before_action :configure_permitted_parameters, if: :devise_controller?

  protected

  def configure_permitted_parameters
    devise_parameter_sanitizer.permit(:sign_up, keys: [:email, :username])
  end
end

Done, reload and sign up^[5].

Cleanup unused components

We will not be using coffee script or turbolinks so let's remove all the related stuff.

Open Gemfile and remove the following lines:

# Use CoffeeScript for .coffee assets and views
gem 'coffee-rails', '~> 4.2'
# Turbolinks makes navigating your web application faster. Read more: https://github.com/turbolinks/turbolinks
gem 'turbolinks', '~> 5'

Open app/assets/javascripts/application.js and remove the following line:

//= require turbolinks

Open app/views/layouts/application.html.erb and change the following lines ^[3]:

    <%= stylesheet_link_tag    'application', media: 'all', 'data-turbolinks-track': 'reload' %>
    <%= javascript_include_tag 'application', 'data-turbolinks-track': 'reload' %>

    <%= stylesheet_link_tag    'application', media: 'all' %>
    <%= javascript_include_tag 'application' %>

Check that your app/assets/javascripts folder doesn't have any files with extension .coffee and if you find any, remove them.²

In the terminal, also execute the following command:

rails tmp:cache:clear

to clear any cached compiled coffee scripts.

Done. Restart you server.

Adding a navigation bar

To improve the usability of the web pages will add a top navigation bar.

Create the directory app/views/shared and a file inside it named _navigation_bar.html.erb. This is going to be the partial responsible for rendering the navigation bar and which later on we will add to the application's default layout in order to be rendered on all web pages. Add these contents:

<nav class="navbar navbar-expand-lg navbar-dark bg-dark justify-content-between">
  <a class="navbar-brand" href="#">Rails chat tutorial</a>
  <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#nav-bar-collapse" aria-controls="navbarColor01" aria-expanded="false" aria-label="Toggle navigation">
    <span class="navbar-toggler-icon"></span>
  </button>

  <% if current_user %>
    <div class="dropdown">
      <a class="nav-link dropdown-toggle" href="#" id="navbarDropdown" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
        <img class="avatar" src="<%= gravatar_url(current_user) %>">
        <%= current_user.username %>
      </a>

      <div class="dropdown-menu dropdown-menu-right" aria-labelledby="navbarDropdown">
        <%= link_to 'Logout', destroy_user_session_path, method: :delete, class: 'dropdown-item' %>
      </div>
    </div>
  <% end %>
</nav>

Mind the gravatar_url(current_user) line. This is a helper method that we are going to use in order to resolve the gravatar url of the signed in user. This is not a builtin method, we have to defined it but it's pretty straightforward.

Edit app/helpers/application_helper.rb and add the following method:

def gravatar_url(user)
  gravatar_id = Digest::MD5::hexdigest(user.email).downcase
  url = "https://gravatar.com/avatar/#{gravatar_id}.png"
end

Note:

As you can see, the user's username, avatar and sign out link will only be rendered if the user is signed in.

The avatar image has a css class avatar. We have to define this class in the application's stylesheets. Create a css file in which we will gather all css class that we will use in the application under the name app/assets/stylesheets/rails-chat-tutorial.scss.

For now add the rule for the avatar:

.avatar {
  max-height:30px;
  border-radius: 15px;
  width:auto;
  vertical-align:middle;
}

and open application.scss to import the newly created stylesheet. Add the line:

@import "rails-chat-tutorial"

We have to add this partial in the application layout. Edit app/views/layouts/application.html.erb and change its contents to:

<!DOCTYPE html>
<html>
  <head>
    <title>RailsChatTutorial</title>
    <%= csrf_meta_tags %>
    <%= csp_meta_tag %>

    <%= stylesheet_link_tag    'application', media: 'all' %>
    <%= javascript_include_tag 'application' %>
  </head>

  <body>
    <div class="container">
      <div class="row">
        <div class="col-12">
          <%= render partial: 'shared/navigation_bar' %>
          <div class="my-3">
            <%= yield %>
          </div>
        </div>
      </div>
    </div>
  </body>
</html>

Reload to view the bar.

Awesome. Fill in with your desired credentials and submit the form.

Room management

We are going to create a simple layout for groups.

One narrow column displaying vertically all the available rooms
One wide column which is going to host the chat messages and form.

The rooms index page will have the second column empty since this column will be present only when user is inside a specific room.

In the index page we will provide the option to create a room.

Room index

First we have to load all rooms in the RoomsController. Open app/controllers/rooms_controller.rb and change the index action as:

def index
  @rooms = Room.all
end

Open app/views/rooms/index.html.erb and change its contents to^[8]:

<div class="row">
  <div class="col-12 col-md-3">
    <div class="mb-3">
      <%= link_to new_room_path, class: "btn btn-primary" do %>
        Create a room
      <% end %>
    </div>

    <% if @rooms.present? %>
      <nav class="nav flex-column">
        <% @rooms.each do |room| %>
          <%= link_to room.name, room_path(room), class: "nav-link room-nav-link" %>
        <% end %>
      </nav>
    <% else %>
      <div class="text-muted">
        The are no rooms
      </div>
    <% end %>
  </div>

  <div class="col">
    <div class="alert alert-primary">
      <h4 class="alert-heading">
        Welcome to the RailsChatTutorial!
      </h4>

      <p>
        We need to talk.
      </p>

      <hr />

      <p>
        You can create or join a room from the sidebar.
      </p>
    </div>
</div>

If there are rooms, the left column of the page will render a vertical navigation with links leading to each room's page. The right column displays a simple welcome message.

Pressing the Create a room button we get the expected error for the non-existent action.

Room new/edit

We have to define the actions for creating and updating a room.

Open the app/controllers/rooms_controller.rb and change its contents to:

class RoomsController < ApplicationController
  # Loads:
  # @rooms = all rooms
  # @room = current room when applicable
  before_action :load_entities

  def index
    @rooms = Room.all
  end

  def new
    @room = Room.new
  end

  def create
    @room = Room.new permitted_parameters

    if @room.save
      flash[:success] = "Room #{@room.name} was created successfully"
      redirect_to rooms_path
    else
      render :new
    end
  end

  def edit
  end

  def update
    if @room.update_attributes(permitted_parameters)
      flash[:success] = "Room #{@room.name} was updated successfully"
      redirect_to rooms_path
    else
      render :new
    end
  end

  protected

  def load_entities
    @rooms = Room.all
    @room = Room.find(params[:id]) if params[:id]
  end

  def permitted_parameters
    params.require(:room).permit(:name)
  end
end

Note: we preload the @rooms and the @room variables making them available to all actions with the before_action :load_entities hook.

We will create a simple form for the Room object and we will use it both when creating and editing a room. Create the app/views/rooms/_form.html.erb and add:

<%= simple_form_for @room do |form| %>
  <%= form.input :name %>
  <%= form.submit "Save", class: 'btn btn-success' %>
<% end %>

Then, create the views for the new/edit action accordingly:

app/views/rooms/new.html.erb

<h1>
  Creating a room  
</h1>

<%= render partial: 'form' %>

app/views/rooms/edit.html.erb

<h1>
  Editing room <%= @room.name %>
</h1>

<%= render partial: 'form' %>

Time to create the first room. From the rooms' index page, press the Create a room

Save and here it is.

Add this class in app/assets/stylesheets/rails-chat-tutorial.scss to improve the display of the rooms.

.room-nav-link {
  border: 1px solid lighten($primary, 40%);
  background: lighten($primary, 45%);

  & + .room-nav-link {
    border-top: 0 none;
  }
}

Note: We will add the edit link in the room's page a.k.a. show action.

Before moving on to the Room page, we will refactor the index page so as to be able to use the left column's content inside the room page as well.

Create the partial app/views/rooms/_rooms.html.erb with contents:

<div class="mb-3">
  <%= link_to new_room_path, class: 'btn btn-primary' do %>
    Create a room
  <% end %>
</div>

<% if @rooms.present? %>
  <nav class="nav flex-column">
    <% @rooms.each do |room| %>
      <%= link_to room.name, room_path(room), class: 'nav-link room-nav-link' %>
    <% end %>
  </nav>
<% else %>
  <div class="text-muted">
    The are no rooms
  </div>
<% end %>

and change the app/views/rooms/index.html.erb to use it:

<div class="row">
  <div class="col-12 col-md-3">
    <%= render partial: 'rooms' %>
  </div>

  <div class="col">
    <div class="alert alert-primary">
      <h4 class="alert-heading">
        Welcome to the RailsChatTutorial!
      </h4>

      <p>
        We need to talk.
      </p>

      <hr />

      <p>
        You can create or join a room from the sidebar.
      </p>
    </div>
  </div>
</div>

Room page

Add the show action in the app/controllers/rooms_controller.rb:

def show
  @room_message = RoomMessage.new room: @room
  @room_messages = @room.room_messages.includes(:user)
end

Notes:

We construct a new room message which we are going to use in the view to build a form for creating the chat messages.
When displaying the room message, we access its user's email attribute to resolve the gravatar hash. We used .includes(:user) in the query for the @room_messages to fetch them along with their users avoiding N+1 queries^[1].

Create the view app/views/rooms/show.html.erb:

<h1>
  <%= @room.name %>
</h1>

<div class="row">
  <div class="col-12 col-md-3">
    <%= render partial: 'rooms' %>
  </div>

  <div class="col">
    <div class="chat">
      <% @room_messages.each do |room_message| %>
        <%= room_message %>
      <% end %>
    </div>

    <%= simple_form_for @room_message, remote: true do |form| %>
      <div class="input-group mb-3">
        <%= form.input :message, as: :string,
                                 wrapper: false,
                                 label: false,
                                 input_html: {
                                   class: 'chat-input'
                                 } %>
        <div class="input-group-append">
          <%= form.submit "Send", class: 'btn btn-primary chat-input' %>
        </div>
      </div>

      <%= form.input :room_id, as: :hidden %>
    <% end %>
  </div>
</div>

Notes:

We reused the app/views/rooms/_rooms.html.erb partial that we created in the previous step
We added a div with class .chat and this is where the room's messages are renderer.
We added a form for the @room_message that we instantiated in the controller. We also used the directive remote: true when we instantiated the form thus the form is going to be submitted by Ajax.
We added a hidden field for the attribute :room_id so that the value reaches the RoomMessagesController once we submit the form.

Style the chat components by adding the following lines to the app/assets/stylesheets/rails-chat-tutorial.scss:

.chat {
  border: 1px solid lighten($secondary, 40%);
  background: lighten($secondary, 50%);
  height: 50vh;
  border-radius: 5px 5px 0 0;
  overflow-y: auto;
}

.chat-input {
  border-top: 0 none;
  border-radius: 0 0 5px 5px;
}

Navigate to a room to see what has been done.

Pressing the Send button nothing happens on the page but if you check the server's console you will notice:

AbstractController::ActionNotFound (The action 'create' could not be found for RoomMessagesController):

Let's fix that.

Creating room messages

This is going to be easy. All we have to do is implement the create action in the RoomMessagesController.

app/controllers/room_messages_controller.rb

class RoomMessagesController < ApplicationController
  before_action :load_entities

  def create
    @room_message = RoomMessage.create user: current_user,
                                       room: @room,
                                       message: params.dig(:room_message, :message)
  end

  protected

  def load_entities
    @room = Room.find params.dig(:room_message, :room_id)
  end
end

Notes:

we preload the room using the room_id parameter that we added as a hidden field in the form in the previous step
we create a new message for the room setting its user to currently signed in user

If you try to submit a message now, again you will see nothing but in the server console you can see from the log that the room message has been created.

Started POST "/room_messages" for ::1 at 2019-04-04 19:24:33 +0300
Processing by RoomMessagesController#create as JS
  Parameters: {"utf8"=>"✓", "room_message"=>{"message"=>"My first message", "room_id"=>"8"}, "commit"=>"Send"}
  User Load (0.2ms)  SELECT  "users".* FROM "users" WHERE "users"."id" = ? ORDER BY "users"."id" ASC LIMIT ?  [["id", 1], ["LIMIT", 1]]
  ↳ /home/iridakos/.rvm/gems/ruby-2.6.2@rails-chat-tutorial/gems/activerecord-5.2.3/lib/active_record/log_subscriber.rb:98
  Room Load (0.2ms)  SELECT  "rooms".* FROM "rooms" WHERE "rooms"."id" = ? LIMIT ?  [["id", 8], ["LIMIT", 1]]
  ↳ app/controllers/room_messages_controller.rb:13
   (0.1ms)  begin transaction
  ↳ app/controllers/room_messages_controller.rb:5
  RoomMessage Create (0.7ms)  INSERT INTO "room_messages" ("room_id", "user_id", "message", "created_at", "updated_at") VALUES (?, ?, ?, ?, ?)  [["room_id", 8], ["user_id", 1], ["message", "My first message"], ["created_at", "2019-04-04 16:24:33.456641"], ["updated_at", "2019-04-04 16:24:33.456641"]]
  ↳ app/controllers/room_messages_controller.rb:5
   (4.0ms)  commit transaction
  ↳ app/controllers/room_messages_controller.rb:5
No template found for RoomMessagesController#create, rendering head :no_content
Completed 204 No Content in 88ms (ActiveRecord: 5.1ms)

A user would expect to have the message field cleared after sending a new message. We don't disappoint users.

Create a file app/assets/javascripts/room.js and add the following:

$(function() {
  $('#new_room_message').on('ajax:success', function(a, b,c ) {
    $(this).find('input[type="text"]').val('');
  });
});

We bind to the ajax:success event triggered by Rails on successful submission of the form and all we want to do is clear the text field's value.

Reload the page and try submitting again and check it out. The field value should be emptied after sending the message.

Displaying room messages

If you reload the page you will see something like this:

Let's beautify the messages.

Replace the contents of app/views/rooms/show.html.erb with:

<h1>
  <%= @room.name %>
</h1>

<div class="row">
  <div class="col-12 col-md-3">
    <%= render partial: 'rooms' %>
  </div>

  <div class="col">
    <div class="chat">
      <% @room_messages.each do |room_message| %>
        <div class="chat-message-container">
          <div class="row no-gutters">
            <div class="col-auto text-center">
              <img src="<%= gravatar_url(room_message.user) %>" class="avatar" alt="">
            </div>

            <div class="col">
              <div class="message-content">
                <p class="mb-1">
                  <%= room_message.message %>
                </p>

                <div class="text-right">
                  <small>
                    <%= room_message.created_at %>
                  </small>
                </div>
              </div>
            </div>
          </div>
        </div>
      <% end %>
    </div>

    <%= simple_form_for @room_message, remote: true do |form| %>
      <div class="input-group mb-3">
        <%= form.input :message, as: :string,
                                 wrapper: false,
                                 label: false,
                                 input_html: {
                                   class: 'chat-input'
                                 } %>
        <div class="input-group-append">
          <%= form.submit "Send", class: 'btn btn-primary chat-input' %>
        </div>
      </div>

      <%= form.input :room_id, as: :hidden %>
    <% end %>
  </div>
</div>

and add the following css classes inside the .chat class:

.chat-message-container {
  padding: 5px;

  .avatar {
    margin: 5px;
  }

  .message-content {
    padding: 5px;
    border: 1px solid $primary;
    border-radius: 5px;
    background: lighten($primary, 10%);
    color: $white;
  }

  & + .chat-message-container {
    margin-top: 10px;
  }
}

Reload the page. Magic.

Introducing WebSockets - ActionCable

Time to start using WebSockets with ActionCable.

Action Cable seamlessly integrates WebSockets with the rest of your Rails application. It allows for real-time features to be written in Ruby in the same style and form as the rest of your Rails application, while still being performant and scalable. It's a full-stack offering that provides both a client-side JavaScript framework and a server-side Ruby framework. You have access to your full domain model written with Active Record or your ORM of choice.
-- Action Cable Overview @ Ruby on Rails Guides (v5.2.3)

Install redis

We are going to use the redis adapter which is a safe option for production environments unlike the async one.

You first must install redis on your system.

To install it on Ubuntu you just have to execute the following commands in your terminal:

sudo apt update
sudo apt install redis-server

To check that installation is successful, in your terminal make sure you get a PONG:

$ redis-cli
127.0.0.1:6379> ping
PONG

Configure ActionCable

Since we are working on the development environment, open your config/cable.yml and replace its contents with:

development:
  adapter: redis
  url: <%= ENV.fetch("REDIS_URL") { "redis://localhost:6379/1" } %>
  channel_prefix: rails-chat-tutorial_development

test:
  adapter: async

production:
  adapter: redis
  url: <%= ENV.fetch("REDIS_URL") { "redis://localhost:6379/1" } %>
  channel_prefix: rails-chat-tutorial_production

Note: we have added an option channel_prefix because:

Additionally, a channel_prefix may be provided to avoid channel name collisions when using the same Redis server for multiple applications
-- Action Cable Overview # Redis Adapter @ Ruby on Rails Guides (v5.2.3)

Finally, we are going to add the dependency in the Gemfile:

gem 'redis'

Don't forget to bundle after altering the Gemfile.

Configure Devise for authenticating websocket connections

When establishing a websocket connection, we don't have access to the user session but we do have access to the cookies. So, in order to be able to authenticate the user we need to do some devise related stuff first (credits to Greg Molnar).

Create an initializer for warden hooks under the name config/initializers/warden_hooks.rb and add the following lines:

Warden::Manager.after_set_user do |user,auth,opts|
  scope = opts[:scope]
  auth.cookies.signed["#{scope}.id"] = user.id
end

Warden::Manager.before_logout do |user, auth, opts|
  scope = opts[:scope]
  auth.cookies.signed["#{scope}.id"] = nil
end

Explain: We add a cookie with the user's id upon successful sign in and we remove it once the user logs out.

Configure the websocket connection

Open app/channels/application_cable/connection.rb and change its contents to the following:

module ApplicationCable
  class Connection < ActionCable::Connection::Base
    identified_by :current_user

    def connect
      self.current_user = find_verified_user
    end

    private

    def find_verified_user
      if verified_user = User.find_by(id: cookies.signed['user.id'])
        verified_user
      else
        reject_unauthorized_connection
      end
    end
  end
end

Explain:

Here identified_by is a connection identifier that can be used to find the specific connection later. Note that anything marked as an identifier will automatically create a delegate by the same name on any channel instances created off the connection.
-- Action Cable Overview # Connection setup @ Ruby on Rails Guides (v5.2.3)

In the find_verified_user method we access the cookie that we previously set in the warden hook.

Create the room channel

A channel encapsulates a logical unit of work, similar to what a controller does in a regular MVC setup.
-- Action Cable Overview # Channels @ Ruby on Rails Guides (v5.2.3)

We will create the RoomChannel in which all Room pages will subscribe to.

Create app/channels/room_channel.rb with the following contents:

class RoomChannel < ApplicationCable::Channel
  def subscribed
    room = Room.find params[:room]
    stream_for room

    # or
    # stream_from "room_#{params[:room]}"
  end
end

Explain:

The subscribed method gets called once a subscription to the channel is established and it is responsible to setup the stream from which data will be sent back and forth.

We are going to configure the room page code later on to request subscriptions to this channel passing the room parameter.

We have two options:

Use stream_for: this way Rails automatically generates a stream name for the given object (room in our case), for example: "room:asdfwer234". When we want afterwards to broadcast data to the stream, all we have to do is call RoomChannel.broadcast_to(room_object, data) in which case Rails resolves the stream name from the room_object. In other words, we don't have to manually resolve the stream name in which the data have to be send (see next item).
- This option is available when the channel handles subscriptions bound to models like in our case, a specific room
Use stream_from: we manually define the name of the stream and later on, when we want to broadcast to the stream, we have to use: ActionCable.server.broadcast("room_#{a_room_id_here}", data).

Broadcast room messages

Every time a room message is being created, we just need to broadcast to the message's room stream.
To do so, alter the create action of the app/controllers/room_messages_controller.rb to this:

def create
  @room_message = RoomMessage.create user: current_user,
                                     room: @room,
                                     message: params.dig(:room_message, :message)

  RoomChannel.broadcast_to @room, @room_message
end

Explain: we added the line RoomChannel.broadcast_to @room, @room_message which will broadcast to the room's specific stream (as explained above) the @room_message transformed to json via the to_json method.

So, on the other side, the client side, we are going to be receiving the json representation of the RoomMessage model. Let's see what that is:

{
  "id":29,
  "room_id":8,
  "user_id":1,
  "message":"My first message",
  "created_at":"2019-04-04T17:09:00.637Z",
  "updated_at":"2019-04-04T17:09:00.637Z"
}

We plan to add the new messages in the room's page via Javascript and this information is not adequate. The only thing we are missing is the user avatar. Time to refactor.

Open app/models/user.rb and add the following method:

def gravatar_url
  gravatar_id = Digest::MD5::hexdigest(email).downcase
  "https://gravatar.com/avatar/#{gravatar_id}.png"
end

We had already implemented this in the app/helpers/application_helper.rb file and we won't be using it anymore so remove it.

Update app/views/shared/_navigation_bar.html.erb and change the previous gravatar resolution to this:

<img class="avatar" src="<%= current_user.gravatar_url %>">

Update app/views/rooms/show.html.erb and change it there too, with:

<img src="<%= room_message.user.gravatar_url %>" class="avatar" alt="">

Finally, we will change the JSON representation of the RoomMessage to include the user's url:

app/models/room_message.rb

def as_json(options)
  super(options).merge(user_avatar_url: user.gravatar_url)
end

Let's confirm that the new JSON transformation is valid:

{
  "id":29,
  "room_id":8,
  "user_id":1,
  "message":"My first message",
  "created_at":"2019-04-04T17:09:00.637Z",
  "updated_at":"2019-04-04T17:09:00.637Z",
  "user_avatar_url":"https://gravatar.com/avatar/02a28db6886d578f75a820b50f2dd334.png"
}

Great, moving on.

Subscribe to the room stream

We are going to add some data in the room page in order to use them via Javascript to subscribe to the appropriate streams each time we visit a room.

Open the file app/views/rooms/show.html.erb and alter the line in which we define the chat div, to this:

<div class="chat" data-channel-subscribe="room" data-room-id="<%= @room.id %>">

Explain: We added two data attributes, one defining to which channel we want to subscribe and one defining to which room we are.

At the end of the file, add the following snippet:

<div class="d-none" data-role="message-template">
  <div class="chat-message-container">
    <div class="row no-gutters">
      <div class="col-auto text-center">
        <img src="" class="avatar" alt="" data-role="user-avatar">
      </div>

      <div class="col">
        <div class="message-content">
          <p class="mb-1" data-role="message-text"></p>

          <div class="text-right">
            <small data-role="message-date"></small>
          </div>
        </div>
      </div>
    </div>
  </div>
</div>

This snippet is going to be used as a template for each incoming message. Every time a message arrives, we will

clone this html
alter the appropriate elements' values and
append the resulting html to the end of the chat div.

Now we will create the Javascript that will do the work of subscribing and handling incoming channel data.

Create the file app/assets/javascripts/channels/room_channel.js and add the following code:

$(function() {
  $('[data-channel-subscribe="room"]').each(function(index, element) {
    var $element = $(element),
        room_id = $element.data('room-id')
        messageTemplate = $('[data-role="message-template"]');

    $element.animate({ scrollTop: $element.prop("scrollHeight")}, 1000)        

    App.cable.subscriptions.create(
      {
        channel: "RoomChannel",
        room: room_id
      },
      {
        received: function(data) {
          var content = messageTemplate.children().clone(true, true);
          content.find('[data-role="user-avatar"]').attr('src', data.user_avatar_url);
          content.find('[data-role="message-text"]').text(data.message);
          content.find('[data-role="message-date"]').text(data.updated_at);
          $element.append(content);
          $element.animate({ scrollTop: $element.prop("scrollHeight")}, 1000);
        }
      }
    );
  });
});

Explain:

For each element that has a data attribute channel-subscribe with value room
- Create a subscription to the "RoomChannel" passing the element's room-id data attribute as a parameter with name room (remember this line of the RoomChannel: Room.find params[:room] ?)
- When data is received, clone the template snippet and alter its contents based on the incoming object attributes.
- Append the newly generated content to the chat div and finally
- Do some animation to impress by scrolling smoothly to the bottom of the div.

Acknowledgments

This tutorial was originally published in my personal blog.

Thank you very much for your feedback.

[1] Armando Andini - N+1 queries
[2] Rodolfo Ruiz - Coffeescript leftovers
[3] Felix Wolfsteller - Turbolinks leftovers
[4] Maria Kravtsova - Migration typo
[5][7][8] Tony Dehnke - Sign up step, Missing step for adding model relations, Missing line from html code block
[6] keytonw - Devise view missing button class
[9] Martin - Mention order of requirements in application.js
[10] Sumak - Remove duplicate authentication related code

That's all! Long post, tired cat photo.

How to add bash completion to your scripts

Lazarus Lazaridis — Wed, 09 Oct 2019 10:11:45 +0000

I recently worked on creating a bash completion script for registering directory aliases and navigating to them with autocomplete in Bash and I found the feature really interesting. In this post I will familiarize you with the process of adding bash completion to your scripts.

What is bash completion?

Bash completion is a functionality through which bash helps users type their commands faster and easier. It accomplishes that by presenting possible options when users press the tab key while typing a command.

$ git<tab><tab>
git                 git-receive-pack    git-upload-archive  
gitk                git-shell           git-upload-pack     
$ git-s<tab>
$ git-shell

How it works

The completion script is code that uses the builtin bash command complete to define which completion suggestions can be displayed for a given executable. The nature of the completion options vary from simple static to highly sophisticated.

Why bother

It is good to provide such a functionality to users:

to save them from typing text when it can be auto-completed
to help them know what are the available continuations to their commands
to prevent errors and improve their experience by hiding or showing options based on what they have already typed

Hands on

Here's what we are going to do in this tutorial.

We will first create a dummy executable script called dothis. All it does is execute the command which resides on the number, that was passed as an argument, in user's history. For example, the following command will simply execute the ls -a command given that it exists in history with number 235:

dothis 235

Then we will create a bash completion script that will display commands along with their number from user's history and we will "bind" it to the dothis executable.

$ dothis <tab><tab>
215 ls
216 ls -la
217 cd ~
218 man history
219 git status
220 history | cut -c 8-

You can see a gif demonstrating the functionality at this tutorial's code repository on GitHub.

Let the show begin.

Creating the executable script

Create a file named dothis in your working directory and add the following code:

if [ -z "$1" ]; then
  echo "No command number passed"
  exit 2
fi

exists=$(fc -l -1000 | grep ^$1 -- 2>/dev/null)

if [ -n "$exists" ]; then
  fc -s -- "$1"
else
  echo "Command with number $1 was not found in recent history"
  exit 2
fi

Notes:

We first check if the script was called with an argument
We then check if the specific number is included in the last 1000 commands
- if it exists we execute the command using the fc functionality
- otherwise we display an error message

Make the script executable with:

chmod +x ./dothis

We are going to execute this script many times in this tutorial so I suggest you place it in a folder that is included in your path so that we can access it from anywhere with just typing dothis.

I installed it in my home bin folder using:

install ./dothis ~/bin/dothis

You can do the same given that you have a ~/bin folder and that it is included in your PATH variable.

Try to see if it's working:

dothis

You should see this.

$ dothis
No command number passed

Done.

Creating the completion script

Create a file named dothis-completion.bash. From now on we will be referring to this file with the term completion script.

Once we add some code to it, we will source it to allow the completion to take effect.
We must source this file every single time we change something in it.

We will discuss our options for registering this script whenever a bash shell opens later on.

Static completion

Suppose that the dothis program supported a list of commands, for example:

now
tomorrow
never

Let's use the complete command to register this list for completion. To use the proper terminology, we say we use the complete command to define a completion specification (compspec) for our program.

Add this to the completion script.

#/usr/bin/env bash
complete -W "now tomorrow never" dothis

What did we specify with the complete command above:

we used the -W (wordlist) option to provide a list of words for completion.
we defined to which "program" these completion words will be used (the dothis parameter)

Source the file:

source ./dothis-completion.bash

Now try pressing tab twice in the command line as shown below:

$ dothis <tab><tab>
never     now       tomorrow

Try again after typing the n:

$ dothis n<tab><tab>
never now

Magic! The completion options are automatically filtered to match only those starting with n.

Note:
The options are not displayed in the order that we defined them in the word list, they are automatically sorted.

There are a lot of other options to be used instead of the -W that we used in this section. Most of them produce completions in a fixed manner, meaning that we don't intervene dynamically to filter their output.

For example, if we wanted to have directory names as completion words for the dothis program, we would change the complete command to the following:

complete -A directory dothis

Pressing tab after the dothis program, we would get a list of the directories in the current directory from which we execute the script:

$ dothis <tab><tab>
dir1/ dir2/ dir3/

Find the complete list of the available flags here.

Dynamic completion

We will be producing the completions of the dothis executable with the following logic:

If user presses the tab key right after the command, we will show the last 50 executed commands along with their numbers in history
If user presses the tab key after typing a number that matches more than one commands from history, we will show only those commands along with their numbers in history
If user presses the tab key after a number that matches exactly one command in history, we auto-complete the number without appending the command's literal (if it's confusing, you will better understand later on, no worries)

Let's start by defining a function that will execute each time user requests completion on a dothis command. Change the completion script to this:

#/usr/bin/env bash
_dothis_completions()
{
  COMPREPLY+=("now")
  COMPREPLY+=("tomorrow")
  COMPREPLY+=("never")
}

complete -F _dothis_completions dothis

Note the following:

we used the -F flag in the complete command defining that the _dothis_completions is the function that will provide the completions of the dothis executable
COMPREPLY is an array variable used to store the completions - the completion mechanism uses this variable to display its contents as completions

Now source the script and go for completion:

$ dothis <tab><tab>
never now tomorrow

Perfect. We produce the same completions as in the previous section with the word list. Or not? Try this:

$ dothis nev<tab><tab>
never     now       tomorrow

As you can see, even though we type nev and then we request for completion, the available options are always the same and nothing gets completed automatically. Why is this happening?

The contents of the COMPREPLY variable are always displayed. The function is responsible to add/remove entries from there now.
If the COMPREPLY variable had only one element then that word would be automatically completed in the command. Since current implementation always return the same three words, this will not happen.

Enter compgen: a builtin command that generates completions supporting most of the options of the complete command (ex. -W for word list, -d for directories) and filtering them based on what already has been typed by the user.

Don't worry if you feel confused, everything will become clear later on.

Type the following in the console to better understand what compgen does:

$ compgen -W "now tomorrow never"
now
tomorrow
never
$ compgen -W "now tomorrow never" n
now
never
$ compgen -W "now tomorrow never" t
tomorrow

So now we can use it but we need to find a way to know what has been typed after the dothis command.
We already have the way. The bash completion facilities provide bash variables related to the completion taking place. Here are the more important ones:

COMP_WORDS: an array of all the words typed after the name of the program the compspec belongs to
COMP_CWORD: an index of the COMP_WORDS array pointing to the word the current cursor is at - in other words, the index of the word the cursor was when the tab key was pressed
COMP_LINE: the current command line

To access the word just after the dothis word, we can use the value of COMP_WORDS[1]

Change the completion script again:

#/usr/bin/env bash
_dothis_completions()
{
  COMPREPLY=($(compgen -W "now tomorrow never" "${COMP_WORDS[1]}"))
}

complete -F _dothis_completions dothis

Source and there you are:

 $ dothis
never     now       tomorrow  
$ dothis n
never  now

Now, instead of the now, tomorrow, never words, we would like to see actual numbers from the command history.

The fc -l command followed by a negative number -n displays the last n commands.
So, we will use:

fc -l -50

which lists the last 50 executed commands along with their numbers. The only manipulation we need to do is replace tabs with spaces in order to be displayed properly from the completion mechanism. sed to the rescue.

Change the completion script as follows:

#/usr/bin/env bash
_dothis_completions()
{
  COMPREPLY=($(compgen -W "$(fc -l -50 | sed 's/\t//')" -- "${COMP_WORDS[1]}"))
}

complete -F _dothis_completions dothis

Source and test in the console:

$ dothis <tab><tab>
632 source dothis-completion.bash   649 source dothis-completion.bash   666 cat ~/.bash_profile
633 clear                           650 clear                           667 cat ~/.bashrc
634 source dothis-completion.bash   651 source dothis-completion.bash   668 clear
635 source dothis-completion.bash   652 source dothis-completion.bash   669 install ./dothis ~/bin/dothis
636 clear                           653 source dothis-completion.bash   670 dothis
637 source dothis-completion.bash   654 clear                           671 dothis 6546545646
638 clear                           655 dothis 654                      672 clear
639 source dothis-completion.bash   656 dothis 631                      673 dothis
640 source dothis-completion.bash   657 dothis 150                      674 dothis 651
641 source dothis-completion.bash   658 dothis                          675 source dothis-completion.bash
642 clear                           659 clear                           676 dothis 651
643 dothis 623  ls -la              660 dothis                          677 dothis 659
644 clear                           661 install ./dothis ~/bin/dothis   678 clear
645 source dothis-completion.bash   662 dothis                          679 dothis 665
646 clear                           663 install ./dothis ~/bin/dothis   680 clear
647 source dothis-completion.bash   664 dothis                          681 clear
648 clear                           665 cat ~/.bashrc

Not bad.

We do have a problem though. Try typing a number as you see it in your completion list and the press the key again.

$ dothis 623<tab>
$ dothis 623  ls 623  ls -la
...
$ dothis 623  ls 623  ls 623  ls 623  ls 623  ls -la

This is happening because in our completion script, we used the ${COMP_WORDS[1]} to always check the first typed word after the dothis command (the number 623 in the above snippet). Hence the completion continues suggesting the same completion again and again while pressing the tab key.

To fix this, we will not allow any kind of completion to take place if at least one argument has already been typed. We will add a condition in our function checking the size of the aforementioned COMP_WORDS array.

#/usr/bin/env bash
_dothis_completions()
{
  if [ "${#COMP_WORDS[@]}" != "2" ]; then
    return
  fi

  COMPREPLY=($(compgen -W "$(fc -l -50 | sed 's/\t//')" -- "${COMP_WORDS[1]}"))
}

complete -F _dothis_completions dothis

Source and retry.

$ dothis 623<tab>
$ dothis 623 ls -la<tab> # SUCCESS: nothing happens here

There is another thing we don't like though. We do want to display the numbers along with the corresponding commands to help users decide which one is the desired but when there is only one completion suggestion and gets automatically picked by the completion mechanism, we shouldn't append the command literal too.

In other words, our dothis executable accepts only a number and we haven't added any functionality checking or expecting other arguments. When our completion function gives only one result, we should trim the command literal and respond only with the command number.

To accomplish this, we will keep the response of the compgen command in an array variable and if its size is 1 we will trim the one and only element to keep just the number. Otherwise, we'll let the array as is.

Change the completion script to this:

#/usr/bin/env bash
_dothis_completions()
{
  if [ "${#COMP_WORDS[@]}" != "2" ]; then
    return
  fi

  # keep the suggestions in a local variable
  local suggestions=($(compgen -W "$(fc -l -50 | sed 's/\t/ /')" -- "${COMP_WORDS[1]}"))

  if [ "${#suggestions[@]}" == "1" ]; then
    # if there's only one match, we remove the command literal
    # to proceed with the automatic completion of the number
    local number=$(echo ${suggestions[0]/%\ */})
    COMPREPLY=("$number")
  else
    # more than one suggestions resolved,
    # respond with the suggestions intact
    COMPREPLY=("${suggestions[@]}")
  fi
}

complete -F _dothis_completions dothis

Registering the completion script

If you want to enable the completion just for you on your machine, all you have to do is add a line in your .bashrc file sourcing the script:

source <path-to-your-script>/dothis-completion.bash

If you want to enable the completion for all users, you can just copy the script under /etc/bash_completion.d/ and it will automatically be loaded by Bash.

Fine tuning the completion script

Some extra steps for better results :)

Displaying each entry in a new line

Well, in the bash completion script I was working on, I too had to present suggestions consisting of two parts. I wanted to display the first part with the default color and the second part with a gray color to point out that it was just help text. In this tutorial's example, it would be nice to present the numbers in the default color but the command literal in another one, less fancy.

Unfortunately, this is not possible at least for the time being because the completions are displayed as plain text and color directives are not processed (for example: \e[34mBlue).

What we can do though to improve user experience (or not :D) is to display each entry in a new line. This solution is not that obvious since again we can't just append a new line character in each COMPREPLY entry. We will follow a rather hackish way and pad suggestion literals to such a width that fills the terminal's width.

Enter printf. If you want to display each suggestion on each own line, change the completion script to the following:

#/usr/bin/env bash
_dothis_completions()
{
  if [ "${#COMP_WORDS[@]}" != "2" ]; then
    return
  fi

  local IFS=$'\n'
  local suggestions=($(compgen -W "$(fc -l -50 | sed 's/\t//')" -- "${COMP_WORDS[1]}"))

  if [ "${#suggestions[@]}" == "1" ]; then
    local number="${suggestions[0]/%\ */}"
    COMPREPLY=("$number")
  else
    for i in "${!suggestions[@]}"; do
      suggestions[$i]="$(printf '%*s' "-$COLUMNS"  "${suggestions[$i]}")"
    done

    COMPREPLY=("${suggestions[@]}")
  fi
}

complete -F _dothis_completions dothis

Source and test:

dothis <tab><tab>
...
499 source dothis-completion.bash                   
500 clear
...       
503 dothis 500

Customizable behavior

In our case, we hard-coded to display the last 50 commands for completion. This is not a good practice. We should first respect what each user might prefer and if he/she hasn't made any preference then we should default to 50.

To accomplish that we will check if an environment variable DOTHIS_COMPLETION_COMMANDS_NUMBER has been set.

Change the completion script one last time:

#/usr/bin/env bash
_dothis_completions()
{
  if [ "${#COMP_WORDS[@]}" != "2" ]; then
    return
  fi

  local commands_number=${DOTHIS_COMPLETION_COMMANDS_NUMBER:-50}
  local IFS=$'\n'
  local suggestions=($(compgen -W "$(fc -l -$commands_number | sed 's/\t//')" -- "${COMP_WORDS[1]}"))

  if [ "${#suggestions[@]}" == "1" ]; then
    local number="${suggestions[0]/%\ */}"
    COMPREPLY=("$number")
  else
    for i in "${!suggestions[@]}"; do
      suggestions[$i]="$(printf '%*s' "-$COLUMNS"  "${suggestions[$i]}")"
    done

    COMPREPLY=("${suggestions[@]}")
  fi
}

complete -F _dothis_completions dothis

Source and test:

export DOTHIS_COMPLETION_COMMANDS_NUMBER=5
$ dothis <tab><tab>
505 clear
506 source ./dothis-completion.bash
507 dothis clear
508 clear
509 export DOTHIS_COMPLETION_COMMANDS_NUMBER=5

Useful links

Code

You can find the code of this tutorial on GitHub.

This post was originally published on my blog.

Long post, cat photo

Let me introduce you to my debugger.

That's all folks!

Composing better emails (with examples from the software development world)

Lazarus Lazaridis — Tue, 08 Oct 2019 07:26:26 +0000

Email communication is not my favorite but since I can't avoid it, I am trying to compose messages in a way that I think it makes it easier for both me and the recipient:

to quickly address what is being communicated
avoid misunderstandings
save time

Here are some tips. They don't apply to all type of messages, I provide before and after examples to better describe each case.

Emphasize text with bold/underlined font

Emphasizing the appropriate parts of a message, especially when it's a long one, you help readers quickly get an idea of what the email is about and easily locate the important stuff after going back to it at some point in the future.

Examples

Before

Hello all,

I noticed that there are many logs for blabla the last few days and I
 don't think that it is normal. I believe the problem is the updated 
version of gem blabla.

I have opened an issue describing the case in Redmine (#455) in the current version.
Feel free to change its priority in case blabla.

Thanks,
Lazarus

After

Hello all,

I noticed that there are many logs for blabla the last few days and
 I don't think that it is normal. I believe the problem is the updated 
version of gem blabla.

I have opened a Redmine issue (#455) describing the case in the 
current version.
Feel free to change its priority in case blabla.

Thanks,
Lazarus

Use specific dates instead of `yesterday`, `tomorrow` etc

The moment you send an email is not the moment that it will be read by its
recipients. Avoid using only temporal adverbs/nouns like yesterday,
today, tomorrow, two hours ago etc but include also the specific
dates/times otherwise they might be misunderstood or require from
recipients to check the email's sent date/time to calculate the actual
time.

Examples

Before

Dear QA,

Yesterday we released a fix for the bug 455 on staging and we plan to 
release it next Monday if you give us the green light by tomorrow end of 
day.

Thanks,
Lazarus

After

Dear QA,

Yesterday, June 25th, 2019 we released a fix for the bug 
#455 on staging and we plan to release it on production next 
Monday (July 1st, 2019) if you give us the green light by tomorrow 
(June 27th, 2019) end of day.

Thanks,
Lazarus

Use links for references

Use bookmarkable links when you refer to something that would eventually
require from the recipient to search for in another platform.

This has two benefits:

Save time
Eliminate ambiguous references

Examples

Before

Dear Phoebe,

I didn't understand the process described on the issue about the logging 
bug. Irida's comment was not very clear either. Can you please help me?

Thanks,
Lazarus

After

Dear Phoebe,

I didn't understand the process described on the issue about the logging 
bug (Redmine #453). This comment from Irida was not very clear either. Can you 
please help me?

Thanks,
Lazarus

Structure long messages

Long messages are in general not very effective and parts of them are
prone to be ignored.

When I have to compose such a message I try to categorize the text in
contextual sections and then structure them using headers and
paragraphs allowing readers to navigate to them at a glance.

Examples

Before

Dear team,

Last week we had a problem with the logs in the production environment. I 
am talking about the Redmine issue #453. We noticed a huge increase in 
the log messages blabla leading to delayed responses because blah blah 
blah. At some point the server run out of disk and everything fell apart 
blah blah blah. Administrators backed up the logs and removed them from 
the server to blah blah blah. We started investigating what is going on 
immediately and after two days we managed to reproduce the error in the 
staging environment as well. The problem was the usage of an external 
library that had a bug which blah blah blah. We removed the library and 
the bug was no longer reproducable in the staging environment. The buggy 
library was blah blah blah. We released the fix yesterday and everything 
seems to be back to normal. We also added some scripts that will notify us 
immediately if such conditions start to emerge.

Thank you for your time,
Lazarus

After

Dear team,

Background
Last week we had a problem with the logs in the production environment. We
 noticed a huge increase in the log messages blabla.

Consequences
The increase led to delayed responses because blah blah blah. At some 
point the server run out of disk and everything fell apart blah blah blah.

Cause of the problem
We started investigating what is going on immediately and after two days 
we managed to reproduce the error in the staging environment as well.
The problem was the usage of an external library that had a bug which blah 
blah blah. The buggy library was blah blah blah.

Actions taken

1. Administrators backed up the logs and removed them 
from the server to blah blah blah.
2. We removed the library and the bug was no longer 
reproducible in the staging environment.
3. We released the fix yesterday, June 26th, 2019.
4. We also added some scripts that will notify us on time 
if such conditions start to emerge.

Current status
The server is up and running, everything seems to be back to 
normal.

More info
Related Redmine issue #453
External library - Official bug report

Thank you for your time,
Lazarus

Be specific on what you request from whom

I have seen many many many emails for which:

the sender wanted something by someone
the recipients
- didn't think they were the ones to provide it
- understood something else than what the sender asked for

I try to be very specific and provide details (when possible) on what I
need and when there's more than one recipients I refer to each one
explicitly using @.

Examples

Before

Dear all,

I have pushed a commit that possibly fixes the bug with the logging in 
staging. I won't be here tomorrow so can you review and release if ok?

Bye.

After

Hey,

I have pushed a commit that 
possibly fixes the bug (Redmine #453) 
with the logging in staging.

Since I won't be here tomorrow, June 27th, can you 
please:

@captain: review the commit
@qa: run the suite to validate 
the fix
@devs: proceed with the production release 
on June 28th given the green light by the QA team?

Sorry for the inconvenience,
Lazarus

Thank you,

Lazarus

Post Scriptum

This post was originally published on my blog.

Find attached a photo of my cats.

goto - navigate to aliased directories

Lazarus Lazaridis — Wed, 07 Mar 2018 11:18:17 +0000

I created a bash utility named goto that allows users to navigate to aliased directories.

It comes with a nice auto-completion script so that whenever you press the tab key after the goto command, bash prompts with suggestions of the available aliases:

$ goto <tab>
bc /etc/bash_completion.d                     
dev /home/iridakos/development
rubies /home/iridakos/.rvm/rubies

Example

The following command will register an alias for a long path:

goto --register workdir /mnt/development/projects/go/workspace

Afterwards, user can navigate to that folder with just:

goto workdir

You can find the code and the installation and usage guides on GitHub.

Update 2018-03-25

The tool can be used also in zsh and there is a brew formula available for macOS users (brew install goto)

(╯°□°）╯︵ ┻━┻

Lazarus Lazaridis — Mon, 05 Feb 2018 16:42:51 +0000

I created a useless gem that prepends the table flipper on Exception messages :D

Check it out here: https://github.com/iridakos/table_flipper

Just published: jquery.docout

Lazarus Lazaridis — Tue, 19 Dec 2017 23:02:33 +0000

I use GitHub pages to host my personal blog and since some of my posts are long tutorials, I created a customizable jQuery plugin that renders a document outline.

jquery.docout GitHub repository

Any feedback is welcome!

Saying "Hello world" with Ruby on Rails

Lazarus Lazaridis — Tue, 21 Nov 2017 19:49:21 +0000

If you are new to Ruby I suggest you first read this which in short explains why you should not give up on learning Ruby.

In this post we will do the first steps in order to get familiar with both the language (Ruby) and the framework (Ruby on Rails). The post is based on my own experience back then, so I hope that anyone new here can understand them easily.

First things first, install ruby and rails on your machine. There are plenty of installation tutorials out there from which you can pick the one matching your machine's operating system. I followed this one in order to install Ruby 2.0 & Rails 4 on OS X Mavericks.

Development environment

You will need:

Text editor: I prefer using GitHub's Atom which is an excellent IDE many plugins. There are a lot of other options but this is something you don't have to decide now. Give them a try and you'll find the one you like the most.
Console: I use iTerm2 which is a powerful replacement for OS X's Terminal application. Find a terminal application for your OS and spend some time customizing to match your preferences, you'll be working a lot in it.
Browser: Your favorite one. I use Chrome or Firefox for development. Well, I used to prefer Chrome but after the release of Firefox Quantum, I can't decide who's the best so I use them both.

Let's begin

Create a folder in which you are going to put the tutorial's code and navigate to it from the command line:

mkdir tutorials
cd tutorials

Now let's create our new application with the name hello_world:

rails new hello_world

The command above will create a folder with the name hello_world.
Inside this folder you will find various files and subfolders which actually constitute a Rails application.

In this post I will only explain the files/folders to which we are going to make changes on (a thorough explanation will be provided in an upcoming one).

You already have a web server installed in your system that comes bundled with Ruby and its name is WEBRick. Let's start it to see what we have created with the last command.

From the command line, navigate to the created folder:

cd hello_world

Start WEBrick with the following command:

rails server

You can also use s instead of server in the previous command which is just an alias and will do the exact same thing:

rails s

You should see something similar to this:

By default, the server listens to port 3000 but you may change to the one you desire by using the -p option:

rails server -p 8080

So, the web server started and our application is successfully deployed. Open your browser and visit the following address:

http://localhost:8080

Tadaaa... You should see something like this:

Before we continue, I will try to explain in a simple way how a rails application works.

Every request to the application is served by methods (called actions) which are defined in special files called controllers.
These actions execute what has to be executed and define what the response will be (for example an html page, a JSON object etc). The responses (e.x. a page) are defined in special files called views but there are cases (such as when responding with a JSON object) that an action's view is not required to be "defined" (well, in such cases we say we have JSON views etc).
The rules (routes) that define which action of which controller will serve each request are placed in a special file called routes.rb

These are enough for the time being. Let's create our first controller named pages.
From the command line:

rails generate controller pages

You will see a bunch of lines coming out from this command but focus on the first one:

Yes, pages_controller.rb is our controller.
In this file we are going to create our action that will serve the "root" (home) request to our application.

So, open this file with your text editor. Its location is:
app/controllers/pages_controller.rb

As you can see, the controller is empty. We will add an action to it, let's call it home:

def home
end

As you can see, our action does nothing since all we want to do is show a static page with text Hello world. Let's add something though just to see it being executed from the server's log:

class PagesController < ApplicationController
  def home
    puts "Hello console!"
  end
end

If you speak Java, puts is similar to Java's System.out.println();

If not told otherwise (which is our case), the home action will try to respond with a view named home too.
So let's create this view in the appropriate folder which is:
app/views/pages/

Create a file in this folder with the name home.html.erb

The erb extension implies that this file will be processed by Rails in order to embed any dynamic content.

Edit this file and add:

<h1>Hello world!</h1>

What's left? Yes, we must route the root requests to our controller's action.

Open with your text editor the routes.rb file which is located here:
config/routes.rb

You will find a bunch of help comments (text starting with #) there which you can delete.

Now, add the following line which tells that the root path / will be served by our controller's home action:

root to: 'pages#home'

If you refresh your browser, you will see the amazing and super complex page we just created:

We could stop here but it would be nice if we had the Hello world! text being passed to the view from the controller's action, yes? Yes.

Open the pages controller again and change the home action:

def home
  @greeting = "Home action says: Hello world!"
end

Here, we declared an instance variable to our controller with name greeting and value Home action says: Hello world!.

This variable is available for use from our corresponding view so open the home.html.erb view and change its contents to the following:

<h1><%= @greeting %></h1>

Refresh the page in your browser and there it is:

There, you just created your first Ruby on Rails application!

This post has been edited and re-posted here from my blog.

DuckRails - I created an opensource tool for developers

Lazarus Lazaridis — Sat, 18 Nov 2017 18:54:03 +0000

I have created an opensource development tool called DuckRails.

Its main purpose is to allow developers to quickly mock API endpoints that for many possible reasons they can't reach at a specific time.

You can find installation instructions here (including setup via docker image).
You can browse the project's GitHub wiki pages for usage guides.

Forem: Lazarus Lazaridis

stup - a shell tool for daily notes

stup

Usage examples

Adding notes

Showing notes

Retrieving all notes for a period of time

Behind the scenes

Creating a chat application from scratch using Rails and WebSockets

Introduction

What are WebSockets

Why WebSockets

Building the application

Setting up the environment

Install ruby

Install rails

Create the rails application

Users and devise

Rooms and messages

Adding authentication

Add bootstrap

Add simple_form

Devise views with bootstrap and simple form

Cleanup unused components

Adding a navigation bar

Room management

Room index

Room new/edit

Room page

Creating room messages

Displaying room messages

Introducing WebSockets - ActionCable

Install redis

Configure ActionCable

Configure Devise for authenticating websocket connections

Configure the websocket connection

Create the room channel

Broadcast room messages

Subscribe to the room stream

Acknowledgments

How to add bash completion to your scripts

What is bash completion?

How it works

Why bother

Hands on

Creating the executable script

Creating the completion script

Static completion

Dynamic completion

Registering the completion script

Fine tuning the completion script

Displaying each entry in a new line

Customizable behavior

Useful links

Code

Long post, cat photo

Composing better emails (with examples from the software development world)

Emphasize text with bold/underlined font

Examples

Before

After

Use specific dates instead of yesterday, tomorrow etc

Examples

Before

After

Use links for references

Examples

Before

After

Structure long messages

Examples

Before

After

Be specific on what you request from whom

Examples

Before

After

Post Scriptum

goto - navigate to aliased directories

Example

Use specific dates instead of `yesterday`, `tomorrow` etc