Skip to content

Commit

Permalink
Docs: Edit 'file-system' module (#1510)
Browse files Browse the repository at this point in the history 
- Add graphviz extension to create a class hierarchy to file system,
  posix and microsoft locators.

- Remove reference to 'file-stream' module. This paragraph was moved
  from module 'locators' and contained a reference to the module
  'file-system', not needed now.

- Rename key parameter 'filename'. The key parameter appears as
  'filename' and in the documentation of the method as 'locator'.

- To eliminate document duplication, I decided to address the issue in
  the paragraph discussing the 'make' method. Since it bears close
  resemblance to the method reference, I opted to remove the initial
  paragraph and provide a link to the reference instead. Additionally,
  I consolidated the documentation for the key parameters 'direction'
  and 'buffer-size' with a more comprehensive explanation.
  • Loading branch information
@fraya
fraya authored Jun 29, 2023
1 parent 7236142 commit 1dba458
Show file tree
Hide file tree
Showing 2 changed files with 119 additions and 47 deletions.
4 changes: 4 additions & 0 deletions documentation/library-reference/source/conf.py
View file
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
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

0 comments on commit 1dba458

Please sign in to comment.