{"id":16582128,"url":"https://github.com/chalin/code_excerpter","last_synced_at":"2025-08-08T01:09:06.182Z","repository":{"id":77274654,"uuid":"134732231","full_name":"chalin/code_excerpter","owner":"chalin","description":"A line-based utility for extracting code regions.","archived":false,"fork":false,"pushed_at":"2024-02-06T23:48:16.000Z","size":40,"stargazers_count":9,"open_issues_count":3,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-01-03T12:50:22.311Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chalin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-05-24T15:08:02.000Z","updated_at":"2024-02-06T22:17:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"1804ecd2-f7ad-46f5-bc1a-2887f2d62387","html_url":"https://github.com/chalin/code_excerpter","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chalin%2Fcode_excerpter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chalin%2Fcode_excerpter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chalin%2Fcode_excerpter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chalin%2Fcode_excerpter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chalin","download_url":"https://codeload.github.com/chalin/code_excerpter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233275576,"owners_count":18651573,"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":[],"created_at":"2024-10-11T22:31:40.389Z","updated_at":"2025-01-09T23:47:26.465Z","avatar_url":"https://github.com/chalin.png","language":"Dart","readme":"# code_excerpter\n\nA line-based builder for extracting code regions from source files.\n\nDocumentation for a package or framework often contains code excerpts.\nThere are two main approaches to ensuring that such **code excerpts remain\nup-to-date** as the package or framework code base evolves.\n(1) A [literate programming][] approach, where **code\nfragments are extracted from the docs**, then analyzed and tested.\n(2) A complementary approach where named **code regions are extracted from\nsources**, and docs are refreshed (as needed) when code regions change.\n\nBoth approaches have their merits, but `code_excerpter`, and its companion tool\n[code_excerpt_updater][], support (2). More specifically:\n\n- `code_excerpter` is a builder that can be used to extract code regions from source files.\n- [code_excerpt_updater][] can be used to refresh code regions inside docs using\n  the output from `code_excerpter`\n\n## Usage synopsis\n\n1. One-time setup: define a builder config file.\n2. Markup your sources with (optionally named) code regions\n   delimited by `#docregion` / `#enddocregion` pairs, each written\n   inside a line comment. An example is given below.\n3. Run the builder.\n4. Use [code_excerpt_updater][] to update your docs.\n\nRepeat steps 2-4 as the code base evolves.\n\n## Examples sources\n\n```dart\n// #docregion imports\nimport 'dart:async';\n// #enddocregion imports\n\n// #docregion main, main-stub\nvoid main() async {\n  // #enddocregion main-stub\n  print('Compute π using the Monte Carlo method.');\n  await for (var estimate in computePi().take(500)) {\n    print('π ≅ $estimate');\n  }\n  // #docregion main-stub\n}\n// #enddocregion main, main-stub\n\n/// Generates a stream of increasingly accurate estimates of π.\nStream\u003cdouble\u003e computePi({int batch: 100000}) async* {\n  // ...\n}\n```\n\nThe regions defined in the Dart source above are: `imports`, `main`, `main-stub`,\nand (implicitly) the **default region** named  `''`.\nIf you don't explicitly delimit the default region, it is assumed to be the\nentire file.\n\nSome of the regions defined in the example above include:\n\n- `imports` region:\n  \u003e ```dart\n  \u003e import 'dart:async';\n  \u003e ```\n\n- `main-stub` region:\n  \u003e ```dart\n  \u003e void main() async {\n  \u003e   // ···\n  \u003e }\n  \u003e ```\n\nThe `main-stub` region is discontinuous, that is, it has a break in it.\nBy default, when the [code_excerpt_updater][] renders a region with breaks,\neach breaks is replaced by a (language-specific) comment line filled with a\nplaster marker (`···`).\n\nFor details concerning the processing of plasters, see the\n[code_excerpt_updater][] documentation.\n\nNotes:\n\n- If a code region end coincides with the file end, then its closing\n  `#enddocregion` can be omitted.\n- The `code_excerpter` supports source files in all popular languages including\n  Dart, HTML, YAML, CSS, SCSS, and more.\n\n## Syntax\n\nAs illustrated above, the region markers can be followed by zero or more comma-separated region names.\n\nA legal **region name** is one of:\n\n- `''`\n- A non-empty sequence of alphanumeric characters possibly containing a hyphen (`-`)\n  or an underscore (`_`).\n\n## Sample builder config\n\nTo use the builder, create a config file such as the following `build.yaml` file:\n\n```yaml\ntargets:\n  $default:\n    sources:\n      include: [examples/**]\n      exclude:\n        - '**/.*/**'\n        - '**/build/**'\n    builders:\n      code_excerpter|code_excerpter:\n        enabled: true\n```\n\nBuild by running this command:\n\n```sh\ndart run build_runner build --output=\u003csome-directory\u003e\n```\n\nYaml files containing excerpts (`*.excerpt.yaml`) will be placed in the build output folder.\n\n[code_excerpt_updater]: https://github.com/chalin/code_excerpt_updater\n[literate programming]: https://en.wikipedia.org/wiki/Literate_programming","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchalin%2Fcode_excerpter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchalin%2Fcode_excerpter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchalin%2Fcode_excerpter/lists"}