postwave 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f460f1e6202c2d56b2c355266fd8819691cdb2a8f12b6aa33febd8a0c6b5d580
-  data.tar.gz: 5159c6aa7c213bfff6ec6f1a2f3fdb8c4f1ef8f03dbe9ff5014b93709ee8c625
+  metadata.gz: 3659ecd8d7d5b7d1fdfaddb0b8538b86414e34687febec04f29c3352dff8d6c2
+  data.tar.gz: f877ba937e8361518ca4a0c16f5d3ae77dfb101ac94becd0e2f2c3ae5f01abf4
 SHA512:
-  metadata.gz: 5102d693e92f76288dbdf152f00cfdf6a386e0b4a27bb4415ba8baccdd13d64b04e624f136bb993046bf7b71facbf5d78848716aa8c146abe6a1f9d006b91282
-  data.tar.gz: cfbb408e719c8a56e54ef81614ae5e7a7a362e1b3f7f863e4e462d449dfab3188beca5e4536fe13381097c1eb14d8b43842c9108d5429f44909aaf87a765961a
+  metadata.gz: a866429e4ad00e427b8302527e4eafcd488d16b938b51d12f370104d9a8dc0abdec1f5b868f62c0afb7b10ac162a120bbe2494d6b4347f521c9c6f35cf9c00cd
+  data.tar.gz: 89575f81e742ca2bcd40d14c6e54ed3618daf4ad8434720ed65b6cdd4350e2189ba0721265351d62d565c49c9ac8c9a4686e96e93eabc358e29984a66999f3c1

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,108 @@ 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"
+```
+
+### 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_builder.rb

@@ -5,6 +5,7 @@ require 'csv'
 require 'time'
 require_relative "blog_utilities"
 require_relative "display_helper"
+require_relative "rss_helper"
 require_relative "post"
 
 module Postwave
@@ -12,6 +13,7 @@ module Postwave
     include Singleton
     include BlogUtilities
     include DisplayHelper
+    include RssHelper
 
     INDEX_HEADERS = ["slug", "date", "title"]
 
@@ -53,6 +55,8 @@ module Postwave
       build_tags_files(tags)
       build_summary(published_posts, tags)
 
+      build_rss(published_posts)
+
       build_time = Time.now - start
       output_build_completed(build_time)
     end
@@ -95,8 +99,8 @@ module Postwave
     def build_summary(posts, tags)
       summary = {
         post_count: posts.count,
-        most_recent_file_name: posts.first.file_name,
-        most_recent_date: posts.first.date,
+        most_recent_file_name: posts.first&.file_name,
+        most_recent_date: posts.first&.date,
         tags: tags.keys
       }
       File.write(File.join(Dir.pwd, POSTS_DIR, META_DIR, SUMMARY_FILE_NAME), summary.to_yaml)

data/lib/postwave/blog_creator.rb

@@ -22,6 +22,8 @@ module Postwave
       build_files
       write_initial_summary_contents
 
+      configure_blog
+
       output_blog_created 
     end
 
@@ -43,7 +45,23 @@ module Postwave
         tags: []
       }
 
-      File.write(File.join(Dir.pwd, POSTS_DIR, META_DIR, SUMMARY_FILE_NAME), summary.to_yaml)
+      File.write(File.join(Dir.pwd, POSTS_DIR, META_DIR, SUMMARY_FILE_NAME), summary.transform_keys(&:to_s).to_yaml)
+    end
+
+    def configure_blog
+      config = {}
+
+      output_blog_name_prompt
+      config[:name] = gets.chomp
+      output_blog_url_prompt
+      config[:url] = gets.chomp
+      output_blog_posts_path_prompt
+      config[:posts_path] = gets.chomp
+      output_blog_description_prompt
+      config[:description] = gets.chomp
+
+      File.write(File.join(Dir.pwd, CONFIG_FILE_NAME), config.transform_keys(&:to_s).to_yaml)
+      output_config_message
     end
   end
 end

data/lib/postwave/blog_utilities.rb

@@ -3,38 +3,47 @@ module Postwave
     CONFIG_FILE_NAME = "postwave.yaml"
     INDEX_FILE_NAME = "index.csv"
     SUMMARY_FILE_NAME = "summary.yaml"
+    RSS_FILE_NAME = "rss"
     POSTS_DIR = "_posts"
     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
+        {}
+      end
+    end
   end
 end

data/lib/postwave/client.rb

@@ -0,0 +1,102 @@
+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)
+
+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
+
+    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/display_helper.rb

@@ -7,6 +7,26 @@ module Postwave
       puts "🌊 Creating new blog..."
     end
 
+    def output_blog_name_prompt
+      puts "Enter the name of this blog (leave blank to skip): "
+    end
+
+    def output_blog_url_prompt
+      puts "Enter the url of this blog (leave blank to skip): "
+    end
+
+    def output_blog_posts_path_prompt
+      puts "Enter the directory for the blog posts (if a post will be at http://example.com/blog/posts/post-title put blog/posts):"
+    end
+
+    def output_blog_description_prompt
+      puts "Enter a short description of this blog (leave blank to skip): "
+    end
+
+    def output_config_message
+      puts "All configuration values can be changed at any time by editing the postwave.yaml file."
+    end
+
     def output_blog_created
       puts "New blog set up.".green
     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
@@ -33,10 +36,13 @@ module Postwave
             next if clean_line.empty?
           end
 
-          field_content["body"] += "#{line}\n"
+          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|
@@ -56,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
 
@@ -73,9 +79,13 @@ 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[..9]}-#{slug}.md"
+      "#{@date.to_s[..9]}-#{slug}.md"
     end
 
     def update_file_name!

data/lib/postwave/rss_helper.rb

@@ -0,0 +1,36 @@
+require_relative "blog_utilities"
+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 << feed_content(posts)
+      end
+    end
+    
+    def feed_content(posts)
+      link = config_values[:url]
+      updated = Time.now.iso8601.to_s
+      title = config_values[:name]
+      description = config_values[:description]
+
+      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.1"
+  VERSION = "0.1.0"
 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.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Dave Schwantes
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-09-15 00:00:00.000000000 Z
+date: 2025-01-17 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,6 +62,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - Gemfile
+- Gemfile.lock
 - README.md
 - Rakefile
 - bin/postwave
@@ -55,9 +70,13 @@ files:
 - 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