{"id":22486942,"url":"https://github.com/Documented-Style-Sheets/Parser","last_synced_at":"2025-08-02T19:33:33.763Z","repository":{"id":4395152,"uuid":"5532236","full_name":"Documented-Style-Sheets/Parser","owner":"Documented-Style-Sheets","description":":page_facing_up: Documented Style Sheets Parser","archived":false,"fork":false,"pushed_at":"2023-01-28T20:50:19.000Z","size":164,"stargazers_count":379,"open_issues_count":9,"forks_count":37,"subscribers_count":24,"default_branch":"main","last_synced_at":"2024-11-16T16:05:38.255Z","etag":null,"topics":["comments","css","detector","dss","javascript","parser","static-analysis","styling"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Documented-Style-Sheets.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2012-08-23T20:50:17.000Z","updated_at":"2024-05-17T16:40:33.000Z","dependencies_parsed_at":"2023-02-15T18:31:13.044Z","dependency_job_id":null,"html_url":"https://github.com/Documented-Style-Sheets/Parser","commit_stats":{"total_commits":101,"total_committers":14,"mean_commits":7.214285714285714,"dds":"0.27722772277227725","last_synced_commit":"967b3824a0d449f44b099ff1e85379b52ef8d6c6"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Documented-Style-Sheets%2FParser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Documented-Style-Sheets%2FParser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Documented-Style-Sheets%2FParser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Documented-Style-Sheets%2FParser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Documented-Style-Sheets","download_url":"https://codeload.github.com/Documented-Style-Sheets/Parser/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228500211,"owners_count":17930009,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["comments","css","detector","dss","javascript","parser","static-analysis","styling"],"created_at":"2024-12-06T17:15:38.433Z","updated_at":"2024-12-06T17:16:17.313Z","avatar_url":"https://github.com/Documented-Style-Sheets.png","language":"JavaScript","readme":"[![npm](https://img.shields.io/npm/v/dss.svg?maxAge=2592000\u0026style=flat-square)](https://www.npmjs.com/package/dss)\n[![npm](https://img.shields.io/npm/dt/dss.svg?maxAge=2592000\u0026style=flat-square)](https://www.npmjs.com/package/dss)\n\n\u003e ⚠️ **Warning:** this project has moved on `npmjs.com` from `\"dss\"` to [`\"@documented-style-sheets/parser\"`](https://npmjs.org/package/@documented-style-sheets/parser)\n\n**DSS**, Documented Style Sheets is a general-purpose comment guide and parser (ex. CSS, LESS, STYLUS, SASS, SCSS \u0026 JS comments). This project does static file analysis and parsing to generate an object to be used for generating styleguides.\n\n\n##### Table of Contents\n\n- [Installation](#installation)\n- [Parsing a File](#parsing-a-file)\n  - [`dss.detector`](#dssdetector-callback-)\n  - [`dss.parser`](#dssparser-name-callback-)\n- [Other Projects](#other-projects)\n\n### Installation\n\n```bash\nnpm i @documented-style-sheets/parser\n```\n\n### Parsing a File\n\nIn most cases, you will want to include the **DSS** parser in a build step that will generate documentation files automatically (or you just want to play around with this returned `Object` for other means); Either way, we officially support a [Grunt Plugin](https://github.com/dsswg/grunt-dss) and a [Gulp Plugin](http://github.com/dsswg/gulp-dss).\n\n### Examples\n\n##### Example Comment Block Format\n\n\n```scss\n//\n// @name Button\n// @description Your standard form button.\n// \n// @state :hover - Highlights when hovering.\n// @state :disabled - Dims the button when disabled.\n// @state .primary - Indicates button is the primary action.\n// @state .smaller - A smaller button\n// \n// @markup\n//   \u003cbutton\u003eThis is a button\u003c/button\u003e\n// \n````\n\n##### Example Usage\n\n```javascript\n// Requirements\nconst fs = require('fs')\nconst { parse } = require('@documented-style-sheets/parser')\n\n// Get file contents\nconst fileContents = fs.readFileSync('styles.css')\n\n// Run the DSS Parser on the file contents\nparse(fileContents, {}, function (parsedObject) {\n  // Output the parsed document\n  console.log(parsedObject)\n})\n````\n\n##### Example Output\n\n```json\n{\n  \"name\": \"Button\",\n  \"description\": \"Your standard form button.\",\n  \"state\": [\n    { \n      \"name\": \":hover\",\n      \"escaped\": \"pseudo-class-hover\",\n      \"description\": \"Highlights when hovering.\"\n    },\n    {\n      \"name\": \":disabled\",\n      \"escaped\": \"pseudo-class-disabled\",\n      \"description\": \"Dims the button when disabled.\"\n    },\n    {\n      \"name\": \".primary\",\n      \"escaped\": \"primary\",\n      \"description\": \"Indicates button is the primary action.\"\n    },\n    {\n      \"name\": \".smaller\",\n      \"escaped\": \"smaller\",\n      \"description\": \"A smaller button\"\n    }\n  ],\n  \"markup\": {\n    \"example\": \"\u003cbutton\u003eThis is a button\u003c/button\u003e\",\n    \"escaped\": \"\u0026lt;button\u0026gt;This is a button\u0026lt;/button\u0026gt;\"\n  }\n}\n````\n#### dss.detector(\\\u003ccallback\\\u003e)\n\nThis method defines the way in which points of interest (ie. variables) are found in lines of text and then, later, parsed. **DSS** dogfoods this API and the default implementation is shown below.\n\n###### Default Detector:\n\n```javascript\n// Describe default detection pattern\n// Note: the current line, as a string, is passed to this function\nconst dss = require('@documented-style-sheets/parser')\ndss.detector(function(line) {\n  if (typeof line !== 'string') {\n    return false\n  }\n  var reference = line.split(\"\\n\\n\").pop()\n  return !!reference.match(/.*@/)\n})\n\ndss.parse(...)\n````\n\n#### dss.parser(\\\u003cname\\\u003e, \\\u003ccallback\\\u003e)\n\n**DSS**, by default, includes 4 parsers for the `name`, `description`, `state` and `markup` of a comment block. You can add to, or override, these defaults by registering a new parser. These defaults also follow a pattern which uses the `@` decorator to identify them. You can modify this behaivour providing a different callback function to `dss.detector()`.\n\n`dss.parser` expects the name of the variable you're looking for and a callback function to manipulate the contents. Whatever is returned by that callback function is what is used in generate JSON.\n\n##### Callback `this`:\n\n- `this.file`: The current file\n- `this.name`: The name of the parser\n- `this.options`: The options that were passed to `dss.parse()` initially\n- `this.line`:\n  - `this.line.contents`: The content associated with this variable\n  - `this.line.from`: The line number where this variable was found\n  - `this.line.to`: The line number where this variable's contents ended\n- `this.block`:\n  - `this.block.contents`: The content associated with this variable's comment block\n  - `this.block.from`: The line number where this variable's comment block starts\n  - `this.block.to`: The line number where this variable's comment block ends\n  \n    \n##### Custom Parser Examples:\n\n```javascript\n// Matches @version\ndss.parser('version', function () {\n  // Just returns the lines contents\n  return this.line.contents\n})\n````\n\n```javascript\ndss.parser('link', function () {\n  // Replace link with HTML wrapped version\n  const exp = /(b(https?|ftp|file)://[-A-Z0-9+\u0026@#/%?=~_|!:,.;]*[-A-Z0-9+\u0026@#/%=~_|])/ig\n  this.line.contents.replace(exp, \"\u003ca href='$1'\u003e$1\u003c/a\u003e\")\n  return line\n})\n````\n\n### Other Projects\n- [Grunt Plugin](http://github.com/dsswg/grunt-dss)\n- [Gulp Plugin](http://github.com/dsswg/gulp-dss)\n- [Sublime Text Plugin](https://github.com/sc8696/sublime-css-auto-comments)\n- [UX Recorder](http://github.com/dsswg/dss-recorder)\n- [UX Player](http://github.com/dsswg/dss-player)\n- [SourceJS Plugin](https://github.com/sourcejs/sourcejs-contrib-dss)\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDocumented-Style-Sheets%2FParser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDocumented-Style-Sheets%2FParser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDocumented-Style-Sheets%2FParser/lists"}