{"id":22695952,"url":"https://github.com/nvoynov/punch","last_synced_at":"2025-10-26T21:40:49.859Z","repository":{"id":50062346,"uuid":"518431803","full_name":"nvoynov/punch","owner":"nvoynov","description":"Punch focuses on business logic layer design in accordance with the principles of The Clean Architecture. It provides basic frame, code-generators, DSL, and CLI","archived":false,"fork":false,"pushed_at":"2024-03-09T11:30:13.000Z","size":183,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-26T20:22:00.609Z","etag":null,"topics":["business-logic-layer","cli","dsl","entity","erb","interactor","plugin","poro","ruby","service","source-code-generator","the-clean-architecture","usecase"],"latest_commit_sha":null,"homepage":"https://nvoynov.github.io/punch/","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nvoynov.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"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}},"created_at":"2022-07-27T11:34:44.000Z","updated_at":"2024-02-06T15:03:39.000Z","dependencies_parsed_at":"2024-03-07T08:50:02.457Z","dependency_job_id":null,"html_url":"https://github.com/nvoynov/punch","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nvoynov%2Fpunch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nvoynov%2Fpunch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nvoynov%2Fpunch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nvoynov%2Fpunch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nvoynov","download_url":"https://codeload.github.com/nvoynov/punch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248658667,"owners_count":21140976,"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":["business-logic-layer","cli","dsl","entity","erb","interactor","plugin","poro","ruby","service","source-code-generator","the-clean-architecture","usecase"],"created_at":"2024-12-10T04:12:54.500Z","updated_at":"2025-10-26T21:40:49.854Z","avatar_url":"https://github.com/nvoynov.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\r\ntitle: Punch Readme\r\nkeywords:\r\n  - ruby\r\n  - code-generator\r\n  - interactor\r\n  - entity\r\n  - gateway\r\n  - port\r\n  - business-logic-layer\r\n  - the-clean-architecture\r\n  - domain-driven-design\r\n...\r\n\r\nThe Punch is an opinionated Ruby Code Generator for Business Logic Layer, built with principles [The Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) and Domain Driven Design. Read [Intro](INTRO.md) to gasp some basic ideas.\r\n\r\n## Intro\r\n\r\nPlaying with [The Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) in 2021 I found it just an amazing tool, but a bit tiresome also because of the necessity to constantly create and require a bunch of standard source like entities, interactors and iths tests. That was the reason for designing Punch.\r\n\r\nI wanted just a few things\r\n\r\n1. Start as small as possible with PORO by adopting entities, interactors, and ports (gateways); postponing technologies (CLI, Web, Message Broker, Data Storage, etc.)\r\n2. Punch (generate, instead of writing manually) interactors and entities to boost productivity and reduce manual work.\r\n\r\n## Installation\r\n\r\nInstall the gem by cloing the repository\r\n\r\n    $ git clone https://github.com/nvoynov/punch.git\r\n    $ cd punch\r\n    $ rake install\r\n\r\n## Usage\r\n\r\nRun the following command for basic usage help:\r\n\r\n    $ punch\r\n\r\nPunch new ruby project directory and run some commands\r\n\r\n    $ punch ruby thing\r\n    $ cd thing\r\n    $ punch clean domain thing\r\n    $ punch clean interactor \"sign in\" email password\r\n    $ punch clean entity credentials email password\r\n    $ punch clean port \"data store\" all put get\r\n\r\n### Clean domain\r\n\r\n    $ punch clean domain thing\r\n\r\nThe command creates the followins sources:\r\n\r\n1. clean_architecture.yml with the domain name\r\n2. lib/thing.rb\r\n3. lib/thing/interactors.rb\r\n3. lib/thing/entities.rb\r\n3. lib/thing/ports.rb\r\n\r\n### Clean thing\r\n\r\n    $ punch clean CONCEPT NAME [PARAM1 PARAM2 PARAM3]\r\n\r\nThe command creates a clean component sources, depending on the CONCEPT prameters will be treated as properties or method parameters.\r\n\r\n    $ punch clean interactor \"sign in\" email password\r\n\r\nWill create\r\n\r\n1. lib/thing/interactors/sign_in.rb\r\n2. test/thing/interactors/test_sign_in.rb\r\n\r\nAnd rewrite lib/thing/interactors.rb by requiring the new interactor (require_relative \"ineractors/sign_in\")\r\n\r\nInteractor and Entity are simple POROs\r\n\r\n```ruby\r\n# SignIn\r\nclass SignIn\r\n  # @param email [Object]\r\n  # @param password [Object]\r\n  def call(email, password)\r\n    # TODO: implement me\r\n  end\r\nend\r\n\r\n# Credentials\r\nclass Credentials\r\n  # @return [Object]\r\n  attr_reader :email\r\n  # @return [Object]\r\n  attr_reader :password\r\n\r\n  # @param email [Object]\r\n  # @param password [Object]\r\n  def initialize(email, password)\r\n    @email = email\r\n    @password = password\r\n  end\r\nend\r\n```\r\n\r\n\r\n[Sources rewriting]{.underline}\r\n\r\nEach generated source will have banner comment with MD5 from content. When one punches file that already exists, punch will check content changes. When one changes source file content (content does not match MD5), punch will hold manual changes and show exclamation mark in log before the filename\r\n\r\n    $ punch clean entity credentials email password\r\n      lib/clean/entities.rb\r\n      lib/claen/entities/credential.rb\r\n      test/clean/entities/test_credentials.rb\r\n\r\nSuppose, one changed `credential.rb` file. Then running the command again, one will see\r\n\r\n    $ punch clean entity credentials email password\r\n      ..\r\n      !lib/claen/entities/credential.rb\r\n      ..\r\n\r\n### Clean DSL\r\n\r\n    $ punch clean dsl DSLFILE\r\n\r\nThe command will punch clean domain build from DSLFILE. One can find the DSL example in [test_dsl.rb](TODO)\r\n\r\n### Pipe and Filter\r\n\r\nFuture puncher will be about pipe and filter\r\n\r\n## Development\r\n\r\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\r\n\r\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).\r\n\r\n## Contributing\r\n\r\nBug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/punch.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnvoynov%2Fpunch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnvoynov%2Fpunch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnvoynov%2Fpunch/lists"}