Hatena::ブログ(Diary)

naoyaのはてなダイアリー

April 29, 2006

Hatena-Keyword-0.02

前のエントリのモジュール、とりあえず CPAN に up できる形にしてみました。

それに合わせていくつか修正も加えてます。

  • RPC::XML::Client->new の引数の渡し方が間違ってた。
  • Jcode は $keyword->jcode で取得するように変更した。
  • POD 書いた。英語がやばげ。

という感じ。まだ CPAN には up してません。懸念事項が幾つか。

  • retrieve というメソッド名。引数に与えたテキストに含まれるキーワードを取得する、というのでこの名前は適切か。
  • 名前空間。Hatena-API-Auth に合わせて Hatena-API-Keyword にするべきか。これは別に Hatena-Keyword でもいいかなとか思ってるけど。

あたりを決めかねてます。コメント歓迎。

NAME
    Hatena::Keyword - Extract Hatena Keywords used in your text

VERSION
    Version 0.02

SYNOPSIS
        use Hatena::Keyword;

        @keywords = Hatena::Keyword->retrieve("Perl and Ruby and Python.");
        print $_->score, "?t", $_ for @keywords;

        $keywords = Hatena::Keyword->retrieve("Hello, Perl!", {
            score => 20,
            cname => qw[(hatena web book)],
        });
        print $_->refcount, "?t", $_->jcode->euc for @$keywords;

        $html = Hatena::Keyword->markup_as_html("Perl and Ruby");
        $html = Hatena::Keyword->markup_as_html("Hello, Perl!", {
            score    => 20,
            cname    => qw[(hatena web book)],
            a_class  => 'keyword',
            a_target => '_blank',
        });

DESCRIPTION
    This module allows you to extract Hatena keywords used in your arbitrary
    text and also allows you to mark up your text as HTML with the keywords.

    It queries Hatena Keyword Link API internally for retrieving terms.

CLASS METHODS
  retrieve($text, ?%options)
    Returns an array or an array reference which contains Hatena::Keyword
    objects extracted from specified text as first argument.

    Note that character encoding of the text must be utf-8. And also
    returned words are encoded as utf-8 string.

    Second argument is a option, which will be passed through to the XML-RPC
    API.

  markup_as_html($text, ?%options)
    Returns a tagged html string with Hatena Keywords like this:

      <a href="http://d.hatena.ne.jp/keyword/Perl">Perl</a> and <a
      href="http://d.hatena.ne.jp/keyword/Ruby">Ruby</a>

    It takes two arguments, same as "retrieve()".

INSTANCE METHODS
  as_string
    Returns a Hatena::Keyword object to a plain string, an alias for
    "word()". Hatena::Keyword objects are also converted to plain strings
    automatically by overloading. This means that objects can be used as
    plain strings in most Perl constructs.

  word
    Returns a plain string of the word.

  score
    Returns a score of the word.

  refcount
    Returns a reference count of the word, which means used times of the
    term whole over the Hatena Diary.

  cname
    Returns a category name of the word.

  jcode
    Returns a Jcode objet which contains the word.

AUTHOR
    Naoya Ito, "<naoya at bloghackers.net>"

BUGS
    Please report any bugs or feature requests to "bug-hatena-keyword at
    rt.cpan.org", or through the web interface at
    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Hatena-Keyword>. I will
    be notified, and then you'll automatically be notified of progress on
    your bug as I make changes.

SUPPORT
    You can find documentation for this module with the perldoc command.

        perldoc Hatena::Keyword

    You can also look for information at:

    * AnnoCPAN: Annotated CPAN documentation
        <http://annocpan.org/dist/Hatena-Keyword>

    * CPAN Ratings
        <http://cpanratings.perl.org/d/Hatena-Keyword>

    * RT: CPAN's request tracker
        <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Hatena-Keyword>

    * Search CPAN
        <http://search.cpan.org/dist/Hatena-Keyword>

SEE ALSO
    Hatena Keyword Auto-Link API <http://tinyurl.com/m5dkm> (redirect to
    d.hatena.ne.jp)
    Hatena Diary <http://d.hatena.ne.jp/>
    Hatena <http://www.hatena.ne.jp/>

COPYRIGHT & LICENSE
    Copyright 2006 Naoya Ito, all rights reserved.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

kosakikosaki 2006/04/29 22:04 うーん、うーん
retrieve だと get とか do とか書いちゃうぐらいに意味が広いので何をするメソッドかドキュメントちゃんと読まないといけないメソッドになってしまうキガス

naoyanaoya 2006/04/29 22:12 やっぱりそうですねえ、対案は何がいいですかね。extract かな。あるいは extract_from。

himazubloghimazublog 2006/04/30 08:34 extractがいいと思います。この単語の「抽出する」という感じが、「retrieve」メソッドのしていることにふさわしいと思うからです。NAMEセクションでもextractを使っていますし。

NAMEセクションの「Extract Hatena Keywords used in your text」は「Extract Hatena Keywords in a String」としてはどうでしょうか。やっていることを素直に表現するとそうなる気がします。その他にも「a」で済むところを「your」としているところがいくつも見受けられます。

DESCRIPTIONの中でHatena Keywordとは何かを説明しないと、Hatenaを知らずにPODを読んだ人は「Hatenaってなんだ?」と思ってしまいますよね。たとえばこんな感じで「A Hatena keyword is an element in a suite of web sites *.hatena.ne.jp having blogs and social bookmarks among others. Please refer to xxxx (in Japanese) for details.」

日本語の文字列についても動作するんですよね。そのことに言及する必要がありますよね。

活用法の例もあるといいですね。モジュールの目的・働きがよりはっきりしますから。たとえばこんな感じで「In Hatena Diary, a blog hosting service, a Hatena keyword found in a posting is linked to the keyword’s page automatically. You can implement the same kind of feature outside Hatena using this module.」

naoyanaoya 2006/04/30 11:00 おおお、どうもです! 素敵すぎます、助かります!

retrieve を extract に変更しつつ、POD の英語をいろいろ書き替えていま CPAN に 0.03 up しました。

- http://bloghackers.net/~naoya/lib/perlmodules/Hatena-Keyword-0.03/

事後になってしまいましたが、ACKNOWLEDGEMENTS に今津さん、それか kosaki さんと、あとブックマークコメントでアドバイスをもらった tsupo さんの名前を記入させていただきました。

ありがとうございます。

# あ、Changes 書き替えるの忘れたw

Connection: close