endpoint results from the CPAN

endpoint

App-org2wp

view release on metacpan or search on metacpan

package App::org2wp;

use 5.010001;
use strict;
use warnings;
use Log::ger;

use Perinci::Object qw(envresmulti);
use POSIX qw(strftime);

our $AUTHORITY = 'cpan:PERLANCAR'; # AUTHORITY
our $DATE = '2022-05-02'; # DATE
our $DIST = 'App-org2wp'; # DIST
our $VERSION = '0.013'; # VERSION

our %SPEC;

sub _fmt_timestamp_org {
    my $time = shift;

    strftime("%Y-%m-%d %a %H:%M", localtime($time));
}

$SPEC{'org2wp'} = {
    v => 1.1,
    summary => 'Publish Org document (or heading) to WordPress as blog post',
    description => <<'_',

This is originally a quick hack because I couldn't make
[org2blog](https://github.com/punchagan/org2blog) on my Emacs installation to
work after some update. `org2wp` uses the same format as `org2blog`, but instead
of being an Emacs package, it is a CLI script written in Perl.

First, create `~/org2wp.conf` containing the API credentials, e.g.:

    ; use INI (IOD) format for this file
    proxy=https://YOURBLOGNAME.wordpress.com/xmlrpc.php
    username=YOURUSERNAME
    password=YOURPASSWORD

Note that `proxy` is the endpoint URL of your WordPress instance's XML-RPC
server, which can be hosted on `wordpress.com` or on other server, including
your own. It has nothing to do with HTTP/HTTPS proxy; the term "proxy" is used
by the <pm:XMLRPC::Lite> and <pm:SOAP::Lite> Perl libraries and `org2wp` simply
uses the same terminology.

You can also put multiple credentials in the configuration file using profile
sections, e.g.:

    ; use INI (IOD) format for this file
    [profile=blog1]
    proxy=https://YOURBLOG1NAME.wordpress.com/xmlrpc.php
    username=YOURUSERNAME
    password=YOURPASSWORD

    [profile=blog2]
    proxy=https://YOURBLOG2NAME.wordpress.com/xmlrpc.php
    username=YOURUSERNAME
    password=YOURPASSWORD

and specify which profile you want using command-line option e.g.
`--config-profile blog1`.

### Document mode

You can use the whole Org document file as a blog post (document mode) or a
single heading as a blog post (heading mode). The default is document mode. To
create a blog post, write your Org document (e.g. in `post1.org`) using this
format:

    #+TITLE: Blog post title
    #+CATEGORY: cat1, cat2
    #+TAGS: tag1,tag2,tag3

    Text of your post ...
    ...

then:

    % org2wp post1.org

this will create a draft post. To publish directly:

    % org2wp --publish post1.org

Note that this will also modify your Org file and insert this setting line at
the top:

    #+POSTID: 1234
    #+POSTTIME: [2020-09-16 Wed 11:51]

where 1234 is the post ID retrieved from the server when creating the post, and
post time will be set to the current local time.

After the post is created, you can update using the same command:

    % org2wp post1.org

You can use `--publish` to publish the post, or `--no-publish` to revert it to
draft.

lib/App/org2wp.pm view on Meta::CPAN


Another example, to schedule a post in the future:

    % org2wp post1.org --schedule 20301225T00:00:00

### Heading mode

In heading mode, each heading will become a separate blog post. To enable this
mode, specify `--post-heading-level` (`-l`) to 1 (or 2, or 3, ...). This will
cause a level-1 (or 2, or 3, ...) heading to be assumed as an individual blog
post. For example, suppose you have `blog.org` with this content:

    * Post A                  :tag1:tag2:tag3:
    :PROPERTIES:
    :CATEGORY: cat1, cat2, cat3
    :END:

    Some text...

    ** a heading of post A
    more text ...
    ** another heading of post A
    even more text ...

    * Post B                  :tag2:tag4:
    Some text ...

with this command:

    % org2wp blog.org -l 1

there will be two blog posts to be posted because there are two level-1
headings: `Post A` and `Post B`. Post A contains level-2 headings which will
become headings of the blog post. Headline tags will become blog post tags, and
to specify categories you use the property `CATEGORY` in the `PROPERTIES`
drawer.

If, for example, you specify `-l 2` instead of `-l 1` then the level-2 headings
will become blog posts.

In heading mode, you can use several options to select only certain headlines
which contain (or don't contain) specified tags.

### FAQ

#### What if I want to set HTTP/HTTPS proxy?

You can set the environment variable `HTTP_proxy` (and `HTTP_proxy_user` and
`HTTP_proxy_pass` additionally). See the <pm:SOAP::Lite> documentation for more
details, which uses <pm:LWP::UserAgent> underneath.

_
    args => {
        proxy => {
            schema => 'str*', # XXX url
            req => 1,
            description => <<'_',

Example: `https://YOURBLOGNAME.wordpress.com/xmlrpc.php`.

Note that `proxy` is the endpoint URL of your WordPress instance's XML-RPC
server, which can be hosted on `wordpress.com` or on other server, including
your own. It has nothing to do with HTTP/HTTPS proxy; the term "proxy" is used
by the <pm:XMLRPC::Lite> and <pm:SOAP::Lite> Perl libraries and `org2wp` simply
uses the same terminology.

_
            tags => ['credential'],
        },
        username => {
            schema => 'str*',
            req => 1,
            tags => ['credential'],
        },
        password => {
            schema => 'str*',
            req => 1,
            tags => ['credential'],
        },

        filename => {
            summary => 'Path to Org document to publish',
            schema => 'filename*',
            req => 1,
            pos => 0,
            cmdline_aliases => {f=>{}},
        },

        post_heading_level => {
            summary => 'Specify which heading level to be regarded as an individula blog post',
            schema => 'posint*',
            cmdline_aliases => {l=>{}},
            description => <<'_',

If specified, this will enable *heading mode* instead of the default *document
mode*. In the document mode, the whole Org document file is regarded as a single
blog post. In the *heading mode*, a heading of certain level will be regarded as
a single blog post.

_
            tags => ['category:heading-mode'],
        },
        include_heading_tags => {
            'x.name.is_plural' => 1,
            'x.name.singular' => 'include_heading_tag',
            summary => 'Only include heading that has all specified tag(s)',
            schema => ['array*', of=>'str*'],
            tags => ['category:heading-mode'],
        },
        exclude_heading_tags => {
            'x.name.is_plural' => 1,
            'x.name.singular' => 'exclude_heading_tag',
            summary => 'Exclude heading that has any of the specified tag(s)',
            schema => ['array*', of=>'str*'],
            tags => ['category:heading-mode'],
        },

        publish => {
            summary => 'Whether to publish post or make it a draft',
            schema => 'bool*',
            description => <<'_',

lib/App/org2wp.pm view on Meta::CPAN

                $file_content =~ s/^/#+POSTID: $new_post_id\n/;
            }
        }

        if (!$do_update_file) {
            log_info("Not updating %s because there are no changes", $filename);
        } else {
            log_trace("Updated file content: <<<%s>>>", $file_content);
            if ($dry_run) {
                log_info("[DRY-RUN] Writing %s", $filename);
            } else {
                log_info("Updating file %s ...", $filename);
                File::Slurper::write_text($filename, $file_content);
            }
        }
    } # L6_INSERT_POST_IDS

    [$dry_run ? 304:200, "OK"];
}

1;
# ABSTRACT: Publish Org document (or heading) to WordPress as blog post

__END__

=pod

=encoding UTF-8

=head1 NAME

App::org2wp - Publish Org document (or heading) to WordPress as blog post

=head1 VERSION

This document describes version 0.013 of App::org2wp (from Perl distribution App-org2wp), released on 2022-05-02.

=head1 FUNCTIONS


=head2 org2wp

Usage:

 org2wp(%args) -> [$status_code, $reason, $payload, \%result_meta]

Publish Org document (or heading) to WordPress as blog post.

This is originally a quick hack because I couldn't make
LL<https://github.com/punchagan/org2blog> on my Emacs installation to
work after some update. C<org2wp> uses the same format as C<org2blog>, but instead
of being an Emacs package, it is a CLI script written in Perl.

First, create C<~/org2wp.conf> containing the API credentials, e.g.:

 ; use INI (IOD) format for this file
 proxy=https://YOURBLOGNAME.wordpress.com/xmlrpc.php
 username=YOURUSERNAME
 password=YOURPASSWORD

Note that C<proxy> is the endpoint URL of your WordPress instance's XML-RPC
server, which can be hosted on C<wordpress.com> or on other server, including
your own. It has nothing to do with HTTP/HTTPS proxy; the term "proxy" is used
by the L<XMLRPC::Lite> and L<SOAP::Lite> Perl libraries and C<org2wp> simply
uses the same terminology.

You can also put multiple credentials in the configuration file using profile
sections, e.g.:

 ; use INI (IOD) format for this file
 [profile=blog1]
 proxy=https://YOURBLOG1NAME.wordpress.com/xmlrpc.php
 username=YOURUSERNAME
 password=YOURPASSWORD
 
 [profile=blog2]
 proxy=https://YOURBLOG2NAME.wordpress.com/xmlrpc.php
 username=YOURUSERNAME
 password=YOURPASSWORD

and specify which profile you want using command-line option e.g.
C<--config-profile blog1>.

=head3 Document mode

You can use the whole Org document file as a blog post (document mode) or a
single heading as a blog post (heading mode). The default is document mode. To
create a blog post, write your Org document (e.g. in C<post1.org>) using this
format:

 #+TITLE: Blog post title
 #+CATEGORY: cat1, cat2
 #+TAGS: tag1,tag2,tag3
 
 Text of your post ...
 ...

then:

 % org2wp post1.org

this will create a draft post. To publish directly:

 % org2wp --publish post1.org

Note that this will also modify your Org file and insert this setting line at
the top:

 #+POSTID: 1234
 #+POSTTIME: [2020-09-16 Wed 11:51]

where 1234 is the post ID retrieved from the server when creating the post, and
post time will be set to the current local time.

After the post is created, you can update using the same command:

 % org2wp post1.org

You can use C<--publish> to publish the post, or C<--no-publish> to revert it to
draft.

lib/App/org2wp.pm view on Meta::CPAN


In heading mode, you can use several options to select only certain headlines
which contain (or don't contain) specified tags.

=head3 FAQ

=head4 What if I want to set HTTP/HTTPS proxy?

You can set the environment variable C<HTTP_proxy> (and C<HTTP_proxy_user> and
C<HTTP_proxy_pass> additionally). See the L<SOAP::Lite> documentation for more
details, which uses L<LWP::UserAgent> underneath.

This function is not exported.

This function supports dry-run operation.


Arguments ('*' denotes required arguments):

=over 4

=item * B<comment_status> => I<str> (default: "closed")

Whether to allow comments (open) or not (closed).

=item * B<exclude_heading_tags> => I<array[str]>

Exclude heading that has any of the specified tag(s).

=item * B<extra_attrs> => I<hash>

Set extra post attributes, e.g. ping_status, post_format, etc.

=item * B<filename>* => I<filename>

Path to Org document to publish.

=item * B<include_heading_tags> => I<array[str]>

Only include heading that has all specified tag(s).

=item * B<password>* => I<str>

=item * B<post_heading_level> => I<posint>

Specify which heading level to be regarded as an individula blog post.

If specified, this will enable I<heading mode> instead of the default I<document
mode>. In the document mode, the whole Org document file is regarded as a single
blog post. In the I<heading mode>, a heading of certain level will be regarded as
a single blog post.

=item * B<post_password> => I<str>

Set password for posts.

=item * B<proxy>* => I<str>

Example: CL<https://YOURBLOGNAME.wordpress.com/xmlrpc.php>.

Note that C<proxy> is the endpoint URL of your WordPress instance's XML-RPC
server, which can be hosted on C<wordpress.com> or on other server, including
your own. It has nothing to do with HTTP/HTTPS proxy; the term "proxy" is used
by the L<XMLRPC::Lite> and L<SOAP::Lite> Perl libraries and C<org2wp> simply
uses the same terminology.

=item * B<publish> => I<bool>

Whether to publish post or make it a draft.

Equivalent to C<--extra-attr post_status=published>, while C<--no-publish> is
equivalent to C<--extra-attr post_status=draft>.

=item * B<schedule> => I<date>

Schedule post to be published sometime in the future.

Equivalent to C<--publish --extra-attr post_date=DATE>. Note that WordPress
accepts date in the C<YYYYMMDD"T"HH:MM:SS> format, but you specify this option in
regular ISO8601 format. Also note that time is in your chosen local timezone
setting.

=item * B<username>* => I<str>


=back

Special arguments:

=over 4

=item * B<-dry_run> => I<bool>

Pass -dry_run=E<gt>1 to enable simulation mode.

=back

Returns an enveloped result (an array).

First element ($status_code) is an integer containing HTTP-like status code
(200 means OK, 4xx caller error, 5xx function error). Second element
($reason) is a string containing error message, or something like "OK" if status is
200. Third element ($payload) is the actual result, but usually not present when enveloped result is an error response ($status_code is not 2xx). Fourth
element (%result_meta) is called result metadata and is optional, a hash
that contains extra information, much like how HTTP response headers provide additional metadata.

Return value:  (any)

=head1 HOMEPAGE

Please visit the project's homepage at L<https://metacpan.org/release/App-org2wp>.

=head1 SOURCE

Source repository is at L<https://github.com/perlancar/perl-App-org2wp>.

=head1 AUTHOR

perlancar <perlancar@cpan.org>

=head1 CONTRIBUTING

( run in 3.248 seconds using v1.01-cache-2.11-cpan-63c85eba8c4 )