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 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