Parser

️ PERINGATAN: Proyek ini telah pindah di npmjs.com dari "dss" ke "@documented-style-sheets/parser"

DSS , lembar gaya yang didokumentasikan adalah panduan komentar tujuan umum dan parser (mis. CSS, kurang, stylus, sass, komentar SCSS & JS). Proyek ini melakukan analisis file statis dan penguraian untuk menghasilkan objek yang akan digunakan untuk menghasilkan styleGuides.

Daftar isi

• Instalasi
• Parsing file
  • dss.detector
  • dss.parser
• Proyek lain

Instalasi

npm i @documented-style-sheets/parser

Parsing file

Dalam kebanyakan kasus, Anda akan ingin memasukkan parser DSS dalam langkah build yang akan menghasilkan file dokumentasi secara otomatis (atau Anda hanya ingin bermain -main dengan Object yang dikembalikan ini untuk cara lain); Either way, kami secara resmi mendukung plugin Grunt dan plugin Gulp.

Contoh

Contoh Format Blok Komentar

 //
// @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>
// 

Contoh penggunaan

 // 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 )
} ) 

Output contoh

{
  "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 (<callback>)

Metode ini mendefinisikan cara di mana tempat menarik (mis. Variabel) ditemukan dalam baris teks dan kemudian, kemudian, diuraikan. DSS Dogfoods API ini dan implementasi default ditunjukkan di bawah ini.

Detektor default:

 // 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 (<name>, <callback>)

DSS , secara default, termasuk 4 parser untuk name , description , state dan markup blok komentar. Anda dapat menambahkan, atau mengganti, default ini dengan mendaftarkan parser baru. Default ini juga mengikuti pola yang menggunakan @ dekorator untuk mengidentifikasi mereka. Anda dapat memodifikasi behaivour ini yang menyediakan fungsi panggilan balik yang berbeda ke dss.detector() .

dss.parser mengharapkan nama variabel yang Anda cari dan fungsi panggilan balik untuk memanipulasi isinya. Apa pun yang dikembalikan oleh fungsi panggilan balik itu adalah apa yang digunakan dalam menghasilkan JSON.

Callback this :

• this.file : file saat ini
• this.name : nama parser
• this.options : Opsi yang diteruskan ke dss.parse() pada awalnya
• this.line :
  • this.line.contents : konten yang terkait dengan variabel ini
  • this.line.from : nomor garis di mana variabel ini ditemukan
  • this.line.to : Nomor baris di mana konten variabel ini berakhir
• this.block :
  • this.block.contents : konten yang terkait dengan blok komentar variabel ini
  • this.block.from : nomor baris di mana blok komentar variabel ini dimulai
  • this.block.to : nomor baris di mana blok komentar variabel ini berakhir

Contoh Parser Kustom:

 // 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
} )

Proyek lain

• Plugin Grunt
• Plugin tegukan
• Plugin Teks Sublim
• Perekam UX
• UX Player
• Plugin SourceJS