1 # -*- coding: utf-8 -*- 2 # Copyright 2011 Google Inc. All Rights Reserved. 3 # Copyright 2011, Nexenta Systems Inc. 4 # 5 # Licensed under the Apache License, Version 2.0 (the "License"); 6 # you may not use this file except in compliance with the License. 7 # You may obtain a copy of the License at 8 # 9 # http://www.apache.org/licenses/LICENSE-2.0 10 # 11 # Unless required by applicable law or agreed to in writing, software 12 # distributed under the License is distributed on an "AS IS" BASIS, 13 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 # See the License for the specific language governing permissions and 15 # limitations under the License. 16 """Implementation of Unix-like cat command for cloud storage providers.""" 17 18 from __future__ import absolute_import 19 20 import re 21 22 from gslib.cat_helper import CatHelper 23 from gslib.command import Command 24 from gslib.command_argument import CommandArgument 25 from gslib.cs_api_map import ApiSelector 26 from gslib.exception import CommandException 27 from gslib.util import NO_MAX 28 29 _SYNOPSIS = """ 30 gsutil cat [-h] url... 31 """ 32 33 _DETAILED_HELP_TEXT = (""" 34 <B>SYNOPSIS</B> 35 """ + _SYNOPSIS + """ 36 37 38 <B>DESCRIPTION</B> 39 The cat command outputs the contents of one or more URLs to stdout. 40 It is equivalent to doing: 41 42 gsutil cp url... - 43 44 (The final '-' causes gsutil to stream the output to stdout.) 45 46 47 <B>WARNING: DATA INTEGRITY CHECKING NOT DONE</B> 48 The gsutil cat command does not compute a checksum of the downloaded data. 49 Therefore, we recommend that users either perform their own validation of the 50 output of gsutil cat or use gsutil cp or rsync (both of which perform 51 integrity checking automatically). 52 53 54 <B>OPTIONS</B> 55 -h Prints short header for each object. For example: 56 57 gsutil cat -h gs://bucket/meeting_notes/2012_Feb/*.txt 58 59 This would print a header with the object name before the contents 60 of each text object that matched the wildcard. 61 62 -r range Causes gsutil to output just the specified byte range of the 63 object. Ranges are can be of these forms: 64 65 start-end (e.g., -r 256-5939) 66 start- (e.g., -r 256-) 67 -numbytes (e.g., -r -5) 68 69 where offsets start at 0, start-end means to return bytes start 70 through end (inclusive), start- means to return bytes start 71 through the end of the object, and -numbytes means to return the 72 last numbytes of the object. For example: 73 74 gsutil cat -r 256-939 gs://bucket/object 75 76 returns bytes 256 through 939, while: 77 78 gsutil cat -r -5 gs://bucket/object 79 80 returns the final 5 bytes of the object. 81 """) 82 83 84 class CatCommand(Command): 85 """Implementation of gsutil cat command.""" 86 87 # Command specification. See base class for documentation. 88 command_spec = Command.CreateCommandSpec( 89 'cat', 90 command_name_aliases=[], 91 usage_synopsis=_SYNOPSIS, 92 min_args=1, 93 max_args=NO_MAX, 94 supported_sub_args='hr:', 95 file_url_ok=False, 96 provider_url_ok=False, 97 urls_start_arg=0, 98 gs_api_support=[ApiSelector.XML, ApiSelector.JSON], 99 gs_default_api=ApiSelector.JSON, 100 argparse_arguments=[ 101 CommandArgument.MakeZeroOrMoreCloudURLsArgument() 102 ] 103 ) 104 # Help specification. See help_provider.py for documentation. 105 help_spec = Command.HelpSpec( 106 help_name='cat', 107 help_name_aliases=[], 108 help_type='command_help', 109 help_one_line_summary='Concatenate object content to stdout', 110 help_text=_DETAILED_HELP_TEXT, 111 subcommand_help_text={}, 112 ) 113 114 # Command entry point. 115 def RunCommand(self): 116 """Command entry point for the cat command.""" 117 show_header = False 118 request_range = None 119 start_byte = 0 120 end_byte = None 121 if self.sub_opts: 122 for o, a in self.sub_opts: 123 if o == '-h': 124 show_header = True 125 elif o == '-r': 126 request_range = a.strip() 127 range_matcher = re.compile( 128 '^(?P<start>[0-9]+)-(?P<end>[0-9]*)$|^(?P<endslice>-[0-9]+)$') 129 range_match = range_matcher.match(request_range) 130 if not range_match: 131 raise CommandException('Invalid range (%s)' % request_range) 132 if range_match.group('start'): 133 start_byte = long(range_match.group('start')) 134 if range_match.group('end'): 135 end_byte = long(range_match.group('end')) 136 if range_match.group('endslice'): 137 start_byte = long(range_match.group('endslice')) 138 else: 139 self.RaiseInvalidArgumentException() 140 141 return CatHelper(self).CatUrlStrings(self.args, 142 show_header=show_header, 143 start_byte=start_byte, 144 end_byte=end_byte) 145
