file Namespace Reference

Namespaces
namespace	internal

Typedefs
using	Options = int

Functions
absl::Status	Open (absl::string_view filename, absl::string_view mode, File **f, Options options)
	As of 2016-01, these methods can only be used with flags = file::Defaults().
File *	OpenOrDie (absl::string_view filename, absl::string_view mode, Options options)
absl::StatusOr< std::string >	GetContents (absl::string_view path, Options options)
absl::Status	GetContents (absl::string_view filename, std::string *output, Options options)
absl::Status	WriteString (File *file, absl::string_view contents, Options options)
absl::Status	SetContents (absl::string_view filename, absl::string_view contents, Options options)
bool	ReadFileToString (absl::string_view file_name, std::string *output)
bool	WriteStringToFile (absl::string_view data, absl::string_view file_name)
bool	ReadFileToProto (absl::string_view file_name, google::protobuf::Message *proto)
void	ReadFileToProtoOrDie (absl::string_view file_name, google::protobuf::Message *proto)
bool	WriteProtoToASCIIFile (const google::protobuf::Message &proto, absl::string_view file_name)
void	WriteProtoToASCIIFileOrDie (const google::protobuf::Message &proto, absl::string_view file_name)
bool	WriteProtoToFile (const google::protobuf::Message &proto, absl::string_view file_name)
void	WriteProtoToFileOrDie (const google::protobuf::Message &proto, absl::string_view file_name)
absl::Status	GetTextProto (absl::string_view filename, google::protobuf::Message *proto, Options options)
absl::Status	SetTextProto (absl::string_view filename, const google::protobuf::Message &proto, Options options)
absl::Status	GetBinaryProto (const absl::string_view filename, google::protobuf::Message *proto, Options options)
absl::Status	SetBinaryProto (absl::string_view filename, const google::protobuf::Message &proto, Options options)
absl::Status	Delete (absl::string_view path, Options options)
absl::Status	Exists (absl::string_view path, Options options)
Options	Defaults ()
template<typename T >
absl::StatusOr< T >	GetTextProto (absl::string_view filename, Options options)
template<typename T >
absl::StatusOr< T >	GetBinaryProto (absl::string_view filename, Options options)
absl::Status	Match (std::string_view pattern, std::vector< std::string > *result, const file::Options &options)
absl::Status	IsDirectory (std::string_view path, const file::Options &options)
absl::Status	RecursivelyCreateDir (std::string_view path, const file::Options &options)
std::string	JoinPath (absl::string_view path1, absl::string_view path2)
bool	IsAbsolutePath (absl::string_view path)
	Return true if path is absolute.
std::string	AddSlash (absl::string_view path)
absl::string_view	Dirname (absl::string_view path)
absl::string_view	Basename (absl::string_view path)
std::pair< absl::string_view, absl::string_view >	SplitPath (absl::string_view path)
absl::string_view	Stem (absl::string_view path)
absl::string_view	Extension (absl::string_view path)
std::string	CleanPath (const absl::string_view unclean_path)
std::string	CollapseSlashes (absl::string_view path)
std::string	JoinPath ()
std::string	JoinPath (absl::string_view path)
template<typename... T>
std::string	JoinPath (absl::string_view path1, absl::string_view path2, absl::string_view path3, const T &... args)
template<typename... T>
std::string	JoinPathRespectAbsolute (const T &... args)
std::string	TempFile (absl::string_view prefix)

Detailed Description

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.

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. A set of file pathname manipulation routines. Calls to each of the following functions assume their input is well-formed (for some currently nebulous definition of the word). You can get a well-formed path by using file::CleanPath(), and future versions of this API may require this.

This collection is largely modelled on Python's os.path module. Filenames are restricted to ASCII characters in most filesystems at Google. There are additional restrictions and quirks for some filesystems. For example, see file/colossus/base/cfs_path.h for filename character set restrictions for Colossus.

One additional filename quirk: for legacy reasons, filenames of the forms: localhost:pathname hostname:pathname hostname.domainname:pathname will all route to ///<file/localfile and use only the pathname part, so long as hostname/hostname.domainname refer to the current host. The primary implication of this behavior is that filenames that do not begin with a leading '/' and that have a ':' before any '/' may be interpreted differently depending on the hostname where they are evaluated.

Typedef Documentation

Options

using file::Options = int

Definition at line 107 of file file.h.

Function Documentation

AddSlash()

std::string file::AddSlash

(

absl::string_view

path

)

If path is non-empty and doesn't already end with a slash, append one to the end.

Definition at line 96 of file path.cc.

Basename()

absl::string_view file::Basename

(

absl::string_view

path

)

Returns the part of the path after the final "/". If there is no "/" in the path, the result is the same as the input.

Note

this function's behavior differs from the Unix basename command if path ends with "/". For such paths, this function returns the empty string.

Definition at line 109 of file path.cc.

CleanPath()

std::string file::CleanPath

(

absl::string_view

path

)

---

Path cleaning utilities.

Note

FileFactory implementations should probably clean paths they receive as needed. They should only clean the pieces of path they understand (in the case of wrapping-functionality like /readaheadfile or /encryptedfile). It cannot universally be done cleanly with common logic.

Common sorts of surprises along those lines:

• file/zipfile allows '/' and '.' in file names (and has no directory structure).
• Colossus probably shouldn't collapse "ttl=8/../" into "/" Collapse duplicate "/"s, resolve ".." and "." path elements, remove trailing "/".

Note

This respects relative vs. absolute paths, but does not invoke any system calls (getcwd(2)) in order to resolve relative paths wrt actual working directory. That is, this is purely a string manipulation, completely independent of process state.

Check for absolute path and determine initial backtrack limit.

Process all parts

1dot ".<whateverisnext>", check for END or SEP.

2dot END or SEP (".." | "../<whateverisnext>").

We can backtrack the previous part

Empty.

Failed to backtrack and we can't skip it either. Rewind and copy.

We can never backtrack over a copied "../" part so set new limit.

If not parsed, copy entire part until the next SEP or EOS.

Skip consecutive SEP occurrences

Calculate and check the length of the cleaned path.

Remove trailing '/' except if it is root path ("/" ==> path_length := 1)

The cleaned path is empty; assign "." as per the spec.

Definition at line 137 of file path.cc.

CollapseSlashes()

std::string file::CollapseSlashes

(

absl::string_view

path

)

Similar to CleanPath, but only collapses duplicate "/"s. (Some filesystems allow "." and ".." in filenames.)

Definition at line 218 of file path.cc.

Defaults()

Options file::Defaults ( )

inline

Definition at line 109 of file file.h.

Delete()

absl::Status file::Delete	(	absl::string_view	path,
		Options	options )

Definition at line 371 of file file.cc.

Dirname()

absl::string_view file::Dirname

(

absl::string_view

path

)

Returns the part of the path before the final "/", EXCEPT:

• If there is a single leading "/" in the path, the result will be the leading "/".
• If there is no "/" in the path, the result is the empty prefix of the input string.

Definition at line 105 of file path.cc.

Exists()

absl::Status file::Exists	(	absl::string_view	path,
		Options	options )

Definition at line 380 of file file.cc.

Extension()

absl::string_view file::Extension

(

absl::string_view

path

)

Returns the part of the basename of path after the final ".". If there is no "." in the basename, the result is empty.

Definition at line 133 of file path.cc.

GetBinaryProto() [1/2]

template<typename T >

absl::StatusOr< T > file::GetBinaryProto	(	absl::string_view	filename,
		Options	options )

Definition at line 134 of file file.h.

GetBinaryProto() [2/2]

absl::Status file::GetBinaryProto	(	const absl::string_view	filename,
		google::protobuf::Message *	proto,
		Options	options )

Definition at line 348 of file file.cc.

GetContents() [1/2]

absl::Status file::GetContents	(	absl::string_view	filename,
		std::string *	output,
		Options	options )

Definition at line 201 of file file.cc.

GetContents() [2/2]

absl::StatusOr< std::string > file::GetContents	(	absl::string_view	path,
		Options	options )

Definition at line 191 of file file.cc.

GetTextProto() [1/2]

absl::Status file::GetTextProto	(	absl::string_view	filename,
		google::protobuf::Message *	proto,
		Options	options )

Definition at line 327 of file file.cc.

GetTextProto() [2/2]

template<typename T >

absl::StatusOr< T > file::GetTextProto	(	absl::string_view	filename,
		Options	options )

Definition at line 123 of file file.h.

IsAbsolutePath()

bool file::IsAbsolutePath

(

absl::string_view

path

)

Return true if path is absolute.

Definition at line 92 of file path.cc.

IsDirectory()

absl::Status file::IsDirectory	(	std::string_view	path,
		const file::Options &	options )

Definition at line 64 of file filesystem.cc.

JoinPath() [1/4]

std::string file::JoinPath ( )

inline

Join multiple paths together. JoinPath and JoinPathRespectAbsolute have slightly different semantics. JoinPath unconditionally joins all paths together, whereas JoinPathRespectAbsolute ignores any segments prior to the last absolute path. For example:

Arguments | JoinPath | JoinPathRespectAbsolute ------------------------—+------------------—+--------------------— 'foo', 'bar' | foo/bar | foo/bar '/foo', 'bar' | /foo/bar | /foo/bar '/foo/', 'bar' | /foo/bar | /foo/bar '/foo', '/bar' | /foo/bar | /bar '/foo/', '/bar' | /foo/bar | /bar '/foo', '/bar', '/baz' | /foo/bar/baz | /baz

The first path may be relative or absolute. All subsequent paths will be treated as relative paths, regardless of whether or not they start with a leading '/'. That is, all paths will be concatenated together, with the appropriate path separator inserted in between. Arguments must be convertible to absl::string_view.

Usage: string path = file::JoinPath("/cns", dirname, filename); string path = file::JoinPath(FLAGS_test_srcdir, filename);

0, 1, 2-path specializations exist to optimize common cases.

Definition at line 82 of file path.h.

JoinPath() [2/4]

std::string file::JoinPath ( absl::string_view path )

inline

Definition at line 83 of file path.h.

JoinPath() [3/4]

std::string file::JoinPath	(	absl::string_view	path1,
		absl::string_view	path2 )

40% of the time in JoinPath() is from calls with 2 arguments, so we specialize that case.

Definition at line 25 of file path.cc.

JoinPath() [4/4]

template<typename... T>

std::string file::JoinPath ( absl::string_view path1, absl::string_view path2, absl::string_view path3, const T &... args )

inline

Definition at line 88 of file path.h.

JoinPathRespectAbsolute()

template<typename... T>

std::string file::JoinPathRespectAbsolute ( const T &... args )

inline

Join multiple paths together, respecting intermediate absolute paths. All paths will be joined together, but if any of the paths is absolute (as defined by IsAbsolutePath()), all prior path segments will be ignored. This is the behavior of the old File::JoinPath(). Arguments must be convertible to absl::string_view.

Usage: string path = file::JoinPathRespectAbsolute("/cns", dirname, filename); string path = file::JoinPathRespectAbsolute(FLAGS_test_srcdir, filename);

Definition at line 104 of file path.h.

Match()

absl::Status file::Match	(	std::string_view	pattern,
		std::vector< std::string > *	result,
		const file::Options &	options )

Definition at line 33 of file filesystem.cc.

Open()

absl::Status file::Open	(	absl::string_view	filename,
		absl::string_view	mode,
		File **	f,
		Options	options )

As of 2016-01, these methods can only be used with flags = file::Defaults().

The caller should free the File after closing it by passing *f to delete.

Definition at line 170 of file file.cc.

OpenOrDie()

File * file::OpenOrDie	(	absl::string_view	filename,
		absl::string_view	mode,
		Options	options )

The caller should free the File after closing it by passing the returned pointer to delete.

Definition at line 182 of file file.cc.

ReadFileToProto()

bool file::ReadFileToProto	(	absl::string_view	file_name,
		google::protobuf::Message *	proto )

Attempt to decode ASCII before deciding binary. Do it in this order because it is much harder for a binary encoding to happen to be a valid ASCII encoding than the other way around. For instance "index: 1\n" is a valid (but nonsensical) binary encoding. We want to avoid printing errors for valid binary encodings if the ASCII parsing fails, and so specify a no-op error collector.

Re-parse the ASCII, just to show the diagnostics (we could also get them out of the ErrorCollector but this way is easier).

Definition at line 269 of file file.cc.

ReadFileToProtoOrDie()

void file::ReadFileToProtoOrDie	(	absl::string_view	file_name,
		google::protobuf::Message *	proto )

Definition at line 298 of file file.cc.

ReadFileToString()

bool file::ReadFileToString	(	absl::string_view	file_name,
		std::string *	output )

Definition at line 252 of file file.cc.

RecursivelyCreateDir()

absl::Status file::RecursivelyCreateDir	(	std::string_view	path,
		const file::Options &	options )

Definition at line 74 of file filesystem.cc.

SetBinaryProto()

absl::Status file::SetBinaryProto	(	absl::string_view	filename,
		const google::protobuf::Message &	proto,
		Options	options )

Definition at line 360 of file file.cc.

SetContents()

absl::Status file::SetContents	(	absl::string_view	filename,
		absl::string_view	contents,
		Options	options )

Definition at line 242 of file file.cc.

SetTextProto()

absl::Status file::SetTextProto	(	absl::string_view	filename,
		const google::protobuf::Message &	proto,
		Options	options )

Definition at line 337 of file file.cc.

SplitPath()

std::pair< absl::string_view, absl::string_view > file::SplitPath

(

absl::string_view

path

)

Return the parts of the path, split on the final "/". If there is no "/" in the path, the first part of the output is empty and the second is the input. If the only "/" in the path is the first character, it is the first part of the output.

Handle the case with no '/' in 'path'.

Handle the case with a single leading '/' in 'path'.

Definition at line 113 of file path.cc.

Stem()

absl::string_view file::Stem

(

absl::string_view

path

)

Returns the part of the basename of path prior to the final ".". If there is no "." in the basename, this is equivalent to file::Basename(path).

Definition at line 129 of file path.cc.

TempFile()

std::string file::TempFile

(

absl::string_view

prefix

)

Definition at line 25 of file temp_path.cc.

WriteProtoToASCIIFile()

bool file::WriteProtoToASCIIFile	(	const google::protobuf::Message &	proto,
		absl::string_view	file_name )

Definition at line 303 of file file.cc.

WriteProtoToASCIIFileOrDie()

void file::WriteProtoToASCIIFileOrDie	(	const google::protobuf::Message &	proto,
		absl::string_view	file_name )

Definition at line 310 of file file.cc.

WriteProtoToFile()

bool file::WriteProtoToFile	(	const google::protobuf::Message &	proto,
		absl::string_view	file_name )

Definition at line 315 of file file.cc.

WriteProtoToFileOrDie()

void file::WriteProtoToFileOrDie	(	const google::protobuf::Message &	proto,
		absl::string_view	file_name )

Definition at line 322 of file file.cc.

WriteString()

absl::Status file::WriteString	(	File *	file,
		absl::string_view	contents,
		Options	options )

Definition at line 231 of file file.cc.

WriteStringToFile()

bool file::WriteStringToFile	(	absl::string_view	data,
		absl::string_view	file_name )

Definition at line 256 of file file.cc.