From 475e0334f7ad3242e09668b2b75a8f9c40ad6b77 Mon Sep 17 00:00:00 2001 From: Josh Holtrop Date: Mon, 12 Aug 2013 22:57:57 -0400 Subject: [PATCH] add some documentation --- lib/gnucash.rb | 5 +++++ lib/gnucash/account.rb | 21 +++++++++++++++++++++ lib/gnucash/account_transaction.rb | 9 +++++++++ lib/gnucash/book.rb | 24 ++++++++++++++++++++++++ lib/gnucash/transaction.rb | 14 +++++++++++++- lib/gnucash/value.rb | 16 ++++++++++++++++ lib/gnucash/version.rb | 1 + 7 files changed, 89 insertions(+), 1 deletion(-) diff --git a/lib/gnucash.rb b/lib/gnucash.rb index cb0a8d0..c4af062 100644 --- a/lib/gnucash.rb +++ b/lib/gnucash.rb @@ -5,7 +5,12 @@ require "gnucash/transaction" require "gnucash/value" require "gnucash/version" +# Namespace module for gnucash gem functionality module Gnucash + # Open a GnuCash book from file. + # The file can be either a plain-text XML file or a gzipped XML file. + # === Arguments + # +fname+ _String_:: Name of the file to open. def self.open(fname) Book.new(fname) end diff --git a/lib/gnucash/account.rb b/lib/gnucash/account.rb index 9aecc1e..0251371 100644 --- a/lib/gnucash/account.rb +++ b/lib/gnucash/account.rb @@ -1,10 +1,23 @@ module Gnucash + # Represent a GnuCash account object class Account + # _String_: The name of the account (unqualified) attr_accessor :name + + # _String_: The account type (such as "EXPENSE") attr_accessor :type + + # _String_: The GUID of the account attr_accessor :id + + # _Array_: List of _AccountTransaction_ transactions associated with this + # account. attr_accessor :transactions + # Create an Account object. + # === Arguments + # +book+ _Book_:: The Gnucash::Book containing the account + # +node+ _Nokogiri::XML::Node_:: Nokogiri XML node def initialize(book, node) @book = book @node = node @@ -17,6 +30,7 @@ module Gnucash @balances = [] end + # Return the fully qualified account name def full_name prefix = "" if @parent_id @@ -28,10 +42,13 @@ module Gnucash prefix + name end + # Internal method used to associate a transaction with the account def add_transaction(act_txn) @transactions << act_txn end + # Internal method used to complete initialization of the Account after + # all transactions have been associated with it. def finalize @transactions.sort! { |a, b| a.date <=> b.date } balance = Value.new(0) @@ -44,11 +61,15 @@ module Gnucash end end + # Return the final balance of the account as a _Gnucash::Value_ def final_balance return Value.new(0) unless @balances.size > 0 @balances.last[:value] end + # Return the balance of the account as of the date given as a + # _Gnucash::Value_. Transactions that occur on the given date are included + # in the returned balance. def balance_on(date) return Value.new(0) unless @balances.size > 0 return Value.new(0) if @balances.first[:date] > date diff --git a/lib/gnucash/account_transaction.rb b/lib/gnucash/account_transaction.rb index 32249b6..5c240a0 100644 --- a/lib/gnucash/account_transaction.rb +++ b/lib/gnucash/account_transaction.rb @@ -1,12 +1,21 @@ module Gnucash + # Class to link a transaction object to an Account. class AccountTransaction + # _Gnucash::Value_: The transaction value for the linked account attr_accessor :value + # Construct an AccountTransaction object. + # This method is used internally when building a Transaction object. + # === Arguments + # +real_txn+ _Gnucash::Transaction_:: The linked Transaction object + # +value+ _Gnucash::Value_:: + # The value of the Transaction split for this account def initialize(real_txn, value) @real_txn = real_txn @value = value end + # Pass through any missing method calls to the linked Transaction object def method_missing(*args) @real_txn.send(*args) end diff --git a/lib/gnucash/book.rb b/lib/gnucash/book.rb index a7512c3..2b26a7f 100644 --- a/lib/gnucash/book.rb +++ b/lib/gnucash/book.rb @@ -2,12 +2,24 @@ require "zlib" require "nokogiri" module Gnucash + # Represent a GnuCash Book class Book + # _Array_ of _Gnucash::Account_ objects in the book attr_accessor :accounts + + # _Array_ of _Gnucash::Transaction_ objects in the book attr_accessor :transactions + + # _String_ in "YYYY-MM-DD" format of the first transaction in the book attr_accessor :start_date + + # _String_ in "YYYY-MM-DD" format of the last transaction in the book attr_accessor :end_date + # Construct a Book object. + # Normally called internally by Gnucash.open() + # === Arguments + # +fname+ _String_:: The file name of the GnuCash file to open. def initialize(fname) begin @ng = Nokogiri.XML(Zlib::GzipReader.open(fname).read) @@ -24,10 +36,22 @@ module Gnucash finalize end + # Return a handle to the Account object that has the given GUID. + # === Arguments + # +id+ _String_:: GUID + # === Return + # _Gnucash::Account_ or +nil+ def find_account_by_id(id) @accounts.find { |a| a.id == id } end + # Return a handle to the Account object that has the given fully-qualified + # name. + # === Arguments + # +full_name+ _String_:: + # Fully-qualified account name (ex: "Expenses::Auto::Gas") + # === Return + # _Gnucash::Account_ or +nil+ def find_account_by_full_name(full_name) @accounts.find { |a| a.full_name == full_name } end diff --git a/lib/gnucash/transaction.rb b/lib/gnucash/transaction.rb index 633bf2f..e5c8670 100644 --- a/lib/gnucash/transaction.rb +++ b/lib/gnucash/transaction.rb @@ -1,10 +1,22 @@ module Gnucash + # Represent a GnuCash transaction. + # Transactions have multiple splits with individual values. + # Splits are created as AccountTransaction objects which are associated + # with an individual account. class Transaction + # _String_: The date of the transaction, in ISO format ("YYYY-MM-DD") attr_accessor :date - attr_accessor :value + + # _String_: The GUID of the transaction attr_accessor :id + + # _String_: The description of the transaction attr_accessor :description + # Create a new Transaction object + # === Arguments + # +book+ _Book_:: The Gnucash::Book containing the transaction + # +node+ _Nokogiri::XML::Node_:: Nokogiri XML node def initialize(book, node) @book = book @node = node diff --git a/lib/gnucash/value.rb b/lib/gnucash/value.rb index 14a66bb..57cb978 100644 --- a/lib/gnucash/value.rb +++ b/lib/gnucash/value.rb @@ -1,13 +1,24 @@ module Gnucash + # Represent a currency value as an integer so that integer math can be used + # for accuracy in computations. class Value include Comparable + # _Fixnum_:: The raw, undivided integer value attr_accessor :val + # Create a new Value object with value 0 def self.zero Value.new(0) end + # Construct a Value object + # === Arguments + # +val+ _String_ or _Fixnum_:: + # Either a _String_ in the form "1234/100" or an integer containing the + # raw value + # +div+ _Fixnum_:: + # The divisor value to use (when +val+ is given as a _Fixnum_) def initialize(val, div = 100) if val.is_a?(String) if val =~ /^(-?\d+)\/(\d+)$/ @@ -24,22 +35,27 @@ module Gnucash end end + # Add two Value objects def +(other) Value.new(@val + other.val) end + # Subtract two Value objects def -(other) Value.new(@val - other.val) end + # Represent the Value as a string (two decimal places) def to_s sprintf("%.02f", to_f) end + # Convert the Value to a Float def to_f @val / @div.to_f end + # Compare two Value objects def <=>(other) @val <=> other.val end diff --git a/lib/gnucash/version.rb b/lib/gnucash/version.rb index 3d44558..b38749c 100644 --- a/lib/gnucash/version.rb +++ b/lib/gnucash/version.rb @@ -1,3 +1,4 @@ module Gnucash + # gem version VERSION = "0.0.1" end