foundation (original) (raw)

A library of utility functions for command-line tools. This is version 1.

• Preliminaries
  • A Brief Guide to Foundation -Notes on getting started with the Foundation library.
• Chapter 1: Setting Up
  Absolute basics.
  • Foundation Module -Starting up and shutting down.
  • POSIX Platforms -A version of our operating system interface suitable for POSIX-compliant operating systems.
  • Windows Platform -A version of our operating system interface suitable for Microsoft Windows.
• Chapter 2: Memory, Streams and Collections
  Creating objects in memory, and forming lists, hashes, and text streams.
  • Debugging Log -To write to the debugging log, a plain text file which traces what we're doing, in order to assist those lost souls debugging it.
  • Memory -To allocate memory suitable for the dynamic creation of objects of different sizes, placing some larger objects automatically into doubly linked lists and assigning each a unique allocation ID number.
  • Foundation Classes -To declare the object classes used in the Foundation module.
  • Locales -Locales are what operating-system people call the text encodings used when interacting with them: in filenames, or when printing to the console.
  • Streams -Support for writing structured textual output, perhaps to the screen, to a file, or to a flexible-sized wide string.
  • Writers and Loggers -Formatted text output to streams.
  • Methods -General support for something approximating method calls.
  • Linked Lists and Stacks -A simple implementation for single-linked lists of objects allocated by Foundation's memory manager, and for last-in-first-out stacks of same.
  • Dictionaries -A simple implementation for a flexible-sized dictionary of key-value pairs.
  • Trees -To provide heterogeneous tree structures, where a node can be any structure known to the Foundation memory manager.
• Chapter 3: The Operating System
  Dealing with the host operating system.
  • Error Messages -A basic system for command-line tool error messages.
  • Command Line Arguments -To parse the command line arguments with which inweb was called, and to handle any errors it needs to issue.
  • Pathnames -Locations of hypothetical or real directories in the filing system.
  • Filenames -Names of hypothetical or real files in the filing system.
  • Case-Insensitive Filenames -On some of the Unix-derived file systems on which Inform runs, filenames are case-sensitive, so that FISH and fish might be different files. This makes extension files, installed by the user, prone to being missed. The code in this section provides a routine to carry out file opening as if filenames are case-insensitive, and is used only for extensions.
  • Shell -Sending commands to the shell, on Unix-like platforms, or simulating this on Windows.
  • Directories -Scanning directories on the host filing system.
  • Time -Managing how we record and use the current time and date.
• Chapter 4: Text Handling
  Reading, writing and parsing text.
  • Characters -Individual characters.
  • C Strings -A minimal library for handling C-style strings.
  • Wide Strings -A minimal library for handling wide C strings.
  • String Manipulation -Convenient routines for manipulating strings of text.
  • Tab Stops -Reading strings where tab characters need to be interpreted as if spaces had been used for the same visual effect.
  • Text Files -To read text files of whatever flavour, one line at a time.
  • Preprocessor -A simple, general-purpose preprocessor for text files, expanding macros and performing repetitions.
  • Tries and Avinues -To examine heads and tails of text, to see how it may inflect.
  • Pattern Matching -To provide a limited regular-expression parser.
  • JSON -To read, validate and write JSON data interchange material.
• Chapter 5: Generating Websites
  For making individual web pages, or gathering them into mini-sites or ebooks.
  • HTML -Utility functions for writing HTML.
  • HTML Entities -Utility functions for dealing with those ampersanded paraphrases of characters which seemed like a good idea in around the year 2000.
  • Markdown -To store the results of parsing the Markdown markup notation.
  • Markdown Phase I -Phase I of the Markdown parser: reading a series of lines into a tree of container and leaf blocks.
  • Markdown Phase II -Phase II of the Markdown parser: fragmenting inline material into emphasis, links, backticked code and so forth.
  • Markdown Rendering -To render a Markdown tree as HTML.
  • Markdown Variations -To specify modified versions of the Markdown markup syntax.
  • Inform-Flavoured Markdown -A form of Markdown adapted to the needs of the Inform tools.
  • Epub Ebooks -To provide for wrapping up sets of HTML files into ePub ebooks.
• Chapter 6: Media
  Examining image and sound files.
  • Binary Files -Routines for reading raw data from binary files.
  • Image Dimensions -These utility routines look at the headers of JPEG and PNG files to find the pixel dimensions of any images supplied by the user for cover art and figures.
  • Sound Durations -These utility routines look at the headers of AIFF, OGG Vorbis or MIDI files to find the durations, and verify that they are what they purport to be.
• Chapter 7: Semantic Versioning
  For reading, storing and comparing standard semantic version numbers.
  • Version Numbers -Semantic version numbers such as 3.7.1.
  • Version Number Ranges -Ranges of acceptable version numbers.
  • Licence Data -Storing names and standard SPDX identifiers for common open source licences.
  • SPDX Licenses -This section was mechanically generated from the JSON file provided by https://spdx.org/licenses/. The version used was 747753e, dated 2024-04-24.
• Chapter 8: Literate Programming
  • Web Structure -To read the structure of a literate programming web from a path in the file system.
  • Bibliographic Data for Webs -To manage key-value pairs of bibliographic data, metadata if you like, associated with a given web.
  • Web Modules -To search for included modules, and track dependencies between them.
  • Build Files -Manages the build metadata for an inweb project.
  • Simple Tangler -Unravelling (a simple version of) Inweb's literate programming notation to access the tangled content.
• Chapter 9: Syntax Colouring
  • Programming Languages -Defining the programming languages supported by Inweb, loading in their definitions from files.
  • Reserved Words -Managing reserved words, that is, significant identifiers, for programming languages.
  • The Painter -A simple syntax-colouring engine.