Class: Osm::Term

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

Constant Summary collapse

SORT_BY = 
[:section_id, :start, :id]

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 184

Instance Attribute Details

#finish ⇒ Date

Returns when the term finishes.

Returns:

  • (Date) —

    when the term finishes



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

attribute :id, :type => Integer

#id ⇒ Fixnum

Returns the id for the term.

Returns:

  • (Fixnum) —

    the id for the term



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

attribute :id, :type => Integer

#name ⇒ Fixnum

Returns the name of the term.

Returns:

  • (Fixnum) —

    the name of the term



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

attribute :id, :type => Integer

#section_id ⇒ Fixnum

Returns the section the term belongs to.

Returns:

  • (Fixnum) —

    the section the term belongs to



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

attribute :id, :type => Integer

#start ⇒ Date

Returns when the term starts.

Returns:

  • (Date) —

    when the term starts



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

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) 


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

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) 


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

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:



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
67
 
# File 'lib/osm/term.rb', line 38

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:



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

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



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

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

#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



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

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



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

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



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

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



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

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



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

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



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

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:



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

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