{"id":13629592,"url":"https://github.com/excubo-ag/Generators.Grouping","last_synced_at":"2025-04-17T09:35:05.734Z","repository":{"id":65469046,"uuid":"289274730","full_name":"excubo-ag/Generators.Grouping","owner":"excubo-ag","description":null,"archived":false,"fork":false,"pushed_at":"2024-10-11T15:03:11.000Z","size":92,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-10-11T15:17:10.579Z","etag":null,"topics":["api","roslyn"],"latest_commit_sha":null,"homepage":"","language":"C#","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/excubo-ag.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2020-08-21T13:20:29.000Z","updated_at":"2024-10-11T15:03:14.000Z","dependencies_parsed_at":"2023-02-14T01:31:56.115Z","dependency_job_id":"f1dc3545-bd6a-4e01-9dee-7d84e2664fe7","html_url":"https://github.com/excubo-ag/Generators.Grouping","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/excubo-ag%2FGenerators.Grouping","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/excubo-ag%2FGenerators.Grouping/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/excubo-ag%2FGenerators.Grouping/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/excubo-ag%2FGenerators.Grouping/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/excubo-ag","download_url":"https://codeload.github.com/excubo-ag/Generators.Grouping/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223751261,"owners_count":17196597,"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":["api","roslyn"],"created_at":"2024-08-01T22:01:14.419Z","updated_at":"2024-11-08T20:31:20.880Z","avatar_url":"https://github.com/excubo-ag.png","language":"C#","funding_links":[],"categories":["Do not want to test 112 ( old ISourceGenerator )"],"sub_categories":["1. [ThisAssembly](https://ignatandrei.github.io/RSCG_Examples/v2/docs/ThisAssembly) , in the [EnhancementProject](https://ignatandrei.github.io/RSCG_Examples/v2/docs/rscg-examples#enhancementproject) category"],"readme":"\r\n# Excubo.Generators.Grouping\r\n\r\n[![Nuget](https://img.shields.io/nuget/v/Excubo.Generators.Grouping)](https://www.nuget.org/packages/Excubo.Generators.Grouping/)\r\n[![Nuget](https://img.shields.io/nuget/dt/Excubo.Generators.Grouping)](https://www.nuget.org/packages/Excubo.Generators.Grouping/)\r\n[![GitHub](https://img.shields.io/github/license/excubo-ag/Generators.Grouping)](https://github.com/excubo-ag/Generators.Grouping)\r\n\r\nSome APIs have a lot of methods.\r\nWhen they all reside in the same object, finding the right API call can be a challenge to the users.\r\nBut replacing the structure of the API from a monolithic API to an API with intuitively named and smaller groups would break existing code.\r\nThe solution is to offer both, without having to write the grouping yourself.\r\n\r\n## How to use\r\n\r\n### 1. Install the nuget package Excubo.Generators.Grouping\r\n\r\nExcubo.Generators.Grouping is distributed [via nuget.org](https://www.nuget.org/packages/Excubo.Generators.Grouping/).\r\n[![Nuget](https://img.shields.io/nuget/v/Excubo.Generators.Grouping)](https://www.nuget.org/packages/Excubo.Generators.Grouping/)\r\n\r\n#### Package Manager:\r\n```ps\r\nInstall-Package Excubo.Generators.Grouping -Version 1.3.0\r\n```\r\n\r\n#### .NET Cli:\r\n```cmd\r\ndotnet add package Excubo.Generators.Grouping --version 1.3.0\r\n```\r\n\r\n#### Package Reference\r\n```xml\r\n\u003cPackageReference Include=\"Excubo.Generators.Grouping\" Version=\"1.3.0\" /\u003e\r\n```\r\n\r\n## Example\r\n\r\nConsider the API for drawing (example inspired by the HTML canvas API):\r\n\r\n```cs\r\npublic class API\r\n{\r\n    // sort order alphabetical, as it would appear in most IDEs\r\n    public void BezierCurveTo(...);\r\n    public void DrawText(...);\r\n    public void Fill();\r\n    public void FillEllipse(...);\r\n    public void FillPolygon(...);\r\n    public void FillRectangle(...);\r\n    public void FillTriangle(...);\r\n    public void LineTo(...);\r\n    public void MoveTo(...);\r\n    public void SaveState(...);\r\n    public void SetFont(...);\r\n    public void SetTextAlign(...);\r\n    public void Stroke();\r\n    public void StrokeEllipse(...);\r\n    public void StrokePolygon(...);\r\n    public void StrokeRectangle(...);\r\n    public void StrokeTriangle(...);\r\n    public void RestoreState(...);\r\n}\r\n```\r\n\r\nUsage could look like\r\n\r\n```cs\r\napi.SaveState();\r\napi.SetFont(\"Comic Sans\");\r\napi.DrawText(\"This API is convoluted\");\r\napi.RestoreState();\r\napi.StrokeRectangle(rect);\r\napi.MoveTo(origin);\r\napi.LineTo(chaos);\r\napi.Stroke();\r\n```\r\n\r\n\r\nIn this API, there are multiple concepts:\r\n- Drawing shapes (filled or just with a stroke)\r\n- State\r\n- Text\r\n- Paths\r\n\r\nTo find methods easier, we can create groups of methods, e.g.:\r\n\r\n- Path methods:\r\n\r\n```cs\r\npublic class API\r\n{\r\n    public struct _Paths\r\n    {\r\n        public void BezierCurveTo(...);\r\n        public void Fill();\r\n        public void LineTo(...);\r\n        public void MoveTo(...);\r\n        public void Stroke();\r\n    }\r\n```\r\n\r\n- State management:\r\n\r\n```cs\r\npublic class API\r\n{\r\n    public struct _State\r\n    {\r\n        public void Save(...);\r\n        public void Restore(...);\r\n    }\r\n}\r\n```\r\n\r\netc.\r\n\r\n:information_source:\r\nThe struct `_GroupName` allows this library to create a property named `GroupName`.\r\nThe group name is always equivalent to the name of the struct without the first character.\r\nIf you dislike `_`, you can use any other character, e.g. `G` for group.\r\n:information_source:\r\n\r\nThis library facilitates writing such groups, without interfering with the original API:\r\n\r\n```cs\r\npublic partial class API\r\n{\r\n    // the groups we want to offer: Paths, State, Text, Shapes\r\n    public partial struct _Paths {}\r\n    public partial struct _Shapes {}\r\n    public partial struct _State {}\r\n    public partial struct _Text {}\r\n    \r\n    // Annotated methods which will be replicated in the groups\r\n    [Group(typeof(_Paths))] public void BezierCurveTo(...);\r\n    [Group(typeof(_Text), \"Draw\")] public void DrawText(...);\r\n    [Group(typeof(_Paths))] public void Fill();\r\n    [Group(typeof(_Shapes))] public void FillEllipse(...);\r\n    [Group(typeof(_Shapes))] public void FillPolygon(...);\r\n    [Group(typeof(_Shapes))] public void FillRectangle(...);\r\n    [Group(typeof(_Shapes))] public void FillTriangle(...);\r\n    [Group(typeof(_Paths))] public void LineTo(...);\r\n    [Group(typeof(_Paths))] public void MoveTo(...);\r\n    [Group(typeof(_State), \"Save\")] public void SaveState(...);\r\n    [Group(typeof(_Text))] public void SetFont(...);\r\n    [Group(typeof(_Text))] public void SetTextAlign(...);\r\n    [Group(typeof(_Paths))] public void Stroke();\r\n    [Group(typeof(_Shapes))] public void StrokeEllipse(...);\r\n    [Group(typeof(_Shapes))] public void StrokePolygon(...);\r\n    [Group(typeof(_Shapes))] public void StrokeRectangle(...);\r\n    [Group(typeof(_Shapes))] public void StrokeTriangle(...);\r\n    [Group(typeof(_State), \"Restore\")] public void RestoreState(...);\r\n}\r\n```\r\n\r\nThe generated code then enables usage like this:\r\n\r\n```cs\r\napi.State.Save();\r\napi.Text.SetFont(\"Helvetica Neue\");\r\napi.Text.Draw(\"This API is intuitive\");\r\napi.State.Restore();\r\napi.Shapes.StrokeRectangle(rect);\r\napi.Paths.MoveTo(origin);\r\napi.Paths.LineTo(order);\r\napi.Paths.Stroke();\r\n```\r\n\r\n## Nested groups\r\n\r\nGroups can even be nested:\r\n\r\n```cs\r\npublic partial class API\r\n{\r\n    // the groups we want to offer: Paths, State, Text, Shapes\r\n    public partial struct _Shapes \r\n    {\r\n        public partial struct _Ellipse {}\r\n        public partial struct _Rectangle {}\r\n    }\r\n    \r\n    // Annotated methods which will be replicated in the groups\r\n    [Group(typeof(_Shapes._Ellipse), \"Fill\")] public void FillEllipse(...);\r\n    [Group(typeof(_Shapes._Rectangle), \"Fill\")] public void FillRectangle(...);\r\n    [Group(typeof(_Shapes._Ellipse), \"Stroke\")] public void StrokeEllipse(...);\r\n    [Group(typeof(_Shapes._Rectangle), \"Stroke\")] public void StrokeRectangle(...);\r\n}\r\n```\r\n\r\nwhich would be used as \r\n\r\n```cs\r\napi.Shapes.Ellipse.Fill();\r\napi.Shapes.Rectangle.Stroke();\r\n```\r\n\r\n## Multiple groups\r\n\r\nA method can be in multiple different groups:\r\n\r\n```cs\r\npublic partial class API\r\n{\r\n    // the groups we want to offer: Shapes, Fill\r\n    public partial struct _Shapes {}\r\n    public partial struct _Fill {}\r\n    \r\n    // Annotated methods which will be replicated in the groups\r\n    [Group(typeof(_Shapes)), Group(typeof(_Fill), \"Ellipse\")] public void FillEllipse(...);\r\n    [Group(typeof(_Shapes)), Group(typeof(_Fill), \"Rectangle\")] public void FillRectangle(...);\r\n}\r\n```\r\n\r\n\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexcubo-ag%2FGenerators.Grouping","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexcubo-ag%2FGenerators.Grouping","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexcubo-ag%2FGenerators.Grouping/lists"}