Синтаксис кода [map]

Автор намеревается сделать формат bb-кода карты универсальным стандартом среди форумов и других инструментов совместной работы, вроде MediaWiki. Здесь описывается формат кода.

Описание

BB-код карты обычно заключён в теги [map]...[/map]. Конечно, это не обязательно: например, в вики в качестве тегов может использоваться HTML: <map>...</map>. Открывающий тег может включать уровень масштаба и необязательные координаты центра карты (широта,долгота): [map=10] или [map=12,59.9,30.5]. В этом случае они приоритетнее автоматически определённых масштаба и центра карты.

Тег содержит неупорядоченный список объектов, разделённых символом точки с запятой. Объектов может не быть — тогда карта показывает место, определённое в открывающем теге, или центрируется на координатах по умолчанию.

Объект может быть маркером, ломаной или полигоном (многоугольником). Все типы определяются списком координат, разделённых пробелами, тоже в формате широта,долгота. У маркеров координата одна, у ломаных — много, у полигонов последняя пара координат равняется первой.

Координаты обычно записываются в проекции WGS-84, но иногда это может быть иначе. Например, при рисовании поверх некоей картинки (например, карты в видеоигре), могут быть использованы координаты в пикселях.

У объектов есть дополнительные атрибуты: строка в скобках после списка координат. Она выглядит как (параметр,параметр|подпись): несколько слов через запятую (из букв и цифр), вертикальная черта и строка подписи. Обе части — параметры и подпись — могут быть пропущены. В отсутствие параметров вертикальную черту можно не указывать, но тогда первая вертикальная черта в подписи должна быть экранирована: \|. Закрывающие скобки в подписи также должны быть экранированы: \). Помимо этих двух, любые символы могут присутствовать в подписи: обычно это строка в формате HTML или BBCode.

Редактор в MapBBCodeUI.js предполагает, что подпись — HTML-код, но экранирует все специальные символы, кроме ограниченного набора тегов (<a>, <br>, <span> и ещё нескольких). Ещё он знает некоторые цвета: так, red окрасит ломаную или полигон в красный цвет, и так далее.

Примеры

[map][/map]

Отображает карту в местоположении по умолчанию, без объектов.

[map=10,59.95,30.27][/map]

Отображает карту Санкт-Петербурга без дополнительных объектов.

[map]59.939,30.3159(Дворцовая)[/map]

Карта центрирована на Дворцовой площади, посередине — маркер. На маркере есть подпись (обычно выводится по щелчку): «Дворцовая».

[map]59.939,30.3159; 59.93709,30.31265 59.93115,30.3602 (black|);
59.94577,30.33244 59.93904,30.3369 59.93408,30.33497 59.92257,30.30776[/map]

Маркер всё ещё на Дворцовой площади; Невский проспект обозначен чёрной линией, а часть Садовой улицы — линией цвета по умолчанию (обычно синего).

[map]55.7547,37.6181 55.7553,37.6191 55.7531,37.6232 55.7528,37.622
     55.7547,37.6181(red|Square)[/map]

Красная площадь в Москве накрыта красным многоугольником, на котором при щелчке появляется всплывающая панель со словом «Square».

BNF

Для упрощения, некоторые базовые нетерминалы определим с помощью регулярных выражений.

<empty>   ::= ""
<zoom>    ::= [12]?[0-9]
<number>  ::= -?[0-9]+(\.[0-9]+)?
<word>    ::= [a-z0-9]+
<noslash> ::= .*?[^\\]

<coordinate>  ::= <number> "," <number>
<coordinates> ::= <coordinate> | <coordinate> " " <coordinate>
<title>       ::= <empty> | <noslash>
<words>       ::= <empty> | <word> | <word> "," <words>
<parameters>  ::= "(" <words> "|" <title> ")" | "(" <title> ")"
<element>     ::= <coordinates> | <coordinates> <parameters>
<elements>    ::= <empty> | <element> | <element> ";" <elements>
<position>    ::= <zoom> | <zoom> "," <coordinate>
<openingtag>  ::= "[map]" | "[map=" <position> "]"
<map>         ::= <openingtag> <elements> "[/map]"

Библиотека

MapBBCode.js — эталонная библиотека для разбора и создания bb-кода [map]. Она содержит полные регулярные выражения для кода и три функции, которые можно использовать в собственных проектах.

• isValid(string) проверяет, что строка содержит корректный bb-код карты.

• stringToObjects(string) разбирает строку кода и возвращает объект:

    {
      objs: [{
        coords: [<координата>, ...],
        text: <строка>,
        params: [<строка>, ...]
      }, ...],
      zoom: <число>,
      pos: <координата>
    }
  

  Формат <координаты> зависит от того, подключена ли библиотека Leaflet: это либо экземпляр класса L.LatLng, либо массив из двух чисел: [latitude, longitude].

• objectsToString(object) принимает объект того же формата, что выдаёт stringToObjects, и возвращает строку bb-кода.

Развитие

Формат bb-кода карты высечен в камне. Но параметры объектов, нетерминалы <word> в BNF, могут содержать что угодно. На этот момент лишь один тип параметра определён: это цвет. Можно добавить, например, ширину линии параметром w<число>, либо тип маркера. Реализации кода карты не обязаны поддерживать какие-либо параметры, поэтому параметры не должны влиять на поведение или форму объектов.