view release on metacpan or  search on metacpan

script/list-org-headlines  view on Meta::CPAN

 # instead of only listing its title, list details about each headline
 $ list-org-headlines --detail FILES ...

 # list all todo items in all Org files
 $ list-org-headlines --todo FILES ...

 # list headlines that are not todo items in all Org files
 $ list-org-headlines --notodo FILES ...

 # list up to level 2 only
 $ list-org-headlines --tolevel 2 FILES ...

 # list *only* level 3
 $ list-org-headlines --from-level 3 --to-level 3 FILES ...

=head1 DESCRIPTION

This is a simple application to list headlines in Org files, first created as a
demo for L<Org::Parser>.

=head1 OPTIONS

C<*> marks required options.

=head2 Main options

=over

=item B<--file>=I<s@>*

(No description)


Can also be specified as the 1st command-line argument and onwards.

Can be specified multiple times.

=item B<--files-json>=I<s>

See C<--file>.

Can also be specified as the 1st command-line argument and onwards.

=item B<--time-zone>=I<s>

Will be passed to parser's options.

If not set, TZ environment variable will be picked as default.


=item B<--today-json>=I<s>

Assume today's date (JSON-encoded).

See C<--today>.

=item B<--today>=I<s>

Assume today's date.

You can provide Unix timestamp or DateTime object. If you provide a DateTime
object, remember to set the correct time zone.


=back

=head2 Configuration options

=over

=item B<--config-path>=I<s>, B<-c>

Set path to configuration file.

Can actually be specified multiple times to instruct application to read from
multiple configuration files (and merge them).


=item B<--config-profile>=I<s>, B<-P>

Set configuration profile to use.

A single configuration file can contain profiles, i.e. alternative sets of
values that can be selected. For example:

 [profile=dev]
 username=foo
 pass=beaver
 
 [profile=production]
 username=bar
 pass=honey

When you specify C<--config-profile=dev>, C<username> will be set to C<foo> and
C<password> to C<beaver>. When you specify C<--config-profile=production>,
C<username> will be set to C<bar> and C<password> to C<honey>.


=item B<--no-config>, B<-C>

Do not use any configuration file.

If you specify C<--no-config>, the application will not read any configuration
file.


=back

=head2 Environment options

=over

=item B<--no-env>

Do not read environment for default options.

If you specify C<--no-env>, the application wil not read any environment
variable.


=back

script/list-org-headlines  view on Meta::CPAN

=item B<--has-tags-json>=I<s>

Only show headlines that have the specified tags (JSON-encoded).

See C<--has-tag>.

=item B<--help>, B<-h>, B<-?>

Display help message and exit.

=item B<--lacks-tag>=I<s@>

Only show headlines that don't have the specified tags.

Can be specified multiple times.

=item B<--lacks-tags-json>=I<s>

Only show headlines that don't have the specified tags (JSON-encoded).

See C<--lacks-tag>.

=item B<--maximum-priority>=I<s>

Only show todo items that have at most this priority.

Note that the default priority list is [A, B, C] (A being the highest) and it
can be customized using the C<#+PRIORITIES> setting.


=item B<--minimum-priority>=I<s>

Only show todo items that have at least this priority.

Note that the default priority list is [A, B, C] (A being the highest) and it
can be customized using the C<#+PRIORITIES> setting.


=item B<--priority>=I<s>

Only show todo items that have this priority.

=item B<--sort-json>=I<s>

Specify sorting (JSON-encoded).

See C<--sort>.

=item B<--sort>=I<s>

Specify sorting.

Default value:

 "due_date"

If string, must be one of 'due_date', '-due_date' (descending).

If code, sorting code will get [REC, DUE_DATE, HL] as the items to compare,
where REC is the final record that will be returned as final result (can be a
string or a hash, if 'detail' is enabled), DUE_DATE is the DateTime object (if
any), and HL is the Org::Headline object.


=item B<--state>=I<s>

Only show todo items that have this state.

=item B<--to-level>=I<s>

Only show headlines having this level as the maximum.

=item B<--todo>

Only show headlines that are todos.

=item B<--version>, B<-v>

Display program's version and exit.

=item B<--with-unknown-priority>

Also show items with no/unknown priority.

Relevant only when used with C<minimum_priority> and/or C<maximum_priority>.

If this option is turned on, todo items that does not have any priority or have
unknown priorities will I<still> be included. Otherwise they will not be
included.


=back

=head1 COMPLETION

This script has shell tab completion capability with support for several
shells.

=head2 bash

To activate bash completion for this script, put:

 complete -C list-org-headlines list-org-headlines

in your bash startup (e.g. F<~/.bashrc>). Your next shell session will then
recognize tab completion for the command. Or, you can also directly execute the
line above in your shell to activate immediately.

It is recommended, however, that you install modules using L<cpanm-shcompgen>
which can activate shell completion for scripts immediately.

=head2 tcsh

To activate tcsh completion for this script, put:

 complete list-org-headlines 'p/*/`list-org-headlines`/'

in your tcsh startup (e.g. F<~/.tcshrc>). Your next shell session will then
recognize tab completion for the command. Or, you can also directly execute the
line above in your shell to activate immediately.