123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203 |
- // Copyright 2018 The Chromium Authors. All rights reserved.
- // 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 <string>
- #include <vector>
- #include "components/zucchini/disassembler.h"
- #include "components/zucchini/image_utils.h"
- #include "components/zucchini/type_ztf.h"
- #include "third_party/abseil-cpp/absl/types/optional.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 { kMaxDigitCount = 3 };
- // Helper class for translating among offset_t, ztf::LineCol and
- // ztf::DeltaLineCol.
- class ZtfTranslator {
- public:
- ZtfTranslator();
- ZtfTranslator(const ZtfTranslator&) = delete;
- const ZtfTranslator& operator=(const ZtfTranslator&) = delete;
- ~ZtfTranslator();
- // Initializes |line_starts_| with the contents of |image|.
- bool Init(ConstBufferView image);
- // Checks if |lc| is a valid location in the file.
- bool IsValid(ztf::LineCol lc) const;
- // Checks if |dlc| relative to |offset| is a valid location in the file.
- bool IsValid(offset_t offset, ztf::DeltaLineCol dlc) const;
- // Returns the offset corresponding to |line_col| if it is valid. Otherwise
- // returns |kInvalidOffset|.
- offset_t LineColToOffset(ztf::LineCol line_col) const;
- // Returns the ztf::LineCol for an |offset| if it is valid. Otherwise returns
- // absl::nullopt.
- absl::optional<ztf::LineCol> OffsetToLineCol(offset_t offset) const;
- private:
- // Returns an iterator to the range containing |offset|. Which is represented
- // by the starting offset. The next element will contain the upper bound of
- // the range.
- std::vector<offset_t>::const_iterator SearchForRange(offset_t offset) const;
- // Returns the length of a 1-indexed line. The caller is expected to check
- // that the requested line exists.
- offset_t LineLength(uint16_t line) const;
- offset_t NumLines() const {
- return static_cast<offset_t>(line_starts_.size() - 1);
- }
- // |line_starts_| is a sorted list of each line's starting offset, along with
- // the image size as the sentinel; it looks like {0, ..., image.size}.
- std::vector<offset_t> line_starts_;
- };
- // Disassembler for Zucchini Text Format (ZTF).
- class DisassemblerZtf : public Disassembler {
- public:
- static constexpr uint16_t kVersion = 1;
- // Target Pools
- enum ReferencePool : uint8_t {
- kAngles, // <>
- kBraces, // {}
- kBrackets, // []
- kParentheses // ()
- };
- // Type breakdown. Should contain all permutations of ReferencePool, Abs|Rel
- // and the possible number of digits (1-3).
- enum ReferenceType : uint8_t {
- kAnglesAbs1,
- kAnglesAbs2,
- kAnglesAbs3,
- kAnglesRel1,
- kAnglesRel2,
- kAnglesRel3,
- kBracesAbs1,
- kBracesAbs2,
- kBracesAbs3,
- kBracesRel1,
- kBracesRel2,
- kBracesRel3,
- kBracketsAbs1,
- kBracketsAbs2,
- kBracketsAbs3,
- kBracketsRel1,
- kBracketsRel2,
- kBracketsRel3,
- kParenthesesAbs1,
- kParenthesesAbs2,
- kParenthesesAbs3,
- kParenthesesRel1,
- kParenthesesRel2,
- kParenthesesRel3,
- kNumTypes
- };
- DisassemblerZtf();
- DisassemblerZtf(const DisassemblerZtf&) = delete;
- const DisassemblerZtf& operator=(const DisassemblerZtf&) = delete;
- ~DisassemblerZtf() override;
- // Applies quick checks to determine if |image| *may* point to the start of a
- // ZTF file. Returns true on success.
- static bool QuickDetect(ConstBufferView image);
- // Disassembler:
- ExecutableType GetExeType() const override;
- std::string GetExeTypeString() const override;
- std::vector<ReferenceGroup> MakeReferenceGroups() const override;
- // Reference Readers, templated to allow configurable digit count and pool.
- template <uint8_t digits, ReferencePool pool>
- std::unique_ptr<ReferenceReader> MakeReadAbs(offset_t lo, offset_t hi);
- template <uint8_t digits, ReferencePool pool>
- std::unique_ptr<ReferenceReader> MakeReadRel(offset_t lo, offset_t hi);
- // Reference Writers, templated to allow configurable digit count and pool.
- template <uint8_t digits, ReferencePool pool>
- std::unique_ptr<ReferenceWriter> MakeWriteAbs(MutableBufferView image);
- template <uint8_t digits, ReferencePool pool>
- std::unique_ptr<ReferenceWriter> MakeWriteRel(MutableBufferView image);
- private:
- friend Disassembler;
- // Disassembler:
- bool Parse(ConstBufferView image) override;
- ZtfTranslator translator_;
- };
- } // namespace zucchini
- #endif // COMPONENTS_ZUCCHINI_DISASSEMBLER_ZTF_H_
|