p4_web_api_client 2014.2.0.pre1

data/lib/p4_web_api_client/errors/perforce_problem.rb

@@ -0,0 +1,25 @@
+module P4WebApiClient
+  module Errors
+    # It's likely that many 'unknown server errors' are actually errors from
+    # the Perforce server. This exception allows your client code to inspect
+    # the returned information to **potentially** handle issues the API code
+    # was unable to deal with. This can happen in cases of funky Perforce
+    # server configurations.
+    #
+    # Expect at least one message describing the problem. Each message contains
+    # 3 attributes: 'MessageCode', 'MessageSeverity', and 'MessageText'. You
+    # probably should only use the message code for any error handling logic,
+    # reserving the other fields for diagnostic usage.
+    class PerforceProblem < Exception
+      attr_accessor :messages
+
+      def initialize(messages)
+        @messages = messages
+      end
+
+      def to_s
+        "PerforceProblem<@messages:[#{@messages}]>"
+      end
+    end
+  end
+end

data/lib/p4_web_api_client/errors/resource_not_found.rb

@@ -0,0 +1,10 @@
+module P4WebApiClient
+  module Errors
+    # This is an unlikely exception case, actually. In some cases (not all) if
+    # a resource is to be edited, and it doesn't exist, you may get this error.
+    # But most of the time your code should probably consider this a problem
+    # in your client logic, and likely not handle it directly.
+    class ResourceNotFound < Exception
+    end
+  end
+end

data/lib/p4_web_api_client/errors/server_error.rb

@@ -0,0 +1,9 @@
+module P4WebApiClient
+  module Errors
+    # This is a generic response for generic problems the API doesn't really
+    # receive any other diagnostic issue with. You should *not* trust the
+    # client object after receiving this.
+    class ServerError < Exception
+    end
+  end
+end

data/lib/p4_web_api_client/errors/unauthenticated.rb

@@ -0,0 +1,11 @@
+module P4WebApiClient
+  module Errors
+    # This is just basically the 403 error type, which doesn't have much
+    # diagnostic information. This can happen if your session is invalid
+    # with perforce, you've used an invalid token, etc. Basically, you need
+    # to create a new session and make sure the auth string you're sending over
+    # is correct.
+    class Unauthenticated < Exception
+    end
+  end
+end

data/lib/p4_web_api_client/errors.rb

@@ -0,0 +1,4 @@
+require 'p4_web_api_client/errors/perforce_problem'
+require 'p4_web_api_client/errors/resource_not_found'
+require 'p4_web_api_client/errors/server_error'
+require 'p4_web_api_client/errors/unauthenticated'

data/lib/p4_web_api_client/models/branch.rb

@@ -0,0 +1,66 @@
+# Copyright (c) 2014 Perforce Software, Inc.  All rights reserved.
+
+require 'time'
+
+module P4WebApiClient
+  module Models
+    # Models the output of a branch spec in the system.
+    #
+    # See also:
+    # - http://www.perforce.com/perforce/r14.2/manuals/cmdref/p4_branch.html
+    # - http://www.perforce.com/perforce/r14.2/manuals/cmdref/p4_branches.html
+    class Branch
+      # The branch name and primary ID
+      attr_accessor :branch
+
+      # Perforce login of the branch owner, this field is not important unless
+      # `option` is :locked
+      attr_accessor :owner
+
+      # DateTime of the last access to the branch spec
+      attr_accessor :access
+
+      # DateTime when the branch was last changed
+      attr_accessor :update
+
+      # Either :unlocked or :locked
+      attr_accessor :options
+
+      # Short description of the branch's purpose
+      attr_accessor :description
+
+      # Mappings from one set of depot files to another set of files. Each
+      # mapping is a string in the array of mappings, separated by whitespace
+      # (or possibly enquoted with '' characters)
+      attr_accessor :view
+
+      def initialize(obj = {})
+        @branch = obj['Branch'] if obj.key?('Branch')
+        @owner = obj['Owner'] if obj.key?('Owner')
+        @access = Time.at(obj['Access']).to_datetime if obj.key('Access')
+        @update = Time.at(obj['Update']).to_datetime if obj.key('Update')
+        @options = obj['Options'].to_sym if obj.key?('Options')
+        @description = obj['Description'] if obj.key?('Description')
+        @view = obj['View'].map(&:clone) if obj.key?('View')
+
+        # If the user has defined symbols in the Ruby-ish API, then use that
+        # too, but we expect the data to be in the right format.
+        obj.each_key do |key|
+          accessor = "#{key}="
+          send(accessor, obj[key]) if self.respond_to?(accessor)
+        end
+      end
+
+      def to_internal_hash
+        hash = {
+          Branch: @branch
+        }
+        hash[:Owner] = @owner if @owner
+        hash[:Options] = @options if @options
+        hash[:Description] = @description if @description
+        hash[:View] = @view if @view
+        hash
+      end
+    end
+  end
+end

data/lib/p4_web_api_client/models/change.rb

@@ -0,0 +1,71 @@
+# Copyright (c) 2014 Perforce Software, Inc.  All rights reserved.
+
+require 'time'
+
+module P4WebApiClient
+  module Models
+    # Represents typical changelist descriptions
+    #
+    # In the future, this may be used to represent changelist specifications,
+    # but currently only models output of the GET /v1/changes command.
+    #
+    # See also:
+    # - http://www.perforce.com/perforce/r14.2/manuals/cmdref/p4_changes.html
+    # - http://www.perforce.com/perforce/r14.2/manuals/cmdref/p4_change.html
+    class Change
+      # If path information exists, this is a depot path specifier that
+      # indicates what files this changelist affects. (This is not documented.)
+      attr_accessor :path
+
+      # A string ID of the change
+      attr_accessor :change
+
+      # DateTime indicating when the change was created
+      attr_accessor :date
+
+      # String client ID the changelist is associated with
+      attr_accessor :client
+
+      # Perforce login of the person who owns this changelist (a string)
+      attr_accessor :user
+
+      # One of :pending, :shelved, :submitted, or :new. Probably :submitted
+      attr_accessor :status
+
+      # One of :restricted or :public
+      attr_accessor :type
+
+      # Textual string description of changelist. Must be set for changes
+      # who have their `status` set to :submitted
+      attr_accessor :description
+
+      # An array of job IDs fixed by this changelist
+      attr_accessor :jobs
+
+      # An array of file paths being submitted in this changelist
+      attr_accessor :files
+
+      def initialize(obj = {})
+        @path = obj['Path'] if obj.key?('Path')
+        @change = obj['Change'] if obj.key?('Change')
+        @date = Time.at(obj['Date']).to_datetime if obj.key?('Date')
+        @client = obj['Client'] if obj.key?('Client')
+        @user = obj['User'] if obj.key?('User')
+        @status = obj['Status'].to_sym if obj.key?('Status')
+        @type = obj['Type'].to_sym if obj.key?('Type')
+        @description = obj['Description'] if obj.key?('Description')
+        # Create copies of these arrays. It's unlikely they'll change but it's
+        # probably not a good idea to just maintain references to the parent
+        @jobs = obj['Jobs'].map(&:clone) if obj.key?('Jobs')
+        @files = obj['Files'].map(&:clone) if obj.key?('Files')
+
+        # If the user has defined symbols in the Ruby-ish API, then use that
+        # too, but we expect the data to be in the right format.
+        obj.each_key do |key|
+          accessor = "#{key}="
+          send(accessor, obj[key]) if self.respond_to?(accessor)
+        end
+      end
+    end
+  end
+end

data/lib/p4_web_api_client/models/client.rb

@@ -0,0 +1,129 @@
+# Copyright (c) 2014 Perforce Software, Inc.  All rights reserved.
+
+require 'time'
+
+module P4WebApiClient
+  module Models
+    # Models the client spec used to define client workspaces in the Perforce
+    # system.
+    #
+    # See also:
+    # - http://www.perforce.com/perforce/r14.2/manuals/cmdref/p4_client.html
+    # - http://www.perforce.com/perforce/r14.2/manuals/cmdref/p4_clients.html
+    class Client
+      # The client workspace name and primary ID
+      attr_accessor :client
+
+      # Perforce login of the user who owns the workspace
+      attr_accessor :owner
+
+      # DateTime when the workspace was last modified
+      attr_accessor :update
+
+      # DateTime when the workspace was last used
+      attr_accessor :access
+
+      # The name of the workstation this workspace resides. If set, client
+      # operations can *only* be run from this host.
+      attr_accessor :host
+
+      # Textual description of the workspace
+      attr_accessor :description
+
+      # Directory (on the local host) relative to which all files in the `view`
+      # are specified. If you change this setting, you must 'physically'
+      # relocate any files that currently reside there.
+      attr_accessor :root
+
+      # Up to two alternate cleint workspace roots
+      #
+      # This enables users to use the same Perforce client on multiple platforms
+      #
+      # See the command reference for more details:
+      # - http://www.perforce.com/perforce/r14.2/manuals/cmdref/p4_client.html
+      attr_accessor :alt_roots
+
+      # A single string defining a set of switches the change behavior of
+      # different commands on the client.
+      #
+      # See the command reference for more details:
+      # - http://www.perforce.com/perforce/r14.2/manuals/cmdref/p4_client.html
+      attr_accessor :options
+
+      # A single string that governs default behavior of p4 submit on this
+      # client.
+      #
+      # See the command reference for more details:
+      # - http://www.perforce.com/perforce/r14.2/manuals/cmdref/p4_client.html
+      attr_accessor :submit_options
+
+      # Configure CR/LF conversion
+      #
+      # See the command reference for more details:
+      # - http://www.perforce.com/perforce/r14.2/manuals/cmdref/p4_client.html
+      attr_accessor :line_end
+
+      # Associates the workspace with the specified stream.
+      attr_accessor :stream
+
+      # A changelist number that sets a back-in-time view of a stream.
+      attr_accessor :stream_at_change
+
+      # If set, restricts the usage of the workspace to the named server.
+      attr_accessor :server_id
+
+      # Array of strings that specifies the mappings between files in the depot
+      # and files in the workspace.
+      attr_accessor :view
+
+      # Restricts access to depot paths to a particular point in time.
+      attr_accessor :change_view
+
+      def initialize(obj = {})
+        @client = obj['Client'] if obj.key?('Client')
+        @owner = obj['Owner'] if obj.key?('Owner')
+        @access = Time.at(obj['Access']).to_datetime if obj.key?('Access')
+        @update = Time.at(obj['Update']).to_datetime if obj.key?('Update')
+        @host = obj['Host'] if obj.key?('Host')
+        @description = obj['Description'] if obj.key?('Description')
+        @root = obj['Root'] if obj.key?('Root')
+        @alt_roots = obj['AltRoots'].map(&:clone) if obj.key?('AltRoots')
+        @options = obj['Options'] if obj.key?('Options')
+        @submit_options = obj['SubmitOptions'] if obj.key?('SubmitOptions')
+        @line_end = obj['LineEnd'] if obj.key?('LineEnd')
+        @stream = obj['Stream'] if obj.key?('Stream')
+        @stream_at_change = obj['StreamAtChange'] if obj.key?('StreamAtChange')
+        @server_id = obj['ServerID'] if obj.key?('ServerID')
+        @view = obj['View'].map(&:clone) if obj.key?('View')
+        @change_view = obj['ChangeView'].map(&:clone) if obj.key?('ChangeView')
+
+        # If the user has defined symbols in the Ruby-ish API, then use that
+        # too, but we expect the data to be in the right format.
+        obj.each_key do |key|
+          accessor = "#{key}="
+          send(accessor, obj[key]) if self.respond_to?(accessor)
+        end
+      end
+
+      def to_internal_hash
+        hash = {
+          Client: @client
+        }
+        hash[:Owner] = @owner if @owner
+        hash[:Host] = @host if @host
+        hash[:Description] = @description if @description
+        hash[:Root] = @root if @root
+        hash[:AltRoots] = @alt_roots if @alt_roots
+        hash[:Options] = @options if @options
+        hash[:SubmitOptions] = @submit_options if @submit_options
+        hash[:LineEnd] = @line_end if @line_end
+        hash[:Stream] = @stream if @stream
+        hash[:StreamAtChange] = @stream_at_change if @stream_at_change
+        hash[:ServerID] = @server_id if @server_id
+        hash[:View] = @view if @view
+        hash[:ChangeView] = @change_view if @change_view
+        hash
+      end
+    end
+  end
+end

data/lib/p4_web_api_client/models/depot.rb

@@ -0,0 +1,97 @@
+# Copyright (c) 2014 Perforce Software, Inc.  All rights reserved.
+
+module P4WebApiClient
+  module Models
+    # Model that can be obtained via file browsing (the files command with no
+    # arguments) *or* via the list_depots command.
+    #
+    # This implements a few methods to assist in file browsing, since our
+    # underlying data is actually quite inconsistent. These methods are shared
+    # between Dir, and File:
+    #
+    # * name - The name without any parent specifier
+    # * depot_path - The typical '//depot/dir1/file' style path specifier
+    # * browsable? - Can you list children of this path?
+    #
+    # For more details on the output fields, see
+    # http://www.perforce.com/perforce/r14.2/manuals/cmdref/p4_depot.html
+    class Depot
+      # The depot name
+      attr_accessor :depot
+
+      # DateTime associated with the depot
+      attr_accessor :date
+
+      # :local, :remote, :spec, :stream, :unload, or :archive
+      attr_accessor :type
+
+      # If type is :remote, this is likely the P4PORT address of the remote
+      # server. May not be set in all cases.
+      attr_accessor :address
+
+      # If type is :local, :spec, or :archive, this points to the relative
+      # location of the depot subdirectory. See command reference for more
+      # details
+      attr_accessor :map
+
+      # Short description of the depot's purpose. Optional
+      attr_accessor :description
+
+      # The user who owns the depot.
+      attr_accessor :owner
+
+      # If type is :spec, this holds an optional suffix for generated paths
+      # to objects in the spec depot. See command reference for more details.
+      attr_accessor :suffix
+
+      # When type is :spec, an optional description of what specs should be
+      # saved. See command reference for more details.
+      attr_accessor :spec_map
+
+      def initialize(obj = {})
+        @depot = obj['Depot'] if obj.key?('Depot')
+        @date = Time.at(obj['Date']).to_datetime if obj.key?('Date')
+        @type = obj['Type'].to_sym if obj.key?('Type')
+        @address = obj['Address'] if obj.key?('Address')
+        @map = obj['Map'] if obj.key?('Map')
+        @description = obj['Description'] if obj.key?('Description')
+        @owner = obj['Owner'] if obj.key?('Owner')
+        @suffix = obj['Suffix'] if obj.key?('Suffix')
+        @spec_map = obj['SpecMap'] if obj.key?('SpecMap')
+
+        # If the user has defined symbols in the Ruby-ish API, then use that
+        # too, but we expect the data to be in the right format.
+        obj.each_key do |key|
+          accessor = "#{key}="
+          send(accessor, obj[key]) if self.respond_to?(accessor)
+        end
+      end
+
+      def name
+        depot
+      end
+
+      def depot_path
+        "//#{depot}"
+      end
+
+      # You should always be able to list files and dirs of a depot (I think),
+      # you just might not get any results.
+      def browsable?
+        true
+      end
+
+      def to_internal_hash
+        hash = {
+          Depot: @depot
+        }
+        hash[:Type] = @type if @type
+        hash[:Address] = @address if @address
+        hash[:Map] = @map if @map
+        hash[:Description] = @description if @description
+        hash[:Owner] = @owner if @owner
+        hash
+      end
+    end
+  end
+end

data/lib/p4_web_api_client/models/dir.rb

@@ -0,0 +1,45 @@
+# Copyright (c) 2014 Perforce Software, Inc.  All rights reserved.
+
+module P4WebApiClient
+  module Models
+    # Model that can be obtained during file browsing - represents directories
+    # in the system.
+    #
+    # This implements a few methods to assist in file browsing, since our
+    # underlying data is actually quite inconsistent. These methods are shared
+    # between Depot, Dir, and File:
+    #
+    # * name - The name without any parent specifier
+    # * depot_path - The typical '//depot/dir1/file' style path specifier
+    # * browsable? - Can you list children of this path?
+    #
+    # For more information, also see http://www.perforce.com/perforce/r14.2/manuals/cmdref/p4_dirs.html
+    class Dir
+      # The depot path to this particular directory
+      attr_accessor :dir
+
+      def initialize(obj = {})
+        @dir = obj['Dir'] if obj.key?('Dir')
+
+        # If the user has defined symbols in the Ruby-ish API, then use that
+        # too, but we expect the data to be in the right format.
+        obj.each_key do |key|
+          accessor = "#{key}="
+          send(accessor, obj[key]) if self.respond_to?(accessor)
+        end
+      end
+
+      def name
+        dir.split('/').last
+      end
+
+      def depot_path
+        dir
+      end
+
+      def browsable?
+        true
+      end
+    end
+  end
+end

data/lib/p4_web_api_client/models/file.rb

@@ -0,0 +1,70 @@
+# Copyright (c) 2014 Perforce Software, Inc.  All rights reserved.
+
+module P4WebApiClient
+  module Models
+    # Model that can be obtained during file browsing - represents head
+    # revisions of active files in the system.
+    #
+    # This implements a few methods to assist in file browsing, since our
+    # underlying data is actually quite inconsistent. These methods are shared
+    # between Depot, Dir, and File:
+    #
+    # * name - The name without any parent specifier
+    # * depot_path - The typical '//depot/dir1/file' style path specifier
+    # * browsable? - Can you list children of this path?
+    #
+    # For more information, also see http://www.perforce.com/perforce/r14.2/manuals/cmdref/p4_files.html
+    class File
+      # The depot path of the file
+      attr_accessor :depot_file
+
+      # Revision number of the file
+      attr_accessor :revision
+
+      # Changelist id that created this file revision - should be a string
+      attr_accessor :change
+
+      # Action taken at the head, one of :add, :edit, :delete, :branch,
+      # :move_add, :move_delete, :integrate, :import, :purge, or :archive
+      attr_accessor :action
+
+      # File type - one of :text, :binary, :symlink, :apple, :resource,
+      # :unicode, :utf16
+      #
+      # See http://www.perforce.com/perforce/r14.2/manuals/cmdref/file.types.html
+      attr_accessor :type
+
+      # DateTime of when the file revision was created
+      attr_accessor :date
+
+      def initialize(obj = {})
+        @depot_file = obj['DepotFile'] if obj.key?('DepotFile')
+        @revision = obj['Revision'].to_i if obj.key?('Revision')
+        @change = obj['Change'] if obj.key?('Change')
+        @action = obj['Action'].gsub(/\//, '_').to_sym if obj.key?('Action')
+        @type = obj['Type'].to_sym if obj.key?('Type')
+        @date = Time.at(obj['Date']).to_datetime if obj.key?('Date')
+
+        # If the user has defined symbols in the Ruby-ish API, then use that
+        # too, but we expect the data to be in the right format.
+        obj.each_key do |key|
+          accessor = "#{key}="
+          send(accessor, obj[key]) if self.respond_to?(accessor)
+        end
+      end
+
+      # Synonym of depot_file, used for consistency between Depot, Dir, and File
+      def depot_path
+        depot_file
+      end
+
+      def browsable?
+        false
+      end
+
+      def name
+        depot_file.split('/').last
+      end
+    end
+  end
+end

data/lib/p4_web_api_client/models/group.rb

@@ -0,0 +1,102 @@
+# Copyright (c) 2014 Perforce Software, Inc.  All rights reserved.
+
+module P4WebApiClient
+  module Models
+    # Models the output of the group spec.
+    #
+    # See also:
+    # - http://www.perforce.com/perforce/r14.2/manuals/cmdref/p4_group.html
+    # - http://www.perforce.com/perforce/r14.2/manuals/cmdref/p4_groups.html
+    class Group
+      # The name and primary ID of the group
+      attr_accessor :group
+
+      # The maximum number of results that members of this group can acccess
+      # from the service from a single command
+      attr_accessor :max_results
+
+      # The maximum number of rows that members of this group can scan from the
+      # service from a single command.
+      attr_accessor :max_scan_rows
+
+      # The maximum length of time (in milliseconds) that any one operation can
+      # lock any database table when scanning data.
+      attr_accessor :max_lock_time
+
+      # The duration (in sections) of the validity of a session ticket created
+      # by
+      attr_accessor :timeout
+
+      # The length of time (in seconds) for which passwords for users in this
+      # group remain valid. To disable password aging, use a value of unset.
+      attr_accessor :password_timeout
+
+      # An array of the Perforce usernames of the group members.
+      attr_accessor :users
+
+      # Array of names of other Perforce groups
+      attr_accessor :subgroups
+
+      # Array of names of other Perforce users, that are allowed to admin this
+      # group. This is independent of group membership. A group owner should
+      # also be a part of the users group if they are intended to take part
+      # in the group
+      attr_accessor :owners
+
+      def initialize(obj = {})
+        @group = obj['Group'] if obj.key?('Group')
+
+        @max_results = obj['MaxResults'].to_i if obj.key?('MaxResults') &&
+                                                 obj['MaxResults'] != 'unset'
+        @max_results = nil if @max_results == 0
+
+        @max_scan_rows = obj['MaxScanRows'].to_i \
+          if obj.key?('MaxScanRows') && obj['MaxScanRows'] != 'unset'
+        @max_scan_rows = nil if @max_scan_rows == 0
+
+        @max_lock_time = obj['MaxLockTime'].to_i \
+          if obj.key?('MaxLockTime') && obj['MaxLockTime'] != 'unset'
+        @max_lock_time = nil if @max_lock_time == 0
+
+        @timeout = obj['Timeout'].to_i \
+          if obj.key?('Timeout') && obj['Timeout'] != 'unset'
+        @timeout = nil if @timeout == 0
+
+        @password_timeout = obj['PasswordTimeout'].to_i \
+          if obj.key?('PasswordTimeout') && obj['PasswordTimeout'] != 'unset'
+        @password_timeout = nil if @password_timeout == 0
+
+        @users = obj['Users'].map(&:clone) if obj.key?('Users')
+        @users = [] unless @users
+        @subgroups = obj['Subgroups'].map(&:clone) if obj.key?('Subgroups')
+        @subgroups = [] unless @subgroups
+        @owners = obj['Owners'].map(&:clone) if obj.key?('Owners')
+        @owners = [] unless @owners
+
+        # If the user has defined symbols in the Ruby-ish API, then use that
+        # too, but we expect the data to be in the right format.
+        obj.each_key do |key|
+          accessor = "#{key}="
+          send(accessor, obj[key]) if self.respond_to?(accessor)
+        end
+      end
+
+      def to_internal_hash
+        hash = {
+          Group: @group
+        }
+
+        hash[:MaxResults] = @max_results.to_s if @max_results
+        hash[:MaxScanRows] = @max_scan_rows.to_s if @max_scan_rows
+        hash[:MaxLockTime] = @max_lock_time.to_s if @max_lock_time
+        hash[:Timeout] = @timeout if @timeout
+        hash[:PasswordTimeout] = @password_timeout if @password_timeout
+        hash[:Users] = @users if @users
+        hash[:Subgroups] = @subgroups if @subgroups
+        hash[:Owners] = @owners if @owners
+
+        hash
+      end
+    end
+  end
+end