________________________________________________________________________

This file is part of Logtalk <https://logtalk.org/>  
SPDX-FileCopyrightText: 1998-2026 Paulo Moura <pmoura@logtalk.org>  
SPDX-License-Identifier: Apache-2.0

Licensed under the Apache License, Version 2.0 (the License);
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an AS IS BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
________________________________________________________________________


`http_directory_listing`
========================

The `http_directory_listing` library provides a router-agnostic helper for
serving HTML directory listings from a configured document root using normalized
`http_core` request and response terms.

This library resolves a relative request path against a document root,
canonicalizes the joined target path using `os::absolute_file_name/2`, rejects
canonicalized escapes with the same outward `404 Not Found` response used for
missing directories, and renders a simple HTML5 listing for existing directory
targets.


API documentation
-----------------

Open the [../../apis/library_index.html#http_directory_listing](../../apis/library_index.html#http_directory_listing)
link in a web browser.


Loading
-------

To load the library, load the `loader.lgt` file:

    | ?- logtalk_load(http_directory_listing(loader)).


Testing
-------

To test this library, load the `tester.lgt` file:

    | ?- logtalk_load(http_directory_listing(tester)).


Current scope
-------------

The current version provides one public object with two public predicates:

- `serve/4`
- `serve/5`

Supported options are:

- `dot_files(Boolean)`
- `directories_first(Boolean)`
- `sort_by(SortBy)`
- `sort_order(SortOrder)`
- `columns(Columns)`
- `type_display(TypeDisplay)`
- `size_display(SizeDisplay)`
- `title(Title)`
- `theme(Theme)`
- `stylesheets(Stylesheets)`
- `exclude(Exclusions)`
- `cache_control(Directives)`
- `expires(Expires)`

Default options are:

- `dot_files(false)`
- `directories_first(true)`
- `sort_by(name)`
- `sort_order(ascending)`
- `columns([name, type, size, modified])`
- `type_display(simple)`
- `size_display(bytes)`
- `title('Directory listing')`
- `theme(default)`
- `stylesheets([])`
- `exclude([])`
- `cache_control([])`
- `expires(none)`

Supported features:

- `GET` and `HEAD`
- `200 OK` HTML directory listings for existing directory targets
- canonical docroot-prefix checks after path normalization
- shared document-root path sandboxing with `http_static_files`
- directory-first sorting by default, with configurable fallback to a single mixed ordering
- sortable `Name`, `Type`, `Size`, and `Modified` columns
- query-driven ordering using `sort=name|type|size|modified` and `order=ascending|descending`
    for visible columns only
- breadcrumb navigation for the current directory path
- parent-directory navigation for non-root listings
- relative links for directory and file entries
- file metadata columns for entry type, file size, and file modification time
- optional column selection while keeping the `Name` column visible
- MIME-based file-type display using `type_display(media)`
- optional file-size display units using `size_display(kilobytes)`,
    `size_display(megabytes)`, `size_display(gigabytes)`, or
    `size_display(terabytes)`
- theme-aware CSS hooks on the generated `<body>`, `<table>`, and entry rows
- optional stylesheet `<link>` generation for custom presentation themes
- optional inclusion of dot files
- configurable exclusion of entry names using exact names, prefixes, suffixes,
    or simple wildcard patterns
- configurable `Cache-Control` and `Expires` response headers
- `404 Not Found` for missing, unsafe, or non-directory targets
- `405 Method Not Allowed` for other methods

Presentation customization uses these option values:

- `columns(Columns)` accepts an ordered subset of `[name, type, size, modified]`
    that must include `name`; hidden columns are also removed from the accepted
    query `sort=` values, with hidden or invalid sort keys falling back to the
    effective default visible column
- `type_display(simple)` keeps the existing `file`/`directory` labels while
    `type_display(media)` renders MIME-based file type text such as `text/plain`
- `size_display(bytes)` renders file sizes as raw byte counts;
    `size_display(kilobytes)`, `size_display(megabytes)`,
    `size_display(gigabytes)`, and `size_display(terabytes)` render sizes with
    one decimal digit using binary multiples and labels such as `1.2 KB` or
    `4.8 MB`; size sorting continues to use the raw byte value
- `theme(Theme)` adds a `theme-Theme` CSS class to the generated `<body>` and
    `<table>` elements
- `stylesheets(Stylesheets)` appends stylesheet links in the generated `<head>`
- `exclude(Exclusions)` removes matching entry names before metadata and
    sorting; entries can be excluded using `name(Name)`, `prefix(Prefix)`,
    `suffix(Suffix)`, `wildcard(Pattern)`, or an atom shortcut for a wildcard
    pattern such as `'.DS_Store'` or `'*.tmp'`; in wildcard patterns, only `*`
    has special meaning

Cache-policy configuration uses these option values:

- `cache_control(Directives)` where `Directives` is a list containing any of
    `public`, `private`, `no_cache`, `no_store`, `no_transform`,
    `must_revalidate`, `proxy_revalidate`, `immutable`, `max_age(Seconds)`,
    `s_maxage(Seconds)`, `stale_while_revalidate(Seconds)`,
    `stale_if_error(Seconds)`, or `extension(Directive)`
- `expires(none)` to omit the header, `expires(Seconds)` for a relative expiry
    from the current system time, or `expires(date_time(Year,Month,Day,Hour,Minute,Second))`
    for an absolute expiry time

The generated HTML includes stable CSS hooks such as:

- `body` class `http-directory-listing theme-Theme`
- `table` class `directory-listing-table theme-Theme columns-...`
- entry row classes `entry entry-directory` and `entry entry-file`
