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 - хеш от исходного файла, для которого были созданы данные хинты. Нужен для обнаружения того, что файл изменился.

Вопросы:

• Нужно предусмотреть расширяемость.
• Как хранить timestamp?
  • Если обычный UNIX timestamp?
  • Если в человекочитаемой дате, то возникает множество проблем: порядок месяца и числа (американский формат: MM-DD-YYYY vs традиционный: DD-MM-YYYY), для сортировки может быть удобнее обратный формат: YYYY-MM-DD и т.п.
• **ToDo Проработать более подробно, когда дело дойдет до редактирования. ** Для случая, когда документ отредактирован и range больше не тот который нужен, хранить несколько строчек до и несколько строчек после участка в исходном тексте для восстановления позиции хинта в документе. (Как в diff. Спасибо east825 за идею.)