[comment {--- punk::docgen generated from inline doctools comments ---}]
[comment {--- punk::docgen DO NOT EDIT DOCS HERE UNLESS YOU REMOVE THESE COMMENT LINES ---}]
[comment {--- punk::docgen overwrites this file ---}]
[manpage_begin punkshell_module_punk::island 0 0.1.0]
[copyright "2024"]
[titledesc {filesystem islands for safe interps}]  [comment {-- Name section and table of contents description --}]
[moddesc {punk::island for safe interps}]             [comment {-- Description at end of page heading --}]
[require punk::island]
[keywords module interp filesystem]
[description]
[para]      Package to a allow a safe interpreter to access islands of the
[para]      filesystem only, i.e. restricted directory trees within the
[para]      filesystem. The package brings back file, open and glob to the child interp
[para]      interpreter, though in a restricted manner.
[para] JN Warning:
[para]   This mechanism can have interactions with package loading from auto_path - needs review.
[section Overview]
[para] overview of punk::island
[subsection Concepts]
[para] -
[subsection dependencies]
[para] packages used by punk::island
[list_begin itemized]
[item] [package {Tcl 8.6}]
[list_end]
[section API]
[subsection {Namespace punk::island::class}]
[para] class definitions
[list_begin enumerated]
[list_end] [comment {--- end class enumeration ---}]
[subsection {Namespace punk::island::interps}]
[para] hosts information for interpreters
[list_begin definitions]
[list_end] [comment {--- end definitions namespace punk::island::interps ---}]
[subsection {Namespace punk::island}]
[para] Core API functions for punk::island
[list_begin definitions]
[call [fun add] [arg child] [arg path]]
[para]       Add a path to the list of paths that are explicitely allowed for access
[para]       to a child interpreter. Access to any path that has not been explicitely
[para]       allowed will be denied. Paths that are added to the list of allowed
[para]       islands are always fully normalized.
[para] Arguments:
   [list_begin arguments]
       [arg_def string child] Identifier of the child interpreter to control
   [list_end]
[call [fun reset] [arg child]]
[para]       Remove all access path allowance and arrange for the interpreter to be
[para]       able to return to the regular safe state.
[para] Arguments:
   [list_begin arguments]
       [arg_def string child] Identifier of the child interpreter
   [list_end]
[list_end] [comment {--- end definitions namespace punk::island ---}]
[subsection {Namespace punk::island::lib}]
[para] Secondary functions that are part of the API
[list_begin definitions]
[list_end] [comment {--- end definitions namespace punk::island::lib ---}]
[section Internal]
[subsection {Namespace punk::island::system}]
[para] Internal functions that are not part of the API
[list_begin definitions]
[call [fun Allowed] [arg child] [arg fname]]
[para]       Check that the file name passed as an argument is within the islands of
[para]       the filesystem that have been registered through the add command for a
[para]       given (safe) interpreter. The path is fully normalized before testing
[para]       against the islands, which themselves are fully normalized.
[para] Arguments:
   [list_begin arguments]
       [arg_def string child] Identifier of the child interpreter
       [arg_def string fname] (relative) path to the file to test
   [list_end]
[call [fun File] [arg child] [arg cmd] [arg args]]
[para]       Parses the options and arguments to the file command to discover which
[para]       paths it tries to access and only return the results of its execution
[para]       when these path are within the allowed islands of the filesystem.
[para] Arguments:
   [list_begin arguments]
       [arg_def string child] Identifier of the child interpreter
       [arg_def string cmd] Subcommand of the file command
       [arg_def string args] Arguments to the file subcommand
   [list_end]
[call [fun Open] [arg child] [arg args]]
[para]       Parses the options and arguments to the open command to discover which
[para]       paths it tries to access and only return the results of its execution
[para]       when these path are within the allowed islands of the filesystem.
[para] Arguments:
   [list_begin arguments]
       [arg_def string child] Identifier of the child interpreter
       [arg_def string args] Arguments to the open subcommand
   [list_end]
[call [fun Expose] [arg child] [arg cmd] [arg args]]
[para]       This procedure allows to callback a command that would typically have
[para]       been hidden from a child interpreter. It does not "interp expose" but
[para]       rather calls the hidden command, so we can easily revert back.
[para] Arguments:
   [list_begin arguments]
       [arg_def string child] Identifier of the child interpreter
       [arg_def string cmd] Hidden command to call
       [arg_def string args] Arguments to the command
   [list_end]
[call [fun Glob] [arg child] [arg args]]
[para]       Parses the options and arguments to the glob command to discover which
[para]       paths it tries to access and only return the results of its execution
[para]       when these path are within the allowed islands of the filesystem.
[para] Arguments:
   [list_begin arguments]
       [arg_def string child] Identifier of the child interpreter
       [arg_def string args] Arguments to the glob command
   [list_end]
[call [fun Init] [arg child] ]
[para]       Initialise child interpreter so that it will be able to perform some
[para]       file operations, but only within some islands of the filesystem.
[para] Arguments:
   [list_begin arguments]
       [arg_def string child] Identifier of the child interpreter
   [list_end]
[list_end] [comment {--- end definitions namespace punk::island::system ---}]
[manpage_end]