systemdy 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: abda4b02a15b8b3dcf89cc3c92fe53027b67708cf07b37b0274f51f11d1e0e07
-  data.tar.gz: 94edeaca38a67b73676e7301f23bcdc25e87da29dce75d4584c36adc3a3f04d0
+  metadata.gz: 90fbfbbdbdcd12922983d5bd751e628f3f7a8b5f3858a420e5e13ad0e73e30da
+  data.tar.gz: cd74d56bcb932d1a067ef936e9133c9097f2df2d0b743c76e30c48e90b8839e0
 SHA512:
-  metadata.gz: 30eda44f1659af67b18de78cb20be466f0986220e4a40963b83bbbc3422dad3a3809dc2f9f94a26bca7f236890ee4e0c682c66edb548d4a280c31a3ad2090f7c
-  data.tar.gz: 868bac0eb61ea2bb42fe849e421fad778d3fc6605f0a43f5c054fd9ac3870674662e19895cc3cfc97980b09e0ed59a5c770551106c3f8f87295bcb43866a6295
+  metadata.gz: 894062ea8f1b6724d72148b81aa27877ba9f53d3ee9264ff89a1009ae10ebc7bc09c83a934f1511cb85a755f9654851c25875faa8d3110c06044506a4b7881f3
+  data.tar.gz: 597bdadedfff3fb63c934d2f6b0666398dbfd01e28d3799578046f427c10c580aee0d3b2070b3b8db5411603c2cb7836327409e93f547088f4e4f9d5cd159d57

data/CHANGELOG.md

@@ -1,5 +1,157 @@
-## [Unreleased]
+## [0.3.0] - 2022-10-21 
+
+### Added
+
+- Method remove_newline_from_system_command to Systemdy::Utility::Formatter class for remove \n characters from system calls
+
+### Changed
+
+- Logic for class Systemdy::Service is_active? and is_enabled? instance methods
+
+## [0.2.1] - 2022-10-11 
+
+### Fixed
+
+- documentation_uri in gemspec
+
+## [0.2.0] - 2022-10-10 
+
+### Added
+
+- Yard documentation of all gem's modules, classes, constants and methods(included methods generated with metaprogramming techniques)
+
+## [0.1.0] - 2022-10-07 
+
+### Added
+
+- Yard-like comments for documentation of the remained gem's classes, constants and modules
+- Yard-like comments for documentation of private methods
+
+### Changed
+
+- Changed markdown README.md structure for yard documentation
+
+## [0.1.0] - 2022-10-06 
+
+### Changed
+
+- URL image path on README.md for proper yard documentation
+- Comments in Systemdy::Utility::Validator class with a yard-like syntax for generate documentation
+- Comments in Systemdy::Service with a yard-like syntax for generate documentation
+
+## [0.1.0] - 2022-10-05 
+
+### Changed
+
+- Systemdy::Utility::Formatter comment section to yard-like syntax for generating documentation
+- Variable name sudo_command to sudo in Systemdy::Service class
+- Logic for the Systemdy::Utility::KeyValueFilter.filter_by_keys class method
+
+### Added
+
+- Yard-style comments for the Systemdy::Utility::Validator.check_if_a_service_exist class method
+- Yard-style comments for the Systemdy::Utility::MessageDisplayer.display_message class method
+- Yard-style comments for the Systemdy::Utility::KeyValueFilter.filter_by_keys class method
+
+### Fixed 
+
+- Yard params description in Systemdy::Utility::Formatter class
+
+## [0.1.0] - 2022-10-04 
+
+### Changed
+
+- README.md for load image logo
+
+### Added
+
+- Image logo
+
+## [0.1.0] - 2022-10-03 
+
+### Changed
+
+- Gem name from Systemd to Systemdy to avoid name conflicts with other rubygems with the same namespace
+
+### Added
+
+- Badges in README.md for render essential metadata of the project
+
+## [0.1.0] - 2022-09-29 
+
+### Changed
+
+- Status method of Systemd::Service class
+- Systemd::Utility::Validator.check_if_a_service_exist class method
+
+### Added 
+
+- Systemd::Utility::KeyValueFilter.filter_by_keys class method
+- Systemd::Utility::KeyValueFilter class for filter hash with provided keys
+
+## [0.1.0] - 2022-09-28 
+
+### Changed
+
+- Moved render_message method from Systemd::Utility::Validator class to Systemd::Utility::MessageDisplayer class
+
+### Added
+
+- Custom exception for Systemd::Utility::Formatter.return_an_array_from_system_command class method 
+- Systemd::Utility::Formatter return_an_array_from_system_command class method 
+- Systemd::Utility::Formatter class
+- Systemd::Utility::MessageDisplayer class with render_message class method
+
+## [0.1.0] - 2022-09-25 
+
+### Added
+
+- Custom test variables to TestVariables module in spec/setup/test_variables.rb with test refactor
+- TestSetup module in spech_helper for share spec's variables
+
+## [0.1.0] - 2022-09-23 
+
+### Changed
+
+- Systemd::Utility::Validator.exist? method with forwardable module for delegation pattern
+
+## [0.1.0] - 2022-09-22 
+
+### Changed
+
+- Removed Systemd::Journal::Unit class in favour of a universal api design 
+
+## [0.1.0] - 2022-09-19 
+
+### Changed
+
+- Methods is_active? and is_enabled? for return a boolean value instead of a string 
+
+### Added
+
+- Systemd::Journal::Unit.display_logs method for manage journalctl units
+- Systemd::Journal::Unit class 
+
+## [0.1.0] - 2022-09-18 
+
+### Added
+
+- Methods mask and unmask to the Systemd::Service class
+- Methods is_enabled? and is_active? and rspec tests the Systemd::Service class for check if a service is enabled or active
+
+## [0.1.0] - 2022-09-17 
+
+### Changed 
+
+- Values of gemspec code_of_conduct and changelog url paths
+
+### Added
+
+- Founded attribute to Systemd::Service class to mark a provided service if is found or not on the system
+- Method exist? for check if a service exist
+- Method status to Systemd::Service class with rspec test
+- Actions method for execute different actions on a systemd service
 
 ## [0.1.0] - 2022-09-15
 
-- Initial release
+- Initial release

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    systemdy (0.1.0)
+    systemdy (0.2.1)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,16 +1,15 @@
-# Systemd
+<img src="https://raw.githubusercontent.com/magic4dev/systemdy/master/systemdy.png" width="1012px" alt="Systemdy Logo">
 
-<div align="center">
-
-![GitHub repo size](https://img.shields.io/github/repo-size/magic4dev/systemdy?label=size&style=flat-square)
-[![GitHub issues](https://img.shields.io/github/issues/magic4dev/systemdy?style=flat-square)](https://github.com/magic4dev/systemdy/issues)
+![Gem](https://img.shields.io/gem/v/systemdy?style=flat-square)
+![Gem](https://img.shields.io/gem/dt/systemdy?style=flat-square)
 [![GitHub forks](https://img.shields.io/github/forks/magic4dev/systemdy?style=flat-square)](https://github.com/magic4dev/systemdy/network)
+[![GitHub issues](https://img.shields.io/github/issues/magic4dev/systemdy?style=flat-square)](https://github.com/magic4dev/systemdy/issues)
 [![GitHub license](https://img.shields.io/github/license/magic4dev/systemdy?style=flat-square)](https://github.com/magic4dev/systemdy/blob/master/LICENSE.txt)
 [![GitHub stars](https://img.shields.io/github/stars/magic4dev/systemdy?style=flat-square)](https://github.com/magic4dev/systemdy/stargazers)
 
-</div>
+# Systemdy
 
-A lightweight gem for interact with systemd.
+A lightweight gem for interact with Systemd.
 
 If your goal is to develop software to quickly manage systemd services or journalctl logs, this gem is for you! :grin:
 
@@ -19,7 +18,7 @@ If your goal is to develop software to quickly manage systemd services or journa
 
 - Lightweight
 - Expressive classes and methods
-- Manage systemd's services lifecycle with minimal effort!
+- Manage Systemd's services lifecycle with minimal effort!
 - Extract and manipulate Journalctl logs with a single action!
 
 ## Table of contents
@@ -55,6 +54,7 @@ If your goal is to develop software to quickly manage systemd services or journa
 * [License](#license)
 * [Useful links and resources](#useful-links-and-resources)
 * [Acknowledgements](#acknowledgements) 
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -72,7 +72,7 @@ Or install it yourself as:
     $ gem install systemdy
 ## Dependencies
 
-The only dependecy you need is [systemd](http://www.freedesktop.org/wiki/Software/systemdy/) installed on your system (specifically libsystemd or the older libsystemdy-journal) in order to use the gem. Currently the gem support systemd 249 or higher.
+The only dependecy you need is [systemd](http://www.freedesktop.org/wiki/Software/systemdy/) installed on your system (specifically libsystemd or the older libsystemd-journal) in order to use the gem. Currently the gem support systemd 249 or higher.
 ## Usage
 
 After installing the gem, the first step is to require it:
@@ -84,11 +84,11 @@ require 'systemdy'
 
 The first goal of this gem is to manage a systemd's service with minimal effort.
 
-This section provides an overview of the Systemdy::Service class for managing the life cycle of a systemdy's service.
+This section provides an overview of the Systemdy::Service class for managing the life cycle of a systemd's service.
 
 ### Create a Systemdy Service object for control a service
 
-The first step is to create a new instance of the systemdy::Service class for control the desired service
+The first step is to create a new instance of the Systemdy::Service class for control the desired service
 
 ```ruby
 my_postgresql_service = Systemdy::Service.new('postgresql')
@@ -260,6 +260,8 @@ This line anable you to run ‘systemctl’ commands without a password.
 
 Save with CTRL + X
 
+Type 'exit' on your terminal as follows:
+
 ```console
 root@my-machine:~# exit
 ```
@@ -388,7 +390,7 @@ Obviously this method require the unit's name as argument, if executed with no a
 "display_unit_logs require an argument!"
 ```
 
-Obviously as for the previous method, you can filter the unit logs by passing **4** positional arguments:
+As for the previous method, you can filter the unit logs by passing **4** positional arguments:
 
 * **argument**: in this case the unit's name
 
@@ -443,7 +445,7 @@ Obviously this method require the GUID as argument, if executed with no argument
 "display_group_id_logs require an argument!"
 ```
 
-Obviously as for the previous method, you can filter the GUID logs by passing **4** positional arguments:
+As for the previous method, you can filter the GUID logs by passing **4** positional arguments:
 
 * **argument**: in this case the GUID
 
@@ -498,7 +500,7 @@ Obviously this method require the UID as argument, if executed with no arguments
 "display_user_id_logs require an argument!"
 ```
 
-Obviously as for the previous method, you can filter the UID logs by passing **4** positional arguments:
+As for the previous method, you can filter the UID logs by passing **4** positional arguments:
 
 * **argument**: in this case the UID
 
@@ -537,7 +539,7 @@ If the passed arguments not match anything the method return an array with a mes
 
 We :heart: pull requests from everyone. 
 
-Everyone interacting in the systemdy project's codebases is expected to follow the [code of conduct](https://github.com/magic4dev/systemdy/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the systemdy's project codebase is expected to follow the [code of conduct](https://github.com/magic4dev/systemdy/blob/master/CODE_OF_CONDUCT.md).
 
 ### Develop a new feature
 
@@ -566,9 +568,8 @@ If you wanna develop a new feature:
 * Write a good commit message
 * Push to your fork
 * [Submit a pull request](https://github.com/magic4dev/systemdy/compare)
-* Wait for us, we will reply as soon as possible
-* We may suggest changes for better code quality
-* Please, if you push more than mone commit let's keep the history clean :stuck_out_tongue_winking_eye:
+* Wait for us, we will reply as soon as possible and if is the case we suggest some changes for a better quality of the code
+* Please, if you push more than one commit let's keep the history clean :stuck_out_tongue_winking_eye:
 
 Thank you for your contribution! :handshake:
 
@@ -599,9 +600,8 @@ If you wanna fix a bug:
 * Write a good commit message
 * Push to your fork
 * [Submit a pull request](https://github.com/magic4dev/systemdy/compare)
-* Wait for us, we will reply as soon as possible
-* We may suggest changes for better code quality
-* Please, if you push more than mone commit let's keep the history clean :stuck_out_tongue_winking_eye:
+* Wait for us, we will reply as soon as possible and if is the case we suggest some changes for a better quality of the code
+* Please, if you push more than one commit let's keep the history clean :stuck_out_tongue_winking_eye:
 
 Thank you for your contribution! :handshake:
 
@@ -619,9 +619,9 @@ and replace:
 
 * let (:real_service_name) { 'postgresql' }
 
-with:
+with a service already installed on your system as follows:
 
-* let (:real_service_name) { 'a_installed_service_on_your_system' }
+* let (:real_service_name) { 'a_service_already_installed_on_your_system' }
 
 ## License
 
@@ -630,7 +630,7 @@ The gem is available as open source under the terms of the [MIT License](https:/
 ## Useful links and resources
 
  - An interesting article on [how to run sudo commands without password](https://www.linuxshelltips.com/run-sudo-commands-without-password/)
- - The official systemdy documentation for [time specification](https://www.freedesktop.org/software/systemd/man/systemd.time.html)
+ - The official Systemd documentation for [time specification](https://www.freedesktop.org/software/systemd/man/systemd.time.html)
  
 ## Acknowledgements
 

data/lib/systemdy/journal.rb

@@ -1,29 +1,20 @@
 module Systemdy
+    # Allows to filter journalctl logs
     class Journal 
 
         # extend SingleForwardableForwardable standard's library module for delegate a specified method to a designated object
         extend SingleForwardable
                
         # list of options for execute journalctl command that not accept arguments
-        # Example command: journalctl -k
-        # the '-k' option not accept arguments
-        # journalctl -k [argument] return
-        # Failed to add match [argument]: Invalid argument
+        # @note The meaning of this constant is that in linux the command ``` journalctl -k ``` not accept arguments
         LIST_OF_OPTIONS_THAT_NOT_ACCEPT_ARGUMENTS = { kernel: '-k' }
         
         # list of options for execute journalctl command that accept arguments
-        # Example command: journalctl -b
-        # the '-b' option accept an argument (the number of the boot)
-        # journalctl -b postgresql return the boots's logs
-        # journalctl -b 3 return the third of the availables boot logs
+        # @note The meaning of this constant is that in linux the command ``` journalctl -b ``` can accept arguments, if executed without argument return the last boot logs
         LIST_OF_OPTIONS_THAT_ACCEPT_AN_ARGUMENT   = { boot: '-b' }
 
         # list of options for execute journalctl command that require arguments
-        # Example command: journalctl -u
-        # the '-u' option require an argument (the name of the unit)
-        # journalctl -u postgresql return the postgresql's logs
-        # journalctl -u without an argument return
-        # journalctl: option requires an argument -- 'u' 
+        # @note The meaning of this constant is that in linux the command like ``` journalctl -u ``` require arguments, if executed without argument return an error
         LIST_OF_OPTIONS_THAT_REQUIRE_AN_ARGUMENT  = { unit: '-u', group_id: '_GID', user_id: '_UID' }
 
         # we delegate return_an_array_from_system_command method to Systemdy::Utility::Formatter class contained in Systemdy/utility/formatter.rb
@@ -31,19 +22,24 @@ module Systemdy
         # we delegate render_message method to Systemdy::Utility::MessageDisplayer class contained in Systemdy/utility/message_displayer.rb
         def_delegator Systemdy::Utility::MessageDisplayer, :render_message 
 
-        # create dynamically class methods based on LIST_OF_OPTIONS_THAT_NOT_ACCEPT_ARGUMENTS constant
-        # we can call the methods:
-        # Systemdy::Journal.display_kernel_logs
-        # this method accept 3 keyword arguments:
-        # 1. since ('the log's initial period')  - String  - default 'yesterday' 
-        # 2. to    ('the log's end period')      - String  - default Time.now.strftime('%H:%M')
-        # 3. lines ('the log's number of lines') - Integer - default 10 .display_kernel_logs
-        # Example:
-        # Systemdy::Journal.display_kernel_logs(since: '1 month ago', lines: 50)
-        # if you call this method without arguments
-        # - it return an array with 10 lines of logs
-        LIST_OF_OPTIONS_THAT_NOT_ACCEPT_ARGUMENTS.each do |message_from, option|
-            define_singleton_method "display_#{message_from}_logs" do |since: 'today', to: Time.now.strftime('%H:%M'), lines: 10|
+        # create dynamically methods based on LIST_OF_OPTIONS_THAT_NOT_ACCEPT_ARGUMENTS constant
+        # @!scope class
+        # @!method display_kernel_logs
+        #   display the +kernel logs+
+        #   @param  since [String] the log's initial period - **default**: +today+
+        #   @param  to [String] the log's end period - **default**: +timenow+
+        #   @param  lines [Integer] the log's number of lines - **default**: +10+
+        #   @return [Array] a list of kernel logs
+        #   @example display the last 10 lines of kernel logs since today to the time execution method
+        #       Systemdy::Journal.display_kernel_logs #=> [...]
+        #   @example display the last the last 20 log lines ranging from a week ago to yesterday
+        #       Systemdy::Journal.display_kernel_logs(since: '1 week ago', to: 'yesterday', lines: 20) #=> [...]
+        #   @example You can also filter the logs by specific dates in the format 'YYYY-MM-DD'
+        #       Systemdy::Journal.display_kernel_logs(since: '2022-08-27', lines: 200) #=> [...]
+        #   @note This method is generated with use of metaprogramming techniques
+        #
+        LIST_OF_OPTIONS_THAT_NOT_ACCEPT_ARGUMENTS.each do |from, option|
+            define_singleton_method "display_#{from}_logs" do |since: 'today', to: Time.now.strftime('%H:%M'), lines: 10|
                 # logs from system call
                 logs = `#{JOURNALCTL_COMMAND} #{option} -S '#{since}' -U '#{to}' -n #{lines} | tail -n #{lines} 2>&1`
                 # logs from system call converted into array
@@ -51,20 +47,27 @@ module Systemdy
             end
         end
         
-        # create dynamically class methods based on LIST_OF_OPTIONS_THAT_ACCEPT_AN_ARGUMENT constant
-        # we can call the methods:
-        # Systemdy::Journal.display_boot_logs
-        # this method accept 4 keyword arguments:
-        # 1. argument ('the boot's number')      - Integer - optional
-        # 2. since ('the log's initial period')  - String  - default 'yesterday' 
-        # 3. to    ('the log's end period')      - String  - default Time.now.strftime('%H:%M')
-        # 4. lines ('the log's number of lines') - Integer - default 10 
-        # Example:
-        # Systemdy::Journal.display_boot_logs(argument: 3, since: '1 month ago', lines: 50)
-        # if you call this method without arguments
-        # - it return an array with 10 lines of logs
-        LIST_OF_OPTIONS_THAT_ACCEPT_AN_ARGUMENT.each do |message_from, option|
-            define_singleton_method "display_#{message_from}_logs" do |argument: '', since: 'today', to: Time.now.strftime('%H:%M'), lines: 10|
+        # create dynamically methods based on LIST_OF_OPTIONS_THAT_ACCEPT_AN_ARGUMENT constant
+        # @!scope class
+        # @!method display_boot_logs
+        #   display the +boot logs+
+        #   @param  argument [Integer] the boot number
+        #   @param  since [String] the log's initial period - **default**: +today+
+        #   @param  to [String] the log's end period - **default**: +timenow+
+        #   @param  lines [Integer] the log's number of lines - **default**: +10+
+        #   @return [Array] a list of boot logs
+        #   @example display the last 10 lines of kernel logs since today to the time execution method
+        #       Systemdy::Journal.display_boot_logs #=> [...]
+        #   @example display the last 50 log lines of the second boot ranging from a month ago to 10:00 of the current day
+        #       Systemdy::Journal.display_boot_logs(argument: 2, since: '1 month ago', to: '10:00', lines: 50) #=> [...]
+        #   @example display the last 20 log of the third boot lines ranging from a week ago to yesterday
+        #       Systemdy::Journal.display_boot_logs(argument: 3, since: '1 week ago', to: 'yesterday', lines: 20) #=> [...]
+        #   @example You can also filter the logs by specific dates in the format 'YYYY-MM-DD'
+        #       Systemdy::Journal.display_boot_logs(since: '2022-08-27', lines: 200) #=> [...]
+        #   @note This method is generated with use of metaprogramming techniques
+        #
+        LIST_OF_OPTIONS_THAT_ACCEPT_AN_ARGUMENT.each do |from, option|
+            define_singleton_method "display_#{from}_logs" do |argument: '', since: 'today', to: Time.now.strftime('%H:%M'), lines: 10|
                 # logs from system call
                 logs = `#{JOURNALCTL_COMMAND} #{option} #{argument} -S '#{since}' -U '#{to}' -n #{lines} | tail -n #{lines} 2>&1`
                 # logs from system call converted into array
@@ -73,27 +76,63 @@ module Systemdy
         end
         
         # create dynamically class methods based on LIST_OF_OPTIONS_THAT_REQUIRE_AN_ARGUMENT constant
-        # we can call the methods:
-        # Systemdy::Journal.display_unit_logs
-        # Systemdy::Journal.display_group_id_logs
-        # Systemdy::Journal.display_user_id_logs
-        # this method accept 4 keyword arguments:
-        # 1. argument ('the unit, the group_id or user_id) - String  - required
-        # 2. since ('the log's initial period')  - String  - default 'yesterday' 
-        # 3. to    ('the log's end period')      - String  - default Time.now.strftime('%H:%M')
-        # 4. lines ('the log's number of lines') - Integer - default 10 
-        # Example:
-        # Systemdy::Journal.display_unit_logs(argument: 'postgresql', since: '1 month ago', lines: 50)
-        # Systemdy::Journal.display_user_id_logs(argument: 1000, since: '1 month ago', lines: 50)
-        # Systemdy::Journal.display_group_id_logs(argument: 1000, since: '1 month ago', lines: 50)
-        LIST_OF_OPTIONS_THAT_REQUIRE_AN_ARGUMENT.each do |message_from, option|
-            define_singleton_method "display_#{message_from}_logs" do |argument: '', since: 'today', to: Time.now.strftime('%H:%M'), lines: 10|
+        # @!scope class
+        # @!method display_unit_logs
+        #   display the +unit logs+
+        #   @param  argument [string] the unit name
+        #   @param  since [String] the log's initial period - **default**: +today+
+        #   @param  to [String] the log's end period - **default**: +timenow+
+        #   @param  lines [Integer] the log's number of lines - **default**: +10+
+        #   @return [Array] a list of unit logs
+        #   @example display the last 50 log lines of the potsgresql service ranging from a month ago to 10:00 of the current day
+        #       Systemdy::Journal.display_unit_logs(argument: 'postgresql', since: '1 month ago', to: '10:00', lines: 50) #=> [...]
+        #   @example display the last 20 log lines of the potsgresql service ranging from a week ago to yesterday
+        #       Systemdy::Journal.display_unit_logs(argument: 'postgresql', since: '1 week ago', to: 'yesterday', lines: 20) #=> [...]
+        #   @example You can also filter the logs by specific dates in the format 'YYYY-MM-DD'
+        #       Systemdy::Journal.display_unit_logs(argument: 'postgresql', since: '2022-08-27', lines: 200) #=> [...]
+        #   @note This method is generated with use of metaprogramming techniques
+        #   @todo This method require the unit name as argument. For more information check out the examples below
+        #
+        # @!method display_group_id_logs
+        #   display the +group_id logs (GUID)+
+        #   @param  argument [Integer] the group id
+        #   @param  since [String] the log's initial period - **default**: +today+
+        #   @param  to [String] the log's end period - **default**: +timenow+
+        #   @param  lines [Integer] the log's number of lines - **default**: +10+
+        #   @return [Array] a list of group id logs
+        #   @example display the last 50 log lines of the GUID 1000 ranging from a month ago to 10:00 of the current day
+        #       Systemdy::Journal.display_group_id_logs(argument: 1000, since: '1 month ago', to: '10:00', lines: 50) #=> [...]
+        #   @example display the last 20 log lines of the GUID 1000 ranging from a week ago to yesterday
+        #       Systemdy::Journal.display_group_id_logs(argument: 1000, since: '1 week ago', to: 'yesterday', lines: 20) #=> [...]
+        #   @example You can also filter the logs by specific dates in the format 'YYYY-MM-DD'
+        #       Systemdy::Journal.display_group_id_logs(argument: 1000, since: '2022-08-27', lines: 200) #=> [...]
+        #   @note This method is generated with use of metaprogramming techniques
+        #   @todo This method require the GUID as argument. For more information check out the examples below
+        #
+        # @!method display_user_id_logs
+        #   display the +user_id logs (UID)+
+        #   @param  argument [Integer] the user id
+        #   @param  since [String] the log's initial period - **default**: +today+
+        #   @param  to [String] the log's end period - **default**: +timenow+
+        #   @param  lines [Integer] the log's number of lines - **default**: +10+
+        #   @return [Array] a list of user id logs
+        #   @example display the last 50 log lines of the UID 1000 ranging from a month ago to 10:00 of the current day
+        #       Systemdy::Journal.display_user_id_logs(argument: 1000, since: '1 month ago', to: '10:00', lines: 50) #=> [...]
+        #   @example display the last 20 log lines of the UID 1000 ranging from a week ago to yesterday
+        #       Systemdy::Journal.display_user_id_logs(argument: 1000, since: '1 week ago', to: 'yesterday', lines: 20) #=> [...]
+        #   @example You can also filter the logs by specific dates in the format 'YYYY-MM-DD'
+        #       Systemdy::Journal.display_user_id_logs(argument: 1000, since: '2022-08-27', lines: 200) #=> [...]
+        #   @note This method is generated with use of metaprogramming techniques
+        #   @todo This method require the UID as argument. For more information check out the examples below
+        #
+        LIST_OF_OPTIONS_THAT_REQUIRE_AN_ARGUMENT.each do |from, option|
+            define_singleton_method "display_#{from}_logs" do |argument: '', since: 'today', to: Time.now.strftime('%H:%M'), lines: 10|
                 # return an error message if the required argument is not provided
                 # render_message class method contained in Systemdy/utility/message_displayer.rb
-                return render_message("display_#{message_from}_logs require an argument!") if argument.to_s.empty?
+                return render_message("display_#{from}_logs require an argument!") if argument.to_s.empty?
                 # combination of option and argument based on typology
                 # '-u postgresql' or '_GUID=1000' or '_UID=1000'
-                option_with_argument = merge_option_with_argument_based_on_option_typology(message_from, option, argument)
+                option_with_argument = merge_option_with_argument_based_on_option_typology(from, option, argument)
                 # logs from system call
                 logs                 = `#{JOURNALCTL_COMMAND} #{option_with_argument} -S '#{since}' -U '#{to}' | tail -n #{lines} 2>&1`
                 # logs from system call converted into array
@@ -101,12 +140,31 @@ module Systemdy
             end
         end
 
+        # @!scope class
+        # @!method return_an_array_from_system_command
+        #   @param system_call [String] system call to convert to an array
+        #   @return [Array] an array-based list of the values ​​returned by making a system call
+        #   @note check out more about this method in Systemdy/utility/formatter.rb
+        #
+        # @!scope class
+        # @!method render_message
+        #   @param message [String] the message to render 
+        #   @return [String] the content of the message
+        #   @note check out more about this method in Systemdy/utility/message_displayer.rb
+        #
+
         # method for return formatted option
-        # Example
-        # merge_option_with_argument_based_on_option_typology(:unit, '-u', 'postgresql') return '-u postgresql'
-        # merge_option_with_argument_based_on_option_typology(:group_id, '_GUID', 1234566) return '_GUID=1000'
-        def self.merge_option_with_argument_based_on_option_typology(message_from, option, argument)
-            message_from == :unit ? "#{option} #{argument}" : "#{option}=#{argument}"
+        #
+        # @param  type [String] the type of command to bind
+        # @param  option [String] the option 
+        # @param  argument [String] the argument
+        # @return [String] the formatted option
+        # @example return formatted option
+        #   merge_option_with_argument_based_on_option_typology(:unit, '-u', 'postgresql') #=> '-u postgresql'
+        #   merge_option_with_argument_based_on_option_typology(:group_id, '_GUID', 1000) #=> '_GUID=1000'
+        #   merge_option_with_argument_based_on_option_typology(:user_id, '_UID', 1000) #=> '_UID=1000'
+        def self.merge_option_with_argument_based_on_option_typology(type, option, argument)
+            type == :unit ? "#{option} #{argument}" : "#{option}=#{argument}"
         end
 
         # make the methods below as private

data/lib/systemdy/service.rb

@@ -1,6 +1,9 @@
 module Systemdy
+    # Allows to control a life-cycle of a systemd's service
+    # @attr_reader command [String] the default 'systemctl' command
+    # @attr_reader name [String] the name of the service
     class Service 
-
+            
         # extend Forwardable standard's library module for delegate a specified method to a designated object
         extend Forwardable
 
@@ -18,104 +21,179 @@ module Systemdy
 
         attr_reader :command, :name
 
-        # we create a new object that accept 1 argument:
-        # 1. the name of the Systemdy service to control (postgresql, redis etc..)
-        # Example:
-        # my_postgresql_service = Systemdy::Service.new('postgresql')
+        # method for create a new Systemdy::Service object 
+        #
+        # @param  name [String] the name of the systemd service to control
+        # @return [Systemdy::Service] a new Systemdy::Service object
+        # @example Create an object
+        #    my_postgresql_service = Systemdy::Service.new('postgresql')
         def initialize(name)
             @command   = SYSTEMCTL_COMMAND # constant contained in Systemdy.rb
             @name      = name 
         end
 
-        # we delegate return_an_array_from_system_command method to Systemdy::Utility::Formatter class contained in Systemdy/utility/formatter.rb
+        # delegate return_an_array_from_system_command method to Systemdy::Utility::Formatter class contained in Systemdy/utility/formatter.rb
         def_delegator Systemdy::Utility::Formatter,        :return_an_array_from_system_command
-        # we delegate render_message method to Systemdy::Utility::MessageDisplayer class contained in Systemdy/utility/message_displayer.rb
+        # delegate remove_newline_from_system_command to Systemdy::Utility::Formatter class contained in Systemdy/utility/formatter.rb
+        def_delegator Systemdy::Utility::Formatter,        :remove_newline_from_system_command
+        # delegate render_message method to Systemdy::Utility::MessageDisplayer class contained in Systemdy/utility/message_displayer.rb
         def_delegator Systemdy::Utility::MessageDisplayer, :render_message 
-        # we delegate check_if_a_service_exist method to Systemdy::Utility::Validator class contained in Systemdy/utility/validator.rb
+        # delegate check_if_a_service_exist method to Systemdy::Utility::Validator class contained in Systemdy/utility/validator.rb
         def_delegator Systemdy::Utility::Validator,        :check_if_a_service_exist 
-        # we delegate filter_by_keys method to Systemdy::Utility::KeyValueFilter class contained in Systemdy/utility/key_value.rb
+        # delegate filter_by_keys method to Systemdy::Utility::KeyValueFilter class contained in Systemdy/utility/key_value.rb
         def_delegator Systemdy::Utility::KeyValueFilter,   :filter_by_keys 
 
-        # method for check if a created service exist
-        # Example:
-        # my_postgresql_service.exist?
-        # if the provided service exist this method return
-        # - true
-        # otherwise return
-        # - false
+        # method for check if a created service +exist+
+        #
+        # @return [Boolean] the presence of the service on the system
+        # @example Create an object
+        #   my_postgresql_service.exist? #=> true
         def exist? 
             check_if_a_service_exist(name) # class method contained in Systemdy/utility/validator.rb
         end
         
         # create dynamically methods based on LIST_OF_ACTIONS constant
-        # after created a new object we can call the methods:
-        # my_postgresql_service.start
-        # my_postgresql_service.restart
-        # my_postgresql_service.stop
-        # my_postgresql_service.enable
-        # my_postgresql_service.disable
-        # my_postgresql_service.reload
-        # my_postgresql_service.mask
-        # my_postgresql_service.unmask
+        # @!method start
+        #   execute action +start+ on the service
+        #   @example start a service
+        #       my_postgresql_service.start
+        #   @note This method is generated with use of metaprogramming techniques
+        #
+        # @!method restart
+        #   execute action +restart+ on the service
+        #   @example restart a service
+        #       my_postgresql_service.restart
+        #   @note This method is generated with use of metaprogramming techniques
+        #
+        # @!method stop
+        #   execute action +stop+ on the service
+        #   @example stop a service
+        #       my_postgresql_service.stop
+        #   @note This method is generated with use of metaprogramming techniques
+        #
+        # @!method enable
+        #   execute action +anable+ on the service
+        #   @example enable a service
+        #       my_postgresql_service.enable
+        #   @note This method is generated with use of metaprogramming techniques
+        #
+        # @!method disable
+        #   execute action +disable+ on the service
+        #   @example disable a service
+        #       my_postgresql_service.disable
+        #   @note This method is generated with use of metaprogramming techniques
+        #
+        # @!method reload
+        #   execute action +reload+ on the service
+        #   @example reload a service
+        #       my_postgresql_service.reload
+        #   @note This method is generated with use of metaprogramming techniques
+        #
+        # @!method mask
+        #   execute action +mask+ on the service
+        #   @example mask a service
+        #       my_postgresql_service.mask
+        #   @note This method is generated with use of metaprogramming techniques
+        #
+        # @!method unmask
+        #   execute action +unmask+ on the service
+        #   @example unmask a service
+        #       my_postgresql_service.unmask
+        #   @note This method is generated with use of metaprogramming techniques
+        #
         LIST_OF_ACTIONS.each do |action|
             define_method action do 
-                sudo_command = Etc.getpwuid(Process.uid).name != 'root' ? 'sudo' : ''
-                exist? ? `#{sudo_command} #{command} #{action} #{name}` : default_error_message()
+                return default_error_message() unless exist?
+                sudo = Etc.getpwuid(Process.uid).name != 'root' ? 'sudo' : ''
+                `#{sudo} #{command} #{action} #{name}` 
             end
         end
 
-        # method for return a key/value pair of the provided service's properties
-        # Example:
-        # my_postgresql_service.properties
-        # return a key/value pair of the provided service's properties
-        # { "Type"=>"oneshot",
-        #   "Restart"=>"no",
-        #   "NotifyAccess"=>"none",
-        #   ....
-        # }
+        # method for return a key/value pair of the service's properties
+        #
+        # @return [Hash] the service's properties
+        # @example display all the properties related to a service
+        #   
+        #   my_postgresql_service.properties 
+        #
+        #     {
+        #       "Type"=>"oneshot",              
+        #       "Restart"=>"no",          
+        #       "ExecMainPID"=>"48615",
+        #       "NotifyAccess"=>"none"
+        #     }
+        #
+        # @note For the sake of brevity, all service-related properties are not shown in this example
         def properties
             array_of_properties = return_an_array_from_system_command(`#{command} show #{name}`)
             array_of_properties.collect { |property| { property.split('=')[0] => property.split('=')[1] } }.reduce({}, :merge)
         end
 
         # method for return the current status of the provided service
-        # Example:
-        # my_postgresql_service.status
-        # return a key/value pair of the provided service's status
-        # { "Id"=>"postgresql.service",              
-        #   "Description"=>"PostgreSQL RDBMS",          
-        #   "ExecMainPID"=>"48615",
-        #   "LoadState"=>"loaded",
-        #   "ActiveState"=>"active",
-        #   "FragmentPath"=>"/lib/Systemdy/system/postgresql.service",
-        #   "ActiveEnterTimestamp"=>"Thu 2022-09-29 17:13:07 CEST",
-        #   "InactiveEnterTimestamp"=>"Thu 2022-09-29 17:12:44 CEST",
-        #   "ActiveExitTimestamp"=>"Thu 2022-09-29 17:12:44 CEST",
-        #   "InactiveExitTimestamp"=>"Thu 2022-09-29 17:13:07 CEST"
-        # } 
+        #
+        # @return [Hash] the service's current status
+        # @example display the current status of the service
+        #   my_postgresql_service.status
+        #
+        #     {
+        #       "Id"=>"postgresql.service",              
+        #       "Description"=>"PostgreSQL RDBMS",          
+        #       "ExecMainPID"=>"48615",
+        #       "LoadState"=>"loaded",
+        #       "ActiveState"=>"active",
+        #       "FragmentPath"=>"/lib/Systemdy/system/postgresql.service",
+        #       "ActiveEnterTimestamp"=>"Thu 2022-09-29 17:13:07 CEST",
+        #       "InactiveEnterTimestamp"=>"Thu 2022-09-29 17:12:44 CEST",
+        #       "ActiveExitTimestamp"=>"Thu 2022-09-29 17:12:44 CEST",
+        #       "InactiveExitTimestamp"=>"Thu 2022-09-29 17:13:07 CEST"
+        #     }
+        #
         def status 
-            exist? ? filter_by_keys(properties, LIST_OF_STATUS_PROPERTIES) : default_error_message()
+            return default_error_message() unless exist?
+            filter_by_keys(properties, LIST_OF_STATUS_PROPERTIES) 
         end
 
         # create dynamically methods based on LIST_OF_STATUSES constant
-        # after created a new object we can call the methods:
-        # my_postgresql_service.is_enabled?
-        # my_postgresql_service.is_active?
-        # if the provided service is active or enabled this method return
-        # - true
-        # otherwise return
-        # - false
+        # @!method is_enabled?
+        #   check if the service is +enabled+
+        #   @return [Boolean] the service is enabled
+        #   @example check if a service is enabled
+        #       my_postgresql_service.is_enabled? #=> true
+        # @note This method is generated with use of metaprogramming techniques
+        #
+        # @!method is_active?
+        #   check if the service is +active+
+        #   @return [Boolean] the service is active
+        #   @example check if a service is active
+        #       my_postgresql_service.is_active? #=> true
+        # @note This method is generated with use of metaprogramming techniques
         LIST_OF_STATUSES.each do |status|
             define_method "is_#{status}?" do 
-                exist? ? return_an_array_from_system_command(`#{command} is-#{status} #{name}`).include?(status) : default_error_message()
+                return default_error_message() unless exist?
+                remove_newline_from_system_command(`#{command} is-#{status} #{name}`) == status
             end
         end
 
-        # method for display error when a service or unit not exist
+        # method to show a message when an action is performed on a service not installed on the system
+        # @return [String] the error message
+        # @example the action start on a service not installed on the system
+        #     a_service_not_installed.start #=> "Unit a_service_not_installed.service could not be found."
         def default_error_message
             render_message("Unit #{name}.service could not be found.") # class method contained in Systemdy/utility/message_displayer.rb
         end
 
+        # @!method return_an_array_from_system_command
+        #   @param system_call [String] system call to convert to an array
+        #   @return [Array] an array-based list of the values ​​returned by making a system call
+        #   @note check out more about this method in Systemdy/utility/formatter.rb
+        #
+        # @!method filter_by_keys
+        #   @param hash [Hash] the hash to filter
+        #   @param list_of_keys [Array] the list of keys to extract from the hash
+        #   @return [Hash] a new hash that contains only the required keys
+        #   @note check out more about this method in Systemdy/utility/key_value_filter.rb
+        #
+
         # make the methods below as private
         private :render_message, :default_error_message, :return_an_array_from_system_command, :filter_by_keys 
     end

data/lib/systemdy/utility/formatter.rb

@@ -1,14 +1,30 @@
 module Systemdy
+    # A module that contains a set of useful classes for add utilities to the Systemdy's core
     module Utility 
+        # Allows to formatting provided data into another type
         class Formatter
-            # method for convert `` system call to array based list
+            # method for convert system calls into an array 
+            #
+            # @param  system_call [String] system call to convert to an array
+            # @return [Array] an array-based list of the values ​​returned by making a system call
+            # @example convert a backtick system call into an array
+            #   list_of_files_in_my_folder = Systemdy::Utility::Formatter.return_an_array_from_system_command(`ls -la`)
+            # @todo execute system calls with backtick instead of system() beacuse system() return only true or false and not the expected value
             def self.return_an_array_from_system_command(system_call)
-                # remove \n from system call returned value
-                system_call_without_new_line = system_call.chomp!
-                # return system error message 
-                return(system_call_without_new_line) if !$?.success?
-                # convert `` system call to array based list
-                system_call_without_new_line.split(/\n/)
+                system_call_without_new_line = remove_newline_from_system_command(system_call)    # remove \n from system call returned value
+                return system_call_without_new_line if !$?.success?                               # return system error message if the process has non-zero exit status
+                system_call_without_new_line.split(/\n/)                                          # convert values returned by `` system call to an array-based list
+            end
+
+            # method for remove +\n+ characters from system calls
+            #
+            # @param  system_call [String] system call to remove +\n+ characters from
+            # @return [String] the result of a system call without +\n+ characters
+            # @example remove +\n+ characters from system calls
+            #   command_without_new_line = Systemdy::Utility::Formatter.remove_newline_from_system_command(`ls -la`)
+            # @todo execute system calls with backtick instead of system() beacuse system() return only true or false and not the expected value
+            def self.remove_newline_from_system_command(system_call)
+                system_call.chomp!    # remove \n from system call returned value
             end
         end
     end

data/lib/systemdy/utility/key_value_filter.rb

@@ -1,9 +1,25 @@
 module Systemdy
+    # A module that contains a set of useful classes for add utilities to the Systemdy's core
     module Utility 
+        # Allows to filter a key/value dataset
         class KeyValueFilter
-            # method for filter an hash with a list of provided keys
+            # a method for filter an hash with a list of provided keys
+            #
+            # @param hash [Hash] the hash to filter
+            # @param list_of_keys [Array] the list of keys to extract from the hash
+            # @return [Hash] a new hash that contains only the required keys
+            # @example a very large hash to filter
+            #   tasks = { task_one: 'learn ruby', task_two: 'learn rspec', task_three: 'create a good documentation', ... } 
+            # @example hash filtered with provided keys
+            #   filtered_hash = Systemdy::Utility::KeyValueFilter.filter_by_keys(tasks, 'task_one', 'task_two')
+            #   #=> {"task_one"=>"learn ruby", "task_two"=>"learn rspec"}
             def self.filter_by_keys(hash, *list_of_keys)
-                filtered_hash = hash.slice(*list_of_keys.flatten) 
+                # convert all hash keys from :key to "key"
+                hash_keys_converted_into_string      = Hash[hash.map{ |key, value| [key.to_s, value] }] 
+                # convert array elements from ":key" to "key"
+                array_elements_converted_into_string = list_of_keys.flatten.map { |element| element.start_with?(':') ? element.gsub(':','') : element }
+                # return an hash with only provided keys 
+                hash_keys_converted_into_string.slice(*array_elements_converted_into_string) 
             end
         end
     end

data/lib/systemdy/utility/message_displayer.rb

@@ -1,9 +1,17 @@
 module Systemdy
+    # A module that contains a set of useful classes for add utilities to the Systemdy's core
     module Utility 
+        # Allows to display messages to the user
         class MessageDisplayer
-            # method for render custom message tho the user
+            # a method for render custom message to the user
+            #
+            # @param message [String] the message to render 
+            # @return [String] the content of the message
+            # @example a custom message to show to the user
+            #   custom_message = Systemdy::Utility::MessageDisplayer.render_message('my custom message')
+            #   #=> "my custom message"
             def self.render_message(message)
-                message
+                message # the content of the message
             end
         end
     end

data/lib/systemdy/utility/validator.rb

@@ -1,12 +1,20 @@
 module Systemdy
+    # A module that contains a set of useful classes for add utilities to the Systemdy's core
     module Utility 
+        # Allows to add validation to a class
         class Validator
-            # method for check if a service exist
-            def self.check_if_a_service_exist(service)
-                `#{SYSTEMCTL_COMMAND} list-unit-files #{service}.service | wc -l`.to_i > 3
+            # a method for check if a service is intalled on the system
+            #
+            # @param name_of_the_service [String] the name of the service
+            # @return [Boolean] the presence of the service on the system
+            # @example check if a service is intalled on the system
+            #   postgresql_service = Systemdy::Utility::Validator.check_if_a_service_exist('postgresql')
+            #   #=> true
+            def self.check_if_a_service_exist(name_of_the_service)
+                `#{SYSTEMCTL_COMMAND} list-unit-files #{name_of_the_service}.service | wc -l`.to_i > 3
                 # 'systemctl list-unit-files name_of_service.service | wc -l' command output:
-                #  3  when there are not matching units
-                #  >3 when there are matching units
+                #  3  when there are not matching units(the service not exist because isn't installed on the system)
+                #  >3 when there are matching units(the service exist because is installed on the system)
             end
         end
     end

data/lib/systemdy/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Systemdy
-  VERSION = "0.1.0"
+  # the current version of the gem
+  VERSION = "0.3.0"
 end

data/lib/systemdy.rb

@@ -13,11 +13,13 @@ require_relative "systemdy/utility/key_value_filter"
 require_relative "systemdy/service"
 require_relative "systemdy/journal"
 
+# Allow to control systemd's services and manage journalctl logs
 module Systemdy
+  # Allows to manange errors
   class Error < StandardError; end
 
-  # systemctl command
+  # systemctl default command
   SYSTEMCTL_COMMAND  = 'systemctl'
-  # journalctl command
+  # journalctl default command
   JOURNALCTL_COMMAND = 'journalctl'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: systemdy
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - magic4dev
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-10-03 00:00:00.000000000 Z
+date: 2022-10-21 00:00:00.000000000 Z
 dependencies: []
 description: 
 email: magic4dev@gmail.com
@@ -33,14 +33,16 @@ files:
 - lib/systemdy/utility/validator.rb
 - lib/systemdy/version.rb
 - sig/systemdy.rbs
-homepage: https://github.com/magic4dev/systemd
+- systemdy.png
+homepage: https://github.com/magic4dev/systemdy
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/magic4dev/systemd
-  source_code_uri: https://github.com/magic4dev/systemd
-  changelog_uri: https://github.com/magic4dev/systemd/blob/master/CHANGELOG.md
-  code_of_conduct_uri: https://github.com/magic4dev/systemd/blob/master/CODE_OF_CONDUCT.md
+  homepage_uri: https://github.com/magic4dev/systemdy
+  source_code_uri: https://github.com/magic4dev/systemdy
+  documentation_uri: https://www.rubydoc.info/github/magic4dev/systemdy/master
+  changelog_uri: https://github.com/magic4dev/systemdy/blob/master/CHANGELOG.md
+  code_of_conduct_uri: https://github.com/magic4dev/systemdy/blob/master/CODE_OF_CONDUCT.md
 post_install_message: 
 rdoc_options: []
 require_paths: