{"id":19640519,"url":"https://github.com/kentnl/ppix-documentname","last_synced_at":"2026-06-12T12:31:18.055Z","repository":{"id":26989381,"uuid":"30453234","full_name":"kentnl/PPIx-DocumentName","owner":"kentnl","description":"Utility to extract a name from a PPI Document","archived":false,"fork":false,"pushed_at":"2017-03-06T05:06:15.000Z","size":107,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-04-26T03:42:29.604Z","etag":null,"topics":["perl"],"latest_commit_sha":null,"homepage":null,"language":"Perl","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/kentnl.png","metadata":{"files":{"readme":"README.mkdn","changelog":"Changes","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-02-07T11:04:11.000Z","updated_at":"2017-03-06T03:30:28.000Z","dependencies_parsed_at":"2022-08-31T21:34:35.536Z","dependency_job_id":null,"html_url":"https://github.com/kentnl/PPIx-DocumentName","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/kentnl/PPIx-DocumentName","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kentnl%2FPPIx-DocumentName","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kentnl%2FPPIx-DocumentName/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kentnl%2FPPIx-DocumentName/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kentnl%2FPPIx-DocumentName/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kentnl","download_url":"https://codeload.github.com/kentnl/PPIx-DocumentName/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kentnl%2FPPIx-DocumentName/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34245217,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["perl"],"created_at":"2024-11-11T14:06:01.313Z","updated_at":"2026-06-12T12:31:18.035Z","avatar_url":"https://github.com/kentnl.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NAME\n\nPPIx::DocumentName - Utility to extract a name from a PPI Document\n\n# VERSION\n\nversion 0.001004\n\n# DESCRIPTION\n\nThis module contains a few utilities for extracting a \"name\" out of an arbitrary Perl file.\n\nTypically, this is the `module` name, in the form:\n\n    package Foo\n\nHowever, it also supports extraction of an override statement in the form:\n\n    # PODNAME: OverrideName::Goes::Here\n\nWhich may be more applicable for documents that lack a `package` statement, or the `package`\nstatement may be \"wrong\", but they still need the document parsed under the guise of having a name\n( for purposes such as POD )\n\n# USAGE\n\nThe recommended approach is simply:\n\n    use PPIx::DocumentName;\n\n    # Get a PPI Document Somehow\n    return PPIx::DocumentName-\u003eextract( $ppi_document );\n\n# METHODS\n\n## extract\n\n    my $docname = PPIx::DocumentName-\u003eextract( $ppi_document );\n\nThis will first attempt to extract a name via the `PODNAME: ` comment notation,\nand then fall back to using a `package Package::Name` statement.\n\n`$ppi_document` is ideally a `PPI::Document`, but will be auto-up-cast if it is\nany of the parameters `PPI::Document-\u003enew()` understands.\n\n## extract\\_via\\_statement\n\n    my $docname = PPIx::DocumentName-\u003eextract_via_statement( $ppi_document );\n\nThis only extract `package Package::Name` statement based document names.\n\n`$ppi_document` is ideally a `PPI::Document`, but will be auto-up-cast if it is\nany of the parameters `PPI::Document-\u003enew()` understands.\n\n## extract\\_via\\_comment\n\n    my $docname = PPIx::DocumentName-\u003eextract_via_comment( $ppi_document );\n\nThis will only extract `PODNAME: ` comment based document names.\n\n`$ppi_document` is ideally a `PPI::Document`, but will be auto-up-cast if it is\nany of the parameters `PPI::Document-\u003enew()` understands.\n\n# ALTERNATIVE NAMES\n\nOther things I could have called this\n\n- `PPIx::PodName` - But it isn't, because it doesn't extract from `POD`, only returns data that may be useful **FOR**\n`POD`\n- `PPIx::ModuleName` - But it kinda isn't either, because its more generic than that and is tailored to extracting\n\"a name\" out of any PPI Document, and they're _NOT_ all modules.\n\n# SIMILAR MODULES\n\nModules that are perceptibly similar to this ones tasks ( but are subtly different in important ways ) are as follows:\n\n- [`Module::Metadata`](https://metacpan.org/pod/Module::Metadata) - Module::Metadata does a bunch of things this module explicitly doesn't\nwant or need to do, and it lacks a bunch of features this module needs.\n\n    Module::Metadata is predominantly concerned with extracting _ALL_ name spaces and _ALL_ versions from a module for the\n    purposes of indexing and indexing related tasks. This also means it has a notion of \"hideable\" name spaces with the purpose\n    of hiding them from `CPAN`.\n\n    Due to being core as well, it is not able to use `PPI` for its features, so the above concerns mean it is also mostly\n    based on careful regex parsing, which can easily be false tripped on miscellaneous in document content.\n\n    Whereas `PPIx::DocumentName` only cares about the _first_ name of a given class, and it cares much more about nested\n    strings being ignored intentionally. It also has a motive to show names _even_ for documents that won't be indexed\n    ( And `Module::Metadata` has no short term plans on exposing hidden document names ).\n\n    `PPIx::DocumentName` also has special logic for the `PODNAME: ` declaration, and may eventually support other\n    mechanisms for extracting a name from \"a document\", which will be not in `Module::Metadata`'s collection of desired\n    use-cases.\n\n- [`Module::Extract::Namespaces`](https://metacpan.org/pod/Module::Extract::Namespaces) - This is probably closer to\n`PPIx::DocumentName`'s requirements, using `PPI` to extract content.\n\n    Most of `Module::Extract::Namespaces`'s code seems to be glue for legacy versions of `PPI` and the remaining\n    code is for loading modules from `@INC` ( Which we don't need ), or special casing IO ( Which is also not necessary,\n    as this module assumes you're moderately acquainted with `PPI` and can do IO yourself )\n\n    `Module::Extract::Namespaces` also obliterates document comments, which of course stands in the way of our auxiliary\n    requirements re `PODNAME: ` declarations.\n\n    It will also not be flexible enough to support other name extraction features we may eventually add.\n\n    And like `Module::Metadata`, it also focuses on extracting _many_ `package` declarations where this module prefers\n    to extract only the _first_.\n\n# ACKNOWLEDGEMENTS\n\nThe bulk of this logic was extrapolated from [`Pod::Weaver::Section::Name`](https://metacpan.org/pod/Pod::Weaver::Section::Name)\nand a related role, [`Pod::Weaver::Role::StringFromComment`](https://metacpan.org/pod/Pod::Weaver::Role::StringFromComment).\n\nThanks to [`RJBS`](cpan:///author/RJBS) for the initial implementation and [`DROLSKY`](cpan:///author/DROLSKY) for some of the improvement patches.\n\n# AUTHOR\n\nKent Fredric \u003ckentnl@cpan.org\u003e\n\n# COPYRIGHT AND LICENSE\n\nThis software is copyright (c) 2017 by Kent Fredric \u003ckentfredric@gmail.com\u003e.\n\nThis is free software; you can redistribute it and/or modify it under\nthe same terms as the Perl 5 programming language system itself.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkentnl%2Fppix-documentname","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkentnl%2Fppix-documentname","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkentnl%2Fppix-documentname/lists"}