splunk-sdk-ruby 0.1.0 → 0.8.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MDQzNDZmNGE2M2MzNzFiZDJmODg4ZTNkZjU4MTdlZDdjMDUwMWRlNA==
+  data.tar.gz: !binary |-
+    NjI4ZDc1MGE0MWQ2ZDBkOGI0ZmZiOTAxMTI5NmEwMDgyNzU2YWFmOA==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    Njc3ODE4ZjBiY2FmMWJhMWRiZWU4MThkYTg4Y2FhYjU0OTc3MjI1NTg5ZTkw
+    OGFlMzJmODU3OTVhNjk5ZGZhOWExOWM4YzY2ODE4ZTBjMTU4OTdiZTcwZTAz
+    MWQwZWMyZjQ1OWM2YTc1MDE2ZWRhNDcyNGMzMTY1MWMyMDJlZmI=
+  data.tar.gz: !binary |-
+    MzRhMTdhYmNjZDkwYTgxNmVlYWMwZTA1MGE4YWIzNjY5YTUwYjMzMTU4MjY2
+    NzZhNjFkZDM1NGFhNjgyOWMwNWY3ODM5ZjJmODQyYmQ3Mzc1ZTgxOGEyZTAw
+    NTAxZjkyNTNiNGM2M2U1Y2FhYTdmN2ExOGU1ZDE0Mzk0OWRlNDE=

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Splunk SDK for Ruby Changelog
 
+## Version 0.8.1 (beta)
+
+### Bugs fixed
+
+* Fixed wrong version number in a few documentation files.
+
+## Version 0.8.0 (beta)
+
+### Breaking changes
+
+* The _raw field in events is now returned as text, not XML. That is, all tags
+  such as the sg elements, are removed, and all characters are unescaped. The
+  XML is available from the segmented_raw method on the event, which returns a
+  string containing the raw XML of the _raw field returned by the server.
+* The severities in messages in Atom feeds are now strings instead of symbols.
+
+### New features
+
+* Added support for inputs via the Service#inputs method, and for modular
+  input kinds via the Service#modular_input_kinds method.
+* Added segmented_raw method to events returned by ResultsReader.
+
+### Bugs fixed
+
+* Added missing Splunk:: prefix in example in the docs for Service.
+* Moved default "segmentation=none" option for asynchronous searches from
+  Job#initialize to Job#events, Job#preview, and Job#results.
+
 ## Version 0.1.0 (preview)
 
 ### Breaking changes

data/README.md

@@ -1,8 +1,8 @@
-# The Splunk Software Development Kit for Ruby (Preview Release)
+# The Splunk Software Development Kit for Ruby (Beta Release)
 
-#### Version 0.1
-This Splunk Software Development Kit (SDK) contains library code and examples
-designed to enable developers to build applications using Splunk.
+#### Version 0.8
+This Splunk Software Development Kit (SDK) for Ruby contains library code and 
+examples designed to enable developers to build applications using Splunk.
 
 Splunk is a search engine and analytic environment that uses a distributed
 map-reduce architecture to efficiently index, search, and process large 
@@ -17,15 +17,6 @@ The Splunk developer platform enables developers to take advantage of the
 same technology used by the Splunk product to build exciting new applications
 that are enabled by Splunk's unique capabilities.
 
-1.  This Preview release is pre-beta, and therefore is incomplete and may have 
-    bugs. A Beta release is planned prior to a general release. 
-
-2.  The Apache license only applies to this SDK and no other software provided 
-    by Splunk.
-
-3.  Splunk, in using the Apache license, is not providing any warranties or 
-    indemnification, or accepting any liabilities with the Preview of this SDK.
-
 ## Getting started with the Splunk SDK for Ruby
 
 The Splunk SDK for Ruby contains code and some examples that show how to
@@ -131,9 +122,7 @@ line, the SDK examples and unit tests use the values from the .splunkrc file.
     # Splunk password
     password=changeme
     # Access scheme (default: https)
-    scheme=https
-    # Your version of Splunk (default: 5.0)
-    version=5.0</pre>
+    scheme=https</pre>
 
 2. Save the file as .splunkrc in the current user's home directory.
 
@@ -172,7 +161,6 @@ Click **Yes**, then continue creating the file.
   running the examples. You can either update to the latest version
   of the SDK, or comment out the <tt>app</tt>, <tt>owner</tt>, and 
   <tt>version</tt> fields.
-* The <tt>version</tt> field is only used by the Splunk SDK for JavaScript.
 
 #### Run the unit tests
 

data/examples/6_work_with_modular_inputs.rb

@@ -0,0 +1,96 @@
+#--
+# Copyright 2011-2012 Splunk, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"): you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#++
+
+##
+# To make this example work, you need to install the example_modular_inputs.spl
+# application in the examples directory in your Splunk instance. It provides
+# two modular inputs called test1 and test2.
+
+require 'splunk-sdk-ruby'
+
+# How to get to the Splunk server. Edit this to match your
+# own Splunk install.
+config = {
+    :scheme => :https,
+    :host => "localhost",
+    :port => 8089,
+    :username => "admin",
+    :password => "changeme"
+}
+
+# First open a connection to Splunk.
+service = Splunk::connect(config)
+
+# List the modular inputs on the server.
+puts "Modular inputs:"
+service.modular_input_kinds.each do |mi|
+  puts "  #{mi["title"]} (#{mi.name})"
+end
+
+# List the parameters to test1
+puts
+puts "Arguments to test1:"
+puts
+args = service.modular_input_kinds["test1"].arguments
+args.each do |key, val|
+  puts "  Arg: #{key}"
+  puts "  Human-readable title: #{val["title"]}"
+  puts "  Description: #{val["description"]}"
+  puts "  Req on\tReq on"
+  puts "  create\tedit\tOrder\tType"
+  puts "  #{val["required_on_create"]}\t\t\t#{val["required_on_edit"]}\t\t#{val["order"]}\t#{val["data_type"]}"
+  puts
+end
+
+# Now we'll create an input of kind test1. The only field we must provide
+# is 'required_on_create', which has the required_on_create=1 in its definition.
+# All the other arguments are optional.
+test1_inputs = service.inputs["test1"]
+
+# Create an input of kind test1.
+INPUT_NAME = "my_input"
+if test1_inputs.has_key?(INPUT_NAME)
+  test1_inputs.delete(INPUT_NAME)
+end
+my_input = test1_inputs.create(
+    INPUT_NAME,
+    :required_on_create => "boris",
+    :number_field => 33
+)
+
+# Print the values of the fields. In the output, number_field and
+# required_on_create will be set, but all others will have no value.
+puts "Initial state:"
+args.keys().each do |arg|
+  puts "  #{arg}: #{my_input[arg] || "(value not set)"}"
+end
+
+# Now we update the input kind. The argument 'arg_required_on_edit' has
+# required_on_edit=1, so we have to send a value for it when we update
+# the input.
+my_input.update(:boolean_field => true, :arg_required_on_edit => "meep")
+my_input.refresh() # We have to refresh to see the changes we made.
+
+puts
+puts "After update:"
+args.keys().each do |arg|
+  puts "  #{arg}: #{my_input[arg] || "(value not set)"}"
+end
+
+# Delete the input we created.
+my_input.delete()
+
+

data/lib/splunk-sdk-ruby/atomfeed.rb

@@ -181,7 +181,7 @@ module Splunk
           element.elements.each do |element|
             if element.name == "msg"
               metadata["messages"] << {
-                  "type" => element.attributes["type"].text.intern,
+                  "type" => element.attributes["type"].text,
                   "message" => children_to_s(element)
               }
             end

data/lib/splunk-sdk-ruby/collection.rb

@@ -25,17 +25,7 @@ require_relative 'splunk_http_error'
 require_relative 'synonyms'
 
 module Splunk
-  # Class representing a collection in Splunk.
-  #
-  # A +Collection+ is a group of items, usually of class +Entity+ or one of its
-  # subclasses, but occasionally another +Collection+. Usually you obtain a
-  # +Collection+ by calling one of the convenience methods on +Service+.
-  #
-  # A +Collection+ is enumerable, and implements many of the methods found on
-  # +Hash+, so methods like +each+, +select+, and +delete_if+ all work, as does
-  # fetching a member of the +Collection+ with [].
-  #
-  class Collection
+  class ReadOnlyCollection
     include Enumerable
     extend Synonyms
 
@@ -49,8 +39,8 @@ module Splunk
       @infinite_count = -1
 
       # @always_fetch tells whether, when creating an entity in this collection,
-      # to bother trying to parse the response and always fetch the new state 
-      # after the fact. This is necessary for some collections, such as users, 
+      # to bother trying to parse the response and always fetch the new state
+      # after the fact. This is necessary for some collections, such as users,
       # which don't return the newly created object.
       @always_fetch = false
     end
@@ -120,100 +110,6 @@ module Splunk
                         state=entry)
     end
 
-    ##
-    # Creates an item in this collection.
-    #
-    # The _name_ argument is required. All other arguments are passed as a hash,
-    # though they vary from collection to collection.
-    #
-    # Returns: the created entity.
-    #
-    # *Example:*
-    #     service = Splunk::connect(:username => 'admin', :password => 'foo')
-    #     service.users.create('jack',
-    #       :password => 'mypassword',
-    #       :realname => 'Jack_be_nimble',
-    #       :roles => ['user'])
-    #
-    def create(name, args={})
-      body_args = args.clone()
-      body_args["name"] = name
-
-      request_args = {
-          :method => :POST,
-          :resource => @resource,
-          :body => body_args
-      }
-      if args.has_key?(:namespace)
-        request_args[:namespace] = body_args.delete(:namespace)
-      end
-
-      response = @service.request(request_args)
-
-      if @always_fetch
-        fetch_args = {:method => :GET,
-                      :resource => @resource + [name]}
-        if args.has_key?(:namespace)
-          fetch_args[:namespace] = args[:namespace]
-        end
-        response = @service.request(fetch_args)
-      end
-      feed = AtomFeed.new(response.body)
-      raise StandardError.new("No entities returned") if feed.entries.empty?
-      entity = atom_entry_to_entity(feed.entries[0])
-      raise StandardError.new("Found nil entity.") if entity.nil?
-      return entity
-    end
-
-    ##
-    # Deletes an item from the collection.
-    #
-    # Entities from different namespaces may have the same name, so if you are
-    # connected to Splunk using a namespace with wildcards in it, there may
-    # be multiple entities in the collection with the same name. In this case
-    # you must specify a namespace as well, or the +delete+ method will raise an
-    # AmbiguousEntityReference error.
-    #
-    # *Example:*
-    #     service = Splunk::connect(:username => 'admin', :password => 'foo')
-    #     props = service.confs['props']
-    #     props.delete('sdk-tests')
-    #
-    def delete(name, namespace=nil)
-      if namespace.nil?
-        namespace = @service.namespace
-      end
-
-      # We don't want to handle any cases about deleting ambiguously named
-      # entities.
-      if !namespace.is_exact?
-        raise StandardError.new("Must provide an exact namespace to delete an entity.")
-      end
-
-      @service.request(:method => :DELETE,
-                       :namespace => namespace,
-                       :resource => @resource + [name])
-      return self
-    end
-
-    ##
-    # Deletes all entities on this collection for which the block returns true.
-    #
-    # If block is omitted, returns an enumerator over all members of the
-    # collection.
-    #
-    def delete_if(&block)
-      # Without a block, just return an enumerator
-      return each() if !block_given?
-
-      values.each() do |entity|
-        if block.call(entity)
-          delete(entity.name, entity.namespace)
-        end
-      end
-
-    end
-
     ##
     # Calls block once for each item in the collection.
     #
@@ -294,7 +190,7 @@ module Splunk
     end
 
     ##
-    # Identical to the +each+ method, but the block is passed both the entity's 
+    # Identical to the +each+ method, but the block is passed both the entity's
     # name, and the entity.
     #
     def each_pair(args={}, &block)
@@ -387,7 +283,10 @@ module Splunk
     # Synonyms: +size+.
     #
     def length()
-      return values().length()
+      response = @service.request(:resource => @resource,
+                                  :query => {"count" => 0})
+      feed = AtomFeed.new(response.body)
+      return Integer(feed.metadata["totalResults"])
     end
 
     synonym "size", "length"
@@ -414,4 +313,108 @@ module Splunk
     synonym "to_a", "values"
   end
 
+  # Class representing a collection in Splunk.
+  #
+  # A +Collection+ is a group of items, usually of class +Entity+ or one of its
+  # subclasses, but occasionally another +Collection+. Usually you obtain a
+  # +Collection+ by calling one of the convenience methods on +Service+.
+  #
+  # A +Collection+ is enumerable, and implements many of the methods found on
+  # +Hash+, so methods like +each+, +select+, and +delete_if+ all work, as does
+  # fetching a member of the +Collection+ with [].
+  #
+  class Collection < ReadOnlyCollection
+    ##
+    # Creates an item in this collection.
+    #
+    # The _name_ argument is required. All other arguments are passed as a hash,
+    # though they vary from collection to collection.
+    #
+    # Returns: the created entity.
+    #
+    # *Example:*
+    #     service = Splunk::connect(:username => 'admin', :password => 'foo')
+    #     service.users.create('jack',
+    #       :password => 'mypassword',
+    #       :realname => 'Jack_be_nimble',
+    #       :roles => ['user'])
+    #
+    def create(name, args={})
+      body_args = args.clone()
+      body_args["name"] = name
+
+      request_args = {
+          :method => :POST,
+          :resource => @resource,
+          :body => body_args
+      }
+      if args.has_key?(:namespace)
+        request_args[:namespace] = body_args.delete(:namespace)
+      end
+
+      response = @service.request(request_args)
+
+      if @always_fetch
+        fetch_args = {:method => :GET,
+                      :resource => @resource + [name]}
+        if args.has_key?(:namespace)
+          fetch_args[:namespace] = args[:namespace]
+        end
+        response = @service.request(fetch_args)
+      end
+      feed = AtomFeed.new(response.body)
+      raise StandardError.new("No entities returned") if feed.entries.empty?
+      entity = atom_entry_to_entity(feed.entries[0])
+      raise StandardError.new("Found nil entity.") if entity.nil?
+      return entity
+    end
+
+    ##
+    # Deletes an item from the collection.
+    #
+    # Entities from different namespaces may have the same name, so if you are
+    # connected to Splunk using a namespace with wildcards in it, there may
+    # be multiple entities in the collection with the same name. In this case
+    # you must specify a namespace as well, or the +delete+ method will raise an
+    # AmbiguousEntityReference error.
+    #
+    # *Example:*
+    #     service = Splunk::connect(:username => 'admin', :password => 'foo')
+    #     props = service.confs['props']
+    #     props.delete('sdk-tests')
+    #
+    def delete(name, namespace=nil)
+      if namespace.nil?
+        namespace = @service.namespace
+      end
+
+      # We don't want to handle any cases about deleting ambiguously named
+      # entities.
+      if !namespace.is_exact?
+        raise StandardError.new("Must provide an exact namespace to delete an entity.")
+      end
+
+      @service.request(:method => :DELETE,
+                       :namespace => namespace,
+                       :resource => @resource + [name])
+      return self
+    end
+
+    ##
+    # Deletes all entities on this collection for which the block returns true.
+    #
+    # If block is omitted, returns an enumerator over all members of the
+    # collection.
+    #
+    def delete_if(&block)
+      # Without a block, just return an enumerator
+      return each() if !block_given?
+
+      values.each() do |entity|
+        if block.call(entity)
+          delete(entity.name, entity.namespace)
+        end
+      end
+    end
+  end
 end