::Com, ::Com::Common

Common parts of well decoupled Ruby libraries.

Overview

This library(gem) contains common classes and modules for other com-rb libraries and toolsets. It defines ::Com and ::Com::Common namespaces, error modules and classes which are commonly used or from which concrete exceptions should be inherited or which should be mixed to concrete exceptions' classes.

Dependencies

Runtime

• MRI Ruby version 2.3.1 or higher

Development

• Bundler version 1.12.5 or higher
• Other dependencies will be installed automatically by running bundle install from library's root directory.

Installation

Production

You can install this library manually with

gem install com-common

with resolving all of their dependencies manually.

The preffered way to install it is to rely on Bundler in your application.

Assuming that, add follow to your Gemfile.

gem "com-common", ">= 0.2.1"

And then execute from the directory with Gemfile (likely it should be your application's root directory):

$ bundle

Adding this library(gem) as a runtime dependency to other libraries(gems)

This is the most common use case of that library. Likely you already know how to do that, but for clarity sake here is some tips and links.

Add follow line to your library's gemspec file:

spec.add_runtime_dependency 'com-common', '>= 0.2.1'

See also official documentation on rubygems about adding runtime dependencies.

Development

While developming new library which depends on changes to com-common you likely want to test you changes to com-common with your own library.

To do this add runtime dependency in your library's gemspec file like described in previous section.

Then add gem definition for com-common to your library's Gemfile with :path parameter which points to root directory of your local copy of com-common.

If we assume that you have follow directory structure of git repositories:

~
|- projects
   |- com-common
   |- your-library

Then you have to add to your Gemfile something like follows:

gem "com-common",
  path: "../com-common"

After all run bundle install to let your changes to make affect.

Usage

Library's interactive prompt

To experiment with that code, run bin/console for an interactive prompt from project's root directory.

Documentation

Exceptions modules and classes hierarchy

For better understanding of exceptions in Ruby see official documentation for ::Exception class.

This library provides following modules and classes for exceptions. Most of modules are intended for tagging exceptions raised from com-rb libraries.

• ::Com::StandartError
  • ::Com::Common::StandardError
• ::Com::Error
  • ::Com::Common::Error
  • ::Com::AbstractMethodError

::Com::StandardError

The module ::Com::StandardError supposed to be mixed into all exceptions of ::StandardError type. In most situation those errors should not be catched. They signals about incorrect usages of interfaces, about code written in incorrect way, unoverrided methods provided by "abstract" classes or modules, etc.

In most cases you can suppose that errors which include this module would be catched on compilation if Ruby would be statically typed language.

::Com::Common::StandardError

The module ::Com::Common::StandardError supposed to be mixed into all exceptions of ::StandardError type from ::Com::Common namespace.

::Com::Error

The module ::Com::Error supposed to be mixed into all exceptions of ::RuntimeError type. In most situations those error should be catched and/or logged. Usually they signals about incorrect way of execution which is based on data received during runtime, unexpected data, catched and reraised exceptions from used libraries, etc.

::Com::Common::Error

The module ::Com::Common::Error supposed to be mixed into all exceptions of ::RuntimeError type from ::Com::Common namespace.

::Com::AbstractMethodError

The class ::Com::AbstractMethodError represents errors related to "abstract" methods.

Note: Despite Ruby does not have conception of abstract methods usually developers do want to force concrete classes to provide implementation for the method called from the base class. In that case called method with assumed obligatory implementation in concrete classes can be desided as abstract method.

For usage examples, see an example for ::Com::AbstractMethodError.method_not_overridden_error method.

Note: sometimes NotImplementedError incorrectly used to communicate the need for "abstract" method implementation.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run bin/console for an interactive prompt that will allow you to experiment. Run bundle exec com-common to use the code located in this directory, ignoring other installed copies of this gem.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in lib/com/common/version.rb, and then run bundle exec rake release to create a git tag for the version, push git commits and tags.

Testing

There are different ways to run tests. You can use the one which you used to.

$ rake # uses default rake task which is spec

or

$ rspec

or

$ rake spec

or

$ rspec spec/

Contributing

1. Clone it: git clone git@github.com:com-rb/com-common.git
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Ensure all tests pass successfully
5. Push to the branch (git push origin my-new-feature)
6. Create a new Pull Request