qcloud_cos 0.3.0 → 0.4.0.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c46f40136350e35780ce86e5a216af26a75ec799
-  data.tar.gz: a90fe51412a6a35a83188e8509d7f51d48b469ec
+  metadata.gz: 75ee730d319d95b7fca2482722203b7e326c03a0
+  data.tar.gz: 7d3f04b960205007488d35688c8cf40146c1e3e2
 SHA512:
-  metadata.gz: 9d889e680582184954f7bb93260762f9406acf285b7c7bb70ff439992bda8157e8e8c19cecc7e16ee367f2786982861d4decc8fe110bf9e73dbf4d38c4af0f30
-  data.tar.gz: ffd68ec5201c615ba2d12598a4595148214260a0a90f30d03c837b318768e0a5651be14e97197bcc2154854c8b298f05d4fb278c1ad416e6fa4e3068f7a91595
+  metadata.gz: 3103a965be5176a4a7cb0346b748e6642d2b35dbb3b6aa9d7fb69be1ece65c4ee9e5b5e0bb222260931afd7a043d8ee06d5e11205a232c14b42f56ed9280c988
+  data.tar.gz: 3f00b1d37848247ac3a12fe521a131c39f4f37612c9600aaf1c8212d0cffcfef7807aa86252addbac7144e71f9c6c817f0be598ef99572a580c92e6d6e017676

data/.gitignore

@@ -7,3 +7,5 @@
 /pkg/
 /spec/reports/
 /tmp/
+.qcloud_cos.yml
+.ruby-version

data/README.md

@@ -49,12 +49,12 @@ More Example and Scenario, visit our [Document](#document)
 
 Here is original Restful API, It has the most detailed and authoritative explanation for every API.
 
-+ [COS RESTful API文档](http://www.qcloud.com/wiki/RESTful_API%E6%96%87%E6%A1%A3)
++ [COS RESTful API文档](http://www.qcloud.com/wiki/RESTful_API%E6%96%87%E6%A1%A3)
 + [COS 详细文档](http://www.qcloud.com/doc/product/227/%E4%BA%A7%E5%93%81%E4%BB%8B%E7%BB%8D)
 
 Here is our RDoc Document, It's well format to help you find more detail about methods.
 
-+ [RDoc Document](http://www.rubydoc.info/gems/qcloud_cos/0.1.0)
++ [RDoc Document](http://www.rubydoc.info/gems/qcloud_cos/0.3.0)
 
 
 Here are some more guides for help you. Welcome to advice.

data/bin/console

@@ -11,12 +11,12 @@ require 'qcloud_cos'
 # Pry.start
 
 QcloudCos.configure do |config|
-  config.app_id = ENV['QCLOUD_APP_ID'] || 'app-id'
-  config.secret_id = ENV['QCLOUD_SECRET_ID'] || 'secret_id'
-  config.secret_key = ENV['QCLOUD_SECRET_KEY'] || 'secret_key'
-  config.endpoint = ENV['QCLOUD_ENDPOINT'] || 'https://web.file.myqcloud.com/files/v1/'
-  config.bucket = ENV['QCLOUD_BUCKET'] || 'privatesdkdemo'
-  config.ssl_ca_file = ENV['SSL_CA_FILE'] || 'path/to/ssl/ca/file'
+  config.app_id = ENV['QCLOUD_COS_APP_ID'] || 'app-id'
+  config.secret_id = ENV['QCLOUD_COS_SECRET_ID'] || 'secret_id'
+  config.secret_key = ENV['QCLOUD_COS_SECRET_KEY'] || 'secret_key'
+  config.endpoint = ENV['QCLOUD_COS_ENDPOINT'] || 'http://web.file.myqcloud.com/files/v1/'
+  config.bucket = ENV['QCLOUD_COS_BUCKET'] || 'privatesdkdemo'
+  config.ssl_ca_file = ENV['QCLOUD_COS_SSL_CA_FILE'] || 'path/to/ssl/ca/file'
 end
 
 require 'irb'

data/bin/qcloud-cos

@@ -0,0 +1,120 @@
+#!/usr/bin/env ruby
+require 'bundler/setup'
+require 'commander/import'
+require 'qcloud_cos/cli'
+require 'awesome_print'
+
+program :name, 'qcloud-cos'
+program :version, QcloudCos::VERSION
+program :description, 'command-line tool for Qcloud COS'
+program :help, 'Author', 'Newell Zhu<zlx.star@gmail.com>'
+default_command :help
+
+command :config do |c|
+  c.syntax = 'qcloud-cos config'
+  c.description = 'Init config, eg: qcloud-cos config'
+  c.action do |args, options|
+    QcloudCos::Cli.config
+  end
+end
+
+command :info do |c|
+  c.syntax = 'qcloud-cos info [options] [dest_path]'
+  c.description = 'Obtain information'
+  c.example 'Obtain bucket information', '$ qcloud-cos info'
+  c.example 'Obtain information for /test/', '$ qcloud-cos info /test/'
+  c.example 'Obtain information for /production.log', '$ qcloud-cos info /production.log'
+  c.example 'Obtain information for /production.log from bucket2', '$ qcloud-cos info --bucket bucket2 /production.log'
+  c.option '--bucket Bucket Name', String, 'specify bucket name, it will override default bucket'
+  c.action do |args, options|
+    abort unless QcloudCos::Cli.environment_configed?
+    begin
+      cli = QcloudCos::Cli.init
+      ap cli.info(args, options), indent: -2
+    rescue => e
+      say_error e.message
+    end
+  end
+end
+
+command :list do |c|
+  c.syntax = 'qcloud-cos list [options] [dest_path]'
+  c.description = 'List objects under [dest_path]'
+  c.example 'List all objects under /', '$ qcloud-cos list'
+  c.example 'List all objects under /test/', '$ qcloud-cos list /test/'
+  c.example 'List first 10 objects under /test/', '$ qcloud-cos list --num 10 /test/'
+  c.example 'List all objects under / for bucket: bucket2', '$ qcloud-cos list --num 10 --bucket bucket2 /test/'
+  c.option '--bucket Bucket Name', String, 'specify bucket name, it will override default bucket'
+  c.option '--num Num', Integer, 'specify max objects, default is 100'
+  c.action do |args, options|
+    abort unless QcloudCos::Cli.environment_configed?
+    begin
+      cli = QcloudCos::Cli.init
+      cli.list(args, options).map{|path| puts path }
+    rescue => e
+      say_error e.message
+    end
+  end
+end
+
+command :upload do |c|
+  c.syntax = 'qcloud-cos upload [options] file [dest_path]'
+  c.description = 'Upload file or folder to COS'
+  c.example 'Upload production.log to /', '$ qcloud-cos upload production.log'
+  c.example 'Upload production.log to /data/', '$ qcloud-cos upload production.log /data/'
+  c.example 'Upload all files under ./test/ to /data/', '$ qcloud-cos upload test/ /data/'
+  c.example 'Upload all files under ./test/ to /data/ with other bucket: bucket2', '$ qcloud-cos upload --bucket bucket2 test/ /data/'
+  c.example 'Upload production.log to /data/ with slice_size and min', '$ qcloud-cos upload --size 10 --min 100 production.log /data/'
+  c.option '--bucket Bucket Name', String, 'specify bucket name, it will override default bucket'
+  c.option '--size Slice Size', Integer, "specify slice size for slice upload in Bytes, default: #{QcloudCos::DEFAULT_SLICE_SIZE}(#{QcloudCos::DEFAULT_SLICE_SIZE/1024/1024}M)"
+  c.option '--min Min Slice File Size', Integer, "specify min slice file size in Bytes, default: default: #{QcloudCos::MIN_SLICE_FILE_SIZE * 1024 * 1024}(#{QcloudCos::MIN_SLICE_FILE_SIZE}M)"
+  c.action do |args, options|
+    abort unless QcloudCos::Cli.environment_configed?
+    begin
+      cli = QcloudCos::Cli.init
+      cli.upload(args, options)
+    rescue => e
+      Commander::UI.say_error e.message
+    end
+  end
+end
+
+command :download do |c|
+  c.syntax = 'qcloud-cos download [options] dest_path [save_path]'
+  c.description = 'Download objects from COS'
+  c.example 'Download file from /data/production.log and save current path', '$ qcloud-cos download /data/production.log'
+  c.example 'Download file from /data/production.log and save under ./data/', '$ qcloud-cos download /data/production.log ./data'
+  c.example 'Download whole folder /data/test/ and save under ./data/', '$ qcloud-cos download /data/test/ ./data'
+  c.example 'Download whole folder /data/test/ from bucket2 and save under ./data/', '$ qcloud-cos download --bucket bucket2 /data/test/ ./data'
+  c.option '--bucket Bucket Name', String, 'specify bucket name, it will override default bucket'
+  c.action do |args, options|
+    abort unless QcloudCos::Cli.environment_configed?
+    begin
+      cli = QcloudCos::Cli.init
+      cli.download(args, options)
+    rescue => e
+      Commander::UI.say_error e.message
+    end
+  end
+end
+
+command :remove do |c|
+  c.syntax = 'qcloud-cos remove [options] dest_path'
+  c.description = 'Remove objects from COS'
+  c.example 'Remove file /data/production.log', '$ qcloud-cos remove /data/production.log'
+  c.example 'Remove folder /data/test/', '$ qcloud-cos remove /data/test/'
+  c.example 'Remove folder /data/test/ in recursive', '$ qcloud-cos remove --recursive /data/test/'
+  c.example 'Remove folder /data/test/ from bucket2', '$ qcloud-cos download --bucket bucket2 /data/test/'
+  c.option '--bucket Bucket Name', String, 'specify bucket name, it will override default bucket'
+  c.option '--[no-]recursive', 'specify recursive or not when remove folder'
+  c.action do |args, options|
+    abort unless QcloudCos::Cli.environment_configed?
+    begin
+      cli = QcloudCos::Cli.init
+      cli.remove(args, options)
+      Commander::UI.say_ok 'OK'
+    rescue => e
+      Commander::UI.say_error e.message
+    end
+  end
+end

data/lib/qcloud_cos.rb

@@ -11,6 +11,8 @@ module QcloudCos
   DEFAULT_SLICE_SIZE = 3_145_728 # 3M
   MIN_SLICE_FILE_SIZE = 10 # 10M
   MAX_RETRY_TIMES = 3
+  QCLOUD_COS_CONFIG = '.qcloud-cos.yml'
+  DEFAULT_ENDPOINT = 'http://web.file.myqcloud.com/files/v1/'
 
   class << self
     include Api
@@ -38,12 +40,10 @@ module QcloudCos
 
     def validates(path, options, path_validate = :file_only)
       Utils.stringify_keys!(options)
-      file_validates(path, path_validate)
-
-      bucket = options['bucket'] || config.bucket
-      fail MissingBucketError unless bucket
 
-      bucket
+      file_validates(path, path_validate)
+      num_validates(options['num'].to_i) if options['num']
+      bucket_validates(options['bucket'])
     end
 
     def fixed_path(path)
@@ -62,5 +62,15 @@ module QcloudCos
         FolderObject.validate(path)
       end
     end
+
+    def num_validates(number)
+      fail InvalidNumError if (number > 199 || number < 1)
+    end
+
+    def bucket_validates(bucket_name)
+      bucket = bucket_name || config.bucket
+      fail MissingBucketError unless bucket
+      bucket
+    end
   end
 end

data/lib/qcloud_cos/api.rb

@@ -9,7 +9,7 @@ module QcloudCos
     # @param path [String] 指定目标路径, 以 / 结尾, 则列出该目录下文件或者文件夹，不以 / 结尾，就搜索该前缀的文件或者文件夹
     # @param options [Hash] 额外参数
     # @option options [String] :bucket (config.bucket_name) 指定当前 bucket, 默认是配置里面的 bucket
-    # @option options [Integer] :num (100) 指定需要拉取的条目
+    # @option options [Integer] :num (100) 指定需要拉取的条目, 可选范围: 1~199
     # @option options [String] :pattern (eListBoth) 指定拉取的内容，可选值: eListBoth, eListDirOnly, eListFileOnly
     # @option options [Integer] :order (0) 指定拉取文件的顺序, 默认为正序(=0), 可选值: 0, 1
     # @option options [String] :context ("") 透传字段，查看第一页，则传空字符串。若需要翻页，需要将前一页返回值中的context透传到参数中。order用于指定翻页顺序。若order填0，则从当前页正序/往下翻页；若order填1，则从当前页倒序/往上翻页。
@@ -110,8 +110,15 @@ module QcloudCos
 
     # 分片上传
     #
+    # @example
+    #
+    #   upload_slice('/data/test.log', 'test.log') do |pr|
+    #     puts "uploaded #{pr * 100}%"
+    #   end
+    #
     # @param dst_path [String] 指定文件的目标路径
     # @param src_path [String] 指定文件的本地路径
+    # @param block [Block] 指定 Block 来显示进度提示
     # @param options [Hash] options
     # @option options [String] :bucket (config.bucket_name) 指定当前 bucket, 默认是配置里面的 bucket
     # @option options [Integer] :biz_attr 指定文件的 biz_attr 由业务端维护, 会在文件信息中返回
@@ -123,7 +130,7 @@ module QcloudCos
     # @raise [InvalidFilePathError] 如果目标路径是非法文件路径
     #
     # @return [Hash]
-    def upload_slice(dst_path, src_path, options = {})
+    def upload_slice(dst_path, src_path, options = {}, &block)
       dst_path = fixed_path(dst_path)
       fail FileNotExistError unless File.exist?(src_path)
       bucket = validates(dst_path, options)
@@ -133,7 +140,6 @@ module QcloudCos
       sign = authorization.sign(bucket)
 
       resp = init_slice_upload(dst_path, filesize, sha, options.merge('sign' => sign))
-      puts "init slice upload: #{resp}"
 
       data = resp['data']
       return data if data.key?('url') # 妙传命中
@@ -150,7 +156,8 @@ module QcloudCos
         retry_times = 0
         begin
           result = upload_part(dst_path, session, offset, filecontent, options)
-          puts "upload part data: #{result}"
+          progress = [offset + slice_size, filesize].min
+          yield((progress.to_f/filesize).round(2)) if block_given?
 
           if result.key?('data') && result['data'].key?('session')
             session = result['data']['session']
@@ -159,7 +166,6 @@ module QcloudCos
           end
         rescue => e
           retry_times += 1
-          puts "retry part upload request with offset:#{offset}, slice_size:#{slice_size} ..."
           retry if retry_times <= config.max_retry_times
           raise e
         end
@@ -168,7 +174,6 @@ module QcloudCos
     end
 
     # 初始化分片上传
-    # @private
     #
     # @param path [String] 指定上传文件的路径
     # @param filesize [Integer] 指定文件总大小
@@ -190,10 +195,8 @@ module QcloudCos
 
       http.post(url, query: query, headers: { 'Authorization' => sign }).parsed_response
     end
-    private :init_slice_upload
 
     # 上传分片数据
-    # @private
     #
     # @param path [String] 指定上传文件的路径
     # @param session [String] 指定分片上传的 session id
@@ -213,7 +216,6 @@ module QcloudCos
 
       http.post(url, query: query, headers: { 'Authorization' => sign }).parsed_response
     end
-    private :upload_part
 
     # 更新文件或者目录信息
     #

data/lib/qcloud_cos/cli.rb

@@ -0,0 +1,345 @@
+# encoding: utf-8
+require 'rubygems'
+require 'commander'
+require 'awesome_print'
+require 'qcloud_cos'
+
+module QcloudCos
+  class Cli
+    include Commander::Methods
+
+    QCLOUD_COS_ENV_MAPPING = {
+      app_id: 'QCLOUD_COS_APP_ID',
+      secret_id: 'QCLOUD_COS_SECRET_ID',
+      secret_key: 'QCLOUD_COS_SECRET_KEY',
+      endpoint: 'QCLOUD_COS_ENDPOINT',
+      bucket: 'QCLOUD_COS_BUCKET',
+      ssl_ca_file: 'QCLOUD_COS_SSL_CA_FILE',
+      max_retry_times: 'QCLOUD_COS_MAX_RETRY_TIMES'
+    }
+
+    # 交互模式配置环境
+    # 命令: $ qcloud-cos config
+    def self.config(config_path = nil)
+      config_path = config_path || QcloudCos::QCLOUD_COS_CONFIG
+      return Commander::UI.say_error("#{config_path} already exist, remove it first or direct edit it!") if File.exist?(config_path)
+
+      app_id = Commander::UI.ask 'Qcloud COS APP ID: '
+      return Commander::UI.say_error("Missing Qcloud COS APP ID") if app_id.empty?
+
+      secret_id = Commander::UI.ask 'Qcloud COS Secret ID: '
+      return Commander::UI.say_error("Missing Qcloud COS Secret ID") if secret_id.empty?
+
+      secret_key = Commander::UI.ask 'Qcloud COS Secret Key: '
+      return Commander::UI.say_error("Missing Qcloud COS Secret Key") if secret_key.empty?
+
+      endpoint = Commander::UI.ask "Default Qcloud COS Endpoint [#{QcloudCos::DEFAULT_ENDPOINT}]: "
+      endpoint = QcloudCos::DEFAULT_ENDPOINT if endpoint.empty?
+      bucket = Commander::UI.ask 'Default Qcloud COS Bucket: '
+
+      write_config(
+        config_path,
+        app_id: app_id,
+        secret_id: secret_id,
+        secret_key: secret_key,
+        endpoint: endpoint,
+        bucket: bucket
+      )
+    end
+
+    # 检查环境是否配置
+    #
+    # @return [Boolean]
+    def self.environment_configed?
+      configed = File.exist?(QcloudCos::QCLOUD_COS_CONFIG) || !ENV['QCLOUD_COS_APP_ID'].to_s.empty?
+      Commander::UI.say_error("Use `qcloud-cos config` first or export your environments") unless configed
+      configed
+    end
+
+    # 检查环境，初始化 Cli
+    def self.init
+      QcloudCos.configure do |config|
+        load_config.each { |k, v| config.send("#{k}=", v) }
+      end
+
+      self.new
+    end
+
+    # 查看信息
+    # 命令： $ qcloud-cos info [options] [dest_path]
+    #
+    # @example
+    #   # 查看 Bucket 信息
+    #   qcloud-cos info
+    #
+    #   # 查看 /production.log 信息
+    #   qcloud-cos info /production.log
+    #
+    #   # 查看 /test/ 信息
+    #   qcloud-cos info /test/
+    #
+    #   # 查看 bucket2 上的 /production.log 信息
+    #   qcloud-cos info --bucket bucket2 /production.log
+    def info(args, options)
+      path = args.shift || '/'
+      opts = parse(options)
+
+      QcloudCos.stat(path, opts)['data']
+    end
+
+    # 列出文件或者文件夹
+    # 使用： $ qcloud-cos list [options] [dest_path]
+    #
+    # @example
+    #
+    #   # 列出 / 下面的所有对象
+    #   qcloud-cos list
+    #
+    #   # 列出 /test/ 下面的所有对象
+    #   qcloud-cos list /test/
+    #
+    #   # 列出 /test/ 下面的前 10 个对象
+    #   qcloud-cos list --num 10 /test/
+    #
+    #   # 列出 bucket2 的 /test/ 下面的所有对象
+    #   qcloud-cos list --bucket bucket2 /test/
+    #
+    def list(args, options)
+      path = args.shift || '/'
+      opts = parse(options)
+      opts[:num] = options.num || 100
+
+      objects = QcloudCos.list(path, opts)
+      objects.map do |object|
+        File.join(path, object.is_a?(QcloudCos::FolderObject) ? "#{object.name}/" : object.name)
+      end
+    end
+
+    # 上传文件或者目录到 COS
+    # 命令: qcloud-cos upload [options] file [dest_path]
+    #
+    # @example
+    #
+    #   # 把 production.log 上传到 /
+    #   qcloud-cos upload production.log
+    #
+    #   # 把 production.log 上传到 /data/ 下面
+    #   qcloud-cos upload production.log /data/
+    #
+    #   # 把 ./test/ 整个文件夹上传到 /data/ 下面
+    #   qcloud-cos upload test/ /data/
+    #
+    #   # 把 ./test/ 整个文件夹上传到 bucket2 的 /data/ 下面
+    #   qcloud-cos upload --bucket bucket2 test/ /data/
+    def upload(args, options)
+      path = args.shift
+      return Commander::UI.say_error("file missing, see example: $ qcloud-cos upload -h") unless path
+      return Commander::UI.say_error("file #{path} not exist") unless File.exist?(path)
+
+      dest_path = args.shift || '/'
+      return Commander::UI.say_error("dest_path must end with /, see example: $ qcloud-cos upload -h") unless dest_path.end_with?('/')
+
+      opts = parse(options)
+      opts[:slice_size] = options.size || QcloudCos::DEFAULT_SLICE_SIZE
+      opts[:min] = options.min || QcloudCos::MIN_SLICE_FILE_SIZE * 1024 * 1024
+
+      if path.end_with?('/')
+        upload_folder(path, dest_path, opts)
+      else
+        upload_file(path, dest_path, opts)
+      end
+    end
+
+    # 下载文件或者目录
+    # 命令: $ qcloud-cos download [options] dest_path [save_path]
+    #
+    # @example
+    #
+    #   # 把 /data/production.log 下载到当前目录
+    #   qcloud-cos download /data/production.log
+    #
+    #   # 把 /data/production.log 下载到 ./data/ 下
+    #   qcloud-cos download /data/production.log ./data
+    #
+    #   # 把 /data/test/ 整个目录下载并保存到 ./data/ 目录下面
+    #   qcloud-cos download /data/test/ ./data
+    #
+    #   # 把 bucket2 下的 /data/test/ 整个目录下载并保存到 ./data/ 下面
+    #   qcloud-cos download --bucket bucket2 /data/test/ ./data
+    #
+    def download(args, options)
+      path = args.shift
+      return Commander::UI.say_error("missing path, see example: $ qcloud-cos download -h") unless path
+      opts = parse(options)
+      opts[:save_path] = args.shift || '.'
+
+      if path.end_with?('/')
+        download_folder(path, opts)
+      else
+        download_file(path, opts)
+      end
+    end
+
+    # 删除目录或者文件夹
+    # 命令: $ qcloud-cos remove [options] dest_path
+    #
+    # @example
+    #
+    #   # 删除文件/data/production.log
+    #   qcloud-cos remove /data/production.log
+    #
+    #   # 删除目录 /data/test/， 目录非空会失败
+    #   qcloud-cos remove /data/test/
+    #
+    #   # 级联删除目录 /data/test/
+    #   qcloud-cos remove --recursive /data/test/
+    #
+    #   # 删除 bucket2 下面的目录 /data/test/
+    #   qcloud-cos download --bucket bucket2 /data/test/
+    def remove(args, options)
+      path = args.shift
+      return Commander::UI.say_error("missing dest_path, see example: $ qcloud-cos remove -h") unless path
+
+      opts = parse(options)
+
+      if path.end_with?('/')
+        QcloudCos.delete_folder(path, opts.merge(recursive: !!options.recursive))
+      else
+        QcloudCos.delete_file(path, opts)
+      end
+    end
+
+    private
+
+    def upload_file(path, dest_path, opts)
+      dest_path = File.join(dest_path, path.split('/').last)
+      file = File.new(path)
+      if file.size > opts[:min]
+        QcloudCos.upload_slice(dest_path, path, Utils.hash_slice(opts, :bucket).merge(slice_size: opts[:slice_size]))
+      else
+        QcloudCos.upload(dest_path, file, Utils.hash_slice(opts, :bucket))
+      end
+      Commander::UI.say_ok "#{path} uploaded to #{dest_path}..."
+    rescue => e
+      Commander::UI.say_error "Failed when uploaded #{path} ===> #{e.message}"
+    ensure
+      file && file.close
+    end
+
+    def upload_folder(path, dest_path, opts)
+      file_path_map = {}
+      Dir.glob("#{path}**/*") do |file_path|
+        split_path = file_path.sub(path, '').split('/')
+        new_path =
+          if File.file?(file_path)
+            split_path.size > 1 ? File.join(dest_path, *split_path[0..-2]) : dest_path
+          else
+            file_path = File.join(file_path, '')
+            File.join(dest_path, *split_path, '')
+          end
+
+        file_path_map[file_path] = new_path
+      end
+      remove_subdirectories(file_path_map)
+
+      file_path_map.each do |file_path, dest_path|
+        if file_path.end_with?('/')
+          QcloudCos.create_folder(dest_path, opts)
+          Commander::UI.say_ok "Create folder #{dest_path}"
+        else
+          upload_file(file_path, dest_path, opts)
+        end
+      end
+    end
+
+    def download_file(path, opts)
+      save_path = opts.delete(:save_path)
+      FileUtils.mkdir_p(save_path) unless File.exist?(save_path)
+
+      file_path = File.join(save_path, path.split('/').last)
+      signed_access_url = opts[:access_url] ? opts.delete(:access_url) : QcloudCos.public_url(path, opts)
+      save_to_file(signed_access_url, file_path)
+      Commander::UI.say_ok("Save #{path} to #{file_path}")
+    rescue => e
+      Commander::UI.say_error("Failed when Download #{path}  ===> #{e.message}")
+    end
+
+    def download_folder(path, opts)
+      save_path = opts.delete(:save_path)
+      loop do
+        objects = QcloudCos.list(path, opts)
+        objects.each do |object|
+          if object.is_a?(QcloudCos::FolderObject)
+            new_path = File.join(save_path, object.name)
+            unless File.exist?(new_path)
+              FileUtils.mkdir_p(new_path) unless File.exist?(new_path)
+              Commander::UI.say_ok "Save #{path}#{object.name}/ to #{new_path}/"
+            end
+            download_folder("#{path}#{object.name}/", opts.merge(save_path: new_path))
+          elsif object.is_a?(QcloudCos::FileObject)
+            if object.access_url
+              download_file("#{path}#{object.name}", opts.merge(save_path: save_path, access_url: object.access_url))
+            else
+              download_file("#{path}#{object.name}", opts.merge(save_path: save_path))
+            end
+          end
+        end
+        break unless objects.has_more
+        opts['context'] = objects.context
+      end
+    end
+
+    def self.load_config
+      file_config = load_file_config
+
+      config = {}
+      QCLOUD_COS_ENV_MAPPING.each do |key, env_name|
+        config[key] = ENV[env_name] || file_config[key.to_s]
+      end
+      config
+    end
+
+    def self.load_file_config
+      return {} unless File.exist?(QcloudCos::QCLOUD_COS_CONFIG)
+
+      Hash[File.open(QcloudCos::QCLOUD_COS_CONFIG).map do |line|
+        key, value = line.split('=')
+        value.chomp!.empty? ? nil : [key, value]
+      end.compact]
+    end
+
+    def parse(options)
+      opts = {}
+      opts[:bucket] = options.bucket if options.bucket
+      opts
+    end
+
+    def remove_subdirectories(path_map)
+      new_map = path_map.dup
+      new_map.each do |_, dest_path|
+        path_map.reject! do |file_path, dest|
+          file_path.end_with?('/') && dest_path.start_with?(dest)
+        end
+      end
+    end
+
+    def save_to_file(access_url, file_path)
+      File.open(file_path, "wb") do |f|
+        f.write HTTParty.get(access_url)
+      end
+    end
+
+    def self.write_config(config_path, options)
+      File.open(config_path, "w") do |file|
+        file.puts "app_id=#{options[:app_id]}"
+        file.puts "secret_id=#{options[:secret_id]}"
+        file.puts "secret_key=#{options[:secret_key]}"
+        file.puts "endpoint=#{options[:endpoint]}"
+        file.puts "bucket=#{options[:bucket]}"
+        file.puts "ssl_ca_file="
+        file.puts "max_retry_times="
+      end
+    end
+
+  end
+end

data/lib/qcloud_cos/configuration.rb

@@ -5,5 +5,10 @@ module QcloudCos
     def max_retry_times
       @max_retry_times || MAX_RETRY_TIMES
     end
+
+    def max_retry_times=(times)
+      @max_retry_times = times.to_i
+      @max_retry_times = MAX_RETRY_TIMES if @max_retry_times.zero?
+    end
   end
 end

data/lib/qcloud_cos/convenient_api.rb

@@ -6,7 +6,8 @@ module QcloudCos
     # @param bucket_name [String] :bucket (config.bucket) 指定当前 bucket, 默认是配置里面的 bucket
     #
     # @return [Hash] 返回 Bucket 信息
-    def bucket_info(bucket_name = config.bucket)
+    def bucket_info(bucket_name = nil)
+      bucket_name = bucket_name || config.bucket
       stat('/', bucket: bucket_name)['data']
     rescue
       {}

data/lib/qcloud_cos/error.rb

@@ -46,4 +46,10 @@ module QcloudCos
       super('分片上传不能缺少 Session ID')
     end
   end
+
+  class InvalidNumError < Error
+    def initialize
+      super('单次列取目录数量必须在1~199')
+    end
+  end
 end

data/lib/qcloud_cos/version.rb

@@ -1,3 +1,3 @@
 module QcloudCos
-  VERSION = '0.3.0'
+  VERSION = '0.4.0.pre'
 end

data/qcloud_cos.gemspec

@@ -14,13 +14,15 @@ Gem::Specification.new do |spec|
   spec.homepage      = 'https://github.com/tencentyun'
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
-  spec.bindir        = 'exe'
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.bindir        = 'bin'
+  spec.executables   = ['qcloud-cos']
   spec.require_paths = ['lib']
 
   spec.add_dependency 'httparty'
   spec.add_dependency 'httmultiparty'
   spec.add_dependency 'addressable'
+  spec.add_dependency 'commander'
+  spec.add_dependency 'awesome_print'
 
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'rake'

data/wiki/get_started.md

@@ -21,7 +21,7 @@
       10. [检查目录下是否有文件夹 (contains_folder?)](#判断目录是否为空)
    3. [文件操作](#文件操作)
       1. [上传文件 (create, upload)](#文件上传)
-      2. [分片上传文件，支持断点续传 (upload_slice)](#文件分片上传)
+      2. [分片上传文件，支持断点续传 (upload_slice)](#大文件分片上传)
       3. [更新文件属性 (update)](#更新属性)
       4. [查询文件信息 (stat)](#目录或者文件查询)
       5. [列出文件 (list, list_files)](#列举目录下文件或目录)
@@ -30,8 +30,19 @@
       8. [文件搜索 (list)](#列举目录下文件或目录)
       9. [检查文件是否存在 (exists?, exist?)](#判断目录或者文件是否存在)
       10. [查看目录下文件数量 (count)](#查看文件和文件夹数目)
-      11. [检查目录下是否有文件 (contains_folder?)](#判断目录是否为空)
- 3. [其它资源](#其它资源)     
+      11. [检查目录下是否有文件 (contains_folder?)](#判断目录是否为空)
+   4. [分片上传 (upload_slice)](#文件分片上传)
+      1. [分片上传大文件 (upload_slice)](#大文件分片上传)
+      2. [分片上传初始化 (init_slice_upload)](#分片上传初始化)
+      3. [分片上传数据 (upload_part)](#分片上传数据)   
+   4. [命令行工具 (qcloud-cos)](#命令行工具)
+      1. [配置 (qcloud-cos config)](#命令行配置)
+      2. [查看信息 (qcloud-cos info)](#info)
+      3. [列出文件 (qcloud-cos list)](#list)
+      4. [上传文件或者目录 (qcloud-cos upload)](#upload)
+      5. [下载文件或者目录 (qcloud-cos download)](#download)
+      6. [删除文件或者目录 (qcloud-cos remove)](#remove)
+ 3. [其它资源](#其它资源)   
 
 
 ##  开发准备
@@ -539,63 +550,6 @@ path = "/myFolder/test.log";
 result = QcloudCos.upload(path, file, biz_attr: 'attr')
 ```
 
-#### 文件分片上传
-
-1.  接口说明
-
- 用于较大文件(一般大于8MB)的上传，调用者可以通过此接口上传较大文件并获得文件的url和唯一标识resource_path（用于调用其他api）。
-
-2.  方法
-
- ```ruby
- QcloudCos.upload_slice(dst_path, src_path, options = {})
- ```
-
-3.  参数和返回值
-
-参数说明：
-
-
-|参数名|类型 |必须 |默认值 |参数描述|
-|-----|----|-----|------|-------|
-| dst_path | String|是  |无 |文件在COS服务端的全路径，不包括/appid/bucketname|
-| src_path | String  |是 |无 |本地要上传文件的全路径|
-| options | Hash | 否 | 无 | 额外参数
-| options['bucket'] | String| 否 | 配置的默认 bucket | Bucket 名称|
-| options['biz_attr'] | String| 否 | 无 | 文件属性，业务端自己维护 |
-| options['slice_size'] |Integer    |否 | 3M|分片大小，用户可以根据网络状况自行设置|
-| options['session']    |String |否 |null   |如果是断点续传, 则带上(唯一标识此文件传输过程的id, 由后台下发, 调用方透传)|
-
-
-返回值, Hash:
-
-
-|参数名 |类型 |必然返回 |参数描述 |
-|------|----|--------|--------|
-|code |Integer |是 |错误码，成功时为0|
-|message |String |是 |错误信息|
-|data |Array  |是 |返回数据|
-|data['access_url'] | String| 是    |生成的文件下载url|
-|data['url']    |String |是 |操作文件的url|
-|data['resource_path']  |String |是 |资源路径. 格式:/appid/bucket/xxx|
-
-API 请求错误，则抛出 RequestError 异常
-
-
-|参数名 |类型 |参数描述 |
-|------|----|--------|
-|code | Int| API 错误码|
-|message | String| 错误信息|
-|original_response | Response | 原始返回结果|
-
-示例代码：
-
-```ruby
-src_path= "/data/test.mp4"
-dst_path = "/myFolder/test.mp4"
-result = QcloudCos.upload_slice(dst_path, src_path)
-```
-
 #### 查看文件和文件夹数目
 
 1.  接口说明
@@ -753,9 +707,380 @@ API 请求错误，则抛出 RequestError 异常
 ```ruby
 path = "/myFolder/test.mp4"
 result = QcloudCos.public_url(path)
-```
+```
+
+
+## 分片上传
+
+分片上传在大文件上传和断点续传方面有很大的作用。我们主要提供了三个接口来帮助你完成上传。
+
+### 大文件分片上传
+
+1.  接口说明
+
+ 用于较大文件的上传，调用者可以通过此接口上传较大文件并获得文件的url。
+ 该接口还还支持断点续传，如果由于网络原因，导致了上传失败，只需要重试即可在自动在之前中断的位置继续上传。
+ 
+ 如果你还需要更进一步的定制需求，可以使用更底层的接口：[init_slice_upload]() + [upload_part]()
+
+2.  方法
+
+ ```ruby
+ QcloudCos.upload_slice(dst_path, src_path, options = {}, &block)
+ ```
+
+3.  参数和返回值
+
+参数说明：
+
+
+|参数名|类型 |必须 |默认值 |参数描述|
+|-----|----|-----|------|-------|
+| dst_path | String|是  |无 |文件在COS服务端的全路径，不包括/appid/bucketname|
+| src_path | String  |是 |无 |本地要上传文件的全路径|
+| block | Blockk  |否 |无 |如果需要显示进度，可以传递一个 Block，Block 需要接受一个参数，是 0~1 的一个小数，表示当前进度|
+| options | Hash | 否 | 无 | 额外参数
+| options['bucket'] | String| 否 | 配置的默认 bucket | Bucket 名称|
+| options['biz_attr'] | String| 否 | 无 | 文件属性，业务端自己维护 |
+| options['slice_size'] |Integer    |否 | 3M|分片大小，用户可以根据网络状况自行设置|
+| options['session']    |String |否 |null   |如果是断点续传, 则带上(唯一标识此文件传输过程的id, 由后台下发, 调用方透传)|
+
+
+返回值, Hash:
+
+
+|参数名 |类型 |必然返回 |参数描述 |
+|------|----|--------|--------|
+|code |Integer |是 |错误码，成功时为0|
+|message |String |是 |错误信息|
+|data |Array  |是 |返回数据|
+|data['access_url'] | String| 是    |生成的文件下载url|
+|data['url']    |String |是 |操作文件的url|
+|data['resource_path']  |String |是 |资源路径. 格式:/appid/bucket/xxx|
+
+API 请求错误，则抛出 RequestError 异常
+
+
+|参数名 |类型 |参数描述 |
+|------|----|--------|
+|code | Int| API 错误码|
+|message | String| 错误信息|
+|original_response | Response | 原始返回结果|
+
+示例代码：
+
+```ruby
+src_path= "/data/test.mp4"
+dst_path = "/myFolder/test.mp4"
+result = QcloudCos.upload_slice(dst_path, src_path)
+result = QcloudCos.upload_slice(dst_path, src_path) do |pr|
+  puts "uploaded #{pr * 100}%"
+end
+```
+
+### 分片上传初始化
+
+1.  接口说明
+
+ 初始化分片上传，正常会返回分片上传 session ID。
+ 
+ 注意：
+ 
+ + 如果该文件 sha 值已存在，则直接返回成功，你可以根据结果中是否包含 data['url'] 判断。
+ + 如果该文件上次分片上传没有成功，data['offset'] 表示了上次上传的位置，你可以从该位置开始上传。
+ + 如果想断点续传，则需要传递上一次 session ID.
+
+2.  方法
+
+ ```ruby
+ QcloudCos.init_slice_upload(path, filesize, sha, options = {})
+ ```
+
+3.  参数和返回值
+
+参数说明：
+
+
+|参数名|类型 |必须 |默认值 |参数描述|
+|-----|----|-----|------|-------|
+| path | String|是  |无 |文件在COS服务端的全路径，不包括/appid/bucketname|
+| filesize | Integer  |是 |无 |本地要上传文件大小|
+| sha | String  |是 |无 |本地要上传文件 sha1 值 |
+| options | Hash | 否 | 无 | 额外参数
+| options['bucket'] | String| 否 | 配置的默认 bucket | Bucket 名称|
+| options['biz_attr'] | String| 否 | 无 | 文件属性，业务端自己维护 |
+| options['slice_size'] |Integer    |否 | 3M|分片大小，用户可以根据网络状况自行设置|
+| options['session']    |String |否 |null   |如果是断点续传, 则带上(唯一标识此文件传输过程的id, 由后台下发, 调用方透传)|
+
+
+返回值, Hash:
+
+
+|参数名 |类型 |必然返回 |参数描述 |
+|------|----|--------|--------|
+|code |Integer |是 |错误码，成功时为0|
+|message |String |是 |错误信息|
+|data |Hash  |是 |返回数据|
+|data['access_url'] | String| 否    |生成的文件下载url|
+|data['url']    |String |否 |操作文件的url|
+|data['resource_path']  |String |否 |资源路径. 格式:/appid/bucket/xxx|
+
+API 请求错误，则抛出 RequestError 异常
+
+
+|参数名 |类型 |参数描述 |
+|------|----|--------|
+|code | Int| API 错误码|
+|message | String| 错误信息|
+|original_response | Response | 原始返回结果|
+
+示例代码：
+
+```ruby
+file = File.new("/data/test.mp4")
+filesize = file.size
+sha = Digest::SHA1.file('/data/test.mp4').hexdigest
+dst_path = "/myFolder/test.mp4"
+result = QcloudCos.init_slice_upload(dst_path, filesize, sha)  # { data: { session: 'dsfasfda' }
+```
+
+### 分片上传数据
+
+1.  接口说明
+
+ 分片上传数据，初始化之后可以分片上传数据，文件上传成功会返回文件的 url。
+ 
+2.  方法
+
+ ```ruby
+ QcloudCos.upload_part(path, session, offset, content, options = {})
+ ```
+
+3.  参数和返回值
+
+参数说明：
+
+
+|参数名|类型 |必须 |默认值 |参数描述|
+|-----|----|-----|------|-------|
+| path | String|是  |无 |文件在COS服务端的全路径，不包括/appid/bucketname|
+| session | Integer  |是 |无 |本次分片上传的 session ID, 初始化的时候会返回|
+| offset | String  |是 |无 |本地要上传的位移|
+| content | String  |是 |无 |本地要上传的内容 |
+| options | Hash | 否 | 无 | 额外参数
+| options['bucket'] | String| 否 | 配置的默认 bucket | Bucket 名称|
+
+
+返回值, Hash:
+
+
+|参数名 |类型 |必然返回 |参数描述 |
+|------|----|--------|--------|
+|code |Integer |是 |错误码，成功时为0|
+|message |String |是 |错误信息|
+|data |Hash  |是 |返回数据|
+|data['access_url'] | String| 否    |生成的文件下载url|
+|data['url']    |String |否 |操作文件的url|
+|data['resource_path']  |String |否 |资源路径. 格式:/appid/bucket/xxx|
+
+API 请求错误，则抛出 RequestError 异常
+
+
+|参数名 |类型 |参数描述 |
+|------|----|--------|
+|code | Int| API 错误码|
+|message | String| 错误信息|
+|original_response | Response | 原始返回结果|
+
+示例代码：
+
+```ruby
+session = 'dsfasfda'
+result = QcloudCos.upload_part(dst_path, session, 100, 'Hello')
+```
+
+## 命令行工具
+
+为了更方便地管理你的 COS，我们提供了命令行工具。
+
+我们主要提供了五个基本命令： info, list, upload, download, remove 来完成你的操作
+
+```
+$ qcloud-cos help
+
+NAME:
+
+    qcloud-cos
+
+  DESCRIPTION:
+
+    command-line tool for Qcloud COS
+
+  COMMANDS:
+        
+    config   Init config, eg: qcloud-cos config         
+    download Download objects from COS          
+    help     Display global or [command] help documentation             
+    info     Obtain information         
+    list     List objects under [dest_path]             
+    remove   Remove objects from COS            
+    upload   Upload file or folder to COS       
+
+  GLOBAL OPTIONS:
+        
+    -h, --help 
+        Display help documentation
+        
+    -v, --version 
+        Display version information
+        
+    -t, --trace 
+        Display backtrace when an error occurs
+```
+
+### 命令行配置
+
+在使用之前，你需要先做一些配置，最快速的方式是使用 `qcloud-cos config` 命令:
+
+```
+$ qcloud-cos config
+Qcloud COS APP ID: 
+Qcloud COS Secret ID: 
+Qcloud COS Secret Key: 
+Default Qcloud COS Endpoint [http://web.file.myqcloud.com/files/v1/]: 
+Default Qcloud COS Bucket: 
+```
+
+它会自动在当前目录下生成一个 `.qcloud-cos.yml` 配置文件。
+
+如果不使用配置文件，你也可以使用环境变量：
+
+```
+export QCLOUD_COS_APP_ID='<your-app-id>'
+export QCLOUD_COS_SECRET_ID='<your-secret-id>'
+export QCLOUD_COS_SECRET_KEY='<your-secret-key>'
+export QCLOUD_COS_ENDPOINT='http://web.file.myqcloud.com/files/v1/'
+export QCLOUD_COS_BUCKET='<your-bucket-name>'
+export QCLOUD_COS_SSL_CA_FILE='<your-ssl-ca-file-path>'
+```
+
+***注意：环境变量会覆盖配置文件中的设置***
+
+
+### info
+
+查看 Bucket，文件或者文件夹信息
+
+基本用法： `qcloud-cos info [options] [dest_path]`
+
+使用范例：
+
+```
+# 查看 Bucket 信息
+$ qcloud-cos info
+
+# 查看 /production.log 信息  
+$ qcloud-cos info /production.log
+
+# 查看 /test/ 信息
+$ qcloud-cos info /test/
+
+# 查看 bucket2 上的 /production.log 信息
+$ qcloud-cos info --bucket bucket2 /production.log 
+```
+
+### list
+
+列出文件或者文件夹
+
+基本用法： `qcloud-cos list [options] [dest_path]`
+
+使用范例：
+
+```
+# 列出 / 下面的所有对象
+$ qcloud-cos list 
+
+# 列出 /test/ 下面的所有对象
+$ qcloud-cos list /test/ 
+
+# 列出 /test/ 下面的前 10 个对象
+$ qcloud-cos list --num 10 /test/ 
+
+# 列出 bucket2 的 /test/ 下面的所有对象
+$ qcloud-cos list --bucket bucket2 /test/ 
+```
+
+### upload
+
+上传文件或者目录到 COS
+
+基本用法： `qcloud-cos upload [options] file [dest_path]`
+
+使用范例：
+
+```
+# 把 production.log 上传到 /
+$ qcloud-cos upload production.log 
+
+# 把 production.log 上传到 /data/ 下面
+$ qcloud-cos upload production.log /data/ 
+
+# 把 ./test/ 整个文件夹上传到 /data/ 下面
+$ qcloud-cos upload test/ /data/  
+
+# 把 ./test/ 整个文件夹上传到 bucket2 的 /data/ 下面
+$ qcloud-cos upload --bucket bucket2 test/ /data/  
+```
+
+### download
+
+下载文件或者目录
+
+基本用法： `qcloud-cos download [options] dest_path [save_path]`
+
+使用范例：
+
+```
+# 把 /data/production.log 下载到当前目录
+$ qcloud-cos download /data/production.log 
+
+# 把 /data/production.log 下载到 ./data/ 下
+$ qcloud-cos download /data/production.log ./data   
+      
+# 把 /data/test/ 整个目录下载并保存到 ./data/ 目录下面
+$ qcloud-cos download /data/test/ ./data
+        
+# 把 bucket2 下的 /data/test/ 整个目录下载并保存到 ./data/ 下面
+$ qcloud-cos download --bucket bucket2 /data/test/ ./data
+```
+
+
+### remove
+
+删除目录或者文件夹
+
+基本用法： `qcloud-cos remove [options] dest_path`
+
+使用范例：
+
+```
+# 删除文件/data/production.log
+$ qcloud-cos remove /data/production.log
+        
+# 删除目录 /data/test/， 目录非空会失败
+$ qcloud-cos remove /data/test/
+        
+# 级联删除目录 /data/test/
+$ qcloud-cos remove --recursive /data/test/
+        
+# 删除 bucket2 下面的目录 /data/test/
+$ qcloud-cos download --bucket bucket2 /data/test/
+```
+
+
 
 ## 其它资源
 
-+ [RDoc 文档](http://www.rubydoc.info/gems/qcloud_cos/0.1.0)
++ [RDoc 文档](http://www.rubydoc.info/gems/qcloud_cos/0.3.0)
 + [腾讯 COS 详细文档](http://www.qcloud.com/doc/product/227/%E4%BA%A7%E5%93%81%E4%BB%8B%E7%BB%8D)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: qcloud_cos
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0.pre
 platform: ruby
 authors:
 - Newell Zhu
 autorequire: 
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2016-01-29 00:00:00.000000000 Z
+date: 2016-01-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -52,6 +52,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: commander
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: awesome_print
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -153,7 +181,8 @@ dependencies:
 description: Ruby SDK For QCloud COS, Enjoy it!
 email:
 - zlx.star@gmail.com
-executables: []
+executables:
+- qcloud-cos
 extensions: []
 extra_rdoc_files: []
 files:
@@ -165,10 +194,12 @@ files:
 - README.md
 - Rakefile
 - bin/console
+- bin/qcloud-cos
 - bin/setup
 - lib/qcloud_cos.rb
 - lib/qcloud_cos/api.rb
 - lib/qcloud_cos/authorization.rb
+- lib/qcloud_cos/cli.rb
 - lib/qcloud_cos/configuration.rb
 - lib/qcloud_cos/convenient_api.rb
 - lib/qcloud_cos/error.rb
@@ -195,9 +226,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.2.0