diff --git a/documentation/library-reference/source/conf.py b/documentation/library-reference/source/conf.py index 3ae374f3f..7e4cd535d 100644 --- a/documentation/library-reference/source/conf.py +++ b/documentation/library-reference/source/conf.py @@ -20,6 +20,10 @@ sys.path.insert(0, os.path.abspath('../..')) from shared_sphinx_config import * +extensions = [ + 'sphinx.ext.graphviz', + 'dylan.domain' +] # -- General configuration ----------------------------------------------------- diff --git a/documentation/library-reference/source/system/file-system.rst b/documentation/library-reference/source/system/file-system.rst index 18fdc95d9..eaddf259a 100644 --- a/documentation/library-reference/source/system/file-system.rst +++ b/documentation/library-reference/source/system/file-system.rst @@ -91,12 +91,70 @@ or a file within the file system. - :class:`` - :class:`` +.. 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="\noa", style=dashed]; + file_locator [label="\noa", style=dashed]; + directory_locator [label="\noa",style=dashed]; + file_system_locator [label="\noa", style=bold, color="#17594A"]; + file_system_file_locator [label="", style=bold, color="#17594A"]; + file_system_directory_locator [label="", 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:`` - :class:`` - :class:`` +.. 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="\noa", style=dashed] ; + directory_locator [label="\noa",style=dashed]; + + file_locator [label="\noa", style=dashed]; + file_system_locator [label="\noa"]; + file_system_file_locator [label=""]; + file_system_directory_locator [label=""] ; + + posix_file_system_locator [label="\noas", style=bold, color="#17594A"]; + posix_directory_locator [label="\ns", style=bold, color="#17594A"] ; + posix_file_locator [label="\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:`` @@ -106,6 +164,45 @@ On Microsoft systems: - :class:`` - :class:`` +.. 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="\noa",style=dashed]; + physical_locator [label="\noa", style=dashed] ; + directory_locator [label="\noa",style=dashed]; + server_locator [label="\noa",style=dashed]; + + file_locator [label="\noa", style=dashed]; + file_system_locator [label="\noa"]; + + microsoft_file_system_locator [label="\na", style=bold, color="#17594A"]; + microsoft_server_locator [label="\nas", style=bold, color="#17594A"]; + microsoft_unc_locator [label="\ns", style=bold, color="#17594A"]; + microsoft_volume_locator [label="\ns", style=bold, color="#17594A"]; + microsoft_directory_locator [label="", style=bold, color="#17594A"]; + microsoft_file_locator [label="", 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:`` @@ -113,47 +210,15 @@ Native locators, which are bound to the host platform: 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 -` module. The :drm:`make` method on :class:`` -does not create direct instances of :class:``, but instead an -instance of a subclass determined by :gf:`type-for-file-stream`. - -make *file-stream-class* - -G.f method - -make #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:`` 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:`` 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:``. - -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:`` does not create +direct instances of :class:``, 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -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: @@ -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:``. - :parameter #key filename: An instance of :drm:``. + :parameter #key locator: An instance of :drm:``. :parameter #key direction: One of ``#"input"``, ``#"output"``, or ``#"input-output"``. The default is ``#"input"``. :parameter #key if-exists: One of :drm:`#f`, ``#"new-version"``, @@ -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:`` or a string - that can be coerced to one. + The *locator* init-keyword should be a :class:`` or + a :drm:`` 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:``. + The *buffer-size* init-keyword can be used to suggest the size of + a stream's buffer. See :class:``. The *element-type* init-keyword specifies the type of the elements in the file named by *filename*. This allows file elements to be