disassembler_ztf.h | Explore in Territory

// Copyright 2018 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef COMPONENTS_ZUCCHINI_DISASSEMBLER_ZTF_H_
#define COMPONENTS_ZUCCHINI_DISASSEMBLER_ZTF_H_

#include <stdint.h>
#include <stdlib.h>

#include <memory>
#include <optional>
#include <string>
#include <vector>

#include "components/zucchini/disassembler.h"
#include "components/zucchini/image_utils.h"
#include "components/zucchini/type_ztf.h"

namespace zucchini {

// Disassembler for text based files. This file format is supported for
// debugging Zucchini and is not intended for production usage.
//
// A valid Zucchini Text Format (ZTF) file is specified as follows:
//
// Header:
//   The first four bytes must be - 'Z' 'T' 'x' 't'
// Footer:
//   The last five bytes must be  - 't' 'x' 'T' 'Z' '\n'
//   (note that terminating new line is required).
// Content:
//   The content can be any sequence of printable ASCII characters and new line
//   (but not carriage return). This excludes the sequence that comprises the
//   Footer.
// References:
//   A reference is either Absolute or Relative. All references must begin and
//   end with a pair of enclosing characters <open>, <close>. The options are:
//     - Angles:      '<' and '>'
//     - Braces:      '{' and '}'
//     - Brackets:    '[' and ']'
//     - Parentheses: '(' and ')'
//
//   A reference contains three items:
//     - A line number       <line>
//     - A delimiter     ',' <delimiter>
//     - A column number     <col>
//     <line> and <col> may contain 1-3 digits and both must contain the same
//     number of digits. If a number is too short then it can be left-padded
//     with '0'.
//
//   For Absolute references, <line> and <col> are 1-based (i.e. positive)
//   index of line and column numbers of a character in the ZTF. This follows
//   standard convention for text editors. Note that "\n" is considered to be
//   part of a preceding line.
//
//     <open><line><delimiter><col><close>
//
//   For Relative references, <line> and <col> are integer offsets deltas of the
//   target's (absolute) line and column relative to the line and column of the
//   reference's first byte (i.e. <open>). Relative references have <sign> ('+'
//   or '-') before <line> and <col>. For the special case of "0", "00", etc.,
//   <sign> must be "+".
//
//     <open><sign><line><delimiter><sign><col><close>
//
//   If a reference points outside the target either in writing or reading it is
//   considered invalid and ignored. Similarly if it overflows a line. i.e. if a
//   line is 10 characters long and a references targets character 11 of that
//   line it is rejected. Lines are delimited with '\n' which is counted toward
//   the line length.
//
//   If a reference is to be written that would overwrite a '\n' character it is
//   ignored as this would break all other line values.

enum : size_t { … };

// Helper class for translating among offset_t, ztf::LineCol and
// ztf::DeltaLineCol.
class ZtfTranslator { … };

// Disassembler for Zucchini Text Format (ZTF).
class DisassemblerZtf : public Disassembler { … };

}  // namespace zucchini

#endif  // COMPONENTS_ZUCCHINI_DISASSEMBLER_ZTF_H_
chromium/components/zucchini/disassembler_ztf.h
