Class: Osm::Term

Inherits:
Model show all
Defined in:
lib/osm/term.rb

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Model

#<, #<=, #>, #>=, #between?, #changed_attributes, configure, #reset_changed_attributes, #to_i

Constructor Details

#initialize ⇒ Object

Initialize a new Term

Parameters:

  • attributes (Hash) —

    The hash of attributes (see attributes for descriptions, use Symbol of attribute name as the key)




# File 'lib/osm/term.rb', line 183

Instance Attribute Details

#finish ⇒ Date

Returns when the term finishes.

Returns:

  • (Date) —

    when the term finishes



16
 
# File 'lib/osm/term.rb', line 16

attribute :id, :type => Integer

#id ⇒ Fixnum

Returns the id for the term.

Returns:

  • (Fixnum) —

    the id for the term



16
 
# File 'lib/osm/term.rb', line 16

attribute :id, :type => Integer

#name ⇒ Fixnum

Returns the name of the term.

Returns:

  • (Fixnum) —

    the name of the term



16
 
# File 'lib/osm/term.rb', line 16

attribute :id, :type => Integer

#section_id ⇒ Fixnum

Returns the section the term belongs to.

Returns:

  • (Fixnum) —

    the section the term belongs to



16
 
# File 'lib/osm/term.rb', line 16

attribute :id, :type => Integer

#start ⇒ Date

Returns when the term starts.

Returns:

  • (Date) —

    when the term starts



16
 
# File 'lib/osm/term.rb', line 16

attribute :id, :type => Integer

Class Method Details

.create(api, options = {}) ⇒ Boolean

Create a term in OSM

Parameters:

  • api (Osm::Api) —

    The api to use to make the request

  • options (Hash) (defaults to: {}) —

    • the configuration of the new term

    @option options [Osm::Section, Fixnum] :section (required) section or section_id to add the term to @option options [String] :name (required) the name for the term @option options [Date] :start (required) the date for the start of term @option options [Date] :finish (required) the date for the finish of term

Returns:

  • (Boolean) —

    if the operation suceeded or not

Raises:

  • (ArgumentError) 


130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/osm/term.rb', line 130

def self.create(api, options={})
  raise ArgumentError, ":section can't be nil" if options[:section].nil?
  raise ArgumentError, ":name can't be nil" if options[:name].nil?
  raise ArgumentError, ":start can't be nil" if options[:start].nil?
  raise ArgumentError, ":finish can't be nil" if options[:finish].nil?
  require_access_to_section(api, options[:section])

  api_data = {
    'term' => options[:name],
    'start' => options[:start].strftime(Osm::OSM_DATE_FORMAT),
    'end' => options[:finish].strftime(Osm::OSM_DATE_FORMAT),
    'termid' => '0'
  }

  data = api.perform_query("users.php?action=addTerm&sectionid=#{options[:section].to_i}", api_data)

  # The cached terms for the section will be out of date - remove them
  get_all(api, options).each do |term|
    cache_delete(api, ['term', term.id]) if term.section_id == section_id
  end
  cache_delete(api, ['terms', api.user_id])

  return data.is_a?(Hash) && data['terms'].is_a?(Hash)
end

.get(api, term_id, options = {}) ⇒ Object

Get a term

Parameters:

  • api (Osm::Api) —

    The api to use to make the request

  • term_id (Fixnum) —

    The id of the required term

Returns:

  • nil if an error occured or the user does not have access to that term

  • (Osm::Term) 


85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/osm/term.rb', line 85

def self.get(api, term_id, options={})
  cache_key = ['term', term_id]

  if !options[:no_cache] && cache_exist?(api, cache_key)
    term = cache_read(api, cache_key)
    return term if can_access_section?(api, term.section_id, options)
  end

  terms = get_all(api, options)
  return nil unless terms.is_a? Array

  terms.each do |term|
    if term.id == term_id
      return (can_access_section?(api, term.section_id, options) ? term : nil)
    end
  end
  return nil
end

.get_all(api, options = {}) ⇒ Array<Osm::Term>

Get the terms that the OSM user can access

Parameters:

  • api (Osm::Api) —

    The api to use to make the request

Returns:



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/osm/term.rb', line 37

def self.get_all(api, options={})
  cache_key = ['terms', api.user_id]

  if !options[:no_cache] && cache_exist?(api, cache_key)
    ids = cache_read(api, cache_key)
    return get_from_ids(api, ids, 'term', options, :get_all)
  end

  data = api.perform_query('api.php?action=getTerms')

  terms = Array.new
  ids = Array.new
  data.each_key do |key|
    data[key].each do |term_data|
      term = Osm::Term.new(
        :id => Osm::to_i_or_nil(term_data['termid']),
        :section_id => Osm::to_i_or_nil(term_data['sectionid']),
        :name => term_data['name'],
        :start => Osm::parse_date(term_data['startdate']),
        :finish => Osm::parse_date(term_data['enddate']),
      )
      terms.push term
      ids.push term.id
      cache_write(api, ['term', term.id], term)
    end
  end

  cache_write(api, cache_key, ids)
  return terms
end

.get_current_term_for_section(api, section, options = {}) ⇒ Osm::Term?

Get the current term for a given section

Parameters:

  • api (Osm::Api) —

    The api to use to make the request

  • section (Osm::Section, Fixnum, #to_i) —

    The section (or its ID) to get terms for

Returns:

  • (Osm::Term, nil) —

    The current term or nil if the user can not access that section

Raises:



110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/osm/term.rb', line 110

def self.get_current_term_for_section(api, section, options={})
  section_id = section.to_i
  terms = get_for_section(api, section_id, options)

  return nil if terms.nil?
  terms.each do |term|
    return term if term.current?
  end

  raise Osm::Error::NoCurrentTerm.new('There is no current term for the section.', section_id)
end

.get_for_section(api, section, options = {}) ⇒ Array<Osm::Term>?

Get the terms that the OSM user can access for a given section

Parameters:

  • api (Osm::Api) —

    The api to use to make the request

  • section (Fixnum) —

    The section (or its ID) of the section to get terms for

Returns:

  • (Array<Osm::Term>, nil) —

    An array of terms or nil if the user can not access that section



73
74
75
76
77
 
# File 'lib/osm/term.rb', line 73

def self.get_for_section(api, section, options={})
  require_access_to_section(api, section, options)
  section_id = section.to_i
  return get_all(api, options).select{ |term| term.section_id == section_id }
end

Instance Method Details

#<=>(another_term) ⇒ Object

Compare Term based on section_id, start then id



236
237
238
239
240
241
 
# File 'lib/osm/term.rb', line 236

def <=>(another_term)
  result = self.section_id <=> another_term.section_id
  result = self.start <=> another_term.start if result == 0
  result = self.id <=> another_term.id if result == 0
  return result
end

#after?(date) ⇒ Boolean

Determine if the term is completly after the passed date

Parameters:

  • date (Date)

Returns:

  • (Boolean) —

    if the term is completly after the passed date



199
200
201
202
 
# File 'lib/osm/term.rb', line 199

def after?(date)
  return false if start.nil?
  return start > date.to_date
end

#before?(date) ⇒ Boolean

Determine if the term is completly before the passed date

Parameters:

  • date (Date)

Returns:

  • (Boolean) —

    if the term is completly before the passed date



191
192
193
194
 
# File 'lib/osm/term.rb', line 191

def before?(date)
  return false if finish.nil?
  return finish < date.to_date
end

#contains_date?(date) ⇒ Boolean

Determine if the provided date is within the term

Parameters:

  • date (Date) —

    The date to test

Returns:

  • (Boolean) —

    if the term started before the date and finishes after the date



229
230
231
232
233
 
# File 'lib/osm/term.rb', line 229

def contains_date?(date)
  return false if start.nil?
  return false if finish.nil?
  return (start <= date) && (finish >= date)
end

#current? ⇒ Boolean

Determine if the term is current

Returns:

  • (Boolean) —

    if the term started before today and finishes after today



220
221
222
223
224
 
# File 'lib/osm/term.rb', line 220

def current?
  return false if start.nil?
  return false if finish.nil?
  return (start <= Date.today) && (finish >= Date.today)
end

#future? ⇒ Boolean

Determine if the term is in the future

Returns:

  • (Boolean) —

    if the term starts after today



206
207
208
209
 
# File 'lib/osm/term.rb', line 206

def future?
  return false if start.nil?
  return start > Date.today
end

#past? ⇒ Boolean

Determine if the term is in the past

Returns:

  • (Boolean) —

    if the term finished before today



213
214
215
216
 
# File 'lib/osm/term.rb', line 213

def past?
  return false if finish.nil?
  return finish < Date.today
end

#update(api) ⇒ Boolean

Update a term in OSM

Parameters:

  • api (Osm::Api) —

    The api to use to make the request

Returns:

  • (Boolean) —

    if the operation suceeded or not

Raises:



160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
 
# File 'lib/osm/term.rb', line 160

def update(api)
  raise Osm::ObjectIsInvalid, 'term is invalid' unless valid?
  require_access_to_section(api, section_id)

  data = api.perform_query("users.php?action=addTerm&sectionid=#{section_id}", {
    'term' => name,
    'start' => start.strftime(Osm::OSM_DATE_FORMAT),
    'end' => finish.strftime(Osm::OSM_DATE_FORMAT),
    'termid' => id
  })

  if data.is_a?(Hash) && data['terms'].is_a?(Hash)
    reset_changed_attributes
    # The cached term will be out of date - remove it
    cache_delete(api, ['term', id])
    return true
  else
    return false
  end
end