ALD 0.0.1 → 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 445063876e8fc4783ef501709c428536506a6dd2
+  data.tar.gz: dada4d739c9e78df7e9d5137ba84fe041fe97303
+SHA512:
+  metadata.gz: bda2ebf48adbcf07d5a9e8b7daea6f82d46d5d4e9d26bf2863b2e9fd73c41c0be14e4836b22b655ad3aebef1cb461129f31f8f67e380fbca9eb173a17a1aed30
+  data.tar.gz: e4d7807db45aba618920471ae6406193e268ebfdd905bd2bb4f51b237c6538589e8740231c4efec5818690fc250c81ed26797b76203077a1e8fb842250dbd22f

data/lib/ALD.rb

@@ -1,8 +1,9 @@
-require 'ALD/package'
-require 'ALD/package_generator'
-require 'ALD/definition'
-require 'ALD/definition_generator.rb'
-require 'ALD/exceptions'
+require_relative 'ALD/package'
+require_relative 'ALD/package_generator'
+require_relative 'ALD/definition'
+require_relative 'ALD/definition_generator.rb'
+require_relative 'ALD/exceptions'
+require_relative 'ALD/api'
 
 module ALD
 end

data/lib/ALD/definition.rb

@@ -1,16 +1,25 @@
 require 'nokogiri'
-require 'ALD/exceptions'
+require_relative 'exceptions'
 
 module ALD
+  # Public: Access information in ALD package definition files.
   class Definition
+    # Internal: Path to the file containing the XML Schema Definition used for
+    # definition validation.
     SCHEMA_FILE = "#{File.dirname(__FILE__)}/schema.xsd"
 
+    # Internal: The XML namespace used by the definitions.
     XML_NAMESPACE = 'ald://package/schema/2014'
 
+    # Internal: The XML Schema instance used for validation
+    #
+    # Returns the Nokogiri::XML::Schema instance representing ::SCHEMA_FILE.
     def self.schema
       @schema ||= Nokogiri::XML::Schema(File.read(SCHEMA_FILE))
     end
 
+    # Internal: The array of attributes which are defined in the root element
+    # of a definition. Each of these gets a dynamically defined method.
     TOPLEVEL_ATTRIBUTES = %w[
       id
       name
@@ -19,12 +28,74 @@ module ALD
       summary
     ]
 
+    # Public: Gets the ID of the item to be represented by this definition.
+    #
+    # Examples
+    #
+    #   puts "Item ID: #{definition.id}"
+    #
+    # Signature
+    #
+    #   id()
+
+    # Public: Gets the name of the item defined by this definition.
+    #
+    # Examples
+    #
+    #   puts "The item is called '#{definition.name}'"
+    #
+    # Signature
+    #
+    #   name()
+
+    # Public: Gets the semver version of this definition's item.
+    #
+    # Examples
+    #
+    #   puts "#{definition.name} v#{definition.version}"
+    #
+    # Signature
+    #
+    #   version()
+
+    # Public: Gets the type of item this definition represents.
+    #
+    # Examples
+    #
+    #   puts "Item type is #{definition.type}"
+    #
+    # Signature
+    #
+    #   type()
+
+    # Public: Gets the item's summary text.
+    #
+    # Examples
+    #
+    #   puts "\n#{definition.summary}\n"
+    #
+    # Signature
+    #
+    #   summary()
+
     TOPLEVEL_ATTRIBUTES.each do |attr|
       define_method attr.to_sym do
         @document.xpath("//@ald:#{attr}", 'ald' => XML_NAMESPACE)[0].value
       end
     end
 
+    # Public: Open a new definition file for analysis.
+    #
+    # source - the source to read the definition from. This can be a
+    #          Nokogiri::XML::Document, a String or any object that responds to
+    #          #read and #close.
+    #
+    # Examples
+    #
+    #   definition = ALD::Definition.new('/path/to/def.xml')
+    #
+    # Raises ALD::InvalidDefinitionError if the supplied source is not a valid
+    # ALD package definition.
     def initialize(source)
       if source.is_a? Nokogiri::XML::Document
         @document = source
@@ -35,35 +106,76 @@ module ALD
       raise InvalidDefinitionError unless valid?
     end
 
+    # Public: Get the defined item's description.
+    #
+    # Returns the description String.
     def description
       @document.xpath("//ald:description", 'ald' => XML_NAMESPACE)[0].text
     end
 
+    # Public: Get the defined item's tags.
+    #
+    # Examples
+    #
+    #   definition.tags.each { |tag| puts " - #{tag}" }
+    #
+    # Returns the Array of Strings that the item is tagged with.
     def tags
       @document.xpath("//ald:tags/ald:tag/@ald:name", 'ald' => XML_NAMESPACE).map { |tag| tag.value }
     end
 
+    # Public: Get the item's authors information
+    #
+    # Examples
+    #
+    #   definition.authors.each do |author|
+    #     puts "Author: #{author['name']}"
+    #     puts "\tUser name: #{author['user-name'] || '(unknown)'}"
+    #     puts "\tHomepage:  #{author['homepage']  || '(unknown)'}"
+    #     puts "\tEmail:     #{author['email']     || '(unknown)'}"
+    #   end
+    #
+    # Returns an Array of Hashes, where each Hash has the 'name' key and *may*
+    # also have 'user-name', 'homepage' and 'email' keys.
     def authors
       attribute_hash '//ald:authors/ald:author', %w[name user-name homepage email]
     end
 
+    # Public: Gets additional links this definition references
+    #
+    # Returns an Array of Hashes, where each Hash has the keys 'name', 'href'
+    # and 'description'-
     def links
      attribute_hash '//ald:links/ald:link', %w[name description href]
     end
 
+    # Internal: Check if the definition is valid.
+    # Library consumers need not call this, as ::new already does.
+    #
+    # Returns true, if the definition is valid according to the schema, false
+    # otherwise.
     def valid?
       Definition.schema.valid?(@document)
     end
 
+    # Public: Get the XML string representing the definition
     def to_s
       @document.to_s
     end
 
     private
 
+    # Internal: Get an Array of attribute Hashes from a list of elements in the
+    # definition.
+    #
+    # xpath - the XPath String pointing to the XML elements in the definition
+    # keys  - the Array of keys to retrieve from the elements
+    #
+    # Returns an Array of Hashes, where each Hash has all those of the given
+    # keys that were actual attributes on the relevant element.
     def attribute_hash(xpath, keys)
       @document.xpath(xpath, 'ald' => XML_NAMESPACE).map do |e|
-        Hash[keys.map { |k| e.attribute_with_ns(k, XML_NAMESPACE) }.reject(&:nil?).map { |a| [a.node_name, a.value] }]
+        Hash[keys.map { |k| e.attribute_with_ns(k, XML_NAMESPACE) }.compact.map { |a| [a.node_name, a.value] }]
       end
     end
   end

data/lib/ALD/exceptions.rb

@@ -7,4 +7,21 @@ module ALD
 
   class InvalidDefinitionError < StandardError
   end
+
+  class API
+    class RequestError < StandardError
+    end
+
+    class AuthenticationError < RequestError
+    end
+
+    class UnsupportedAuthMethodError < AuthenticationError
+    end
+
+    class NoAuthError < AuthenticationError
+    end
+
+    class InvalidAuthError < AuthenticationError
+    end
+  end
 end

data/lib/ALD/package.rb

@@ -1,22 +1,29 @@
 require 'zip'
-require 'ALD/definition'
-require 'ALD/exceptions'
+require_relative 'definition'
+require_relative 'exceptions'
 
 module ALD
-  # Represents an ALD package file containing an app or library and its definition
+  # Public: Represents an ALD package file containing an app or library and its
+  # definition.
   class Package
 
-    # The rubyzip Zip::File object containing the data
+    # Internal: The rubyzip Zip::File object containing the data.
     attr_reader :archive
 
-    # The ALD::Definition instance representing the definition contained in the package
+    # Public: The ALD::Definition instance representing the definition contained
+    # in the package. Use this to extract all the information on the package.
     attr_reader :definition
 
-    # Opens a new ALD package file
+    # Public: Opens a new ALD package file.
     #
-    # file - a Zip::File instance or the path to the file
+    # file - a String representing the path to the file or a Zip::File instance
     #
     # Returns a new ALD::Package instance representing the package file
+    #
+    # Raises ALD::NoDefinitionError if the package contains no definition file.
+    #
+    # Raises ALD::InvalidPackageError if the package is not valid according to
+    # its definition.
     def initialize(file)
       if file.is_a? Zip::File
         @archive = file
@@ -30,27 +37,35 @@ module ALD
       @definition = Definition.new(def_entry.get_input_stream)
       raise InvalidPackageError, 'The given ZIP file is not a valid ALD archive!' unless Package.valid?(@archive, @definition)
 
-      # file access
+      # todo: file access
     end
 
-    # Closes a no longer required package
+    # Public: Closes a no longer required package. While this method has little
+    # effect for now, calling it should be considered best practice and ensures
+    # forward-compatibility.
+    #
+    # Returns nothing.
     def close
       @archive.close
     end
 
-    # Alias for new
+    # Public: Alias for ::new
     def self.open(file)
       new(file)
     end
 
-    # Tests if a given archive is a valid ALD package
+    # Public: Tests if a given archive is a valid ALD package. Although part of
+    # the public API, most library consumers will not need to call it, as it is
+    # already called by ::new.
+    #
+    # Not yet implemented.
     #
-    # file - a Zip::File instance for the package
+    # file       - a Zip::File instance for the package
     # definition - an ALD::Definition instance the package must meet
     #
     # Returns true if it is valid, false otherwise
     def self.valid?(file, definition)
-      true
+      true # todo
     end
   end
 end

data/lib/ALD/package_generator.rb

@@ -1,7 +1,7 @@
-require 'ALD/definition'
-require 'ALD/definition_generator'
-require 'ALD/package'
-require 'ALD/exceptions'
+require_relative 'definition'
+require_relative 'definition_generator'
+require_relative 'package'
+require_relative 'exceptions'
 
 module ALD
   class Package

metadata

@@ -1,8 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ALD
 version: !ruby/object:Gem::Version
-  version: 0.0.1
-  prerelease: 
+  version: 0.1.0
 platform: ruby
 authors:
 - maul.esel
@@ -14,7 +13,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: rubyzip
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -22,7 +20,6 @@ dependencies:
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -30,7 +27,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -38,27 +34,94 @@ dependencies:
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
         version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: net-http-digest_auth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: semantic
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.17'
 description: A gem containing helpers for the ALD API, the ALD package format and
   ALD package definitions.
 email: 
@@ -76,26 +139,25 @@ files:
 homepage: https://github.com/Library-Distribution/ALD.rb
 licenses:
 - MIT
+metadata: {}
 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
+rubygems_version: 2.0.3
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: Utility gem for the ALD protocol
 test_files: []