device-identifier 0.0.1

data/README.md

@@ -0,0 +1,206 @@
+# Device identifier models
+
+Models for device identifiers, e.g. MAC addresses and other identifiers for VoIP phones.
+
+Rationale:
+
+- Hard-phones have an Ethernet MAC address.
+- Soft-phones don't. They have/need some sort of identification string
+  (any sequence of bytes).
+- Both are device identifiers, with the MAC address being a sub-class.
+
+Author: Philipp Kempgen, [http://kempgen.net](http://kempgen.net)
+
+
+## Inheritance
+
+The class inheritance is as follows:
+
+- **`Base`**
+	
+	Base model class, providing validations etc.
+	
+	- **`BinaryAddress`**
+		
+		Model for a raw binary address.
+		
+		- **`DeviceIdentifier`**
+			
+			Model for a device identifier.
+			
+			- **`MacAddress`**
+				
+				Model for a MAC address.
+		
+		- **`MacAddressPartial`**
+			
+			Model for a partial MAC address.
+			
+			- **`MacAddressOui`**
+				
+				Model for the OUI (vendor part) of a MAC address.
+
+
+## Device identifiers
+
+There are 2 kinds of device identifiers: the generic `DeviceIdentifier` and the more specific `MacAddress`.
+
+Both support the methods in following (amongst others):
+
+- `bytes`
+	
+	The raw bytes.
+
+- `ascii( opts = nil )`
+	
+	An ASCII representation (hex format).
+
+- `to_s( opts = nil )`
+	
+	An ASCII representation (hex format).
+
+
+## Classes
+
+
+### `Base`
+
+Includes some `ActiveModel` mix-ins (`ActiveModel::Validations` etc.).
+
+Provides methods such as `valid?`.
+
+
+### `BinaryAddress`
+
+**Inheritance**:
+`Base` >
+`BinaryAddress`
+
+Model for a raw binary address.
+
+Includes the `::Comparable` mix-in.
+
+Class methods:
+
+- `self.from_raw( str )`
+	
+	Initializer. Creates a new object from a raw representation.
+
+- `self.from_hex( str )`
+	
+	Initializer. Creates a new object from a hex representation,
+	with or without "`:`" or "`-`" separators.
+
+Instance methods:
+
+- `bytes`
+	
+	The raw bytes.
+
+- `bytesize`
+	
+	The number of bytes.
+
+- `length`
+	
+	Alias for `bytesize`.
+
+- `ascii( opts = nil )`
+	
+	An ASCII representation (hex format).
+	
+	Default options are:
+		
+		{
+			:sep     => '',     # separator, typically ":" or "-" or ""
+			:upcase  => false,  # use uppercase?
+		}
+	
+	Returns `nil` if invalid.
+
+- `to_int`
+	
+	An integer representation.
+
+- `starts_with?( other )`
+	
+	Whether it starts with the other `BinaryAddress`.
+
+- `start_with?( other )`
+	
+	Alias for `starts_with?( other )`.
+
+
+### `DeviceIdentifier`
+
+**Inheritance**:
+`Base` >
+`BinaryAddress` >
+`DeviceIdentifier`
+
+Model for a device identifier.
+
+Validates that the raw address has a minimum length of 1 byte.
+
+
+### `MacAddress`
+
+**Inheritance**:
+`Base` >
+`BinaryAddress` >
+`DeviceIdentifier` >
+`MacAddress`
+
+Model for a MAC address.
+
+Instance methods:
+
+- `multicast?`
+	
+	If it's a multicast MAC address (integer value of first byte odd).
+
+- `null?`
+	
+	If it's a null address (all 6 bytes \x00: 00:00:00:00:00:00).
+
+- `pretty( opts = nil )`
+
+	A pretty ASCII representation (hex format).
+	
+	Default options are:
+		
+		{
+			:sep     => ':',    # separator, typically ":" or "-" or ""
+			:upcase  => true,   # use uppercase?
+		}
+	
+	The default options are the same as for the inherited `ascii` method, except that the separator is "`:`" instead of "".
+
+- `oui_raw`
+
+	The OUI (vendor) part (first 3 bytes) in raw format.
+
+
+### `MacAddressPartial`
+
+**Inheritance**:
+`Base` >
+`BinaryAddress` >
+`MacAddressPartial`
+
+Model for a partial MAC address.
+
+
+### `MacAddressOui`
+
+**Inheritance**:
+`Base` >
+`BinaryAddress` >
+`MacAddressPartial` >
+`MacAddressOui`
+
+Model for the OUI (vendor) part of a MAC address.
+
+Validates that the raw address has a length of 3 bytes.
+
+

data/lib/dev-id/base.rb

@@ -0,0 +1,59 @@
+require 'dev-id'
+require 'active_model'
+
+module ::DevId
+	
+	# @private
+	class BasicActiveModel
+		extend  ::ActiveModel::Naming
+		include ::ActiveModel::Validations
+		include ::ActiveModel::MassAssignmentSecurity
+		include ::ActiveModel::Conversion
+	#	extend  ::ActiveModel::Callbacks
+		
+		validate :before, :do_before_validation
+		
+		def initialize( attrs={} )
+			assign_attributes( attrs )
+		end
+		
+		# see `activerecord/lib/active_record/attribute_assignment.rb`
+		def assign_attributes( new_attributes, options={} )
+			return unless new_attributes.present?
+			
+			attributes = new_attributes.stringify_keys
+			
+			unless options[:without_protection]
+				attributes = sanitize_for_mass_assignment( attributes, options[:as] || :default )
+			end
+			
+			attributes.each { |k, v|
+				#setter_name = :"#{k}="
+				#send( setter_name, v )  if respond_to?( setter_name )
+				send( :"#{k}=", v )
+			}
+			
+			#self
+			nil
+		end
+		
+		def persisted?
+			false
+		end
+		
+		def do_before_validation
+			@errors.clear
+			before_validation()
+		end
+		
+		def before_validation
+			# override in sub-classes
+		end
+	end
+	
+	# @private
+	class Base < BasicActiveModel
+	end
+	
+end
+

data/lib/dev-id/binary_address.rb

@@ -0,0 +1,136 @@
+require 'dev-id/base'
+require 'scanf'
+
+module ::DevId
+	
+	# Model for a raw binary address.
+	#
+	class BinaryAddress < Base
+		
+		include ::Comparable
+		
+		# The raw address.
+		attr_accessor :raw
+		
+		def before_validation
+			if raw
+				raw = raw.to_s.force_encoding( ::Encoding::ASCII_8BIT )
+			end
+		end
+		
+		validates_presence_of :raw
+		
+		# Default options for conversion to ASCII in the `ascii`
+		# method.
+		DEFAULT_TO_ASCII_OPTS = {
+			:sep => '',  # typically ":" or "-" or ""
+			:upcase => false,
+		}.freeze
+		
+		def bytes
+			(raw || '').bytes
+		end
+		
+		def bytesize
+			(raw || '').bytesize
+		end
+		alias :length :bytesize
+		
+		# Construct a new instance from a raw string.
+		#
+		def self.from_raw( str )
+			addr = self.new( :raw => str )
+		end
+		
+		# Construct a new instance from a hex string.
+		#
+		def self.from_hex( str )
+			addr = self.new()
+			str = str.to_s.dup
+			str.force_encoding( ::Encoding::ASCII_8BIT )
+			str.gsub!( /[:\-]/, '' )
+			raw = str.scanf( '%2X' ) { |x,| x.to_i.chr( ::Encoding::ASCII_8BIT ) }.
+				join( ''.force_encoding( ::Encoding::ASCII_8BIT ) )
+			addr.raw = raw
+			return addr
+		end
+		
+		# ASCII representation.
+		#
+		def ascii( opts = nil )
+			return nil  if ! valid?
+			opts = DEFAULT_TO_ASCII_OPTS.merge( opts || {} )
+			return self.bytes.map{ |b| (opts[:upcase] ? '%02X' : '%02x') % [b] }.join( opts[:sep] )
+		end
+		
+		# `to_s` is an alias for `ascii`.
+		#
+		def to_s( opts = nil )
+			ascii( opts )
+		end
+		
+		# If `other` is of the same class, compares the raw values.
+		# Returns `nil` unless `self` and `other` have a raw address.
+		# Returns `nil` if `other` is an instance of a different class.
+		#
+		def <=>( other )
+			return nil  unless other.kind_of?( BinaryAddress )
+			return nil  unless (self.raw && other.raw)
+			return self.raw <=> other.raw  #OPTIMIZE ?
+		end
+		
+		# `to_int` helps with `include?`.
+		#
+		# http://rhnh.net/2009/08/03/range-include-in-ruby-1-9
+		#
+		# Note: ActiveSupport (as of Version 3.2.1) messes with
+		# Range#include?() (in
+		# `lib/active_support/core_ext/range/include_range.rb`)
+		# even though they say "The native Range#include? behavior
+		# is untouched.", so you will have to use Range#cover?()
+		# instead.
+		#
+		def to_int
+			v = 0
+			self.bytes.to_a.reverse.each_with_index { |b,i|
+				vb = b
+				i.times {
+					vb = vb << 8
+				}
+				v += vb
+			}
+			return v
+		end
+		
+		def ==( other )
+			return super  unless other.kind_of?( BinaryAddress )
+			return false  unless (self.raw && other.raw)
+			return self.raw == other.raw
+		end
+		alias :'eql?' :'=='
+		
+		def starts_with?( other )
+			return super  unless other.kind_of?( BinaryAddress )
+			return false  unless (self.raw && other.raw)
+			return self.raw.start_with?( other.raw )
+		end
+		alias :'start_with?' :'starts_with?'
+		
+		def =~( other )
+			return super  unless other.kind_of?( BinaryAddress )
+			return false  unless (self.raw && other.raw)
+			return (self.bytesize > other.bytesize) ?
+				self .raw.start_with?( other.raw ) :
+				other.raw.start_with?( self .raw )
+		end
+		alias :'eql?' :'=='
+		
+		def !~( other )
+			return ! (self =~ other)
+		end
+		
+		#TODO getbyte, [], byteslice
+		
+	end
+end
+

data/lib/dev-id/device_identifier.rb

@@ -0,0 +1,14 @@
+require 'dev-id/binary_address'
+require 'scanf'
+
+module ::DevId
+	
+	# Model for a device identifier.
+	#
+	class DeviceIdentifier < BinaryAddress
+		
+		validates_length_of   :raw, :minimum => 1, :allow_blank => false, :allow_nil => true
+		
+	end
+end
+

data/lib/dev-id/mac_address.rb

@@ -0,0 +1,80 @@
+require 'dev-id/device_identifier'
+require 'dev-id/binary_address'
+
+module ::DevId
+	
+	# Model for a MAC address.
+	#
+	# 6 bytes.
+	#
+	class MacAddress < DeviceIdentifier
+		
+		validates_length_of :raw, :is => 6
+		
+		# Default options for conversion to ASCII in the `pretty`
+		# method.
+		DEFAULT_TO_PRETTY_OPTS = {
+			:sep => ':',  # typically ":" or "-" or ""
+			:upcase => true,
+		}.freeze
+		
+		# Whether the MAC address is a multicast address.
+		#
+		def multicast?
+			return nil  if ! valid?
+			return (raw.getbyte(0).to_i % 2) != 0
+		end
+		
+		# Whether the MAC address is the "null" address (6 NULL
+		# bytes).
+		#
+		def null?
+			return nil  if ! valid?
+			return raw == (?\0.force_encoding( ::Encoding::ASCII_8BIT ) * 6)
+		end
+		
+		# Pretty ASCII representation.
+		#
+		def pretty( opts = nil )
+			return nil  if ! valid?
+			opts = DEFAULT_TO_PRETTY_OPTS.merge( opts || {} )
+			return ascii( opts )
+		end
+		
+		# The OUI (vendor part) as a raw string.
+		#
+		def oui_raw
+			return nil  if ! valid?
+			return raw.byteslice( 0, 3 )
+		end
+		
+		# `to_s` is an alias for `pretty`.
+		#
+		def to_s( opts = nil )
+			pretty( opts )
+		end
+		
+	end
+end
+
+module ::DevId
+	
+	# Model for a partial MAC address.
+	#
+	class MacAddressPartial < BinaryAddress
+	end
+end
+
+module ::DevId
+	
+	# Model for the OUI (vendor part) of a MAC address.
+	#
+	# 3 bytes.
+	#
+	class MacAddressOui < MacAddressPartial
+		
+		validates_length_of :raw, :is => 3
+		
+	end
+end
+

data/lib/dev-id/version.rb

@@ -0,0 +1,13 @@
+# This file should not require anything, as it's loaded in the
+# `*.gemspec` file.
+
+module ::DevId
+	
+	# The version of this Gem.
+	VERSION = [ 0, 0, 1 ].freeze
+	
+	# The version of this Gem as a string.
+	VERSION_STR = VERSION.map(& :to_s).join('.').freeze
+	
+end
+

data/lib/dev-id.rb

@@ -0,0 +1,9 @@
+# `DevId` namespace
+module ::DevId
+end
+
+require 'dev-id/base'
+require 'dev-id/binary_address'
+require 'dev-id/device_identifier'
+require 'dev-id/mac_address'
+

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: device-identifier
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Philipp Kempgen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-04-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.2'
+description: Models for device identifiers, e.g. MAC addresses for hardware clients
+  and arbitrary identifier strings for software clients.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/dev-id/base.rb
+- lib/dev-id/binary_address.rb
+- lib/dev-id/device_identifier.rb
+- lib/dev-id/mac_address.rb
+- lib/dev-id/version.rb
+- lib/dev-id.rb
+- README.md
+homepage: https://github.com/philipp-kempgen/device-identifier
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: Models for device identifiers.
+test_files: []
+has_rdoc: