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

Hint Format

Jump to bottom
yaromir edited this page Feb 15, 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" : ""
    }
]
}

Некоторые комментарии к не совсем очевидным полям: 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 . +:

  • Общепринятый стандарт.

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

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

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

Clone this wiki locally