Skip to content
This repository was archived by the owner on Oct 9, 2020. It is now read-only.

Hint Format

Jump to bottom
east825 edited this page Feb 18, 2013 · 20 revisions

Обсуждение формата файла с хинтами

Формат должен быть одновременно относительно простым для машинной генерации ?и относительно человекочитаемым?.

По поводу человекочитаемости спорный вопрос: подразумевается ли, что кто-то будет вручную набирать хинты plain текстом? Если в плагин когда-нибудь будет добавлена возможность сохранения файла с хинтами - человекочитаемость самого формата не нужна.

Варианты:

  • JSON документ
  • XML

Пока склоняемся к JSON. Примерный формат:

{
"meta": {
    "createdTimestamp" : "",
    "modifiedTimestamp" : "",
    "author" : "",
    "createdWith" : "",
    "sourceFileHash" : ""
},
"hints": [
    {
        "range": {
            "start": {
                "line" : 7,
                "column" : 42
            },
            "end": {
                "line" : 13,
                "column" : 42
            }
        },
        "hintText" : ""
    },
    {
        "range": {
            "start": {
                "line" : 7,
                "column" : 42
            },
            "end": {
                "line" : 13,
                "column" : 42
            }
        },
        "hintText" : ""
    }
]
}

Комментарии east825: У меня есть следующие предложения касательно представления файла хинтов:

  • убрать ключ meta. Он кажется мне избыточным, проще все метаданные кидать прямо в корень. Таким образом в файле будут хинты (обязательная запись) и опциональная метаинформация.
  • кажется разумным не ограничивать облать хинта одним диапазоном. Например, рецензент может решить одно замечание отнести к нескольким местам в исходных текстах. Возможность использования нескольких курсоров в Sublime только этому способствует.
  • мне кажется, что диапазон можно представить как-нибудь попроще, например, списком из четырех целых чисел как [fromLine, fromCol, toLine, toCol]

Некоторые комментарии к не совсем очевидным полям: createdWith - строка, описывающая версию ПО, которым был создан данный документ. sourceFileHash - хеш от исходного файла, для которого были созданы данные хинты. Нужен для обнаружения того, что файл изменился.

Вопросы:

Q:

  • Нужно предусмотреть расширяемость.

Q:

  • Как хранить timestamp?
    • Если обычный UNIX timestamp?
    • Если в человекочитаемой дате, то возникает множество проблем: порядок месяца и числа (американский формат: mm-dd-yyyy vs традиционный: dd-mm-yyyy), для сортировки может быть удобнее обратный формат: yyyy-mm-dd и т.п.

A:

Спасибо east825.

  • Хорошее предложение: хранить в ISO08601: yyyy-mm-dd:hh:mm:ss .

+:

  • Общепринятый стандарт.
  • От старшей единицы измерения к младшей - удобно сортировать, если понадобится.
  • Компромисс между человекочитаемостью и удобством манипулирования (например, той же сортировки).

Q:

  • Для случая, когда документ отредактирован и range больше не тот который нужен, хранить несколько строчек до и несколько строчек после участка в исходном тексте для восстановления позиции хинта в документе. (Как в diff. Спасибо east825 за идею.) ToDo Проработать более подробно, когда дело дойдет до редактирования.

Clone this wiki locally