Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Edit 'file-system' module #1510

Merged
merged 2 commits into from
Jun 29, 2023
Merged

Docs: Edit 'file-system' module #1510

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2e4a1a3
Docs: Edit 'file-system' module
fraya Jun 29, 2023
9484660
Refine 'locator' keyword description
fraya Jun 29, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions documentation/library-reference/source/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,10 @@
sys.path.insert(0, os.path.abspath('../..'))
from shared_sphinx_config import *

extensions = [
'sphinx.ext.graphviz',
'dylan.domain'
]

# -- General configuration -----------------------------------------------------

Expand Down
162 changes: 115 additions & 47 deletions documentation/library-reference/source/system/file-system.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,12 +91,70 @@ or a file within the file system.
- :class:`<file-system-file-locator>`
- :class:`<file-system-directory-locator>`

.. graphviz::
:caption: File system locator class diagram. Dashed boxes are
classes from module `locators`.

digraph G {
fontname="Arial,sans-serif";
node [shape=box, color=gray];

physical_locator [label="<physical-locator>\noa", style=dashed];
file_locator [label="<file-locator>\noa", style=dashed];
directory_locator [label="<directory-locator>\noa",style=dashed];
file_system_locator [label="<file-system-locator>\noa", style=bold, color="#17594A"];
file_system_file_locator [label="<file-system-file-locator>", style=bold, color="#17594A"];
file_system_directory_locator [label="<file-system-directory-locator>", style=bold, color="#17594A"];

physical_locator -> file_system_locator;
physical_locator -> directory_locator;
physical_locator -> file_locator;
file_system_locator -> file_system_file_locator;
file_locator -> file_system_file_locator;
file_system_locator -> file_system_directory_locator;
directory_locator -> file_system_directory_locator;
}

On Posix systems:

- :class:`<posix-file-system-locator>`
- :class:`<posix-directory-locator>`
- :class:`<posix-file-locator>`

.. graphviz::
:caption: Posix file system hierarchy. Dashed boxes are classes
from module `locators`.

digraph G {
fontname="Arial,sans-serif";
node [shape=box, color=gray];

physical_locator [label="<physical-locator>\noa", style=dashed] ;
directory_locator [label="<directory-locator>\noa",style=dashed];

file_locator [label="<file-locator>\noa", style=dashed];
file_system_locator [label="<file-system-locator>\noa"];
file_system_file_locator [label="<file-system-file-locator>"];
file_system_directory_locator [label="<file-system-directory-locator>"] ;

posix_file_system_locator [label="<posix-file-system-locator>\noas", style=bold, color="#17594A"];
posix_directory_locator [label="<posix-directory-locator>\ns", style=bold, color="#17594A"] ;
posix_file_locator [label="<posix-file-locator>\ns", style=bold, color="#17594A"]

physical_locator -> file_locator;
physical_locator -> file_system_locator;
physical_locator -> directory_locator;
directory_locator -> file_system_directory_locator;
file_locator -> file_system_file_locator;
file_system_locator -> file_system_file_locator;
file_system_locator -> file_system_directory_locator;
file_system_locator -> posix_file_system_locator;
file_system_directory_locator -> posix_directory_locator;
file_system_file_locator -> posix_file_locator;
posix_file_system_locator -> posix_directory_locator;
posix_file_system_locator -> posix_file_locator;
}

On Microsoft systems:

- :class:`<microsoft-server-locator>`
Expand All @@ -106,54 +164,61 @@ On Microsoft systems:
- :class:`<microsoft-directory-locator>`
- :class:`<microsoft-file-locator>`

.. graphviz::
:caption: Microsoft file system hierarchy. Dashed boxes are classes
from module `locators`.

digraph G {
fontname="Arial,sans-serif";
node [shape=box, color=gray];

locator [label="<locator>\noa",style=dashed];
physical_locator [label="<physical-locator>\noa", style=dashed] ;
directory_locator [label="<directory-locator>\noa",style=dashed];
server_locator [label="<server-locator>\noa",style=dashed];

file_locator [label="<file-locator>\noa", style=dashed];
file_system_locator [label="<file-system-locator>\noa"];

microsoft_file_system_locator [label="<microsoft-file-system-locator>\na", style=bold, color="#17594A"];
microsoft_server_locator [label="<microsoft-server-locator>\nas", style=bold, color="#17594A"];
microsoft_unc_locator [label="<microsoft-unc-locator>\ns", style=bold, color="#17594A"];
microsoft_volume_locator [label="<microsoft-volume-locator>\ns", style=bold, color="#17594A"];
microsoft_directory_locator [label="<microsoft-directory-locator>", style=bold, color="#17594A"];
microsoft_file_locator [label="<microsoft-file-locator>", style=bold, color="#17594A"];

locator -> server_locator;
locator -> physical_locator;
physical_locator -> file_locator;
physical_locator -> file_system_locator;
physical_locator -> directory_locator;
server_locator -> microsoft_server_locator;
directory_locator -> microsoft_directory_locator;
file_locator -> microsoft_file_locator;
file_system_locator -> microsoft_file_system_locator;
microsoft_file_system_locator -> microsoft_directory_locator;
microsoft_file_system_locator -> microsoft_file_locator;
microsoft_server_locator -> microsoft_unc_locator;
microsoft_server_locator -> microsoft_volume_locator;
}


Native locators, which are bound to the host platform:

- :const:`<native-file-system-locator>`

File streams
------------

File streams are intended only for accessing the contents of files. More
general file handling facilities, such as renaming, deleting, moving, and
parsing directory names, are provided by the :doc:`file-system
</system/file-system>` module. The :drm:`make` method on :class:`<file-stream>`
does not create direct instances of :class:`<file-stream>`, but instead an
instance of a subclass determined by :gf:`type-for-file-stream`.

make *file-stream-class*

G.f method

make <file-stream> #key locator: direction: if-exists:
if-does-not-exist: buffer-size: element-type:
asynchronous?: share-mode => *file-stream-instance*
File streams are intended only for accessing the contents of
files. More general file handling facilities, such as renaming,
deleting, moving, and parsing directory names, are provided by this
module.

Creates and opens a stream over a file, and returns a new instance of a
concrete subclass of :class:`<file-stream>` that streams over the
contents of the file referenced by *filename*. To determine the concrete
subclass to be instantiated, this method calls the generic function
:gf:`type-for-file-stream`.

The ``locator:`` init-keyword should be a string naming a file. If the
:doc:`Locators <../system/locators>` library is in use, *filename*
should be an instance of :class:`<locator>` or a string that can be
coerced to one.

The ``direction:`` init-keyword specifies the direction of the stream.
This can be one of ``#"input"``, ``#"output"``, or ``#"input-output"``.
The default is ``#"input"``.

The ``if-exists:`` and ``if-does-not-exist:`` init-keywords specify actions
to take if the file named by *filename* does or does not already exist
when the stream is created. These init-keywords are discussed in more
detail in `Options when creating file streams`_.

The ``buffer-size:`` init-keyword can be used to suggest the size of a
stream's buffer. See :class:`<buffered-stream>`.

The ``element-type:`` init-keyword specifies the type of the elements in
the file named by *filename*. See `Options when creating file
streams`_ for more details.
The :drm:`make` method on :class:`<file-stream>` does not create
direct instances of :class:`<file-stream>`, but instead an instance of
a subclass determined by :gf:`type-for-file-stream`. See
`make`_ and `Options when creating file streams`_ below.

Options when creating file streams
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand Down Expand Up @@ -854,6 +919,8 @@ File-System module.
Repeatedly follows symbolic links starting with *file* until it finds a
non-link file or directory, or a non-existent link target.

.. _make:

.. method:: make
:specializer: <file-stream>

Expand All @@ -862,7 +929,7 @@ File-System module.
:signature: make *file-stream-class* #key *filename* *direction* *if-exists* *if-does-not-exist* *buffer-size* *element-type* => *file-stream-instance*

:parameter file-stream-class: The class :class:`<file-stream>`.
:parameter #key filename: An instance of :drm:`<object>`.
:parameter #key locator: An instance of :drm:`<object>`.
:parameter #key direction: One of ``#"input"``, ``#"output"``, or
``#"input-output"``. The default is ``#"input"``.
:parameter #key if-exists: One of :drm:`#f`, ``#"new-version"``,
Expand All @@ -885,19 +952,20 @@ File-System module.
instantiated, this method calls the generic function
:gf:`type-for-file-stream`.

The *filename* init-keyword should be a string naming a file. If
the :doc:`Locators <../system/locators>` library is in use,
*filename* should be an instance of :class:`<locator>` or a string
that can be coerced to one.
The *locator* init-keyword should be a :class:`<file-locator>` or
a :drm:`<string>` that can be coerced to one.

The *direction* init-keyword specifies the direction of the stream.
The *direction* init-keyword specifies the direction of the
stream. This can be one of ``#"input"``, ``#"output"``, or
``#"input-output"``. The default is ``#"input"``.

The *if-exists* and *if-does-not-exist* init-keywords specify
actions to take if the file named by *filename* does or does not
already exist when the stream is created. These init-keywords are
discussed in more detail in `Options when creating file streams`_.

The *buffer-size* init-keyword is explained in :class:`<buffered-stream>`.
The *buffer-size* init-keyword can be used to suggest the size of
a stream's buffer. See :class:`<buffered-stream>`.

The *element-type* init-keyword specifies the type of the elements
in the file named by *filename*. This allows file elements to be
Expand Down