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.

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.

If home directory is not specific, exception occur.

If home directory already exists, exception occur.

If creating directory fail, exception occur.

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

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

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};
  $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>
  $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>

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}