Parser

️ AVERTISSEMENT: Ce projet a évolué npmjs.com de "dss" à "@documented-style-sheets/parser"

DSS , Documentred Style Sheets est un guide de commentaires à usage général et un analyseur (Ex. CSS, moins, Stylus, Sass, SCSS & JS Commentaires). Ce projet fait une analyse de fichiers statique et l'analyse pour générer un objet à utiliser pour générer des style de style.

Table des matières

• Installation
• Analyser un fichier
  • dss.detector
  • dss.parser
• Autres projets

Installation

npm i @documented-style-sheets/parser

Analyser un fichier

Dans la plupart des cas, vous voudrez inclure l'analyseur DSS dans une étape de construction qui générera automatiquement des fichiers de documentation (ou vous voulez simplement jouer avec cet Object retourné pour d'autres moyens); Quoi qu'il en soit, nous soutenons officiellement un plugin grogné et un plugin Gulp.

Exemples

Exemple de format de bloc de commentaires

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

Exemple d'utilisation

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

Exemple de sortie

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

Cette méthode définit la manière dont les points d'intérêt (c'est-à-dire les variables) se trouvent dans les lignes de texte puis, plus tard, analysés. DSS Dogfoods cette API et l'implémentation par défaut est indiquée ci-dessous.

Détecteur par défaut:

 // 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 (<nom>, <nalback>)

DSS , par défaut, comprend 4 analyseurs pour le name , description , state et markup d'un bloc de commentaires. Vous pouvez ajouter ou remplacer ces défauts en enregistrant un nouvel analyseur. Ces valeurs par défaut suivent également un modèle qui utilise le décorateur @ pour les identifier. Vous pouvez modifier ce comportement en fournissant une fonction de rappel différente à dss.detector() .

dss.parser s'attend au nom de la variable que vous recherchez et à une fonction de rappel pour manipuler le contenu. Tout ce qui est renvoyé par cette fonction de rappel est ce qui est utilisé pour générer JSON.

Rappel this :

• this.file : le fichier actuel
• this.name : le nom de l'analyseur
• this.options : les options qui ont été transmises à dss.parse() initialement
• this.line :
  • this.line.contents : le contenu associé à cette variable
  • this.line.from : le numéro de ligne où cette variable a été trouvée
  • this.line.to : le numéro de ligne où le contenu de cette variable s'est terminé
• this.block :
  • this.block.contents : le contenu associé au bloc de commentaires de cette variable
  • this.block.from : le numéro de ligne où commence le bloc de commentaires de cette variable
  • this.block.to : le numéro de ligne où se termine le bloc de commentaires de cette variable

Exemples d'analyseurs personnalisés:

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

Autres projets

• Plugin grogné
• Plugin Gulp
• Plugin de texte sublime
• Enregistreur UX
• Joueur UX
• Plugin SourceJS