NAME

Giblog::API - Giblog API

DESCRIPTION

Giblog::API defines sevral methods to manipulate HTML contents.

METHODS

new

  my $api = Giblog::API->new(%params);

Create Giblog::API object.

Parameters:

giblog

Set Giblog object.

By giblog method, you can access this parameter.
```
  my $giblog = $api->giblog;
```

giblog

  my $giblog = $api->giblog;

Get Giblog object.

config

  my $config = $api->config;

Get Giblog config. This is hash reference.

Config is loaded by read_config method.

If config is not loaded, this method return undef.

get_vars

  my $vars = $api->get_vars;

Get a Giblog variables that are defined in giblog.conf. This is hash reference.

  # giblog.conf
  use strict;
  use warnings;
  use utf8;

  {
    site_title => 'mysite・',
    site_url => 'http://somesite.example',
    # Variables
    vars => {
      '$giblog_test_variable' => 'Giblog Test Variable',
    },
  }

Before using this method, read_config method must be called.

If config is not loaded, this method return undef.

If vars option is not defined, this method return undef.

Examples:

  # Get a Giblog variable
  my $vars = $api->get_vars;
  my $giblog_test_variable = $vars->{'$giblog_test_variable'};

home_dir

  my $home_dir = $api->home_dir;

Get home directory.

read_config

  my $config = $api->read_config;

Parse "giblog.conf" in home directory and return hash reference.

"giblog.conf" must end with correct hash reference. Otherwise exception occur.

  # giblog.conf
  {
    site_title => 'mysite',
    site_url => 'http://somesite.example',
  }

After calling "read_config", You can also get config by config method.

clear_config

  $api->clear_config;

Clear config. Set undef to config.

create_dir

  $api->create_dir($dir);

Create directory.

If Creating directory fail, exception occur.

create_file

  $api->create_file($file);

Create file.

If Creating file fail, exception occur.

write_to_file

  $api->write_to_file($file, $content);

Write content to file. Content is encoded to UTF-8.

If file is not exists, file is created automatically.

If Creating file fail, exception occur.

slurp_file

  my $content = $api->slurp_file($file);

Get file content. Content is decoded from UTF-8.

If file is not exists, exception occur.

rel_file

  my $file = $api->rel_file('foo/bar');

Get combined path of home directory and specific relative path.

If home directory is not set, return specific path.

create_website_from_proto

  $api->create_website_from_proto($home_dir, $module_name);

Create website home directory and copy files from prototype directory.

Prototype directory is automatically detected from module name.

If module name is "Giblog::Command::new_foo" and the loading path is "lib/Giblog/Command/new_foo.pm", path of prototype directory is "lib/Giblog/Command/new_foo/proto".

  lib/Giblog/Command/new_foo.pm
                    /new_foo/proto

Module must be loaded before calling "create_website_from_proto". otherwise exception occur.

The web site directry is initialized by git and public direcotry is also initialized by git.

  git init foo
  git init foo/public

If home directory is not specific, a exception occurs.

If home directory already exists, a exception occurs.

If creating directory fail, a exception occurs.

If proto directory corresponding to module name is not specific, a exception occurs.

If proto direcotry corresponding to module name is not found, a exception occurs.

If git command is not found, a exception occurs.

copy_static_files_to_public

  $api->copy_static_files_to_public;

Copy static files in "templates/static" directory to "public" directory.

get_templates_files

  my $files = $api->get_templates_files;

Get file names in "templates" directory in home directory.

Files in "templates/common" directory and "templates/static" directory and hidden files(which start with ".") is not contained.

Got file name is relative name from "templates" directory.

For example,

  index.html
  blog/20190312121345.html
  blog/20190314452341.html

get_content

  $api->get_content($data);

Get content from relative file name from "templates" directory. Content is decoded from UTF-8.

INPUT:

  $data->{file}

OUTPUT:

  $data->{content}

Example:

  # Get content from templates/index.html
  $data->{file} = 'index.html';
  $api->get_content($data);
  my $content = $data->{content};

parse_giblog_syntax

  $api->parse_giblog_syntax($data);

Parse input text as "Giblog syntax", and return output.

INPUT:

  $data->{content}

OUTPUT:

  $data->{content}

Example:

  # Parse input as giblog syntax
  $data->{content} = <<'EOS';
  Hello World!

  <b>Hi, Yuki</b>

  <div>
    OK
  </div>

  <pre>
  my $foo = 1 > 3 && 2 < 5;
  </pre>
  EOS
  
  $api->parse_giblog_syntax($data);
  my $content = $data->{content};

Giblog syntax

Giblog syntax is simple syntax to write content easily.

1. Add p tag automatically

Add p tag to inline element starting from the beginning of line.

  # Input
  Hello World!
  
  <b>Hi, Yuki</b>
  
  <div>
    OK
  </div>
  
  # Output
  <p>
    Hello World!
  </p>
  <p>
    <b>Hi, Yuki</b>
  </p>
  <div>
    OK
  </div>

Empty line is deleted.

2. Escape >, <, & in pre tag

If pre tag starts at the beginning of the line and its end tag starts at the beginning of the line, execute HTML escapes ">" and "<" between them.

  # Input
  <pre>
  my $foo = 1 > 3 && 2 < 5;
  </pre>

  # Output
  <pre>
  my $foo = 1 &gt; 3 &amp;&amp; 2 &lt; 5;
  </pre>

parse_title

  $api->parse_title($data);

Get title from text of tag which class name is "title".

If parser can't get title, title become undef.

INPUT:

  $data->{content}

OUTPUT:

  $data->{title}

Example:

  # Get title
  $data->{content} = <<'EOS';
  <div class="title">Perl Tutorial</div>
  EOS
  $api->parse_title($data);
  my $title = $data->{title};

parse_title_from_first_h_tag

  $api->parse_title_from_first_h_tag($data);

Get title from text of first h1, h2, h3, h4, h5, h6 tag.

If parser can't get title, title become undef.

INPUT:

  $data->{content}

OUTPUT:

  $data->{title}

Example:

  # Get title
  $data->{content} = <<'EOS';
  <h1>Perl Tutorial</h1>
  EOS
  $api->parse_title_from_first_h_tag($data);
  my $title = $data->{title};

add_page_link

  $api->add_page_link($data);
  $api->add_page_link($data, $opt);

Add page link to text of tag which class name is "title".

If parser can't get title, content is not changed.

INPUT:

  $data->{file}
  $data->{content}

OUTPUT:

  $data->{content}

"file" is relative path from "templates" directory.

If added link is the path which combine "/" and value of "file".

if $opt->{root} is specifed and this match $data->{file}, added link is "/".

Example:

  # Add page link
  $data->{file} = 'blog/20181012123456.html';
  $data->{content} = <<'EOS';
  <div class="title">Perl Tutorial</div>
  EOS
  $api->add_page_link($data);
  my $content = $data->{content};

Content is changed to

  <div class="title"><a href="/blog/20181012123456.html">Perl Tutorial</a></div>

Example: root page

  # Add page link
  $data->{file} = 'index.html';
  $data->{content} = <<'EOS';
  <div class="title">Perl Tutorial</div>
  EOS
  $api->add_page_link($data);
  my $content = $data->{content};

Content is changed to

  <div class="title"><a href="/">Perl Tutorial</a></div>

add_page_link_to_first_h_tag

  $api->add_page_link_to_first_h_tag($data);
  $api->add_page_link_to_first_h_tag($data, $opt);

Add page link to text of first h1, h2, h3, h4, h5, h6 tag.

If parser can't get title, content is not changed.

INPUT:

  $data->{file}
  $data->{content}

OUTPUT:

  $data->{content}

"file" is relative path from "templates" directory.

If added link is the path which combine "/" and value of "file".

if $opt->{root} is specifed and this match $data->{file}, added link is "/".

Example: entry page

  # Add page link
  $data->{file} = 'blog/20181012123456.html';
  $data->{content} = <<'EOS';
  <h1>Perl Tutorial</h1>
  EOS
  $api->add_page_link_to_first_h_tag($data);
  my $content = $data->{content};

Content is changed to

  <h1><a href="/blog/20181012123456.html">Perl Tutorial</a></h1>

Example: root

  # Add page link
  $data->{file} = 'index.html';
  $data->{content} = <<'EOS';
  <h1>Perl Tutorial</h1>
  EOS
  $api->add_page_link_to_first_h_tag($data);
  my $content = $data->{content};

Content is changed to

  <h1><a href="/">Perl Tutorial</a></h1>

add_content_after_first_p_tag

  $api->add_content_after_first_p_tag($data, $opt);

Add contents after the first p tag.

INPUT:

  $data->{content}
  $opt->{content}

OUTPUT:

  $data->{content}

$data->{content} is the current content. $opt->{content} is the added content.

Example:

  # Add contents after the first p tag.
  $data->{content} = <<'EOS';
  <h2>Perl Tutorial</h2>
  <p>
    Foo
  </p>
  <p>
    Bar
  </p>
  EOS
  $api->add_content_after_first_p_tag($data, {content => "<div>Added Contents</div>");
  my $content = $data->{content};

Content is changed to

  <h2>Perl Tutorial</h2>
  <p>
    Foo
  </p>
  <div>Added Contents</div>
  <p>
    Bar
  </p>

add_content_after_first_h_tag

  $api->add_content_after_first_h_tag($data, $opt);

Add contents after the first h1, h2, h3, h4, h5, h6 tag.

INPUT:

  $data->{content}
  $opt->{content}

OUTPUT:

  $data->{content}

$data->{content} is the current content. $opt->{content} is the added content.

Example:

  # Add contents after the first p tag.
  $data->{content} = <<'EOS';
  <h2>Perl Tutorial</h2>
  <h3>Perl Tutorial</h3>
  EOS
  $api->add_content_after_first_h_tag($data, {content => "<div>Added Contents</div>");
  my $content = $data->{content};

Content is changed to

  <h2>Perl Tutorial</h2>
  <div>Added Contents</div>
  <h3>Perl Tutorial</h3>

replace_vars

  $api->replace_vars($data);

Replace a Giblog variables in the content with the values of vars options that are defined in giblog.conf.

  # giblog.conf
  use strict;
  use warnings;
  use utf8;

  {
    site_title => 'mysite・',
    site_url => 'http://somesite.example',
    # Variables
    vars => {
      '$giblog_test_variable' => 'Giblog Test Variable',
    },
  }

INPUT:

  $data->{content}

OUTPUT:

  $data->{content}

$data->{content} is the current content.

Example:

  # Replace a Giblog variables
  $data->{content} = <<'EOS';
  <p><%= $giblog_test_variable %></p>
  <p><%= $giblog_test_variable %></p>
  EOS
  $api->replace_vars($data);
  my $content = $data->{content};

Content is changed to

  <p>Giblog Test Variable</p>
  <p>Giblog Test Variable</p>

parse_description

  $api->parse_description($data);

Get description from text of tag which class name is "description".

Both of left spaces and right spaces are removed. This is Unicode space.

If parser can't get description, description become undef.

INPUT:

  $data->{content}

OUTPUT:

  $data->{description}

Example:

  # Get description
  $data->{content} = <<'EOS';
  <div class="description">
    Perl Tutorial is site for beginners of Perl 
  </div>
  EOS
  $api->parse_description($data);
  my $description = $data->{description};

Output description is "Perl Tutorial is site for beginners of Perl".

parse_description_from_first_p_tag

  $api->parse_description_from_first_p_tag($data);

Get description from text of first p tag.

HTML tag is removed.

Both of left spaces and right spaces is removed. This is Unicode space.

If parser can't get description, description become undef.

INPUT:

  $data->{content}

OUTPUT:

  $data->{description}

Example:

  # Get description
  $data->{content} = <<'EOS';
  <p>
    Perl Tutorial is site for beginners of Perl 
  </p>
  <p>
    Foo, Bar
  </p>
  EOS
  $api->parse_description_from_first_p_tag($data);
  my $description = $data->{description};

Output description is "Perl Tutorial is site for beginners of Perl".

parse_keywords

  $api->parse_keywords($data);

Get keywords from text of tag which class name is "keywords".

If parser can't get keywords, keywords become undef.

INPUT:

  $data->{content}

OUTPUT:

  $data->{keywords}

Example:

  # Get keywords
  $data->{content} = <<'EOS';
  <div class="keywords">Perl,Tutorial</div>
  EOS
  $api->parse_keywords($data);
  my $keywords = $data->{keywords};

parse_first_img_src

  $api->parse_first_img_src($data);

Get image src from src attribute of first img tag.

If parser can't get image src, image src become undef.

INPUT:

  $data->{content}

OUTPUT:

  $data->{img_src}

Example:

  # Get first_img_src
  $data->{content} = <<'EOS';
<img class="ppp" src="/path">
  EOS
  $api->parse_first_img_src($data);
  my $img_src = $data->{img_src};

Output img_src is "/path".

read_common_templates

  $api->read_common_templates($data);

Read common templates in "templates/common" directory.

The follwoing templates is loaded. Content is decoded from UTF-8.

"meta.html", "header.html", "footer.html", "side.html", "top.html", "bottom.html"

OUTPUT:

  $data->{meta}
  $data->{header}
  $data->{footer}
  $data->{side}
  $data->{top}
  $data->{bottom}

add_meta_title

Add title tag to meta section.

INPUT:

  $data->{title}
  $data->{meta}

OUTPUT:

  $data->{meta}

If value of "meta" is "foo" and "title" is "Perl Tutorial", output value of "meta" become "foo\n<title>Perl Tutorial</title>"

add_meta_description

Add meta description tag to meta section.

INPUT:

  $data->{description}
  $data->{meta}

OUTPUT:

  $data->{meta}

If value of "meta" is "foo" and "description" is "Perl is good", output value of "meta" become "foo\n<meta name="description" content="Perl is good">"

build_entry

Build entry HTML by "content" and "top", "bottom".

INPUT:

  $data->{content}
  $data->{top}
  $data->{bottom}

OUTPUT:

  $data->{content}

Output is the following HTML.

  <div class="entry">
    <div class="top">
      $data->{top}
    </div>
    <div class="middle">
      $data->{content}
    </div>
    <div class="bottom">
      $data->{bottom}
    </div>
  </div>

build_html

Build whole HTML by "content" and "header", "bottom", "side", "footer".

INPUT:

  $data->{content}
  $data->{header}
  $data->{bottom}
  $data->{side}
  $data->{footer}

OUTPUT:

  $data->{content}

Output is the following HTML.

  <!DOCTYPE html>
  <html>
    <head>
      $data->{meta}
    </head>
    <body>
      <div class="container">
        <div class="header">
          $data->{header}
        </div>
        <div class="main">
          <div class="content">
            $data->{content}
          </div>
          <div class="side">
            $data->{side}
          </div>
        </div>
        <div class="footer">
          $data->{footer}
        </div>
      </div>
    </body>
  </html>

write_to_public_file

Write content to file in "public" directory. Content is encoded to UTF-8.

If value of "file" is "index.html", write path become "public/index.html"

INPUT:

  $data->{content}
  $data->{file}

If the original content of the file is same as the new content of the file is same, this method don't write to public file. This means file time stamp is not be updated.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 945:: Non-ASCII character seen before =encoding in ''mysite・','. Assuming UTF-8

To install Giblog, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Giblog

CPAN shell

perl -MCPAN -e shell
install Giblog

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

DESCRIPTION

METHODS

new

giblog

config

get_vars

home_dir

read_config

clear_config

create_dir

create_file

write_to_file

slurp_file

rel_file

create_website_from_proto

copy_static_files_to_public

get_templates_files

get_content

parse_giblog_syntax

parse_title

parse_title_from_first_h_tag

add_page_link

add_page_link_to_first_h_tag

add_content_after_first_p_tag

add_content_after_first_h_tag

replace_vars

parse_description

parse_description_from_first_p_tag

parse_keywords

parse_first_img_src

read_common_templates

add_meta_title

add_meta_description

build_entry

build_html

write_to_public_file

Module Install Instructions