FileMeta

File Identity and Metadata Project
by Brandt Redd

CodeBits

CodeBits are an application of FileMeta Principles to accomplish lightweight code sharing. The unit of sharing is a single source code file called a CodeBit. Each CodeBit file begins with metadata encapsulated in a comment so that it doesn’t interfere with the function of the code itself. The metadata follows the SoftwareSourceCode schema from Schema.org and is encoded in YAML

The metadata includes a keyword indicating that the file is CodeBit, name, URL to the master copy, and version number. Optional fields include description, copyright, license, and so forth.

This page includes the following sections:

FMCodeBit Application

The FMCodeBit application is used to keep CodeBits up to date. It checks source files and reads the metadata to determine which are CodeBits. For each CodeBit it finds, the application checks the master copy of that CodeBit on the web to determine whether it is up to date. If a newer copy is available, the application prompts the user for confirmation and then updates the CodeBit.

CodeBit Specification

In the following text, ALL CAPS key words should be interpreted per RFC 2119.

CodeBits are source code files with a metadata block near the beginning of the file. The metadata is in MicroYaml format (a subset of YAML) and uses metadata property definitions from the SoftwareSourceCode type of Schema.org. At a minimum, the metadata block MUST include the ‘url’, ‘version’, and ‘keywords’ properties and ‘CodeBit’ MUST appear in the keywords. RECOMMENDED properties include ‘name’, ‘description’, and ‘license’. Other metadata properties are optional.

The version number SHOULD use semantic versioning.

It MUST begin with a YAML ‘Begin Document’ indicator which is a line with just three dashes. It MUST end with a YAML ‘End Document’ indicator which is a line with just three dots.

Typically the metadata block is enclosed by multiline comment delimiters appropriate to the programming language. Presently, programming languages that lack multiline comments are not supported.

Sample Metadata Block

Here is a sample metadata block for a C# source code file.

/*
---
# Metadata in YAML format (This is a YAML comment)
name: MySharedCode.cs
description: Shared code demonstration module
url: https://github.com/FileMeta/AcmeIndustries/raw/master/MySharedCode.cs
version: 1.4
keywords: CodeBit
dateModified: 2017-05-24
copyrightHolder: Henry Higgins
copyrightYear: 2017
license: https://opensource.org/licenses/BSD-3-Clause
...
*/

Known CodeBits

The following is a short (but growing) list of known CodeBits.

  • ConsoleHelper: (C#) A class for making console applications more friendly when invoked from a debugger or a shortcut.
  • DateTag: (C#) A class that represents date/time metadata including timezone and precision information often neglected by other date parsers and formatters.
  • ExifToolWrapper: (C#) A wrapper class for Phil Harvey’s excellent ExifTool.
  • HtmlReader: (C#) A compact and full-featured HTML parser for .NET that implements the XmlReader interface.
  • IsomCoreMetadata (C#) A class for retrieving and updating core metadata from files in .MP4, .MOV, .M4A, and other ISO Base Media Format files.
  • MetaTag A class for embedding and extracting metadata tags in free-form text fields according to the proposed MetaTag specification.
  • MicroYaml: (C#) A simple parser and serializer for the MicroYaml dialect of the YAML file format.
  • TimeZoneTag: (C#) A class for parsing and formatting TimeZone metadata.
  • WinShellPropertyStore: (C#) .NET Wrapper classes for the Windows Property System.