sem4r 0.1.1

data/lib/sem4r/cli/cli_common_args.rb

@@ -0,0 +1,293 @@
+# -------------------------------------------------------------------------
+# Copyright (c) 2009-2010 Sem4r sem4ruby@gmail.com
+# 
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+# 
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+# 
+# -------------------------------------------------------------------------
+
+module Sem4r
+
+  class CliCommonArgs
+
+    def initialize
+      # defaults
+      @options = OpenStruct.new({
+          :verbose => true,
+          :force   => false,
+          :default_logging => true,
+          # :dump_soap_to_file => true,
+          # :dump_soap_to_directory => true,
+          :profile => 'sandbox'
+        })
+    end
+
+    def parse_and_run(argv)
+      parse(argv)
+    end
+
+    def parse(argv)
+
+      begin
+        rest = opt_parser(@options).parse(argv)
+      rescue OptionParser::AmbiguousOption => e
+        puts e.message
+        return false
+      end
+
+      if rest.length > 0
+        # cannot happen
+        puts "unknow options #{rest.join}"
+        return false
+      end
+
+      if @options.list_profiles
+        puts "Profiles:"
+        profiles = Adwords.profiles( @options.config_name )
+        names = profiles.keys.map &:to_s
+        names.sort.each do |s|
+          puts "  #{s} (#{profiles[s]['email']})"
+        end
+      end
+
+      !@options.exit
+    end
+
+    def opt_parser(options)
+      opt_parser = OptionParser.new
+      opt_parser.banner =  "Sem is a simple command line interface using the sem4r library."
+      opt_parser.separator "It's alpha software, please don't use in production or use it at your risk!"
+      opt_parser.separator "Further information: http://www.sem4r.com"
+      opt_parser.separator ""
+      opt_parser.separator "Usage: sem [options] [COMMAND [command options]]"
+
+      opt_parser.separator ""
+      opt_parser.separator "execute COMMAND to an adwords account using google adwords api"
+      opt_parser.separator "To view help and options for a particular command, use 'sem COMMAND -h'"
+
+      #
+      # common options
+      #
+      opt_parser.separator ""
+      opt_parser.separator "common options: "
+      opt_parser.separator ""
+
+      opt_parser.on("-h", "--help", "show this message") do
+        puts opt_parser
+        options.exit = true
+      end
+
+      opt_parser.on("--version", "show the sem4r version") do
+        puts "sem4r version #{Sem4r::version}"
+        options.exit = true
+      end
+
+      opt_parser.on("-v", "--[no-]verbose", "run verbosely") do |v|
+        options.verbose = v
+      end
+
+      opt_parser.on("-q", "--quiet", "quiet mode as --no-verbose") do |v|
+        options.verbose = false
+      end
+
+      opt_parser.on("-l", "--list-commands", "list commands") do
+        puts "SEM commands are:"
+        commands = CliCommand.commands.values.sort {|a,b| a.command <=> b.command }
+        commands.each do |cmd|
+          printf "  %-20s %s\n", cmd.command, cmd.description
+        end
+        puts
+        puts "For help on a particular command, use 'sem COMMAND -h'"
+        options.exit = true
+      end
+
+      opt_parser.separator ""
+      opt_parser.separator "logging options: "
+      opt_parser.separator ""
+
+      opt_parser.on("--log FILE", "log sem4r messages to file") do |v|
+        options.logger = v
+      end
+
+      opt_parser.on("-f", "--dump-file FILE", "dump soap conversation to file") do |v|
+        options.dump_soap_to_file = v
+      end
+
+      str = "dump soap conversation to directory: each \n"
+      str << (" " * 37) + "request/response is in a single file"
+      opt_parser.on("-d", "--dump-dir DIRECTORY", str) do |v|
+        options.dump_soap_to_directory = v
+      end
+
+      opt_parser.separator ""
+      opt_parser.separator "profile and credentials options: "
+      opt_parser.separator "  credentials options overwrite profile attributes"
+      opt_parser.separator ""
+
+      str =  "file where profiles are defined\n"
+      str << (" " * 37) + "(default $HOME/.sem4r/sem4r.yaml)"
+      opt_parser.on("--config CONFIG", str) do |config|
+        options.config_name = config
+      end
+
+      opt_parser.on("--list-profiles", "list profiles") do
+        options.list_profiles = true
+        options.exit = true
+      end
+
+      opt_parser.on("-p", "--profile PROFILE", "select profile (default is sandbox)") do |profile|
+        options.profile = profile
+      end
+
+      # email
+      opt_parser.on("--email EMAIL",
+        "email of adwords account") do |email|
+        options.email = email
+      end
+
+      # password
+      opt_parser.on("--password PASSWORD",
+        "password of adwords account") do |password|
+        options.password = password
+      end
+
+      # developer token
+      opt_parser.on("--token TOKEN",
+        "developer token to access adwords api") do |token|
+        options.developer_token = token
+      end
+
+      # client account
+      opt_parser.on("-c", "--client EMAIL",
+        "email for client account") do |email|
+        options.client_email = email
+      end
+      opt_parser.separator ""
+      opt_parser
+    end
+
+    def read_credentials_from_console
+      unless @options.environment
+        # The new and improved choose()...
+        say("\nThis is the new mode (default)...")
+        choose do |menu|
+          menu.prompt = "Please choose your favorite programming language?  "
+
+          menu.choice :ruby do say("Good choice!") end
+          menu.choices(:python, :perl) do say("Not from around here, are you?") end
+        end
+      end
+
+      @options.email           ||= ask("Enter adwords email:     ")
+      @options.password        ||= ask("Enter adwords password:  ") { |q| q.echo = "x" }
+      @options.developer_token ||= ask("Enter adwords developer_token:  ")
+
+      config = {
+        :environment     => @options.environment,
+        :email           => @options.email,
+        :password        => @options.password,
+        :developer_token => @options.developer_token
+      }
+
+      pp config
+      unless agree("credentials are correct?")
+        exit
+      end
+      config
+    end
+
+    def account
+      #
+      # select profile
+      #
+      options = {}
+      if @options.config_name
+        options[:config_file] = @options.config_name
+      end
+      adwords = Adwords.new( @options.profile, options )
+      if @options.verbose
+        puts "using #{adwords.profile} profile"
+        puts "config file is #{adwords.config_file}"
+      end
+
+      #
+      # logging soap conversation
+      #
+      if @options.default_logging
+        configdir = File.join( ENV['HOME'], ".sem4r" )
+        unless File.exists?(configdir)
+          puts "Directory #{configdir} not exists"
+          FileUtils.mkdir(configdir)
+        end
+        dir = File.join(configdir, Time.new.strftime("%Y%m%d-soap-dump"))
+        @options.dump_soap_to_directory = dir
+        
+        file = File.join(configdir, Time.new.strftime("%Y%m%d-sem4r-log"))
+        @options.logger = file
+      end
+
+      if @options.dump_soap_to_file
+        filename = @options.dump_soap_to_file
+        o = { :file => filename }
+        adwords.dump_soap_options( o )
+      end
+      if @options.dump_soap_to_directory
+        dir = @options.dump_soap_to_directory
+        o = { :directory => dir, :format => true }
+        adwords.dump_soap_options( o )
+      end
+      if @options.verbose and adwords.dump_soap?
+        puts "Logging soap conversation to '#{adwords.dump_soap_where}'"
+      end
+      if !adwords.dump_soap?
+        puts "it is highly recommended to activate the dump soap log"
+      end
+
+      #
+      # logging
+      #
+      # filename = File.join( tmp_dirname, File.basename(example_file).sub(/\.rb$/, ".log") )
+      if @options.logger
+        # filename = "sem.log"
+        adwords.logger = @options.logger
+      end
+      if adwords.logger
+        puts "Logger activated"
+      end
+      # adwords.logger = Logger.new(STDOUT)
+
+      #
+      # select account for command
+      #
+      if @options.client_email
+        account = adwords.account.client_accounts.find{ |c| c.client_email =~ /^#{@options.client_email}/ }
+        if account.nil?
+          puts "client account not found"
+        else
+          puts "using client #{account.client_email}"
+        end
+      else
+        account = adwords.account
+      end
+      return account
+    end
+
+  end
+
+end

data/lib/sem4r/cli/cli_download_report.rb

@@ -0,0 +1,81 @@
+# -------------------------------------------------------------------------
+# Copyright (c) 2009-2010 Sem4r sem4ruby@gmail.com
+# 
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+# 
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+# 
+# -------------------------------------------------------------------------
+
+module Sem4r
+  class CliDownloadReport < CliCommand
+
+    def self.command
+      "download"
+    end
+
+    def self.description
+      "download a generated report"
+    end
+
+    def initialize(common_args)
+      @common_args = common_args
+    end
+
+    def command_opt_parser(options)
+      opt_parser = OptionParser.new
+      opt_parser.banner = "Usage #{self.class.command} [command_options ] <report_id>"
+      opt_parser.separator ""
+      opt_parser.separator "#{self.class.description}"
+      opt_parser.on("-h", "--help", "show this message") do
+        puts opt_parser
+        options.exit = true
+      end
+    end
+
+    def parse_and_run(argv)
+      options = OpenStruct.new
+      rest = command_opt_parser(options).parse( argv )
+      if options.exit
+        return false
+      end
+      if rest.length != 1
+        puts "missing report id"
+        return false
+      end
+
+      account = @common_args.account
+      report_id = rest[0].to_i
+      report = account.reports.find { |r| r.id == report_id }
+      if report.nil?
+        puts "report '#{report_id}' not found"
+        return false
+      end
+
+      if report.status != 'Completed'
+        puts "cannot donwload report with status '#{report.status}'"
+        return false
+      end
+      report.download("test_report.xml")
+
+      account.adwords.p_counters
+      return true
+    end
+
+  end
+end

data/lib/sem4r/cli/cli_helpers.rb

@@ -0,0 +1,57 @@
+module Sem4r
+  # From http://gist.github.com/72234
+  #
+  # mysql-style output for an array of ActiveRecord objects
+  #
+  # Usage:
+  #   report(records)  # displays report with all fields
+  #   report(records, :field1, :field2, ...) # displays report with given fields
+  #
+  # Example:
+  # >> report(records, :id, :amount, :created_at)
+  # +------+-----------+--------------------------------+
+  # | id   | amount    | created_at                     |
+  # +------+-----------+--------------------------------+
+  # | 8301 | $12.40    | Sat Feb 28 09:20:47 -0800 2009 |
+  # | 6060 | $39.62    | Sun Feb 15 14:45:38 -0800 2009 |
+  # | 6061 | $167.52   | Sun Feb 15 14:45:38 -0800 2009 |
+  # | 6067 | $12.00    | Sun Feb 15 14:45:40 -0800 2009 |
+  # | 6059 | $1,000.00 | Sun Feb 15 14:45:38 -0800 2009 |
+  # +------+-----------+--------------------------------+
+  # 5 rows in set
+  #
+  def self.report(items, *fields)
+    # find max length for each field; start with the field names themselves
+    max_len = Hash[*fields.map {|f| [f, f.to_s.length]}.flatten]
+
+    items.each do |item|
+      fields.each do |field|
+        len = item.send(field).to_s.length
+        max_len[field] = len if len > max_len[field]
+      end
+    end
+
+    border = '+-' + fields.map {|f| '-' * max_len[f] }.join('-+-') + '-+'
+    title_row = '| ' + fields.map {|f| sprintf("%-#{max_len[f]}s", f.to_s) }.join(' | ') + ' |'
+
+    puts border
+    puts title_row
+    puts border
+
+    items.each do |item|
+      row = '| ' + fields.map {|f| sprintf("%-#{max_len[f]}s", item.send(f)) }.join(' | ') + ' |'
+      puts row
+    end
+
+    puts border
+    puts "#{items.length} rows in set\n"
+  end
+end
+
+if __FILE__ == $0
+  require 'ostruct'
+  o = OpenStruct.new
+  o.a = 1
+  o.b = 2
+  Sem4r::report( [o], :a, :b )
+end

data/lib/sem4r/cli/cli_ideas.rb

@@ -0,0 +1,100 @@
+# -------------------------------------------------------------------------
+# Copyright (c) 2009-2010 Sem4r sem4ruby@gmail.com
+# 
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+# 
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+# 
+# -------------------------------------------------------------------------
+
+module Sem4r
+
+  class CliIdeas < CliCommand
+
+    def self.command
+      "ideas"
+    end
+
+    def self.description
+      "list ideas"
+    end
+
+    def initialize(common_args)
+      @common_args = common_args
+    end
+
+    def opt_parser(options)
+      opt_parser = OptionParser.new
+      opt_parser.banner= "#{self.class.description}"
+      opt_parser.separator "Usage: sem [options] idea <keyword>"
+
+      opt_parser.separator ""
+      opt_parser.separator "common options: "
+      opt_parser.separator ""
+      opt_parser.on("-h", "--help", "show this message") do
+        puts opt_parser
+        options.exit = true
+      end
+    end
+
+    def parse_and_run(argv)
+      options = OpenStruct.new
+      rest = opt_parser(options).parse( argv )
+      return false if options.exit
+      if rest.length < 1
+        puts "keyword missing see help"
+        return false
+      end
+      
+      @keyword =  rest[1]
+      account = @common_args.account
+      unless account
+        puts "select an account!"
+      else
+        _run account
+      end
+    end
+
+    def _run(account)
+      ideas = account.targeting_idea  do
+        idea_type    "KEYWORD"
+        request_type "IDEAS"
+
+        related_to_keyword_search_parameter do
+          text       @keyword
+          match_type 'EXACT'
+        end
+      end
+
+      items = []
+      ideas.each do |i|
+        i.each do |a|
+          next if a.class != TKeywordAttribute
+          o = OpenStruct.new
+          o.text  = a.text
+          o.match = a.match_type
+          items << o
+        end
+      end
+
+      Sem4r::report(items, :text, :match)
+      account.adwords.p_counters
+    end
+
+  end
+end

data/lib/sem4r/cli/cli_list_ads.rb

@@ -0,0 +1,74 @@
+# -------------------------------------------------------------------------
+# Copyright (c) 2009-2010 Sem4r sem4ruby@gmail.com
+# 
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+# 
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+# 
+# -------------------------------------------------------------------------
+
+module Sem4r
+
+  CliListAds = CliCommand.define_command("ads", "list ads") do |account|
+    puts "List AdGroup Advertising"
+
+    # if the accounts have client_accounts it is a master
+    client_accounts = account.client_accounts
+    if client_accounts.empty?
+      client_accounts = [account]
+    end
+
+    items = []
+    need_newline = false
+
+    client_accounts.each do |client_account|
+      if need_newline
+        puts
+        need_newline = false
+      end
+
+      #--
+      puts "examinate account '#{client_account.credentials.client_email}'"
+      client_account.campaigns.each do |campaign|
+        # puts "examinate campaign '#{campaign}'"
+        campaign.ad_groups.each do |ad_group|
+          # puts "examinate adgroup '#{ad_group}'"
+          ad_group.ads.each do |ad|
+            o = OpenStruct.new
+            o.client   = client_account.credentials.client_email
+            o.campaign = campaign.name
+            o.ad_group = ad_group.name
+            o.url      = ad.url
+            o.url      = ad.display_url
+            items << o
+          end
+          print "."
+          need_newline = true
+        end
+      end
+      #--
+
+    end
+    if need_newline
+      puts
+      need_newline = false
+    end
+    report(items, :client, :campaign, :ad_group, :url, :display_url)
+    account.adwords.p_counters
+  end
+end

data/lib/sem4r/cli/cli_list_keywords.rb

@@ -0,0 +1,76 @@
+# -------------------------------------------------------------------------
+# Copyright (c) 2009-2010 Sem4r sem4ruby@gmail.com
+# 
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+# 
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+# 
+# -------------------------------------------------------------------------
+
+module Sem4r
+
+  CliListKeywords = CliCommand.define_command("keywords", "list keywords") do |account |
+
+    # if the account have client_accounts it is a master
+    client_accounts = account.client_accounts
+    if client_accounts.empty?
+      client_accounts = [account]
+    end
+
+    items = []
+    need_newline = false
+    client_accounts.each do |client_account|
+      if need_newline
+        puts 
+        need_newline = false
+      end
+      puts "examinate account '#{client_account.credentials.client_email}'"
+      client_account.campaigns.each do |campaign|
+        # puts "examinate campaign '#{campaign}'"
+        campaign.ad_groups.each do |ad_group|
+          ad_group.criterions.each do |criterion|
+          
+            row = OpenStruct.new
+            row.client   = client_account.credentials.client_email
+            row.campaign = campaign.name
+            row.ad_group = ad_group.name
+
+            row.type     = criterion.type
+            case criterion.type
+            when Criterion::Keyword
+              row.text  = criterion.text
+              row.match = criterion.match
+            when Criterion::Placement
+              row.text  = criterion.url
+            end
+            items << row
+            print "."
+            need_newline = true
+          end
+        end
+      end
+    end
+    if need_newline
+      puts
+      need_newline = false
+    end
+    report(items, :client, :campaign, :ad_group, :type, :text, :match)
+    account.adwords.p_counters
+  end
+
+end