in reply to Re: Meta-perl - sorting my perl subs with perl?
in thread Meta-perl - sorting my perl subs with perl?

This should work. But think hard about keeping comments and POD in the right place, e.g. either at the top of the file or before the sub to be commented. You might start with a 4-state state machine: 
start-of-file -> ??? -> sub-header
sub-header -> /^sub / -> in-sub
in-sub -> /^}$/ -> sub-header
sub-header -> eof() || /^__(END|DATA)__$/ -> end-of-file

[download]
And remember to save that last non-empty "sub-header" when you reach EOF.

Replies are listed 'Best First'.
Re^3: Meta-perl - sorting my perl subs with perl?
by JavaFan (Canon) on Jan 20, 2012 at 23:14 UTC
    In my world, there's only place for POD to go: at the end of the file.

    Comments are easy. If there are comments related to a sub, but outside of the sub, they'll precede the sub and have their comment marker in the left column.

    But luckily, I never have felt the urge to sort my subs in alphabetical order; to me that makes as much sense as sorting my bookshelves on colour. I group related subs together.

[reply]
      In my world, there's only place for POD to go: at the end of the file.
      After getting used to Emacs's docstrings, I find that style annoying. The docstring is actually within the function, explains its usage, and gets extracted when you compile documentation. If you put all your POD at the end, you either lose the ability to put usage next to the function, or have to duplicate your POD in a comment.
[reply]
        POD != comment. The intended audience is different. If you treat them as the same, both sides will suffer.

        Comments are for the programmer, that is, the person maintaining the code. POD is there to create a manual. The intended audience is the user of the code. I usually do not document my subs in the same order as they appear in the file, and I typically have quite a number of subs that will not be documented in the user manual. And I want to be able to reorder my subs, or my documentation, without having to reorder the other.

        have to duplicate your POD in a comment.
        So what? If the goal is to minimize the work you need to do as a programmer, don't write any POD or comments. If the the goal is to create a better product, I don't care if there's some duplication going on. Copy and paste is cheap and easy. (But it will be a selective copy and paste anyway).
[reply]
        > After getting used to Emacs's docstrings, I find that style annoying

        BTW: One of the clear advantages of Python are docstrings.

        I agree to a certain point, that docstrings are perfect for "source" documentation for maintainers.

        If it comes to "usage" documentation separated POD is IMHO better to show the big picture.

        Since this thread is about extracting subs we are clearly talking about the first kind of documentation

        I regularly tried to have discussions on that matter (since there is a big overlap between both kind of documentation) but that normally ends in flame wars... :(

        Cheers Rolf

[reply]

      As I mentioned upstream, it's difficult to subgroup this... morass more. I've already pulled out the content that's going to be on every document into another module from the stuff that's optional and might show up "anywhere" into another module.

      The naming scheme on the subs is already going to group subs sorted alphabetically about as well as I can get them further grouped.

      It's either that or I'll have three to five modules with two to four subs in them (for the few tables that have a few variations), and a gigantic "misc" lump. Which is barely helpful.

      But thank you, /^sub/ is a facepalmingly simple solution. Of course I don't need to balance braces. Jeeze. All this text is rotting my brain.

[reply]

In Section Seekers of Perl Wisdom