Task 663: .SHTML File Format

1. Properties of the .SHTML File Format Intrinsic to Its File System

The .SHTML file format is a text-based extension of HTML designed for Server-Side Includes (SSI), primarily processed by web servers such as Apache via the mod_include module. It lacks a binary signature or complex file system-level structure, functioning instead as a plain-text file with embedded directives. The following list enumerates key intrinsic properties derived from the official Apache HTTP Server documentation (version 2.4) and related specifications:

• File Extension: .shtml (conventionally used to signal server-side processing; alternative extensions like .shtm may apply but are less standard).
• MIME Type: text/html (output after processing; input files are parsed before delivery to clients).
• Content Structure: Plain-text file containing HTML markup interspersed with SGML-style comments for SSI directives (format: <!--#element [attribute="value" [...]] -->). Directives are processed sequentially, with support for nesting (e.g., includes within includes).
• Character Encoding: Typically UTF-8 or ASCII-compatible; supports entity encoding (&, etc.) by default for output to prevent cross-site scripting. Directives allow explicit decoding/encoding options (e.g., url, base64, entity via echo or set attributes).
• Directive Syntax: Must begin with <!--# (no whitespace permitted after --), followed by element name and optional quoted attributes (double/single quotes or backticks). Ends with --> (preceded by whitespace to distinguish from HTML comments). Variable substitution uses $VAR or ${VAR} within strings.
• Supported Elements (Directives): comment (silent comment), config (output configuration: echomsg, errmsg, sizefmt, timefmt), echo (variable output with encoding/decoding), exec (external program execution: cgi or cmd), fsize (file size display: file or virtual), flastmod (file last-modified time: file or virtual), include (file/program inclusion: file, virtual, onerror), printenv (all variables), set (variable assignment with encoding/decoding), flow control (if, elif, else, endif with boolean expressions).
• Built-in Variables: DATE_GMT (GMT date), DATE_LOCAL (local date), DOCUMENT_ARGS (query string), DOCUMENT_NAME (filename), DOCUMENT_PATH_INFO (path info), DOCUMENT_URI (URI path), LAST_MODIFIED (document mod time), QUERY_STRING_UNESCAPED (decoded query), USER_NAME (file owner); plus standard CGI variables.
• Expression Syntax for Flow Control: Defaults to Apache expression parser (ap_expr); legacy mode (via SSILegacyExprParser on) supports operators like =, !=, <, >, regex (/pattern/), logical &&/||, grouping (), and negation !.
• Default Formatting: Time uses strftime format %A, %d-%b-%Y %H:%M:%S %Z; size uses bytes (or abbrev for abbreviated units like "1K"); undefined echo variables render as (none); parsing errors show [an error occurred while processing this directive].
• Processing Constraints: Relative paths only (no absolute / or ../ in file attribute to prevent root escapes); virtual uses %-encoded URL-paths; subrequests (e.g., includes) inherit access controls; execution restricted by IncludesNOEXEC option; no PATH_INFO by default.
• Output Behavior: Directives replaced server-side; comments stripped; ETags and Last-Modified headers stripped by default (configurable via SSIETag/SSILastModified/XBitHack); supports conditional inclusion and variable manipulation for dynamic content.

These properties ensure secure, dynamic HTML generation without requiring full scripting languages like PHP.

2. Two Direct Download Links for .SHTML Files

The following are publicly accessible URLs to example .SHTML files. These can be downloaded directly via right-click "Save As" or tools like curl/wget (e.g., curl -O <URL>). They contain valid SSI directives for demonstration:

• https://www2.ifa.hawaii.edu/styles/guide10/Using_SSI.shtml (University of Hawaii SSI tutorial with include examples).
• http://kappazushi.jp/menu/list.shtml (Kappa Sushi menu page, processed with potential includes for dynamic elements).

3. Ghost Blog Embedded HTML JavaScript for Drag-and-Drop .SHTML Property Dump

The following is a self-contained HTML snippet with embedded JavaScript, suitable for embedding in a Ghost CMS blog post (e.g., via an HTML card). It enables drag-and-drop of a .SHTML file, reads it client-side using the File API, parses for SSI directives, and dumps format properties (from section 1) plus file-specific details (e.g., size, extracted directives) to a <pre> element on-screen. No server processing is required.

4. Python Class for .SHTML Handling

The following Python class opens a .SHTML file, reads/decodes it as UTF-8 text, parses for directives, supports writing back (with optional content modification), and prints all properties from section 1 plus file-specific details to console.

import os
import re

class SHTMLHandler:
    def __init__(self, filepath):
        self.filepath = filepath
        self.content = None
        if not os.path.exists(filepath) or not filepath.endswith('.shtml'):
            raise ValueError("Invalid .SHTML file path.")

    def read(self):
        """Read and decode the file as UTF-8."""
        with open(self.filepath, 'r', encoding='utf-8') as f:
            self.content = f.read()
        return self.content

    def write(self, content=None):
        """Write content back to file (uses self.content if None)."""
        if content is None:
            content = self.content
        with open(self.filepath, 'w', encoding='utf-8') as f:
            f.write(content)

    def print_properties(self):
        """Print format properties and file-specific details."""
        if self.content is None:
            self.read()
        size = len(self.content)
        directives = re.findall(r'<!--#[\s\S]*?-->', self.content)
        unique_elements = list(set(re.match(r'<!--#(\w+)', d).group(1) for d in directives if re.match(r'<!--#(\w+)', d)))
        print(f"File: {self.filepath}")
        print(f"Size: {size} characters")
        print("Encoding: UTF-8")
        print("\nFormat Properties:")
        print("- Extension: .shtml")
        print("- MIME Type: text/html")
        print("- Directive Syntax: <!--#element ... -->")
        print("- Supported Elements: comment, config, echo, exec, fsize, flastmod, include, printenv, set, if/elif/else/endif")
        print("- Built-in Variables: DATE_GMT, DATE_LOCAL, DOCUMENT_NAME, etc.")
        print("- Default Time Format: %A, %d-%b-%Y %H:%M:%S %Z")
        print("- Default Size Format: bytes")
        print("- Default Undefined Echo: (none)")
        print("- Default Error Msg: [an error occurred while processing this directive]")
        print(f"\nFile-Specific:")
        print(f"- Number of Directives: {len(directives)}")
        print(f"- Unique Elements: {', '.join(unique_elements) if unique_elements else 'None'}")
        print("\nExtracted Directives:")
        for d in directives:
            print(d)
        print("\nRaw Content Preview (first 500 chars):")
        print(self.content[:500] + "..." if len(self.content) > 500 else self.content)

# Example usage:
# handler = SHTMLHandler('example.shtml')
# handler.read()
# handler.print_properties()
# handler.write()  # Writes back unchanged

5. Java Class for .SHTML Handling

The following Java class (compatible with Java 8+) opens a .SHTML file, reads/decodes it as UTF-8, parses for directives using regex, supports writing back, and prints properties to console (System.out).

import java.io.*;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.*;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class SHTMLHandler {
    private String filepath;
    private String content;

    public SHTMLHandler(String filepath) {
        this.filepath = filepath;
        File file = new File(filepath);
        if (!file.exists() || !filepath.endsWith(".shtml")) {
            throw new IllegalArgumentException("Invalid .SHTML file path.");
        }
    }

    public String read() throws IOException {
        content = Files.readString(Paths.get(filepath), StandardCharsets.UTF_8);
        return content;
    }

    public void write(String newContent) throws IOException {
        if (newContent == null) {
            newContent = content;
        }
        Files.writeString(Paths.get(filepath), newContent, StandardCharsets.UTF_8);
    }

    public void printProperties() {
        if (content == null) {
            try {
                read();
            } catch (IOException e) {
                System.err.println("Error reading file: " + e.getMessage());
                return;
            }
        }
        int size = content.length();
        Pattern directivePattern = Pattern.compile("<!--#[\\s\\S]*?-->");
        Matcher matcher = directivePattern.matcher(content);
        List<String> directives = new ArrayList<>();
        while (matcher.find()) {
            directives.add(matcher.group());
        }
        Set<String> uniqueElements = new HashSet<>();
        Pattern elementPattern = Pattern.compile("<!--#(\\w+)");
        for (String d : directives) {
            Matcher elMatcher = elementPattern.matcher(d);
            if (elMatcher.find()) {
                uniqueElements.add(elMatcher.group(1));
            }
        }
        System.out.println("File: " + filepath);
        System.out.println("Size: " + size + " characters");
        System.out.println("Encoding: UTF-8");
        System.out.println("\nFormat Properties:");
        System.out.println("- Extension: .shtml");
        System.out.println("- MIME Type: text/html");
        System.out.println("- Directive Syntax: <!--#element ... -->");
        System.out.println("- Supported Elements: comment, config, echo, exec, fsize, flastmod, include, printenv, set, if/elif/else/endif");
        System.out.println("- Built-in Variables: DATE_GMT, DATE_LOCAL, DOCUMENT_NAME, etc.");
        System.out.println("- Default Time Format: %A, %d-%b-%Y %H:%M:%S %Z");
        System.out.println("- Default Size Format: bytes");
        System.out.println("- Default Undefined Echo: (none)");
        System.out.println("- Default Error Msg: [an error occurred while processing this directive]");
        System.out.println("\nFile-Specific:");
        System.out.println("- Number of Directives: " + directives.size());
        System.out.println("- Unique Elements: " + (uniqueElements.isEmpty() ? "None" : String.join(", ", uniqueElements)));
        System.out.println("\nExtracted Directives:");
        for (String d : directives) {
            System.out.println(d);
        }
        System.out.println("\nRaw Content Preview (first 500 chars):");
        String preview = content.length() > 500 ? content.substring(0, 500) + "..." : content;
        System.out.println(preview);
    }

    // Example usage:
    // public static void main(String[] args) {
    //     SHTMLHandler handler = new SHTMLHandler("example.shtml");
    //     handler.printProperties();
    //     // handler.write("Modified content"); // Uncomment to write
    // }
}

6. JavaScript Class for .SHTML Handling (Node.js)

The following Node.js-compatible JavaScript class (ES6+) opens a .SHTML file using fs, reads/decodes as UTF-8, parses directives, supports writing back, and prints properties to console (console.log). Requires Node.js runtime.

const fs = require('fs');
const path = require('path');

class SHTMLHandler {
  constructor(filepath) {
    this.filepath = filepath;
    if (!fs.existsSync(filepath) || !path.extname(filepath) === '.shtml') {
      throw new Error('Invalid .SHTML file path.');
    }
    this.content = null;
  }

  read() {
    this.content = fs.readFileSync(this.filepath, 'utf8');
    return this.content;
  }

  write(newContent = null) {
    if (newContent === null) {
      newContent = this.content;
    }
    fs.writeFileSync(this.filepath, newContent, 'utf8');
  }

  printProperties() {
    if (this.content === null) {
      this.read();
    }
    const size = this.content.length;
    const directiveRegex = /<!--#[\s\S]*?-->/g;
    const directives = this.content.match(directiveRegex) || [];
    const uniqueElements = [...new Set(directives.map(d => {
      const match = d.match(/<!--#(\w+)/);
      return match ? match[1] : 'unknown';
    }))].filter(el => el !== 'unknown');
    console.log(`File: ${this.filepath}`);
    console.log(`Size: ${size} characters`);
    console.log('Encoding: UTF-8');
    console.log('\nFormat Properties:');
    console.log('- Extension: .shtml');
    console.log('- MIME Type: text/html');
    console.log('- Directive Syntax: <!--#element ... -->');
    console.log('- Supported Elements: comment, config, echo, exec, fsize, flastmod, include, printenv, set, if/elif/else/endif');
    console.log('- Built-in Variables: DATE_GMT, DATE_LOCAL, DOCUMENT_NAME, etc.');
    console.log('- Default Time Format: %A, %d-%b-%Y %H:%M:%S %Z');
    console.log('- Default Size Format: bytes');
    console.log('- Default Undefined Echo: (none)');
    console.log('- Default Error Msg: [an error occurred while processing this directive]');
    console.log('\nFile-Specific:');
    console.log(`- Number of Directives: ${directives.length}`);
    console.log(`- Unique Elements: ${uniqueElements.length ? uniqueElements.join(', ') : 'None'}`);
    console.log('\nExtracted Directives:');
    directives.forEach(d => console.log(d));
    console.log('\nRaw Content Preview (first 500 chars):');
    const preview = this.content.length > 500 ? this.content.substring(0, 500) + '...' : this.content;
    console.log(preview);
  }
}

// Example usage:
// const handler = new SHTMLHandler('example.shtml');
// handler.printProperties();
// handler.write(); // Writes back unchanged

7. C Class (Struct with Functions) for .SHTML Handling

The following C implementation uses standard library functions (stdio.h, stdlib.h, string.h, regex.h for parsing) to open a .SHTML file, read as text (assuming UTF-8), parse directives, support writing back, and print properties to stdout. Compile with gcc -o handler handler.c -lregex (POSIX regex). Handles basic error checking.

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <regex.h>
#include <sys/stat.h>

typedef struct {
    char *filepath;
    char *content;
    long size;
} SHTMLHandler;

SHTMLHandler* shtml_create(const char *filepath) {
    SHTMLHandler *handler = malloc(sizeof(SHTMLHandler));
    if (!handler) return NULL;
    handler->filepath = strdup(filepath);
    handler->content = NULL;
    handler->size = 0;
    struct stat st;
    if (stat(filepath, &st) != 0 || !strstr(filepath, ".shtml")) {
        free(handler->filepath);
        free(handler);
        return NULL;
    }
    handler->size = st.st_size;
    return handler;
}

void shtml_destroy(SHTMLHandler *handler) {
    if (handler) {
        free(handler->content);
        free(handler->filepath);
        free(handler);
    }
}

char* shtml_read(SHTMLHandler *handler) {
    FILE *f = fopen(handler->filepath, "r");
    if (!f) return NULL;
    fseek(f, 0, SEEK_END);
    long fsize = ftell(f);
    rewind(f);
    handler->content = malloc(fsize + 1);
    fread(handler->content, 1, fsize, f);
    handler->content[fsize] = '\0';
    fclose(f);
    return handler->content;
}

void shtml_write(SHTMLHandler *handler, char *new_content) {
    if (!new_content) new_content = handler->content;
    FILE *f = fopen(handler->filepath, "w");
    if (f) {
        fputs(new_content, f);
        fclose(f);
    }
}

void shtml_print_properties(SHTMLHandler *handler) {
    if (!handler->content) shtml_read(handler);
    printf("File: %s\n", handler->filepath);
    printf("Size: %ld characters\n", handler->size);
    printf("Encoding: UTF-8\n");
    printf("\nFormat Properties:\n");
    printf("- Extension: .shtml\n");
    printf("- MIME Type: text/html\n");
    printf("- Directive Syntax: <!--#element ... -->\n");
    printf("- Supported Elements: comment, config, echo, exec, fsize, flastmod, include, printenv, set, if/elif/else/endif\n");
    printf("- Built-in Variables: DATE_GMT, DATE_LOCAL, DOCUMENT_NAME, etc.\n");
    printf("- Default Time Format: %%A, %%d-%%b-%%Y %%H:%%M:%%S %%Z\n");
    printf("- Default Size Format: bytes\n");
    printf("- Default Undefined Echo: (none)\n");
    printf("- Default Error Msg: [an error occurred while processing this directive]\n");

    // Simple regex for directives (POSIX)
    regex_t regex;
    regcomp(&regex, "<!--#[^>]*-->", REG_EXTENDED);
    regmatch_t matches[10];
    int num_directives = 0;
    char *unique_elements[20]; // Limited
    int num_unique = 0;
    char *ptr = handler->content;
    while (regexec(&regex, ptr, 1, matches, 0) == 0) {
        num_directives++;
        // Extract element (basic parse)
        char *start = ptr + matches[0].rm_so + 6; // Skip <!--#
        char *space = strchr(start, ' ');
        if (!space) space = strchr(start, '>');
        if (space) {
            int len = space - start;
            if (num_unique < 20) {
                unique_elements[num_unique] = malloc(len + 1);
                strncpy(unique_elements[num_unique], start, len);
                unique_elements[num_unique][len] = '\0';
                num_unique++;
            }
        }
        ptr += matches[0].rm_eo;
    }
    regfree(&regex);

    printf("\nFile-Specific:\n");
    printf("- Number of Directives: %d\n", num_directives);
    printf("- Unique Elements: ");
    for (int i = 0; i < num_unique; i++) {
        if (i > 0) printf(", ");
        printf("%s", unique_elements[i]);
        free(unique_elements[i]);
    }
    printf("\n\nExtracted Directives: (simplified count; full parse requires advanced regex)\n");
    printf("%d found\n", num_directives);
    printf("\nRaw Content Preview (first 500 chars):\n");
    char *preview = handler->content;
    int len = strlen(preview) > 500 ? 500 : strlen(preview);
    fwrite(preview, 1, len, stdout);
    if (strlen(preview) > 500) printf("...");
    printf("\n");
}

// Example usage:
// int main() {
//     SHTMLHandler *handler = shtml_create("example.shtml");
//     if (handler) {
//         shtml_print_properties(handler);
//         shtml_write(handler, NULL); // Writes back
//         shtml_destroy(handler);
//     }
//     return 0;
// }