Parser

️ Предупреждение: этот проект перешел на npmjs.com от "dss" к "@documented-style-sheets/parser"

DSS , документированные листы стилей-это руководство по комментариям общего назначения и анализатор (Ex. CSS, Less, Stylus, Sass, SCSS & JS Comments). Этот проект выполняет статический анализ файлов и анализ для генерации объекта, который будет использоваться для генерации StyleGuides.

Оглавление

• Установка
• Анализ файла
  • dss.detector
  • dss.parser
• Другие проекты

Установка

npm i @documented-style-sheets/parser

Анализ файла

В большинстве случаев вы захотите включить DSS -анализатор в шаг сборки, который будет автоматически генерировать файлы документации (или вы просто хотите поиграть с этим возвращенным Object для других средств); В любом случае, мы официально поддерживаем плагин с ворчанием и плагин Gulp.

Примеры

Пример формата блока комментариев

 //
// @name Button
// @description Your standard form button.
// 
// @state :hover - Highlights when hovering.
// @state :disabled - Dims the button when disabled.
// @state .primary - Indicates button is the primary action.
// @state .smaller - A smaller button
// 
// @markup
//   <button>This is a button</button>
// 

Пример использования

 // Requirements
const fs = require ( 'fs' )
const { parse } = require ( '@documented-style-sheets/parser' )

// Get file contents
const fileContents = fs . readFileSync ( 'styles.css' )

// Run the DSS Parser on the file contents
parse ( fileContents , { } , function ( parsedObject ) {
  // Output the parsed document
  console . log ( parsedObject )
} ) 

Пример вывода

{
  "name" : " Button " ,
  "description" : " Your standard form button. " ,
  "state" : [
    { 
      "name" : " :hover " ,
      "escaped" : " pseudo-class-hover " ,
      "description" : " Highlights when hovering. "
    },
    {
      "name" : " :disabled " ,
      "escaped" : " pseudo-class-disabled " ,
      "description" : " Dims the button when disabled. "
    },
    {
      "name" : " .primary " ,
      "escaped" : " primary " ,
      "description" : " Indicates button is the primary action. "
    },
    {
      "name" : " .smaller " ,
      "escaped" : " smaller " ,
      "description" : " A smaller button "
    }
  ],
  "markup" : {
    "example" : " <button>This is a button</button> " ,
    "escaped" : " &lt;button&gt;This is a button&lt;/button&gt; "
  }
}

dss.detector (<обратный вызов>)

Этот метод определяет способ, которым интересующие точки (т.е. переменные) обнаружены в строках текста, а затем, позже, проанализированы. DSS Dogfoods Этот API и реализация по умолчанию показаны ниже.

Детектор по умолчанию:

 // Describe default detection pattern
// Note: the current line, as a string, is passed to this function
const dss = require ( '@documented-style-sheets/parser' )
dss . detector ( function ( line ) {
  if ( typeof line !== 'string' ) {
    return false
  }
  var reference = line . split ( "nn" ) . pop ( )
  return ! ! reference . match ( / .*@ / )
} )

dss . parse ( ... ) 

dss.parser (<mame>, <обратный вызов>)

DSS , по умолчанию, включает в себя 4 анализатора для name , description , state и markup блока комментариев. Вы можете добавить или переопределить эти значения по умолчанию, зарегистрировав новый анализатор. Эти значения по умолчанию также следуют за шаблоном, который использует декоратор @ для их идентификации. Вы можете изменить это Behaivour, предоставляя другую функцию обратного вызова dss.detector() .

dss.parser ожидает названия переменной, которую вы ищете, и функцию обратного вызова, чтобы манипулировать содержимым. Все, что возвращается этой функцией обратного вызова, - это то, что используется в Generate JSON.

this вызов:

• this.file : текущий файл
• this.name : имя анализатора
• this.options : варианты, которые были переданы dss.parse() изначально
• this.line :
  • this.line.contents : содержание, связанное с этой переменной
  • this.line.from : номер строки, где была найдена эта переменная
  • this.line.to : номер строки, где закончилось содержимое этой переменной
• this.block :
  • this.block.contents : контент, связанный с блоком комментариев этой переменной
  • this.block.from : номер строки, где начинается блок комментариев этой переменной
  • this.block.to : номер строки, где заканчивается блок комментариев этой переменной

Пользовательские примеры анализатора:

 // Matches @version
dss . parser ( 'version' , function ( ) {
  // Just returns the lines contents
  return this . line . contents
} ) 

 dss . parser ( 'link' , function ( ) {
  // Replace link with HTML wrapped version
  const exp = / (b(https?|ftp|file): / / [ - A - Z0 - 9 + & @# / % ? = ~ _ | ! : , . ; ] * [ - A - Z0 - 9 + & @# / %= ~ _ | ] ) / ig
  this . line . contents . replace ( exp , "<a href='$1'>$1</a>" )
  return line
} )

Другие проекты

• Грант плагин
• Плагин Gulp
• Подличный текстовый плагин
• UX Регистратор
• UX Player
• Плагин SourceJS