Hint Format

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

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

По поводу человекочитаемости спорный вопрос: подразумевается ли, что кто-то будет вручную набирать хинты 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 .

+:

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

Q:

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