// SPDX-FileCopyrightText: © 2021 Matthias Andreas Benkard <code@mail.matthias.benkard.de>
//
// SPDX-License-Identifier: LGPL-3.0-or-later

/**
 * Provides record classes describing the elements of <a
 * href="https://ostreedev.github.io/ostree/">OSTree</a> repositories and factory methods to create
 * {@link eu.mulk.jgvariant.core.Decoder} instances for them.
 *
 * <h2>OStree repository structure</h2>
 *
 * <p>An OSTree repository has the following layout:
 *
 * <dl>
 *   <dt>{@code config}
 *   <dd>
 *       <p>A plain text file that contains various settings. Among other things, this defines the
 *       <a href="https://ostreedev.github.io/ostree/formats/#the-archive-format">archive format</a>
 *       of the repository and whether files are compressed ({@code mode=archive-z2}) or plain
 *       ({@code mode=bare}, {@code mode=bare-user}).
 *   <dt>{@code summary}
 *   <dd>
 *       <p>A {@link eu.mulk.jgvariant.ostree.Summary} object containing information on what is
 *       available under {@code refs/}, {@code deltas/}, and {@code delta-indexes/}.
 *       <p>This file may or may not exist and, if it exists, may or may not be up to date.
 *   <dt>{@code refs/heads{/name...}}
 *   <dd>
 *       <p>Plain-text files containing {@link eu.mulk.jgvariant.ostree.Checksum}s in hex format
 *       (see {@link eu.mulk.jgvariant.ostree.Checksum#ofHex}) referring to {@link
 *       eu.mulk.jgvariant.ostree.Commit} objects. See below for the layout of the {@code objects/}
 *       directory that this refers to.
 *   <dt>{@code objects/{ξ₀ξ₁}/{ξ₂ξ₃ξ₄ξ₅...}.{ext}}
 *   <dd>
 *       <p>Objects of various types as described by {@link eu.mulk.jgvariant.ostree.ObjectType} and
 *       keyed by {@link eu.mulk.jgvariant.ostree.Checksum}.
 *       <p>Among other things, this is where you find {@link eu.mulk.jgvariant.ostree.Commit}
 *       ({@code .commit)}, {@link eu.mulk.jgvariant.ostree.DirTree} ({@code .dirtree}), and {@link
 *       eu.mulk.jgvariant.ostree.DirMeta} ({@code .dirmeta}) objects as well as plain ({@code
 *       .file}) or compressed files ({@code .filez}).
 *       <p>Static delta information is not stored here, but in the {@code deltas/} and {@code
 *       delta-indexes/} directories (if available).
 *       <p>The individual parts of the file path are defined as follows:
 *       <dl>
 *         <dt>{@code {ξ₀ξ₁}}
 *         <dd>the first two characters of {@link eu.mulk.jgvariant.ostree.Checksum#hex()}
 *         <dt>{@code {ξ₂ξ₃ξ₄ξ₅...}}
 *         <dd>the substring of {@link eu.mulk.jgvariant.ostree.Checksum#hex()} starting from the
 *             3rd character
 *         <dt>{@code {ext}}
 *         <dd>the {@link eu.mulk.jgvariant.ostree.ObjectType#fileExtension()} of the object type
 *       </dl>
 *   <dt id="delta-superblock">{@code deltas/{ν₀ν₁}/{ν₂ν₃ν₄ν₅...}/superblock}
 *   <dd>
 *       <p>A {@link eu.mulk.jgvariant.ostree.DeltaSuperblock} to get from nothing (an empty commit)
 *       to the commit named by the checksum encoded in the path.
 *       <p>The individual parts of the file path are defined as follows:
 *       <dl>
 *         <dt>{@code {ν₀ν₁}}
 *         <dd>the first two characters of {@link
 *             eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the target commit the delta
 *             ends at
 *         <dt>{@code {ν₂ν₃ν₄ν₅...}}
 *         <dd>the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the
 *             target commit the delta ends at starting from the 3rd character
 *       </dl>
 *   <dt>{@code deltas/{ν₀ν₁}/{ν₂ν₃ν₄ν₅...}/{digit...}}
 *   <dd>
 *       <p>A {@link eu.mulk.jgvariant.ostree.DeltaPartPayload} belonging to a delta that goes from
 *       nothing (an empty commit) to the commit named by the checksum encoded in the path.
 *       <p>The individual parts of the file path are defined as follows:
 *       <dl>
 *         <dt>{@code {ν₀ν₁}}
 *         <dd>the first two characters of {@link
 *             eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the target commit the delta
 *             ends at
 *         <dt>{@code {ν₂ν₃ν₄ν₅...}}
 *         <dd>the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the
 *             target commit the delta ends at starting from the 3rd character
 *       </dl>
 *   <dt>{@code deltas/{μ₀μ₁}/{μ₂μ₃μ₄μ₅...}-{ν₀ν₁ν₂ν₃ν₄ν₅...}/superblock}
 *   <dd>
 *       <p>A {@link eu.mulk.jgvariant.ostree.DeltaSuperblock} to get from the source commit
 *       referenced by the first checksum encoded in the path to the target commit referenced in the
 *       second checksum encoded in the path.
 *       <p>The individual parts of the file path are defined as follows:
 *       <dl>
 *         <dt>{@code {μ₀μ₁}}
 *         <dd>the first two characters of {@link
 *             eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the source commit the delta
 *             starts from
 *         <dt>{@code {μ₂μ₃μ₄μ₅...}}
 *         <dd>the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the
 *             source commit the delta starts from starting from the 3rd character
 *         <dt>{@code {ν₀ν₁ν₂ν₃ν₄ν₅...}}
 *         <dd>the full {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the target
 *             commit the delta ends at
 *       </dl>
 *   <dt>{@code deltas/{μ₀μ₁}/{μ₂μ₃μ₄μ₅...}-{ν₀ν₁ν₂ν₃ν₄ν₅...}/{digit...}}
 *   <dd>
 *       <p>A {@link eu.mulk.jgvariant.ostree.DeltaPartPayload} belonging to a delta that goes from
 *       the source commit referenced by the first checksum encoded in the path to the target commit
 *       referenced in the second checksum encoded in the path.
 *       <p>The individual parts of the file path are defined as follows:
 *       <dl>
 *         <dt>{@code {μ₀μ₁}}
 *         <dd>the first two characters of {@link
 *             eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the source commit the delta
 *             starts from
 *         <dt>{@code {μ₂μ₃μ₄μ₅...}}
 *         <dd>the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the
 *             source commit the delta starts from starting from the 3rd character
 *         <dt>{@code {ν₀ν₁ν₂ν₃ν₄ν₅...}}
 *         <dd>the full {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the target
 *             commit the delta ends at
 *       </dl>
 * </dl>
 */
@API(status = Status.EXPERIMENTAL)
package eu.mulk.jgvariant.ostree;

import org.apiguardian.api.API;
import org.apiguardian.api.API.Status;