postwave 0.0.2 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9ded40bea3eeb7f6f76e5de2f3df929f4ced4d3e8045af330747b5390b06e70
-  data.tar.gz: cc9f0bbe6554d86b510972d59eb979dd41911ad9b081a0a44c04ef974005ee38
+  metadata.gz: ee98e42b5e3436991cfb73764252e21db5ed18c9bfd2760045ee268250d1c79a
+  data.tar.gz: 63e682e894bb2838ee0a46393b75b600ad83197a1fc4b9735b2a7e77897dafe8
 SHA512:
-  metadata.gz: 1550146a4c3967f077312340d58e3b61691a0022e38c5bc225bae21da657be95b3340ac3a5ef04866f8d5a6861b996ec8161f0ecb57c6309a13d97c3e445d435
-  data.tar.gz: aaec0f9aa5ad0ae598e204e777cfb80eb0087ca59717d6a60a40d7e615407545a4a4d1d1d5190706889ecedfa34c427c00367801c1996a89e5a400330991330e
+  metadata.gz: 7df94a047a4875a2f317ed26f0c30bec4f1a6178967ab721280cb5c40fdb41e35f790537ccbf40a151c9fcddf61862adad0c058ffc04f5dab944ccec48b58652
+  data.tar.gz: 182ae4013b7064810db4f5358d5202100ef8ce3563c79edcfc0af121f4f95f622f9641f5b9b53563916deb8c385123697b1443260ef1377b0a66d695792cc1be

data/Gemfile

@@ -1,4 +1,4 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in trackstar.gemspec
+# Specify your gem's dependencies in postwave.gemspec
 gemspec

data/Gemfile.lock

@@ -0,0 +1,22 @@
+PATH
+  remote: .
+  specs:
+    postwave (0.0.2)
+      redcarpet (~> 3.6)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    rake (12.3.3)
+    redcarpet (3.6.0)
+
+PLATFORMS
+  arm64-darwin-21
+
+DEPENDENCIES
+  bundler
+  postwave!
+  rake (~> 12.3)
+
+BUNDLED WITH
+   2.2.31

data/README.md

@@ -1,21 +1,23 @@
 # Postwave 🌊
 
+[![Gem Version](https://badge.fury.io/rb/postwave.svg)](https://badge.fury.io/rb/postwave)
+
 Write your posts statically. Interact with them dynamically.
 
 ## What is Postwave?
 
 Postwave is an opinionated flat-file based based blog engine.
 
-It lets you write posts in Markdown and then display them on a dynamic site using a client library.
-
-## Getting Started
+It lets you write posts in Markdown and then display them on a dynamic site using the client functionality.
 
-### Installation
+## Installation
 
 ```
 gem install postwave
 ```
 
+## Authoring Posts
+
 ### Setup
 
 ```
@@ -51,11 +53,11 @@ postwave.yaml
 > postwave post
 ```
 
-This will generate at new Markdown file in the `_posts/` directory. The filename will be the current timestamp. This will eventually be overwritten by the `build` command, so don't worry too much about it. The file will have a general structure like this:
+This will generate at new Markdown file in the `_posts/` directory. The title is set to a random string of characters.  The filename will be the current timestamp.  This will eventually be overwritten by the `build` command, so don't worry too much about it. The file will have a general structure like this:
 
 ```
 ---
-title:
+title: FNJEXWZP
 date: 2022-01-01
 tags:
 ---
@@ -82,15 +84,112 @@ draft: true
 ```
 
 This will "build" the blog. This involves:
-- regenerating the `index.csv` file
+- regenerating the `/meta/index.csv` file
 - generating slugs for each posts based on the post title and ensuring that there are no duplicate slugs
 - changing the post file names to match `yyyy-dd-mm-slug.md`
-- updating the `summary.yaml`
+- updating the `/meta/summary.yaml`
 - creating and updating tag files (which will be `/tags/[tag-name].yaml` files for each tag)
+- updating the `/meta/rss` file to create a feed for your posts
+
+## Displaying Posts
+
+You can now use Postwave's build in client to display this posts in your project.
+
+### Include the Client In Your Project
+
+```ruby
+require 'postwave/client'
+```
+
+### Create a Postwave Client
+```ruby
+postwave_client = Postwave::Client.new("path/to/config/postwave.yaml")
+```
+
+If you'd like to preload all the posts:
+```ruby
+postwave_client = Postwave::Client.new("path/to/config/postwave.yaml", preload: true)
+```
+
+### Get a Single Post
+
+Pass in the stub (the filename without '.md') for the post.
+```ruby
+post = postwave_client.post("my-great-post")
+
+# <Postwave::Post title="My Great Post", date=<Time ...>, tags=["tag1"], body="bla bla bla..">
+
+puts post.title
+# "My Great Post"
+puts post.body
+# "bla bla bla..."
+puts post.body_html # uses Redcarpt to convert body Markdown to HTML
+# "<p>bla bla bla...</p>"
+```
+
+### Get a Collection of Posts
+
+This will give you a list of posts for displaying on a page.
+
+You can also filter by tags and specify offsets and limits (useful for pagination).
+
+```ruby
+posts = postwave_client.posts
+
+# [<Postwave::Post ...>, <Postwave::Post ...>, ...]
+
+tagged_posts = postwave_client.posts(tag: "lizards")
 
-## Available Client Libraries
+page2_posts = postwave_client.posts(offset: 10, limit: 10)
+```
+Posts will be in reverse chronological order.
+
+### Get an Index of Posts
+
+This will give you a quick list of post summaries containing the title, date, and stub, useful for building an archive page or quick index of posts.
+
+You can also specify offsets and limits (useful for pagination).
+```ruby
+index = postwave_client(index)
+
+# [<Postwave::PostStub title="My Great Post", date=<Time ...>, stub="my-great-post">, <Postwave::PostStub ...>, ...]
+
+puts index.first.stub
+# my-great-post
+
+page2_index = postwave_client.index(offset: 10, limit: 10)
+```
+Index will be in reverse chronological order.
+
+### Get Tags Used In the Blog
+
+```ruby
+tags = postwave_client.tags
+
+# ["tag1", "tag2", "another-tag"]
+```
 
-- [Ruby](https://github.com/dorkrawk/postwave-ruby-client)
+### Get Details For A Tag
+
+```ruby
+tag = postwave_clinet.tag("tag1")
+
+# <Postwave::Tag tile="tag1", count=1, post_slugs=["my-great-post"]>
+```
+
+### Get Text For An RSS Feed
+
+```ruby
+rss = postwave_client.rss
+
+# "<?xml version="1.0" encoding="utf-8"?>..."
+```
+
+## Run Tests
+
+```
+rake test
+```
 
 ## What is Postwave Not?
 

data/lib/postwave/blog_utilities.rb

@@ -8,41 +8,41 @@ module Postwave
     META_DIR = "meta"
     TAGS_DIR = "tags"
 
-    def is_set_up?
-      missing_paths = find_missing_paths
+    def is_set_up?(blog_root = Dir.pwd)
+      missing_paths = find_missing_paths(blog_root)
       missing_paths.empty?
     end
 
-    def file_paths
+    def file_paths(blog_root = Dir.pwd)
       [
-        File.join(Dir.pwd, CONFIG_FILE_NAME),
-        File.join(Dir.pwd, POSTS_DIR, META_DIR, INDEX_FILE_NAME),
-        File.join(Dir.pwd, POSTS_DIR, META_DIR, SUMMARY_FILE_NAME),
+        File.join(blog_root, CONFIG_FILE_NAME),
+        File.join(blog_root, POSTS_DIR, META_DIR, INDEX_FILE_NAME),
+        File.join(blog_root, POSTS_DIR, META_DIR, SUMMARY_FILE_NAME),
       ]
     end
 
-    def directory_paths
+    def directory_paths(blog_root = Dir.pwd)
       [
-        File.join(Dir.pwd, POSTS_DIR),
-        File.join(Dir.pwd, POSTS_DIR, META_DIR),
-        File.join(Dir.pwd, POSTS_DIR, META_DIR, TAGS_DIR),
+        File.join(blog_root, POSTS_DIR),
+        File.join(blog_root, POSTS_DIR, META_DIR),
+        File.join(blog_root, POSTS_DIR, META_DIR, TAGS_DIR),
       ]
     end
 
-    def find_missing_paths
-      paths_to_check = directory_paths + file_paths
+    def find_missing_paths(blog_root = Dir.pwd)
+      paths_to_check = directory_paths(blog_root) + file_paths(blog_root)
       missing_paths = []
       paths_to_check.each do |path|
-        missing_paths << path if !FileTest.exists?(path)
+        missing_paths << path if !FileTest.exist?(path)
       end
       missing_paths
     end
 
     def config_values
       @config_values ||= if yaml_load = YAML.load_file(File.join(Dir.pwd, CONFIG_FILE_NAME))
-          yaml_load.transform_keys(&:to_sym)
-        else
-          {}
+        yaml_load.transform_keys(&:to_sym)
+      else
+        {}
       end
     end
   end

data/lib/postwave/client.rb

@@ -0,0 +1,113 @@
+require_relative "post"
+require_relative "errors"
+require_relative "blog_utilities"
+
+require "csv"
+require "time"
+require "yaml"
+
+Postwave::PostStub = Struct.new(:date, :title, :slug)
+Postwave::Tag = Struct.new(:name, :count, :post_slugs)
+Postwave::Pagination = Struct.new(:current_page, :prev_page, :next_page, :total_pages)
+
+module Postwave
+  class Client
+    include BlogUtilities
+
+    def initialize(config_path, preload: false)
+      raise MissingConfigError unless is_valid_config?(config_path)
+      
+      @blog_root = File.dirname(config_path)
+      raise InvalidBlogError unless is_set_up?(@blog_root)
+
+      @all_posts = get_all_posts if preload
+    end
+
+    # returns: an array of PostStub Structs - [<struct PostStub date=Time, title="", stub="">]
+    def index(offset: 0, limit: nil)
+      working_index = @full_index || get_full_index
+      count = limit || working_index.size
+      working_index[offset, count]
+    end
+
+    # returns: a post - Postwave::Post
+    def post(slug)
+      post_file_path = Dir["#{File.join(@blog_root, POSTS_DIR)}/*#{slug}.md"].first
+      
+      raise PostNotFoundError unless post_file_path && File.exist?(post_file_path)
+
+      Postwave::Post.new_from_file_path(post_file_path)
+    end
+
+    # returns: an array of posts - [Postwave::Post]
+    def posts(offset: 0, limit: nil, tag: nil)
+      posts = @all_posts || get_all_posts
+      posts = posts.select { |post| post.tags.include?(tag) } if tag
+      count = limit || posts.size
+      posts[offset, count]
+    end
+
+    # returns: an array of tags - [String]
+    def tags
+      summary = @blog_summary || get_summary
+      summary[:tags]
+    end
+
+    # returns: a Tag Struct - <Tag tag: "", count: Integer, post_slugs: ["post-slug",..]
+    def tag(tag)
+      tag_file_path = File.join(@blog_root, POSTS_DIR, META_DIR, TAGS_DIR, "#{tag}.yaml")
+      raise TagNotFoundError unless File.exist?(tag_file_path)
+
+      tag_info = YAML.load_file(tag_file_path)
+
+      Postwave::Tag.new(tag, tag_info[:count], tag_info[:post_slugs])
+    end
+
+    # returns: a string of the xml representing an RSS feed of posts - String
+    def rss
+      rss_file_path = File.join(@blog_root, POSTS_DIR, META_DIR, RSS_FILE_NAME)
+      rss = File.open(rss_file_path)
+      rss.read
+    end
+
+    # reuturns: a Pagination Struct - <struct Pagination current_page=3, prev_page=2, next_page=4, total_pages=20>
+    def pagination(current_page: 1, per_page: 10)
+      summary = @blog_summary || get_summary
+      total_pages = (summary[:post_count].to_f / per_page).ceil
+      in_bound_current = current_page.clamp(1, total_pages)
+      prev_page = in_bound_current > 1 ? in_bound_current - 1 : nil
+      next_page = in_bound_current < total_pages ? in_bound_current + 1 : nil
+      Postwave::Pagination.new(in_bound_current, prev_page, next_page, total_pages)
+    end
+
+    private
+
+    def is_valid_config?(config_path)
+      File.exist?(config_path)
+    end
+
+    def get_all_posts
+      posts = []
+      Dir.glob(File.join(@blog_root, POSTS_DIR, "*.md")) do |post_file_path|
+        posts << Postwave::Post.new_from_file_path(post_file_path)
+      end
+      posts.reject! { |p| p.draft if p.respond_to? :draft }
+      posts.sort_by { |p| p.date }.reverse
+    end
+
+    def get_full_index
+      full_index = []
+      index_contents = CSV.read(File.join(@blog_root, POSTS_DIR, META_DIR, INDEX_FILE_NAME))
+      index_contents.shift # skip header                 
+      index_contents.each do |post|
+      full_index << Postwave::PostStub.new(Time.parse(post[1]), post[2], post[0])
+      end
+      full_index
+    end
+
+    def get_summary
+      summary_file_path = File.join(@blog_root, POSTS_DIR, META_DIR, SUMMARY_FILE_NAME)
+      YAML.load_file(summary_file_path)
+    end
+  end
+end

data/lib/postwave/errors.rb

@@ -0,0 +1,16 @@
+module Postwave
+  class PostwaveError < StandardError
+  end
+
+  class MissingConfigError < PostwaveError
+  end
+
+  class InvalidBlogError < PostwaveError
+  end
+
+  class PostNotFoundError < PostwaveError
+  end
+
+  class TagNotFoundError < PostwaveError
+  end
+end

data/lib/postwave/post.rb

@@ -1,7 +1,8 @@
 require_relative "blog_utilities"
+require "redcarpet"
 
 module Postwave
-   class Post
+  class Post
     include BlogUtilities
 
     KNOWN_FIELDS = %w(title date tags title_slug body draft)
@@ -10,6 +11,8 @@ module Postwave
 
     attr_accessor :file_name
 
+    @@markdown = Redcarpet::Markdown.new(Redcarpet::Render::HTML, fenced_code_blocks: true)
+
     def self.new_from_file_path(path)
       metadata_delimter_count = 0
       body_buffer_count = 0
@@ -59,8 +62,8 @@ module Postwave
       @file_name = file_name
 
       field_content.each do |field, value|
-        instance_variable_set("@#{field}", value)
-        self.class.send(:attr_accessor, field)
+        instance_variable_set("@#{field}", value) unless self.instance_variables.include?("@#{field}".to_sym)
+        self.class.send(:attr_reader, field) unless self.public_methods.include?(field.to_sym)
       end
     end
 
@@ -76,6 +79,10 @@ module Postwave
       @slug = new_slug
     end
 
+    def body_html
+      @@markdown.render(@body)
+    end
+
     def generated_file_name
       # YYYY-MM-DD-slug-from-title.md
       "#{@date.to_s[..9]}-#{slug}.md"

data/lib/postwave/rss_helper.rb

@@ -1,35 +1,36 @@
 require_relative "blog_utilities"
-require "rss"
+require "erb"
+require 'redcarpet'
 
 module Postwave
   module RssHelper
     include BlogUtilities
 
+    FeedPost = Struct.new(:title, :link, :body, :date, :tags)
+
     def build_rss(posts)
       File.open(File.join(Dir.pwd, POSTS_DIR, META_DIR, RSS_FILE_NAME), "w") do |rss|
-        rss << rss_content(posts)
+        rss << feed_content(posts)
       end
     end
     
-    def rss_content(posts)
-      RSS::Maker.make("2.0") do |maker|
-        maker.channel.title = config_values[:name]
-        maker.channel.description = config_values[:description]
-        maker.channel.link = config_values[:url]
-        maker.channel.generator = "Postwave"
-        maker.channel.updated = Time.now.to_s
-
-        posts.each do |post|
-          link = "#{config_values[:url]}/#{config_values[:posts_path]}/#{post.slug}"
+    def feed_content(posts)
+      link = config_values[:url]
+      updated = Time.now.iso8601.to_s
+      title = config_values[:name]
+      description = config_values[:description]
 
-          maker.items.new_item do |item|
-            item.title = post.title
-            item.link = link
-            item.description = post.body
-            item.pubDate = post.date
-          end
-        end
+      markdown = Redcarpet::Markdown.new(Redcarpet::Render::HTML, fenced_code_blocks: true)
+      feed_posts = posts.map do |post|
+        post_link = "#{config_values[:url]}/#{config_values[:posts_path]}/#{post.slug}"
+        html_body = CGI.unescapeHTML(markdown.render(post.body))
+        FeedPost.new(post.title, post_link, html_body, post.date.iso8601, post.tags)
       end
+
+      path = File.join(__dir__, "templates/feed.erb")
+      template = File.read(path)
+      renderer = ERB.new(template)
+      renderer.result(binding)
     end
   end
 end

data/lib/postwave/templates/feed.erb

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="utf-8"?>
+<feed xmlns="http://www.w3.org/2005/Atom">
+  <generator uri="https://github.com/dorkrawk/postwave" version="<%= Postwave::VERSION %>">Postwave</generator>
+  <link href="<%= link %>" rel="self" type="application/atom+xml" />
+  <link href="<%= link %>" />
+  <updated><%= updated %></updated>
+  <id><%= link %></id>
+  <title type="html"><%= title %></title>
+  <subtitle><%= description %></subtitle>
+  <% feed_posts.each do |post| %>
+  <entry>
+    <title><%= post.title %></title>
+    <link href="<%= post.link %>" rel="alternate" type="text/html" title="<%= post.title %>" />
+    <id><%= post.link %></id>
+    <published><%= post.date %></published>
+    <updated><%= post.date %></updated>
+    <author>
+      <name><%= title %></name>
+    </author>
+    <content type="html">
+      <![CDATA[<%= post.body %>]]>
+    </content>
+    <% post.tags.each do |tag| %>
+    <category term="<%= tag %>" />
+    <% end %>
+  </entry>
+  <% end %>
+</feed>

data/lib/postwave/version.rb

@@ -1,3 +1,3 @@
 module Postwave
-  VERSION = "0.0.2"
+  VERSION = "0.1.1"
 end

data/lib/postwave.rb

@@ -14,7 +14,7 @@ module Postwave
       Postwave::BlogBuilder.instance.build
     else
       if options[:version]
-        puts "postwave #{VERSION} [ruby]"
+        puts "postwave #{VERSION}"
       end
     end
   end

data/postwave.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
   spec.executables   = ['postwave']
   spec.require_paths = ["lib"]
 
-  # spec.add_dependency ""
+  spec.add_dependency "redcarpet", '~> 3.6'
 
   spec.add_development_dependency "bundler"
   spec.add_development_dependency "rake", "~> 12.3"

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: postwave
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.1
 platform: ruby
 authors:
 - Dave Schwantes
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-17 00:00:00.000000000 Z
+date: 2025-02-24 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -48,19 +62,21 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - Gemfile
+- Gemfile.lock
 - README.md
 - Rakefile
 - bin/postwave
-- crystal/src/postwave.cr
-- crystal/src/postwave/post.cr
 - lib/postwave.rb
 - lib/postwave/blog_builder.rb
 - lib/postwave/blog_creator.rb
 - lib/postwave/blog_utilities.rb
+- lib/postwave/client.rb
 - lib/postwave/display_helper.rb
+- lib/postwave/errors.rb
 - lib/postwave/post.rb
 - lib/postwave/post_creator.rb
 - lib/postwave/rss_helper.rb
+- lib/postwave/templates/feed.erb
 - lib/postwave/version.rb
 - postwave.gemspec
 homepage: https://github.com/dorkrawk/postwave

data/crystal/src/postwave/post.cr

@@ -1,77 +0,0 @@
-class Postwave::Post
-  KNOWN_FIELDS = %w(title date tags title_slug body draft)
-  REQUIRED_FIELDS = %w(title date)
-  MEATADATA_DELIMTER = "---"
-
-  def self.new_from_file_path(path : String)
-    metadata_delimter_count = 0
-    body_buffer_count = 0
-    field_content = { "body" => "" }
-
-    File.readlines(path).each do |line|
-      clean_line = line.strip
-
-      if clean_line == MEATADATA_DELIMTER
-        metadata_delimter_count += 1
-        next
-      end
-
-      if metadata_delimter_count == 0
-        next
-      elsif metadata_delimter_count == 1
-        field, value = clean_line.split(":", 2).map(&:strip)
-        field_content[field] = value
-      else
-        if body_buffer_count == 0
-          body_buffer_count += 1
-          next if clean_line.empty?
-        end
-
-        field_content["body"] += "#{line}"
-      end      
-    end
-
-    # turn "date" into a Time object
-    field_content["date"] = Time.parse(field_content["date"])
-
-    # turn "tags" into an array
-    if field_content["tags"]
-      field_content["tags"] = field_content["tags"].split(",").map do |tag|
-        tag.downcase.strip.gsub(' ', '-').gsub(/[^\w-]/, "")
-      end
-    end
-
-    # turn "draft" into boolean
-    if field_content["draft"]
-      field_content["draft"] = field_content["draft"].downcase == "true"
-    end
-
-    self.new(path, field_content)
-  end
-
-  def initialize(@file_name : String, field_content : Hash)
-
-    field_content.each do |field, value|
-      # instance_variable_set("@#{field}", value)
-      self.send("@#{field}".to_sym, value)
-      self.class.send(:attr_accessor, field)
-    end
-  end
-
-  def title_slug : String
-    @title_slug ||= @title.downcase.strip.gsub(' ', '-').gsub(/[^\w-]/, "")
-  end
-
-  def slug : String
-    @slug ||= @title_slug
-  end
-
-  def slug=(new_slug)
-    @slug = new_slug
-  end
-
-  def generated_file_name
-    # YYYY-MM-DD-slug-from-title.md
-    "#{@date.to_s[..9]}-#{slug}.md"
-  end
-end

data/crystal/src/postwave.cr

@@ -1,4 +0,0 @@
-require "./postwave/*"
-
-module Postwave
-end