explain_payslip.rb
#!/usr/bin/env ruby
require 'bigdecimal'
require 'bigdecimal/util'
require 'open-uri'
require 'openssl'
require 'optparse'
require 'ostruct'
require 'rbconfig'
require 'yaml'
# For 1.8 we need to redefine the SSL::VERIFY_PEER constant so that clients can reach
# the version file on Github (mainly a problem on Windows). Modifying this constant is
# only applicable for Ruby versions =< 1.8 so we don't bother doing it for any others (they
# are passed an arg to the open() method). Redefining this constant results in a warning on the
# output. Hopefully users will just ignore it.
OpenSSL::SSL::VERIFY_PEER = OpenSSL::SSL::VERIFY_NONE unless RUBY_VERSION.to_f > 1.8
REPO_LINK = "http://github.com/nathanshox/PayslipExplainator"
SCRIPT_VERSION = 1.2
SCRIPT_VERSION_FILE_URL = "https://raw.github.com/nathanshox/PayslipExplainator/master/version"
class OptionsParser
#
# Return a structure describing the options.
#
def self.parse(args)
# The options specified on the command line will be collected in *options*.
# Set default values here.
options = OpenStruct.new
options.config_file_path = File.join(File.dirname(File.expand_path(__FILE__)), 'payslip_config.yml')
options.pause = false
options.check_for_update = true
opts = OptionParser.new do |opts|
opts.banner = "Usage: explain_payslip.rb [options]"
opts.separator ""
opts.separator "Specific options:"
opts.on("-c", "--config PATH", "Specify path to a config file") do |path|
options.config_file_path = path
end
opts.on("-p", "--[no-]pause", "Pause after each calculation") do |p|
options.pause = p
end
opts.on("-n", "--no-update-check", "Do not check for new version of script") do
options.check_for_update = false
end
opts.separator ""
opts.separator "Common options:"
opts.on_tail("-h", "--help", "Show this message") do
puts opts
exit
end
opts.on_tail("-v", "--version", "Show script version") do
puts "PayslipExplainator"
puts "Version: #{SCRIPT_VERSION}"
exit
end
end
opts.parse!(args)
options
end
end
# Misc methods
# Print section header
def print_header(headline)
puts "\n\n" + "#" * 80
puts "### #{headline} " + ( "#" * (80 - 5 - headline.length))
end
# Load key from config and return value as Hash
def load_hash_from_config(config, key)
value = config[key]
if value.nil?
abort "Did not find #{key} in config file"
end
return value
end
# Load key from config and return value as BigDecimal
def load_bd_from_config(config, key)
value = config[key]
if value.nil?
abort "Did not find #{key} in config file"
end
return BigDecimal.new(value.to_s)
end
# puz (print unless zero)
def puz(string, value)
puts string unless value.zero?
end
# Print out hash values, and return sum of values
def print_and_total_hash(input_hash)
total = BigDecimal.new("0")
input_hash.each do |key, value|
v = BigDecimal.new(value.to_s)
puz "\t#{v.to_digits}\t(#{key.gsub("_", " ").capitalize})", v
total = total + v
end
return total
end
def open_browser(url)
host_os = RbConfig::CONFIG['host_os']
if host_os =~ /mswin|mingw|cygwin/
command = "start #{url}"
elsif host_os =~ /darwin/
command = "open #{url}"
elsif host_os =~ /linux/
command = "xdg-open #{url}"
end
system command
end
# This function doesn't return until it reads something from input, thereby pausing execution
# of the script
def pause
print "\n<<SCRIPT PAUSED. PRESS ANY KEY TO CONTINUE...>>"
gets.chomp
end
def calculate_paye(taxable_amount, standard_cutoff_rate, tax_credits)
result = Hash.new
result['taxable_at_lower_rate_amount'] = taxable_amount > standard_cutoff_rate ? standard_cutoff_rate : taxable_amount
result['taxable_at_higher_rate_amount'] = taxable_amount > standard_cutoff_rate ? (taxable_amount - standard_cutoff_rate) : BigDecimal.new("0")
result['tax_payable_at_lower_rate'] = (result['taxable_at_lower_rate_amount'] * BigDecimal.new("0.20"))
result['tax_payable_at_higher_rate'] = (result['taxable_at_higher_rate_amount'] * BigDecimal.new("0.40"))
result['paye_pre_tax_credits_deduction'] = result['tax_payable_at_lower_rate'] + result['tax_payable_at_higher_rate']
result['paye'] = (result['paye_pre_tax_credits_deduction'] - tax_credits).round 2
return result
end
def calculate_usc(taxable_amount, point_five_percent_band, two_percent_band, four_point_five_percent_band)
result = Hash.new
already_charged = 0
result['chargable_at_point_five'] = taxable_amount > point_five_percent_band ? point_five_percent_band : taxable_amount
already_charged += point_five_percent_band
result['chargable_at_two'] = taxable_amount > (already_charged + two_percent_band) ? two_percent_band : ( taxable_amount > already_charged ? (taxable_amount - already_charged) : BigDecimal.new("0"))
already_charged += two_percent_band
result['chargable_at_four_point_five'] = taxable_amount > (already_charged + four_point_five_percent_band) ? four_point_five_percent_band : ( taxable_amount > already_charged ? (taxable_amount - already_charged) : BigDecimal.new("0"))
already_charged += four_point_five_percent_band
result['chargable_at_eight'] = taxable_amount > already_charged ? (taxable_amount - already_charged) : BigDecimal.new("0")
result['usc_payable_at_point_five'] = (result['chargable_at_point_five'] * BigDecimal.new("0.005"))
result['usc_payable_at_two'] = (result['chargable_at_two'] * BigDecimal.new("0.02"))
result['usc_payable_at_four_point_five'] = (result['chargable_at_four_point_five'] * BigDecimal.new("0.045"))
result['usc_payable_at_eight'] = (result['chargable_at_eight'] * BigDecimal.new("0.08"))
result['usc'] = (result['usc_payable_at_point_five'] + result['usc_payable_at_two'] + result['usc_payable_at_four_point_five'] + result['usc_payable_at_eight']).round 2
return result
end
## START OF MAIN #########################################################################
# Parse arguments
options = OptionsParser.parse(ARGV)
puts "#" * 80
puts "# PAYSLIP EXPLAINATOR"
puts "#" * 80
puts ""
puts "Welcome to the Payslip Explainator. Let's try decrypt your payslip."
puts ""
# Check script version
if options.check_for_update
begin
puts "Checking for new version of the script..."
# TODO Add a timeout here
if RUBY_VERSION.to_f < 1.9
latest_version = open(SCRIPT_VERSION_FILE_URL).read.to_f
else
latest_version = open(SCRIPT_VERSION_FILE_URL, :ssl_verify_mode => OpenSSL::SSL::VERIFY_NONE).read.to_f
end
if latest_version > SCRIPT_VERSION
puts "Version #{latest_version} of script is available. You are currently using version #{SCRIPT_VERSION}."
puts "You can download the latest script from #{REPO_LINK}"
print "Would you like to download the latest version now? (yes/no) >: "
if gets.downcase.strip == 'yes'
puts "Opening browser..."
exit open_browser(REPO_LINK)
else
puts "Continuing execution of this version (#{SCRIPT_VERSION}) of the script"
end
else
puts "You have the latest version of the script"
end
rescue
puts "Couldn't check for latest version of script."
puts "Are you connected to the internet? Can you access #{REPO_LINK} in your web browser?"
puts "Continuing execution of script"
end
end
# Attempt to load config file ############################################################
if File.exists? options.config_file_path
config_file = YAML::load_file options.config_file_path
if config_file
print "\nYour payslip.yml file has been found and loaded\n\n"
regular_salary = load_bd_from_config config_file, "regular_salary"
pension_contribution_percentage = load_bd_from_config config_file, "pension_contribution_percentage"
espp_contribution_percentage = load_bd_from_config config_file, 'espp'
car_allowance_hash = load_hash_from_config config_file, "car_allowance"
salary_sacrifice_hash = load_hash_from_config config_file, "salary_sacrifice"
benefit_in_kind_hash = load_hash_from_config config_file, "benefit_in_kind"
misc_deductions_hash = load_hash_from_config config_file, "misc_deductions"
standard_cutoff_rate = load_bd_from_config config_file, "standard_cutoff_rate"
tax_credit = load_bd_from_config config_file, "tax_credit"
usc_point_five_percent_band = load_bd_from_config config_file, "point_five_percent_band"
usc_two_percent_band = load_bd_from_config config_file, "two_percent_band"
usc_four_point_five_percent_band = load_bd_from_config config_file, "four_point_five_percent_band"
end
else
abort "Couldn't find #{options.config_file_path}. Does this file exist?"
end
# Get other input values #################################################################
print 'Did you receive overtime or on-call pay this month? Enter 0 for no extra pay. >: '
extra_pay = gets.to_d
print 'Did you receive a PL&I bonus this month? Enter 0 for no bonus. >: '
pli_bonus = gets.to_d
print 'Did you receive a CAP Award this month? Enter 0 for no award. >: '
gross_bonus_award = gets.to_d
print 'Did you receive a Connected Recognition Award this month? (yes or no) >: '
if gets.strip == 'yes'
print 'What is the total voucher amount? >: '
cr_voucher_amount = gets.to_d
print 'what is the total gross amount on your payslip? >: '
cr_gross_amount = gets.to_d
else
cr_voucher_amount = BigDecimal.new("0")
cr_gross_amount = BigDecimal.new("0")
end
bik_to_enter = true
print 'Do you have a variable benefit in kind you want to enter? (yes or no) >: '
bik_to_enter = gets.strip == 'yes' ? true : false
while bik_to_enter
print 'What is the benefit in kind? >: '
var_bik_key = gets.strip
print 'How much is the benefit in kind? >: '
var_bik_value = gets.strip
benefit_in_kind_hash[var_bik_key] = var_bik_value
print 'Do you have another variable benefit in kind you want to enter? (yes or no) >: '
bik_to_enter = gets.strip == 'yes' ? true : false
end
print 'Did you receive any refunds this pay period? Enter 0 for no refunds >: '
refund = gets.to_d
print 'Did you receive an ESPP gain this pay period? Enter 0 for no gain >: '
espp_gain = gets.to_d
print_header "Input Values"
puts "These are the values the script is using to calculate your payslip\n"
puts "-Regular Salary: #{regular_salary.to_digits}"
puts "-Overtime/On-Call Pay: #{extra_pay.to_digits}"
puts "-PL&I Bonus: #{pli_bonus.to_digits}"
puts "-CAP Award: #{gross_bonus_award.to_digits}"
puts "-Connected Recognition Award"
puts "\tVoucher Amount: #{cr_voucher_amount.to_digits}"
puts "\tGross Amount: #{cr_gross_amount.to_digits}"
puts "-Pension Contribution: #{pension_contribution_percentage.to_digits}%"
puts "-ESPP: #{espp_contribution_percentage.to_digits}%"
puts "-Car Allowance: #{car_allowance_hash}"
puts "-Salary Sacrifice: #{salary_sacrifice_hash}"
puts "-Refund: #{refund.to_digits}"
puts "-Benefit in Kind: #{benefit_in_kind_hash}"
puts "-Misc Deductions: #{misc_deductions_hash}"
puts "-ESPP Gain: #{espp_gain.to_digits}"
puts "-PAYE Standard rate cutoff: #{standard_cutoff_rate.to_digits}"
puts "-PAYE Tax credit: #{tax_credit.to_digits}"
puts "-USC 0.5% Band: #{usc_point_five_percent_band.to_digits}"
puts "-USC 2% Band: #{usc_two_percent_band.to_digits}"
puts "-USC 4.5% Band: #{usc_four_point_five_percent_band.to_digits}"
pause unless !options.pause
# Salary Sacrifices ######################################################################
print_header "Salary Sacrfices"
salary_sacrifice_total = print_and_total_hash salary_sacrifice_hash
puts ""
puts "TOTAL SALARY SACRIFICE = #{salary_sacrifice_total.to_digits}"
pause unless !options.pause
# Car Allowance ##########################################################################
print_header "Car Allowance"
if car_allowance_hash["type"] == "cash"
puts "Your car allowance is paid in cash so is considered in your Gross Income below"
elsif car_allowance_hash["type"] == "bik"
puts "Your Car Allowance is a Benefit in Kind so it has been added to that section below"
benefit_in_kind_hash["car_allowance"] = car_allowance_hash["value"].to_s
else
puts "You have not specified you are in receipt of Car Allowance."
puts "If you are, change your config to 'cash' or 'bik' as appropriate"
end
pause unless !options.pause
# Gross Income ###########################################################################
print_header "Gross Income"
puz "Gross Income\t+ #{regular_salary.to_digits}\t\t(Regular salary)", regular_salary
puz "\t\t+ #{extra_pay.to_digits}\t\t(Overtime/On-Call Pay)", extra_pay
puz "\t\t+ #{gross_bonus_award.to_digits}\t\t(CAP Award)", gross_bonus_award
puz "\t\t+ #{pli_bonus.to_digits}\t\t(PL&I Bonus)", pli_bonus
puz "\t\t+ #{cr_gross_amount.to_digits}\t\t(Connected Recognition Gross Amount)", cr_gross_amount
if car_allowance_hash["type"] == "cash"
car_allowance = BigDecimal.new(car_allowance_hash["value"].to_s)
puts "\t\t+ #{car_allowance.to_digits}\t\t(Car Allowance)"
else
car_allowance = BigDecimal.new("0")
end
puz "\t\t- #{salary_sacrifice_total.to_digits}\t\t(Salary Sacrifices)", salary_sacrifice_total
gross_income = regular_salary + extra_pay + gross_bonus_award + pli_bonus + cr_gross_amount + car_allowance - salary_sacrifice_total
puts ""
puts "TOTAL GROSS INCOME = #{gross_income.to_digits}"
pause unless !options.pause
# Calculate Benefit in Kind ##############################################################
print_header "Benefit in Kind"
bik_total = print_and_total_hash benefit_in_kind_hash
puts ""
puts "TOTAL BENEFIT IN KIND = #{bik_total.to_digits}"
pause unless !options.pause
# Calculate Pension Contribution #########################################################
if pension_contribution_percentage > 0
print_header "Pension Contribution"
puts "Your pension contribution is #{pension_contribution_percentage.to_digits}%"
puts ""
puts "Input for pension contribution = #{regular_salary.to_digits} (Regular Salary)"
puts ""
pension_contribution = ((regular_salary / 100) * pension_contribution_percentage).round(2)
puts "#{regular_salary.to_digits} @ #{pension_contribution_percentage.to_digits}% = #{pension_contribution.to_digits}"
puts ""
puts "TOTAL PENSION CONTRIBUTION = #{pension_contribution.to_digits}"
else
pension_contribution = BigDecimal.new("0")
end
pause unless !options.pause
# Calculate PAYE #########################################################################
print_header "PAYE"
puz "Input for PAYE\t+ #{gross_income.to_digits}\t\t(Gross Income)", gross_income
puz "\t\t+ #{bik_total.to_digits}\t\t(Benefit In Kind)", bik_total
puz "\t\t+ #{espp_gain.to_digits}\t\t(ESPP Gain)", espp_gain
puz "\t\t- #{pension_contribution.to_digits}\t\t(Pension Contribution)", pension_contribution
paye_input = gross_income + bik_total + espp_gain - pension_contribution
puts "Total Input\t= #{paye_input.to_digits}"
puts ""
paye_result = calculate_paye paye_input, standard_cutoff_rate, tax_credit
puts "#{paye_result['taxable_at_lower_rate_amount'].to_digits} @ 20%\t #{paye_result['tax_payable_at_lower_rate'].round(2).to_digits}\t(#{paye_result['tax_payable_at_lower_rate'].to_digits})"
puts "#{paye_result['taxable_at_higher_rate_amount'].to_digits} @ 40%\t #{paye_result['tax_payable_at_higher_rate'].round(2).to_digits}\t(#{paye_result['tax_payable_at_higher_rate'].to_digits})"
puts "\t\t= #{paye_result['paye_pre_tax_credits_deduction'].round(2).to_digits}\t(#{paye_result['paye_pre_tax_credits_deduction'].to_digits})"
puts "\t\t- #{tax_credit.to_digits} (Monthly tax credit)"
puts ""
puts "TOTAL PAYE\t= #{paye_result['paye'].to_digits}"
pause unless !options.pause
# Calculate USC ##########################################################################
print_header "USC"
puz "Input for USC\t+ #{gross_income.to_digits}\t\t(Gross Income)", gross_income
puz "\t\t+ #{bik_total.to_digits}\t\t(Benefit In Kind)", bik_total
puz "\t\t+ #{espp_gain.to_digits}\t\t(ESPP Gain)", espp_gain
usc_input = gross_income + bik_total + espp_gain
puts "Total Input\t= #{usc_input.to_digits}"
puts ""
usc_result = calculate_usc usc_input, usc_point_five_percent_band, usc_two_percent_band, usc_four_point_five_percent_band
puts "#{usc_result['chargable_at_point_five'].to_digits} @ 0.5%\t #{usc_result['usc_payable_at_point_five'].round(2).to_digits}\t(#{usc_result['usc_payable_at_point_five'].to_digits})"
puts "#{usc_result['chargable_at_two'].to_digits} @ 2%\t #{usc_result['usc_payable_at_two'].round(2).to_digits}\t(#{usc_result['usc_payable_at_two'].to_digits})"
puts "#{usc_result['chargable_at_four_point_five'].to_digits} @ 4.5%\t #{usc_result['usc_payable_at_four_point_five'].round(2).to_digits}\t(#{usc_result['usc_payable_at_four_point_five'].to_digits})"
puts "#{usc_result['chargable_at_eight'].to_digits} @ 8%\t #{usc_result['usc_payable_at_eight'].round(2).to_digits}\t(#{usc_result['usc_payable_at_eight'].to_digits})"
puts ""
puts "TOTAL USC\t= #{usc_result['usc'].to_digits}"
pause unless !options.pause
# Calculate PRSI #########################################################################
print_header "PRSI"
puz "Input for PRSI\t+ #{gross_income.to_digits}\t\t(Gross Income)", gross_income
puz "\t\t+ #{bik_total.to_digits}\t\t(Benefit In Kind)", bik_total
puz "\t\t+ #{espp_gain.to_digits}\t\t(ESPP Gain)", espp_gain
prsi_input = gross_income + bik_total + espp_gain
puts "Total Input\t= #{prsi_input.to_digits}"
puts ""
total_prsi = (prsi_input * BigDecimal.new("0.04")).round(2)
puts "#{prsi_input.to_digits} @ 4% = #{total_prsi.to_digits}"
puts ""
puts "TOTAL PRSI\t= #{total_prsi.to_digits}"
pause unless !options.pause
# Calculate ESPP #########################################################################
if espp_contribution_percentage > 0
print_header "ESPP"
puz "Input for ESPP\t+ #{regular_salary.to_digits}\t(Regular Salary)", regular_salary
puz "\t\t+ #{extra_pay.to_digits}\t(Overtime/On-Call Pay)", extra_pay
puz "\t\t+ #{pli_bonus.to_digits}\t(PL&I Bonus)", pli_bonus
espp_input = regular_salary + extra_pay + pli_bonus
puts "Total Input\t= #{espp_input.to_digits}"
puts ""
espp = ((espp_input / 100) * espp_contribution_percentage).round(2)
puts "#{espp_input.to_digits} @ #{espp_contribution_percentage.to_digits}% = #{espp.to_digits}"
puts ""
puts "TOTAL ESPP CONTRIBUTION = #{espp.to_digits}"
else
espp = BigDecimal.new("0")
end
pause unless !options.pause
# Misc Deductions ########################################################################
print_header "Misc Deductions"
misc_deductions_total = print_and_total_hash misc_deductions_hash
puts ""
puts "TOTAL MISC DEDUCTIONS = #{misc_deductions_total.to_digits}"
pause unless !options.pause
# Net Pay ################################################################################
print_header "Net Pay"
puz "\t #{gross_income.to_digits}\t(Gross Income)", gross_income
puz "\t+ #{refund.to_digits}\t(Refund)", refund
puz "\t- #{cr_voucher_amount.to_digits}\t(Connected Recognition Voucher)", cr_voucher_amount
puz "\t- #{paye_result['paye'].to_digits}\t(PAYE)", paye_result['paye']
puz "\t- #{usc_result['usc'].to_digits}\t(USC)", usc_result['usc']
puz "\t- #{total_prsi.to_digits}\t(PRSI)", total_prsi
puz "\t- #{pension_contribution.to_digits}\t(Pension Contribution)", pension_contribution
puz "\t- #{espp.to_digits}\t(ESPP)", espp
puz "\t- #{misc_deductions_total.to_digits}\t(Misc Deductions)", misc_deductions_total
net_income = gross_income + refund - cr_voucher_amount - paye_result['paye'] - usc_result['usc'] - total_prsi - pension_contribution - espp - misc_deductions_total
puts "\t= #{net_income.to_digits}"
puts ""
puts "TOTAL NET INCOME = #{net_income.to_digits}"