Class: LUSI::API::Calendar::Year

Inherits:
LUSI::API::Core::Code show all
Extended by:
LUSI::API::Core::Util
Defined in:
lib/lusi_api/calendar.rb

Overview

Represents an academic year in the LUSI API

Instance Attribute Summary collapse

Attributes inherited from LUSI::API::Core::BasicCode

#description, #identity

Class Method Summary collapse

Instance Method Summary collapse

Methods included from LUSI::API::Core::Util

lusi_year, lusi_year_identity

Constructor Details

#initialize(xml = nil, lookup = nil, full_year: nil, **kwargs) ⇒ void

Initialises a new Year instance

Parameters:

  • full_year (String, nil) (defaults to: nil) —

    the full text description of the academic year



150
151
152
153
154
155
 
# File 'lib/lusi_api/calendar.rb', line 150

def initialize(xml = nil, lookup = nil, full_year: nil, **kwargs)
  super(xml, lookup, **kwargs)
  self.full_year = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:FullYear', full_year)
  # Store the lookup service for year arithmetic operations
  self.lookup = lookup
end

Instance Attribute Details

#full_year ⇒ String?

Returns the full text description of the academic year.

Returns:

  • (String, nil) —

    the full text description of the academic year



99
100
101
 
# File 'lib/lusi_api/calendar.rb', line 99

def full_year
  @full_year
end

#lookup ⇒ LUSI::API::Core::Lookup::LookupService?

Returns the lookup service for object resolution.

Returns:



103
104
105
 
# File 'lib/lusi_api/calendar.rb', line 103

def lookup
  @lookup
end

Class Method Details

.get_current_academic_year(api = nil, lookup = nil) {|obj| ... } ⇒ LUSI::API::Calendar::Year

Returns a Year instance for the current academic year

Parameters:

Yields:

  • (obj) —

    Passes the Year instance to the block

Yield Parameters:

Returns:



111
112
113
114
115
116
 
# File 'lib/lusi_api/calendar.rb', line 111

def self.get_current_academic_year(api = nil, lookup = nil)
  xml = api.call('LUSIReference', 'General.asmx', 'GetCurrentAcademicYear')
  obj = new(LUSI::API::Core::XML.xml_at(xml, 'xmlns:Year'), lookup)
  yield(obj) if block_given?
  obj
end

.get_instance(api = nil, lookup = nil, *years, use_lookup: true, **kwargs) {|obj| ... } ⇒ Array<LUSI::API::Calendar::Year>?

Returns selected or all defined year instances Remaining positional parameters are years or year identities of the required years

Parameters:

  • api (LUSI::API::Core::API) (defaults to: nil) —

    the LUSI API instance

  • lookup (LUSI::API::Core::Lookup::LookupService, nil) (defaults to: nil) —

    the lookup service for object resolution

  • use_lookup (Boolean) (defaults to: true) —

    if true, use the lookup service to identify instances before trying the API

Yields:

  • (obj) —

    Passes the Year instance to the block

Yield Parameters:

Returns:



126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/lusi_api/calendar.rb', line 126

def self.get_instance(api = nil, lookup = nil, *years, use_lookup: true, **kwargs)
  results = nil
  # Search the lookup service if required
  if lookup && use_lookup
    year_lookup = lookup.service(:year)
    results = year_lookup.values if year_lookup
  end
  # Search the API if required
  results = super(api, lookup, 'LUSIReference', 'General.asmx', 'GetYears', 'xmlns:Year') if results.nil?
  # Return the results
  if results.nil? || years.nil? || years.empty?
    # No results or no filtering required
    results
  else
    # Return the year instances for the specified years
    years = years.map { |year| lusi_year_identity(year) }
    results.select { |result| years.include?(result.identity) }
  end
end

Instance Method Details

#+(years = 0) ⇒ LUSI::API::Calendar::Year

Returns the year instance n years after this one

Parameters:

  • years (Integer) (defaults to: 0) —

    the number of years to add to the instance’s year

Returns:



160
161
162
 
# File 'lib/lusi_api/calendar.rb', line 160

def +(years = 0)
  self.offset(years)
end

#-(years = 0) ⇒ LUSI::API::Calendar::Year

Returns the year instance n years before this one

Parameters:

  • years (Integer) (defaults to: 0) —

    the number of years to subtract from the instance’s year

Returns:



167
168
169
 
# File 'lib/lusi_api/calendar.rb', line 167

def -(years = 0)
  self.offset(-years)
end

#next(count = 1) ⇒ LUSI::API::Calendar::Year

Returns the year instance immediately following this one

Returns:



173
174
175
176
177
178
179
180
181
182
 
# File 'lib/lusi_api/calendar.rb', line 173

def next(count = 1)
  count = count.to_i
  if count == 1
    self.offset(1)
  else
    result = []
    (1..count).each { |offset| result.push(self.offset(offset)) }
    result
  end
end

#offset(years = 0) ⇒ LUSI::API::Calendar::Year

Returns the year instance n years after/before this one

Parameters:

  • years (Integer) (defaults to: 0) —

    the number of years to add to the instance’s year

Returns:



187
188
189
190
 
# File 'lib/lusi_api/calendar.rb', line 187

def offset(years = 0)
  return self if years == 0
  year = self.class.lusi_year(self, self.lookup, as_instance: true, offset: years)
end

#previous(count = 1) ⇒ LUSI::API::Calendar::Year

Returns the year instance immediately preceding this one

Returns:



194
195
196
197
198
199
200
201
202
203
 
# File 'lib/lusi_api/calendar.rb', line 194

def previous(count = 1)
  count = count.to_i
  if count == 1
    self.offset(-1)
  else
    result = []
    (1..count).each { |offset| result.push(self.offset(-offset)) }
    result
  end
end

#range(from = nil, to = nil) ⇒ Array<LUSI::API::Calendar::Year>

Returns a list of year instances around (immediately preceding and following) this one

Parameters:

  • from (Integer, Range) (defaults to: nil) —

    the starting offset relative to the current year

  • to (Integer) (defaults to: nil) —

    the ending offset relative to the current year

Returns:



209
210
211
212
213
214
 
# File 'lib/lusi_api/calendar.rb', line 209

def range(from = nil, to = nil)
  from = (from..to) unless from.is_a?(Range)
  result = []
  from.each { |offset| result.push(self.offset(offset)) }
  result
end

#to_s ⇒ String

Returns a string representation of the Year instance

Returns:

  • (String) —

    the string representation of the Year instance



218
219
220
 
# File 'lib/lusi_api/calendar.rb', line 218

def to_s
  self.full_year
end