linux_stat 0.6.3 → 0.6.4

data/lib/linux_stat/kernel.rb

@@ -1,16 +1,22 @@
 module LinuxStat
 	module Kernel
 		class << self
+			##
 			# Returns the Linux Kernel version.
+			#
 			# If the information isn't available, it will return a frozen empty string.
+			#
 			# The output is also cached (memoized) ; as changing the value in runtime is unexpected.
 			def version
 				return ''.freeze if string.empty?
 				@@version ||= splitted[2]
 			end
 
+			##
 			# Returns the name of the user who built the kernel using KBUILD_FLAGS.
+			#
 			# If the information isn't available, it will return a frozen empty string.
+			#
 			# The output is also cached (memoized) ; as changing the value in runtime is unexpected.
 			def build_user
 				@@build_user ||= string.split(/(\(.+\))/).each(&:strip!)
@@ -18,8 +24,11 @@ module LinuxStat
 					.split[0].to_s[1..-2].to_s.freeze
 			end
 
+			##
 			# Returns the compiler used to compile the Linux Kernel.
+			#
 			# If the information isn't available, it will return a frozen empty string.
+			#
 			# The output is also cached (memoized) ; as changing the value in runtime is unexpected.
 			def compiler
 				return ''.freeze if string.empty?
@@ -37,8 +46,11 @@ module LinuxStat
 				end << compiler_version
 			end
 
+			##
 			# Returns the compiler version used to compile the Linux Kernel.
+			#
 			# If the information isn't available, it will return a frozen empty string.
+			#
 			# The output is also cached (memoized) ; as changing the value in runtime is unexpected.
 			def compiler_version
 				@@compiler_version ||= string.split(/(\(.+?\))/).each(&:strip!)
@@ -46,20 +58,28 @@ module LinuxStat
 					.find { |x| x[/[\d.]+/] }.to_s[/[\d.]+/].to_s.freeze
 			end
 
+			##
 			# Returns the time when the kernel was compiled.
+			#
 			# The return value is a Time object.
+			#
 			# If the information isn't available, it will return nil
 			#
 			# The time will be searched in specific order.
-			# It will match any date matching any of these formats:
+			#
+			# * It will match any date matching any of these formats:
 			# 1. %b %d %H:%M:%S %z %Y
 			# 2. %d %b %Y %H:%M:%S %z
 			# 3. %Y-%m-%d
+			#
 			# Most kernels have date in them in this format.
 			#
 			# Do note that Ruby sometimes fails to work with timezones like BST for example.
+			#
 			# In such case, the timezone is unrealiable and often returns the local timezone.
+			#
 			# You have to use regexp yourself to get the proper zone.
+			#
 			# Use LinuxStat::Kernel.build_date_string to get the original string if you need that.
 			#
 			# The output is also cached  (memoized) ; as changing the value in runtime is unexpected.
@@ -91,20 +111,29 @@ module LinuxStat
 				end
 			end
 
+			##
 			# Returns the time when the kernel was compiled.
+			#
 			# The return value is a String.
+			#
 			# If the information isn't available, it will return nil
 			#
 			# The time will be searched in specific order.
-			# It will match any date matching any of these formats:
+			#
+			# * It will match any date matching any of these formats:
+			#
 			# 1. %b %d %H:%M:%S %z %Y
 			# 2. %d %b %Y %H:%M:%S %z
 			# 3. %Y-%m-%d
+			#
 			# Most kernels have date in them in this format.
 			#
 			# Do note that Ruby sometimes fails to work with timezones like BST for example.
+			#
 			# In such case, the timezone is unrealiable and often returns the local timezone.
+			#
 			# You have to use regexp yourself to get the proper zone.
+			#
 			# Use LinuxStat::Kernel.build_date_string to get the original string if you need that.
 			#
 			# The output is also cached (memoized) ; as changing the value in runtime is unexpected.
@@ -133,14 +162,19 @@ module LinuxStat
 				end
 			end
 
+			##
 			# Reads maximum 1024 bytes from /proc/version and returns the string.
+			#
 			# The output is also cached ; as changing the value in runtime is unexpected.
 			def string
 				@@string ||= File.readable?('/proc/version') ? IO.read('/proc/version', 1024).tap(&:strip!) : ''
 			end
 
+			##
 			# Returns the sc_clk_tck or the same output from command `getconf CLK_TCK`.
+			#
 			# Also, clk_tck is an alias of this method.
+			#
 			# The output is also cached ; as changing the value in runtime is unexpected.
 			def ticks
 				@@tick ||= LinuxStat::Sysconf.sc_clk_tck

data/lib/linux_stat/memory.rb

@@ -1,6 +1,7 @@
 module LinuxStat
 	module Memory
 		class << self
+			##
 			# Returns the memory details reported by /proc/meminfo. In this format:
 			#    {:total=>3836264, :used=>3097952, :available=>738312, :percent_used=>80.75, :percent_available=>19.25}
 			#
@@ -20,6 +21,7 @@ module LinuxStat
 				percent_available = total == 0 ? 0.0 : available.*(100).fdiv(total).round(2)
 
 				# We have all the methods, but each methods reads the same file
+				#
 				# So better to use the above calculation
 				{
 					total: total,
@@ -30,6 +32,7 @@ module LinuxStat
 				}
 			end
 
+			##
 			# Returns the total memory details reported by /proc/meminfo.
 			# The value is in Kilobyte.
 			#
@@ -39,6 +42,7 @@ module LinuxStat
 				IO.foreach('/proc/meminfo').first.split[1].to_i
 			end
 
+			##
 			# Returns the total memory details reported by /proc/meminfo.
 			# The value is in Kilobyte.
 			#
@@ -48,6 +52,7 @@ module LinuxStat
 				IO.foreach('/proc/meminfo').first(3)[-1].split[1].to_i
 			end
 
+			##
 			# Returns the amount of memory used reported by /proc/meminfo.
 			# The value is in Kilobyte.
 			#
@@ -58,6 +63,7 @@ module LinuxStat
 				memory[0].split[1].to_i - memory[2].split[1].to_i
 			end
 
+			##
 			# Returns the percentage of memory used reported by /proc/meminfo.
 			#
 			# It retuns an Integer but if the info is not available, it will return nil
@@ -68,6 +74,7 @@ module LinuxStat
 				total.-(memory[2].split[1].to_i).*(100).fdiv(total).round(2)
 			end
 
+			##
 			# Returns the percentage of memory used reported by /proc/meminfo.
 			#
 			# It retuns an Integer but if the info is not available,  it will return nil

data/lib/linux_stat/mounts.rb

@@ -1,7 +1,9 @@
 module LinuxStat
 	module Mounts
 		class << self
+			##
 			# Reads /proc/mounts and returns the output splitted with \n.
+			#
 			# In other words, it's same as running IO.readlines('/proc/mounts').each(&:strip!)
 			#
 			# It returns an Array.
@@ -10,6 +12,7 @@ module LinuxStat
 				mounts
 			end
 
+			##
 			# Reads /proc/mounts and returns list of devices.
 			#
 			# It returns an Array.
@@ -18,6 +21,7 @@ module LinuxStat
 				mounts.map { |x| x.split(?\s.freeze).first }
 			end
 
+			##
 			# Reads /proc/mounts and returns partition name of the device mounted at /.
 			#
 			# It returns a String.
@@ -26,6 +30,7 @@ module LinuxStat
 				find_root[0].to_s
 			end
 
+			##
 			# Reads /proc/mounts and returns the file system of the device mounted at /.
 			#
 			# It returns a String.
@@ -34,6 +39,7 @@ module LinuxStat
 				find_root[2].to_s
 			end
 
+			##
 			# Reads /proc/mounts and returns the options used for mounting /.
 			#
 			# It returns a String.
@@ -42,6 +48,7 @@ module LinuxStat
 				find_root[3].to_s
 			end
 
+			##
 			# Reads /proc/mounts and finds all tmpfs.
 			#
 			# It returns a Hash
@@ -54,13 +61,18 @@ module LinuxStat
 				ret
 			end
 
+			##
 			# mount_point(dev = root)
+			#
 			# Where device = block device.
+			#
 			# The default argument is the root block device.
 			#
 			# It helps you find the mountpoint of a block device.
 			# For example:
+			#
 			#    LinuxStat::Mounts.mount_point('/dev/sdb1')
+			#
 			#    => "/run/media/sourav/5c2b7af7-d4c3-4ab4-a035-06d18ffc8e6f"
 			#
 			# The return type is String.
@@ -81,12 +93,15 @@ module LinuxStat
 				m
 			end
 
+			##
 			# list_devices_mount_point()
 			#
 			# It shows all the block devices corresponding to mount points.
 			#
 			# For example:
+			#
 			#    LinuxStat::Mounts.list_devices_mount_point
+			#
 			#    => {"proc"=>"/proc", "sys"=>"/sys", "dev"=>"/dev", "run"=>"/run", "/dev/sda2"=>"/", "securityfs"=>"/sys/kernel/security", "tmpfs"=>"/run/user/1000", "devpts"=>"/dev/pts", "cgroup2"=>"/sys/fs/cgroup/unified", "cgroup"=>"/sys/fs/cgroup/perf_event", "pstore"=>"/sys/fs/pstore", "none"=>"/sys/fs/bpf", "systemd-1"=>"/proc/sys/fs/binfmt_misc", "debugfs"=>"/sys/kernel/debug", "mqueue"=>"/dev/mqueue", "hugetlbfs"=>"/dev/hugepages", "tracefs"=>"/sys/kernel/tracing", "configfs"=>"/sys/kernel/config", "fusectl"=>"/sys/fs/fuse/connections", "gvfsd-fuse"=>"/run/user/1000/gvfs", "/dev/sdb1"=>"/run/media/sourav/5c2b7af7-d4c3-4ab4-a035-06d18ffc8e6f", "binfmt_misc"=>"/proc/sys/fs/binfmt_misc"}
 			#
 			# The return type is Hash.
@@ -104,13 +119,17 @@ module LinuxStat
 				m
 			end
 
+			##
 			# devices_stat
+			#
 			# [ Not to confuse this method with device_stat(dev) which shows only one device's info ]
 			#
 			# It shows all the block devices corresponding to mount points and data from LinuxStat::FS.stat(arg)
 			#
 			# For example:
+			#
 			#    LinuxStat::Mounts.devices_stat
+			#
 			#    => {"proc"=>{:mountpoint=>"/proc", :total=>0, :free=>0, :available=>0, :used=>0, :percent_used=>NaN, :percent_free=>NaN, :percent_available=>NaN}, "/dev/sdb1"=>{:mountpoint=>"/run/media/sourav/5c2b7af7-d4c3-4ab4-a035-06d18ffc8e6f", :total=>31466008576, :free=>2693931008, :available=>2693931008, :used=>28772077568, :percent_used=>91.44, :percent_free=>8.56, :percent_available=>8.56}}
 			#
 			# The return type is Hash.
@@ -142,12 +161,17 @@ module LinuxStat
 				m
 			end
 
+			##
 			# device_stat(dev = root)
+			#
 			# [ Not to confuse this method with devices_stat() which shows all devices ]
+			#
 			# It shows all the block devices corresponding to mount points and data from LinuxStat::FS.stat(arg)
 			#
 			# For example:
+			#
 			#    LinuxStat::Mounts.device_stat('/dev/sda2')
+			#
 			#    => {"/dev/sda2"=>{:mountpoint=>"/", :total=>119981191168, :free=>35298562048, :available=>35298562048, :used=>84682629120, :percent_used=>70.58, :percent_free=>29.42, :percent_available=>29.42}}
 			#
 			# The return type is Hash.

data/lib/linux_stat/net.rb

@@ -2,7 +2,10 @@ module LinuxStat
 	module Net
 		class << self
 			DEV = '/proc/net/dev'.freeze
+
+			##
 			# Returns the local IP address of the system as a String.
+			#
 			# If the information isn't available, it will a frozen empty string.
 			def ipv4_private
 				require 'socket' unless defined?(Socket)
@@ -10,7 +13,9 @@ module LinuxStat
 				ip ? ip.ip? ? ip.ip_unpack[0].freeze : ''.freeze : ''.freeze
 			end
 
+			##
 			# Returns the total bytes received and transmitted as Hash.
+			#
 			# For example:
 			#    {:received=>56602867, :transmitted=>6940922}
 			#
@@ -29,6 +34,7 @@ module LinuxStat
 				}
 			end
 
+			##
 			# Returns the total bytes received as Integer.
 			#
 			# But if the status isn't available it will return nil.
@@ -41,6 +47,7 @@ module LinuxStat
 				data.map { |x| x.split[index].to_i }.sum
 			end
 
+			##
 			# Returns the total bytes transmitted as Integer.
 			#
 			# But if the status isn't available it will return nil.
@@ -53,7 +60,9 @@ module LinuxStat
 				data.map { |x| x.split[index].to_i }.sum
 			end
 
+			##
 			# usage(interval = 0.1)
+			#
 			# Where interval is the time between polling in seconds. The default is 0.1 seconds.
 			#
 			# The return type is a Hash, containg the current internet usage (received, transmit) in B/s.
@@ -62,8 +71,11 @@ module LinuxStat
 			#    {:received=>436060.0, :transmitted=>50350.0}
 			#
 			# If the system transmits 100 kb in the interval,
+			#
 			# this method will return 1000 kb/s. That is, it estimates
+			#
 			# the data it will transmit in one second. Thus, a good and reliable interval is 1 second
+			#
 			# It will return an empty Hash if the info (/proc/net/dev) isn't available.
 			def usage(interval = 0.1)
 				return {} unless File.readable?(DEV)

data/lib/linux_stat/os.rb

@@ -1,6 +1,7 @@
 module LinuxStat
 	module OS
 		class << self
+			##
 			# Reads /etc/os-release and returns a Hash. For example:
 			#    {:NAME=>"Arch Linux", :PRETTY_NAME=>"Arch Linux", :ID=>"arch", :BUILD_ID=>"rolling", :ANSI_COLOR=>"38;2;23;147;209", :HOME_URL=>"https://www.archlinux.org/", :DOCUMENTATION_URL=>"https://wiki.archlinux.org/", :SUPPORT_URL=>"https://bbs.archlinux.org/", :BUG_REPORT_URL=>"https://bugs.archlinux.org/", :LOGO=>"archlinux"}
 			#
@@ -8,13 +9,15 @@ module LinuxStat
 			#
 			# The amount of data read is 4096 bytes. Any more than that will result in truncated output.
 			#
-			# The information is also cached, and once loaded, won't change in runtime. Because changing the /etc/lsb-release
+			# The information is also cached, and once loaded, won't change in runtime.
+			# Because changing the /etc/lsb-release
 			# isn't expected in runtime.
 			def os_release
 				# cached (memoized) ; as changing the value in runtime is unexpected
 				@@os_release ||= File.readable?('/etc/os-release') ? release('/etc/os-release') : {}
 			end
 
+			##
 			# Reads /etc/lsb-release and returns a Hash. For example:
 			#    {:LSB_VERSION=>"1.4", :DISTRIB_ID=>"Arch", :DISTRIB_RELEASE=>"rolling", :DISTRIB_DESCRIPTION=>"Arch Linux"}
 			#
@@ -22,14 +25,16 @@ module LinuxStat
 			#
 			# The amount of data read is 4096 bytes. Any more than that will result in truncated output.
 			#
-			# The information is also cached, and once loaded, won't change in runtime. Because changing the /etc/lsb-release
-			# isn't expected in runtime.
+			# The information is also cached, and once loaded, won't change in runtime.
+			# Because changing the /etc/lsb-release isn't expected in runtime.
 			def lsb_release
 				# cached (memoized) ; as changing the value in runtime is unexpected
 				@@lsb_release ||= File.readable?('/etc/lsb-release') ? release('/etc/lsb-release') : {}
 			end
 
+			##
 			# Reads /etc/lsb-release or /etc/os-release tries to get information about the distribution.
+			#
 			# If the information isn't available, it will read and return /etc/issue.
 			#
 			# The return type is String.
@@ -52,6 +57,7 @@ module LinuxStat
 				end
 			end
 
+			##
 			# Uses utsname.h to determine the machine
 			#
 			# It returns a String but if the info isn't available, it will return an empty String
@@ -59,6 +65,7 @@ module LinuxStat
 				@@machine ||= LinuxStat::Uname.machine
 			end
 
+			##
 			# Uses utsname.h to determine the system nodename
 			#
 			# It returns String but if the info isn't available, it will return an empty String
@@ -66,6 +73,7 @@ module LinuxStat
 				@@nodename ||= LinuxStat::Uname.nodename
 			end
 
+			##
 			# Reads /etc/hostname and returns the hostname.
 			#
 			# The return type is String.
@@ -78,8 +86,11 @@ module LinuxStat
 				end
 			end
 
+			##
 			# Reads ruby configuration and tries to guess if the system is 64 bit.
+			#
 			# If it fails then it runs utsname.h to guess the machine.
+			#
 			# It the machine is 64 bits, it will return 64, else it returns 32.
 			#
 			# The return type is strictly Integer and doesn't fail.
@@ -91,6 +102,7 @@ module LinuxStat
 				end
 			end
 
+			##
 			# Reads /proc/uptime and returns the system uptime:
 			#    {:hour=>10, :minute=>34, :second=>12.59}
 			#

data/lib/linux_stat/prettify_bytes.rb

@@ -1,12 +1,21 @@
 module LinuxStat
 	module PrettifyBytes
 		class << self
+			##
 			# Converts a number to decimal byte units and outputs with the metric prefix
 			# For example,
 			#
-			# LinuxStat::PrettifyBytes.convert_decimal(1000)    # => "1.0 kilobyte"
-			# LinuxStat::PrettifyBytes.convert_decimal(1000 ** 3)    # => "1.0 gigabyte"
-			# LinuxStat::PrettifyBytes.convert_decimal(1024 ** 3)   # => "1.07 gigabytes"
+			# LinuxStat::PrettifyBytes.convert_decimal(1000)
+			#
+			# => "1.0 kilobyte"
+			#
+			# LinuxStat::PrettifyBytes.convert_decimal(1000 ** 3)
+			#
+			# => "1.0 gigabyte"
+			#
+			# LinuxStat::PrettifyBytes.convert_decimal(1024 ** 3)
+			#
+			# => "1.07 gigabytes"
 			def convert_decimal(n)
 				@@d_units ||= %W(#{''} kilo mega giga tera peta exa zetta)
 					.map.with_index { |x, i| [x, 1000.**(i + 1)] }
@@ -19,9 +28,17 @@ module LinuxStat
 			# Converts a number to binary byte units and outputs with the IEC prefix
 			# For example,
 			#
-			# LinuxStat::PrettifyBytes.convert_binary(1000)    # => "1000.0 bytes"
-			# LinuxStat::PrettifyBytes.convert_binary(1000 ** 3)    # => "953.67 mebibytes"
-			# LinuxStat::PrettifyBytes.convert_binary(1024 ** 3)   # => "1.0 gibibyte"
+			# LinuxStat::PrettifyBytes.convert_binary(1000)
+			#
+			# => "1000.0 bytes"
+			#
+			# LinuxStat::PrettifyBytes.convert_binary(1000 ** 3)
+			#
+			# => "953.67 mebibytes"
+			#
+			# LinuxStat::PrettifyBytes.convert_binary(1024 ** 3)
+			#
+			# => "1.0 gibibyte"
 			def convert_binary(n)
 				@@b_units ||= %W(#{''} kibi mebi gibi tebi pebi exbi zebi)
 					.map.with_index { |x, i| [x, 1024.**(i + 1)] }
@@ -34,9 +51,17 @@ module LinuxStat
 			# Converts a number to decimal byte units
 			# For example,
 			#
-			# LinuxStat::PrettifyBytes.convert_short_decimal(1000)    # => "1.0 kB"
-			# LinuxStat::PrettifyBytes.convert_short_decimal(1000 ** 3)   # => "1.0 GB"
-			# LinuxStat::PrettifyBytes.convert_short_decimal(1024 ** 3)    # => "1.07 GB"
+			# LinuxStat::PrettifyBytes.convert_short_decimal(1000)
+			#
+			# => "1.0 kB"
+			#
+			# LinuxStat::PrettifyBytes.convert_short_decimal(1000 ** 3)
+			#
+			# => "1.0 GB"
+			#
+			# LinuxStat::PrettifyBytes.convert_short_decimal(1024 ** 3)
+			#
+			# => "1.07 GB"
 			def convert_short_decimal(n)
 				@@sd_units ||= %W(#{''} k M G T P E Z)
 					.map.with_index { |x, i| [x, 1000.**(i + 1)] }
@@ -46,12 +71,22 @@ module LinuxStat
 				"#{pad_left(converted)} #{unit[0]}B"
 			end
 
+			##
 			# Converts a number to binary byte units
+			#
 			# For example,
 			#
-			# LinuxStat::PrettifyBytes.convert_short_binary(1000)    # => "1000 B"
-			# LinuxStat::PrettifyBytes.convert_short_binary(1000 ** 3)   # => "953.67 MiB"
-			# LinuxStat::PrettifyBytes.convert_short_binary(1024 ** 3)    # => "1.0 GiB"
+			# LinuxStat::PrettifyBytes.convert_short_binary(1000)
+			#
+			# => "1000 B"
+			#
+			# LinuxStat::PrettifyBytes.convert_short_binary(1000 ** 3)
+			#
+			# => "953.67 MiB"
+			#
+			# LinuxStat::PrettifyBytes.convert_short_binary(1024 ** 3)
+			#
+			# => "1.0 GiB"
 			def convert_short_binary(n)
 				return "#{n} B" if n < 1024