Parser

Euen WARNUNG: Dieses Projekt hat npmjs.com von "dss" zu "@documented-style-sheets/parser" übertragen.

DSS , dokumentierte Style Sheets ist ein allgemeiner Kommentarführer und Parser (z. B. CSS, Less, Stylus, Sass, SCSS & JS-Kommentare). Dieses Projekt führt eine statische Dateianalyse und Parsen durch, um ein Objekt zu generieren, das zum Generieren von StyleGuides verwendet werden soll.

Inhaltsverzeichnis

• Installation
• Analyse einer Datei
  • dss.detector
  • dss.parser
• Andere Projekte

Installation

npm i @documented-style-sheets/parser

Analyse einer Datei

In den meisten Fällen möchten Sie den DSS -Parser in einen Build -Schritt einbeziehen, in dem Dokumentationsdateien automatisch generiert werden (oder Sie möchten nur mit diesem zurückgegebenen Object für andere Mittel herumspielen). In beiden Fällen unterstützen wir offiziell ein Grunzen -Plugin und ein Gulp -Plugin.

Beispiele

Beispiel Kommentarblockformat

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

Beispiel Verwendung

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

Beispielausgabe

{
  "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; "
  }
}

ds.detektor (<Callback>)

Diese Methode definiert die Art und Weise, wie sich Punkte von Interesse (dh Variablen) in Textlinien und später analysiert haben. DSS Dogfoods Diese API und die Standardimplementierung ist unten aufgeführt.

Standarddetektor:

 // 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 enthält standardmäßig 4 Parsers für den name , description , state und markup eines Kommentarblocks. Sie können diese Standardeinstellungen hinzufügen oder überschreiben, indem Sie einen neuen Parser registrieren. Diese Standardeinstellungen folgen auch einem Muster, das den @ Decorator verwendet, um sie zu identifizieren. Sie können dieses Behaivour ändern, der eine andere Rückruffunktion als dss.detector() bereitstellt.

dss.parser erwartet den Namen der gesuchten Variablen und eine Rückruffunktion, um den Inhalt zu manipulieren. Was auch immer durch diese Rückruffunktion zurückgegeben wird, wird verwendet, um JSON zu generieren.

Rufen Sie this :

• this.file : Die aktuelle Datei
• this.name : Der Name des Parsers
• this.options : Die Optionen, die anfangs an dss.parse() übergeben wurden
• this.line :
  • this.line.contents : Der mit dieser Variablen verknüpfte Inhalt
  • this.line.from : Die Zeilennummer, in der diese Variable gefunden wurde
  • this.line.to : Die Zeilennummer, in der die Inhalte dieser Variablen endete
• this.block :
  • this.block.contents : Der mit dem Kommentarblock dieser Variablen zugeordnete Inhalt
  • this.block.from : Die Zeilennummer, in der der Kommentarblock dieser Variablen beginnt
  • this.block.to : Die Zeilennummer, in der der Kommentarblock dieser Variablen endet

Beispiele für benutzerdefinierte Parser:

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

Andere Projekte

• Grunzen Plugin
• Gulp Plugin
• Sublime Text Plugin
• UX Recorder
• UX -Spieler
• SourceJS -Plugin