{"id":16582120,"url":"https://github.com/chalin/code_excerpt_updater","last_synced_at":"2025-07-20T22:06:37.220Z","repository":{"id":77274653,"uuid":"90026920","full_name":"chalin/code_excerpt_updater","owner":"chalin","description":null,"archived":false,"fork":false,"pushed_at":"2024-02-06T22:25:08.000Z","size":146,"stargazers_count":5,"open_issues_count":6,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-13T05:02:30.116Z","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":"mit","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":"2017-05-02T11:38:54.000Z","updated_at":"2024-02-06T22:25:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"a85d5261-18f3-481f-bb4e-f087777432cd","html_url":"https://github.com/chalin/code_excerpt_updater","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/chalin/code_excerpt_updater","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chalin%2Fcode_excerpt_updater","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chalin%2Fcode_excerpt_updater/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chalin%2Fcode_excerpt_updater/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chalin%2Fcode_excerpt_updater/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chalin","download_url":"https://codeload.github.com/chalin/code_excerpt_updater/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chalin%2Fcode_excerpt_updater/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266205450,"owners_count":23892464,"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:36.224Z","updated_at":"2025-07-20T22:06:37.199Z","avatar_url":"https://github.com/chalin.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Markdown code-block updater\n\nThis is the repo for a simple _line-based_ updater for markdown code-blocks preceded by XML\nprocessor instructions of the form `\u003c?code-excerpt ...?\u003e`. Dart (`.dart`), markdown (`.md`), and \nJade (`.jade`) files are processed. For Dart source files, code blocks in API comments are updated.\n\n## 1. Installation\n\n```shell\npub global activate --source git https://github.com/chalin/code_excerpt_updater.git\n```\n\n## 2. Usage\n\n```\nUsage: code_excerpt_updater [OPTIONS] file_or_directory...\n\n    --exclude=\u003cPATH_REGEXP,...\u003e       Paths to exclude when processing a directory recursively.\n                                      Dot files and directorys are always excluded.\n\n    --fail-on-refresh                 Report a non-zero exit code if a fragment is refreshed.\n-p, --fragment-dir-path               PATH to directory containing code fragment files\n                                      (defaults to \"\", that is, the current working directory).\n\n-h, --help                            Show command help.\n-i, --indentation                     NUMBER. Default number of spaces to use as indentation for code inside code blocks.\n                                      (defaults to \"0\")\n\n-q, --src-dir-path                    PATH to directory containing code used in diffs\n                                      (defaults to \"\", that is, the current working directory).\n\n-w, --write-in-place                  Write updates to files in-place.\n    --[no-]escape-ng-interpolation    Escape Angular interpolation syntax {{...}} as {!{...}!}.\n                                      (defaults to on)\n\n    --plaster                         TEMPLATE. Default plaster template to use for all files.\n                                      For example, \"// Insert your code here\"; use \"none\" to remove plasters.\n\n    --replace                         REPLACE-EXPRESSIONs. Global replace argument. See README for syntax.\n    --yaml                            Read excerpts from *.excerpt.yaml files.\n```\n\nReturns a non-zero exit code errors occur during file processing, or if fragments were refreshed and \n`--fail-on-refresh` is requested.\n\n## 3. `\u003c?code-excerpt?\u003e` syntax\n\n### a. Code fragment\n\nThe instruction comes in three forms. The first (and most common) form must immediately precede a markdown code block:\n\n\n    \u003c?code-excerpt \"path/file.ext (optional-region-name)\" arg0=\"value0\" ...?\u003e\n    ```\n      ...\n    ```\n\nThe first (unnamed) argument defines a path to a fragment file. The argument can optionally name a code fragment region\n\u0026mdash; any non-word character sequences (`\\w+`) in the region name are converted to a hyphen.\n\nRecognized arguments are:\n\n- `from=\"string|/regex/\"`: skips the initial lines until one is found matching the given pattern.\n- `region`, a code fragment region name.\n- `replace=\"/regexp/replacement/g;...\"` defines one or more semi-colon separated [regular expression][]/replacement\n  expression pairs for use in a global search-and-replace applied to the code excerpt.\n  The replacement expression can contain capture group syntax `$\u0026`, `$1`, `$2`, ... .\n- `remove=\"string|/regexp/\"`: remove the lines, from the identified code excerpt file, which contain the given string\n   or match _regexp_. To match a string starting with a slash, escape it.\n- `retain=\"string|/regexp/\"`: retain the lines, from the identified code excerpt file, which contain the given string\n   or match _regexp_. To match a string starting with a slash, escape it.\n- `indent-by` defines the number of spaces to be used to indent the code in the code block.\n   (Default is no indentation.)\n- `path-base`, when provided, must be the only argument. Its use is described below in the second instruction form.\n- `plaster=\"...\"` determines how plaster marker lines are handled in excerpts. When set to \"none\", the plaster marker\n  lines are removed. Otherwise, the attribute value defines a plaster template, possibly containing `$defaultPlaster`.\n  Examples: `plaster=\"/* $defaultPlaster */\"`, `plaster=\"/* add your code here */\"`.\n  When using legacy excerpts, the only supported value of this attribute is \"none\".\n  The default plaster is `···`, contained in a language-specific comment that is determined from the excerpt directive.\n  The language is the code-block language, if specified, otherwise it is taken to be the excerpt path extension.\n- `skip=\"n\"`: skips the first _n_ lines of the excerpt when _n_ is non-negative; drops (skips) the last\n  _n_ lines otherwise.\n- `take=\"n\"`: takes the first _n_ lines of the excerpt when _n_ is non-negative; takes the last\n  _n_ lines otherwise.\n- `to=\"string|/regex/\"`: skips the lines after the first line found matching the given pattern.\n\nNotes:\n- Arguments are processed in the order they appear. This is significant for arguments like\n  `replace`, `remove`, etc.\n- The `\u003c?code-excerpt?\u003e` instruction can optionally be preceded by an single-line comment\n  token. Namely either `//` or `///`.\n- Path, and arguments if given, must be enclosed in double quotes.\n- It is a limitation of processing instructions that it cannot contain a `\u003e` character.\n  This limitation can be overcome in some situations: e.g., in a regexp, use `\\x3E` as an encoding of `\u003e`.\n- If both `retain` and `replace` arguments are provided, the `retain` filter is always applied first.\n\n### b. Code diff\n\nThe second form of the instruction must also be followed by a code block:\n\n    \u003c?code-excerpt \"path/file1.ext (optional-region-name)\" diff-with=\"path2/file2.ext2\" optional-args?\u003e\n    ```\n      ...\n    ```\n\nIf you diff files whose paths share a prefix and/or suffix, then you can drop the\n`diff-with` argument and use the Bash path-brace syntax instead. For example:\n\n    \u003c?code-excerpt \"path/{subpath1,subpath2}/file.ext (optional-region-name)\" optional-args?\u003e\n    ```\n      ...\n    ```\n\nThese are the optional arguments (usage is explained further below):\n\n- `from=\"regexp\"`\n- `to=\"regexp\"`\n- `diff-u=\"NUM\"`\n\nWhen the code_excerpt_updater is run, it will update the content of the code\nblock with the output of `diff -u path/filtered_file1.ext path2/filtered_file2.ext2` truncated at the first diff \noutput line that matches the `to` regular expression, where the `filtered_file*.ext*` represents the corresponding\nfile `file*.ext*` but with docregion tags removed. When an optional region name is provided, then the named regions\n(the same in both files) are compared.\n\nIf `diff-u=\"NUM\"` is used, then the diff command is called with the `-U NUM` flag instead of `-u`.\n\n### c. Set instruction\n\nUse a set instruction to globally set a path base, or a replace expression (using the syntax described above).\n\nA global **replace** instructions applies to all subsequence code-excerpt instructions. To reset, use an\nempty replace argument. If a code-excerpt instruction has a replace argument, the global replace\nis applied after the code-excerpt-specific replace.\n\nHere is an example of setting a **path base**:\n\n```\n\u003c?code-excerpt path-base=\"subdirPath\"?\u003e\n```\n\nFollowing this instruction, the paths to file fragments will be interpreted relative to the `path-base` argument.\n\n### Limitations\n\nXML processing instructions cannot contain `\u003e`. In particular this means that attribute values cannot contain `\u003e`,\nwhich is a limitation for the diff `from` and `to` regular expressions.\n\n## 4. Code excerpt lookup and updating\n\nThe updater does not create code fragment files. It does expect such files to \nexist and be named following the conventions described below.\n\nFor a directive like `\u003c?code-excerpt \"dir/file.ext\" region=\"rname\"?\u003e`, the updater will search the\nfragment folder, for a file named:\n\n- `dir/file-rname.ext.txt`\u003cbr\u003e\n   or\n- `dir/file.ext.txt`\u003cbr\u003e\n   if the region is omitted\n\nIf no such fragment is found, it will search the source directory (`--src-dir-path`) for a file named:\n\n- `dir/file.ext`\n\nIf the updater finds a (fragment or original source) file, it will replace the lines contained within\nthe markdown code block with those from that file, indenting each\nfragment file line as specified by the `indent-by` argument.\n\nFor example, if `hello.dart.txt` contains the line \"print('Hi');\" then\n\n```\n/// \u003c?code-excerpt \"hello.dart\" indent-by=\"2\"?\u003e\n/// ```dart\n///   print('Bonjour');\n/// ```\n```\n\nwill be updated to\n\n```\n/// \u003c?code-excerpt \"hello.dart\" indent-by=\"2\"?\u003e\n/// ```dart\n///   print('Hi');\n/// ```\n```\n\n## 5. Example\n\nConsider the following API doc excerpt from the\n[NgStyle](https://webdev.dartlang.org/api/angular/angular.common/NgStyle-class) class.\n\n```dart\n    /// ### Examples\n    ///\n    /// Try the [live example][ex] from the [Template Syntax][guide] page. Here are\n    /// the relevant excerpts from the example's template and the corresponding\n    /// component class:\n    ///\n    /// \u003c?code-excerpt \"docs/template-syntax/lib/app_component.html\" region=\"NgStyle\"?\u003e\n    /// ```html\n    /// ```\n    ///\n    /// \u003c?code-excerpt \"docs/template-syntax/lib/app_component.dart\" region=\"NgStyle\"?\u003e\n    /// ```dart\n    /// ```\n```\n\nGiven an appropriate path to the folder containing code fragment files, this\nupdate tool would generate:\n\n```dart\n    /// ### Examples\n    ///\n    /// Try the [live example][ex] from the [Template Syntax][guide] page. Here are\n    /// the relevant excerpts from the example's template and the corresponding\n    /// component class:\n    ///\n    /// \u003c?code-excerpt \"docs/template-syntax/lib/app_component.html\" region=\"NgStyle\"?\u003e\n    /// ```html\n    /// \u003cdiv\u003e\n    ///   \u003cp [ngStyle]=\"setStyle()\" #styleP\u003eChange style of this text!\u003c/p\u003e\n    /// \n    ///   \u003clabel\u003eItalic: \u003cinput type=\"checkbox\" [(ngModel)]=\"isItalic\"\u003e\u003c/label\u003e |\n    ///   \u003clabel\u003eBold: \u003cinput type=\"checkbox\" [(ngModel)]=\"isBold\"\u003e\u003c/label\u003e |\n    ///   \u003clabel\u003eSize: \u003cinput type=\"text\" [(ngModel)]=\"fontSize\"\u003e\u003c/label\u003e\n    /// \n    ///   \u003cp\u003eStyle set to: \u003ccode\u003e'{{styleP.style.cssText}}'\u003c/code\u003e\u003c/p\u003e\n    /// \u003c/div\u003e\n    /// ```\n    ///\n    /// \u003c?code-excerpt \"docs/template-syntax/lib/app_component.dart\" region=\"NgStyle\"?\u003e\n    /// ```dart\n    /// bool isItalic = false;\n    /// bool isBold = false;\n    /// String fontSize = 'large';\n    /// String fontSizePx = '14';\n    /// \n    /// Map\u003cString, String\u003e setStyle() {\n    ///   return {\n    ///     'font-style': isItalic ? 'italic' : 'normal',\n    ///     'font-weight': isBold ? 'bold' : 'normal',\n    ///     'font-size': fontSize\n    ///   };\n    /// }\n    /// ```\n```\n\n## 6. Tests\n\nRepo tests can be launched from `test/main.dart`.\n\n[regular expression]: https://api.dartlang.org/stable/dart-core/RegExp-class.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchalin%2Fcode_excerpt_updater","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchalin%2Fcode_excerpt_updater","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchalin%2Fcode_excerpt_updater/lists"}