Eiffeldoc: BASIC_DIRECTORY

+

Point of view

All features

expanded class BASIC_DIRECTORY

Summary

Very low-level basic tools for file-system directory handling and file path manipulation. This class intended to be platform independent as much as possible. In order to remove from the client side the burden of file path computation, this class tries to compute automatically the system file notation using argument(s) of some of the very first call(s). As soon as the system notation has been properly detected, the result is internally memorized for all objects of type BASIC_DIRECTORY in a common private buffer. Besides the low-level nature of operations one can found in this class, all file path manipulations are done in a smart way (except when the system file path notation has not been detected automatically, which is quite uncommon). As an example, even if the directory separator is internally detected, this information is _intentionally_ kept private to avoid low-level manipulation from the client side. Finally, this class is expanded in order to avoid as much as possible memory allocations.

Also consider high level facade class DIRECTORY if you don't want to deal directly with low level directory streams.

Direct parents: Insert list: ANY
Known children: Insert list: XDG

Overview

Features

{}

directory_stream: POINTER

This pointer memorize the current directory stream being scanned (used to compute is_connected).
current_entry: POINTER

When is_connected, memorize the current entry in the current directory_stream.

State of Current basic directory stream:

is_connected: BOOLEAN

Is Current connected to some directory stream ?
end_of_input: BOOLEAN

Is end of input reached ?

Connect and disconnect:

connect_to (directory_path: ABSTRACT_STRING)

Try to connect Current to some existing directory_path.
connect_with (some_path: ABSTRACT_STRING)

Try to connect Current to some directory using some_path which may be either an existing directory path or some arbitrary file path name.
connect_to_current_working_directory

Try to connect Current to the current working directory.
disconnect

Do not forget to call this feature when you have finished with some previously opened directory stream.

Scanning:

last_entry: STRING

Unique global buffer (once object) to get the last information computed by many routines of this class: read_entry, connect_with connect_to_current_working_directory, compute_parent_directory_of, ...
read_entry

Read the next entry name and update last_entry and end_of_input accordingly.

File path handling tools:

compute_parent_directory_of (some_path: ABSTRACT_STRING)

Using some_path (which may be either a file path or a directory path) tries to compute in the last_entry buffer the parent directory of some_path.
compute_subdirectory_with (parent_path: ABSTRACT_STRING, entry_name: ABSTRACT_STRING)

Try to compute in the last_entry buffer the new subdirectory path obtained when trying to concatenate smartly parent_path with some entry_name.
compute_file_path_with (parent_path: ABSTRACT_STRING, file_name: ABSTRACT_STRING)

Try to compute in the last_entry buffer the new file path obtained when trying to concatenate smartly parent_path with some file_name.
compute_absolute_file_path_with (path: ABSTRACT_STRING)

Try to compute an absolute path equivalent to path and store it in last_entry.
compute_short_name_of (path: ABSTRACT_STRING)

Try to find the short name of the file or directory given by its path and store it in last_entry.
valid_path (path: ABSTRACT_STRING): BOOLEAN

Is the syntax of path valid for the system notation?
change_current_working_directory (directory_path: ABSTRACT_STRING)

Try to change the current working directory using some directory_path.
current_working_directory: FIXED_STRING

The current working directory.
ensure_system_notation
require_system_notation: BOOLEAN

Same as ensure_system_notation, useful for contracts

Disk modification:

create_new_directory (directory_path: ABSTRACT_STRING): BOOLEAN

Try to create a new directory using the directory_path name.
remove_directory (directory_path: ABSTRACT_STRING): BOOLEAN

Try to remove directory directory_path which must be empty.
remove_files_of (directory_path: ABSTRACT_STRING)

Try to remove all files (not subdirectories) of directory specified by directory_path.
remove_recursively (directory_path: ABSTRACT_STRING): BOOLEAN

Try to remove all files and all subdirectories of directory specified by directory_path.

Miscellaneous:

{DIRECTORY_NOTATION_HANDLER}

system_notation_buffer: REFERENCE[DIRECTORY_NOTATION]

Unique common buffer to memorize the system path notation.
system_notation_detected: BOOLEAN
unix_notation: BOOLEAN
The Unix like file path notation looks like:
```
  /LibertyEiffel/sys/system.se
```
windows_notation: BOOLEAN
The Windows like file path notation looks like:
```
  C:\LibertyEiffel\sys\system.se
```
cygwin_notation: BOOLEAN
The Cygwin like file path notation looks like:
```
  //C/LibertyEiffel/sys/system.se
```
set_notation_using (some_path: ABSTRACT_STRING)

Try to detect automatically the file system notation.
reset_notation_using (some_path: ABSTRACT_STRING)

Try to detect automatically the file system notation.
reset_notation

{}

tmp_path: STRING
directory_open (path_pointer: POINTER): POINTER

Try to open some existing directory using path.
directory_read_entry (dirstream: POINTER): POINTER

Read an return a new entry using the directory handle dirstream obtained with function basic_directory_open.
directory_get_entry_name (entry: POINTER): POINTER

Read an return a new entry using the directory handle dirstream obtained with function basic_directory_open.
directory_close (dirstream: POINTER): BOOLEAN

Try to close some opened dirstream directory.
directory_current_working_directory: POINTER

Try to get the current working directory path.
directory_chdir (destination: POINTER): BOOLEAN

Try to change the current working directory using destination.
directory_mkdir (directory_path: POINTER): BOOLEAN

Try to create a new directory using directory_path.
directory_rmdir (directory_path: POINTER): BOOLEAN

Try to remove directory_path.

directory_stream: POINTER

writable attribute

{}

This pointer memorize the current directory stream being scanned (used to compute is_connected).

current_entry: POINTER

writable attribute

{}

When is_connected, memorize the current entry in the current directory_stream.

is_connected: BOOLEAN

effective function

Is Current connected to some directory stream ?

end_of_input: BOOLEAN

effective function

Is end of input reached ?

require

is_connected

connect_to (directory_path: ABSTRACT_STRING)

effective procedure

Try to connect Current to some existing directory_path.

After this call, the client supposed to use is_connected to check that the stream is ready to be used.

require

not is_connected
not directory_path.is_empty
common_buffer_protection: last_entry /= directory_path

ensure

is_connected implies not end_of_input

connect_with (some_path: ABSTRACT_STRING)

effective procedure

Try to connect Current to some directory using some_path which may be either an existing directory path or some arbitrary file path name.

When some_path is the path of some readable existing directory, this directory is opened and the effect of connect_with is equivalent to connect_to. When some_path is not an existing readable directory path, connect_with tries to open the directory which may contains some_path viewed as a file path name. After this call, the client is supposed to use is_connected to check that the stream is ready to be used and the last_entry buffer to know about the corresponding opened directory path. Whatever the result, some_path is left unchanged.

require

not is_connected
not some_path.is_empty
common_buffer_protection: last_entry /= some_path

ensure

is_connected implies not end_of_input

connect_to_current_working_directory

effective procedure

Try to connect Current to the current working directory.

After this call, the client is supposed to use is_connected to check that the stream is ready to be used and the last_entry buffer to know about the name of the current working directory.

require

not is_connected

ensure

is_connected implies not end_of_input

disconnect

effective procedure

Do not forget to call this feature when you have finished with some previously opened directory stream.

require

is_connected

ensure

not is_connected

last_entry: STRING

once function

Unique global buffer (once object) to get the last information computed by many routines of this class: read_entry, connect_with connect_to_current_working_directory, compute_parent_directory_of, ...

read_entry

effective procedure

Read the next entry name and update last_entry and end_of_input accordingly.

require

is_connected
not end_of_input

compute_parent_directory_of (some_path: ABSTRACT_STRING)

effective procedure

Using some_path (which may be either a file path or a directory path) tries to compute in the last_entry buffer the parent directory of some_path.

When some_path is a path with no parent directory, the last_entry buffer is_empty after this call. This operation does not perform any disk access.

require

not some_path.is_empty
common_buffer_protection: last_entry /= some_path

compute_subdirectory_with (parent_path: ABSTRACT_STRING, entry_name: ABSTRACT_STRING)

effective procedure

Try to compute in the last_entry buffer the new subdirectory path obtained when trying to concatenate smartly parent_path with some entry_name.

When this fails the last_entry buffer is_empty after this call. This operation does not perform any disk access. Whatever the result, parent_path and entry_name are left unchanged.

require

not parent_path.is_empty
not entry_name.is_empty
common_buffer_protection1: last_entry /= parent_path
common_buffer_protection2: last_entry /= entry_name

compute_file_path_with (parent_path: ABSTRACT_STRING, file_name: ABSTRACT_STRING)

effective procedure

Try to compute in the last_entry buffer the new file path obtained when trying to concatenate smartly parent_path with some file_name.

When this fails the last_entry buffer is_empty after this call. This operation does not perform any disk access. Whatever the result, parent_path and file_name are left unchanged.

require

not parent_path.is_empty
not file_name.is_empty
common_buffer_protection1: last_entry /= parent_path
common_buffer_protection2: last_entry /= file_name

compute_absolute_file_path_with (path: ABSTRACT_STRING)

effective procedure

Try to compute an absolute path equivalent to path and store it in last_entry.

When this fails the last_entry buffer is_empty after this call. This operation does not perform any disk access. Whatever the result, path is left unchanged.

require

valid_path(path)
common_buffer_protection: last_entry /= path

ensure

last_entry.is_empty or else system_notation.is_absolute_path(last_entry.out)

compute_short_name_of (path: ABSTRACT_STRING)

effective procedure

Try to find the short name of the file or directory given by its path and store it in last_entry.

When this fails the last_entry buffer is_empty after the call. This operation does not perform any disk access. Whatever the result, path is left unchanged.

valid_path (path: ABSTRACT_STRING): BOOLEAN

effective function

Is the syntax of path valid for the system notation?

ensure

system_notation_detected implies Result = system_notation.is_valid_path(path.out)
not system_notation_detected implies Result = not path.is_empty

change_current_working_directory (directory_path: ABSTRACT_STRING)

effective procedure

Try to change the current working directory using some directory_path.

 When the operation
possible, the last_entry buffer is updated with the new current working directory path,
otherwise, when the modification is not possible the last_entry buffer is_empty after this
call. Whatever the result, directory_path is left unchanged.

require

not is_connected
common_buffer_protection1: last_entry /= directory_path

ensure

not is_connected

current_working_directory: FIXED_STRING

effective function

The current working directory.

Always returns the same once STRING.

ensure_system_notation

once procedure

ensure

system_notation /= Void

require_system_notation: BOOLEAN

once function

Same as ensure_system_notation, useful for contracts

ensure

system_notation /= Void
Result

create_new_directory (directory_path: ABSTRACT_STRING): BOOLEAN

effective function

Try to create a new directory using the directory_path name.

Returns True on success.

require

not is_connected

ensure

not is_connected

remove_directory (directory_path: ABSTRACT_STRING): BOOLEAN

effective function

Try to remove directory directory_path which must be empty.

Returns True on success.

require

not is_connected

ensure

not is_connected

remove_files_of (directory_path: ABSTRACT_STRING)

effective procedure

Try to remove all files (not subdirectories) of directory specified by directory_path.

require

not is_connected

ensure

not is_connected

remove_recursively (directory_path: ABSTRACT_STRING): BOOLEAN

effective function

Try to remove all files and all subdirectories of directory specified by directory_path.

require

not is_connected

ensure

not is_connected

is_case_sensitive: BOOLEAN

effective function

system_notation: DIRECTORY_NOTATION

effective function

system_notation_buffer: REFERENCE[DIRECTORY_NOTATION]

once function

{DIRECTORY_NOTATION_HANDLER}

Unique common buffer to memorize the system path notation.

system_notation_detected: BOOLEAN

effective function

{DIRECTORY_NOTATION_HANDLER}

unix_notation: BOOLEAN

effective function

{DIRECTORY_NOTATION_HANDLER}

The Unix like file path notation looks like:

  /LibertyEiffel/sys/system.se

windows_notation: BOOLEAN

effective function

{DIRECTORY_NOTATION_HANDLER}

The Windows like file path notation looks like:

  C:\LibertyEiffel\sys\system.se

cygwin_notation: BOOLEAN

effective function

{DIRECTORY_NOTATION_HANDLER}

The Cygwin like file path notation looks like:

  //C/LibertyEiffel/sys/system.se

set_notation_using (some_path: ABSTRACT_STRING)

effective procedure

{DIRECTORY_NOTATION_HANDLER}

Try to detect automatically the file system notation.

require

not some_path.is_empty
not system_notation_detected

reset_notation_using (some_path: ABSTRACT_STRING)

effective procedure

{DIRECTORY_NOTATION_HANDLER}

Try to detect automatically the file system notation.

reset_notation

effective procedure

{DIRECTORY_NOTATION_HANDLER}

tmp_path: STRING

once function

{}

directory_open (path_pointer: POINTER): POINTER

{}

Try to open some existing directory using path.

When Result is_not_null, the directory correctly opened and Result is a valid handle for this directory. Using Result, one can then scan the content of the directory using function basic_directory_read_entry and basic_directory_get_entry_name. Finally, a is_not_null directory must be closed using function basic_directory_close.

require

path_pointer.is_not_null

directory_read_entry (dirstream: POINTER): POINTER

{}

Read an return a new entry using the directory handle dirstream obtained with function basic_directory_open.

When there is no more entry, the Result becomes is_null.

require

dirstream.is_not_null

directory_get_entry_name (entry: POINTER): POINTER

{}

Read an return a new entry using the directory handle dirstream obtained with function basic_directory_open.

When there is no more entry, the Result becomes is_null.

require

entry.is_not_null

directory_close (dirstream: POINTER): BOOLEAN

{}

Try to close some opened dirstream directory.

A True result indicates that the directory correctly closed.

require

dirstream.is_not_null

directory_current_working_directory: POINTER

{}

Try to get the current working directory path.

directory_chdir (destination: POINTER): BOOLEAN

{}

Try to change the current working directory using destination.

directory_mkdir (directory_path: POINTER): BOOLEAN

{}

Try to create a new directory using directory_path.

directory_rmdir (directory_path: POINTER): BOOLEAN

{}

Try to remove directory_path.