til-rb 0.0.2 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40d7142e1a89db2641e1d6da0699c13ee4a4da511331c9822deaef61ca9d546b
-  data.tar.gz: 29eedc188aa255a16d0cb9734412594013b1b2a18ae2836c5194cc0a3ae827e5
+  metadata.gz: 929173ad31be6464b75779784d2c1bb1d37f04d548b1869783e156bc1a13cb11
+  data.tar.gz: 351871aa23247e031ab56b163a3e3684b8cc995d8fe0dc65b6c529b851c51332
 SHA512:
-  metadata.gz: d58c4a7620cfd20fc9901fa3bc10526662a6eea6c0393d58334976cf67a002a871bfad747c6b8ddd95190e824a9f98d2cd81548eebab2811cccefdda7a0d6aa6
-  data.tar.gz: c8f88bf4d8a0336efafcbcb4d0add65a8979845fbea4e34cca19e29a2563e06668335c94d22a3af1003f5eb35782db1329de158685a7518b84131276a0ea6486
+  metadata.gz: ce2a20ab053f5e3ed0f8bb68cd085beb60e87a5f45c39e9af95626714eb309275f6464b9d5690ad6b7eedf34b6d476999b890ac16e72db8b1fc2dc0a838eedb8
+  data.tar.gz: c418c12ae3bf2ee02255350c330b6271a07d0bcd053ea2b45acf762b852e5e0eb04daf4676bbec9980bfe803f2e6b83c598bd39e51075527fbf8233b9f2f4087

data/README.md

@@ -5,3 +5,69 @@
 A work-in-progress tool to maintain a TIL repo.
 
 Inspiration: https://github.com/jbranchaud/til
+
+See it in action below:
+
+![til in action](til.gif)
+
+## Installation
+
+### Step 1: Install the gem
+
+```
+gem install til-rb
+```
+
+You will also need `fzf` to run `til`, it's available on homebrew, so unless you already installed it, you'll have to run
+
+```
+brew install fzf
+```
+
+_fzf is technically not a hard requirement, we really could have a slightly different workflow if it's not available.
+Given that I currently am the only user, there's no need to change this at the moment, but if you'd like to use this
+gem without `fzf`, let me know and I'll happily work on it!_
+
+### Step 2: Create a GitHub repo
+
+You need a GitHub repo to store your TILs. The gem has pretty strict expectations about the format of the README.md
+file, so I recommend forking [this repo](https://github.com/pjambet/til-template), or just copying the content to a
+fresh new repo.
+
+Note: The format expectations mentioned above are the following:
+
+- A "categories" section as defined by a leading markdown separator `---`, followed by a blank line, the `###
+  Categories` title, and a list of all the categories.
+- A links section as defined by a leading markdown separator `---`, followed by a blank line and a series of markdown
+  titles for each categories present in the previous section.
+
+### Step 3: Add the environment variables
+
+Add the following variables to your environment:
+
+- `GH_TOKEN`: The only required scope is `public_repo` if your TIL repo is public and `repo` if it is private. You can
+  create a token [in the GitHub
+  settings](https://github.com/settings/tokens/new?scopes=public_repo&description=Token%20for%20til-rb)
+- `GH_REPO`: The repo name, e.g. `pjambet/til`
+
+You might want to add those to either your `.bashrc` or `.zshrc` but please be careful in case you share those publicly
+as the token is private and *must not* be shared publicly.
+
+Note: An earlier version of this gem used different names, `GH_TOKEN` & `GH_REPO`, it still works, but is not the
+recommended approach anymore, see #2.
+
+### Step 4:
+
+Run `til` from the command line
+
+## Future improvements
+
+- An `init` command that will create a repo for you
+- A `configure` command that will store the token and the repo name in a file in `~/.config/til/config` or `~/.til`
+
+## Known issues
+
+The current version (0.0.5) deletes the temporary file before attempting to create the new commit, so if anything goes
+wrong there, the content of the file will be lost.
+This will be fixed soon, by only deleting the temporary file after the commit was created, but please keep that in mind
+if you typed a long TIL and definitely don't want to lose its content.

data/bin/til

@@ -1,5 +1,20 @@
 #!/usr/bin/env ruby
 
 require 'til-rb'
+require 'optparse'
 
-Til::Core.run
+options = {}
+OptionParser.new do |opts|
+  opts.banner = 'Usage: til [options]'
+
+  opts.on('-t', '--title=TITLE', 'Set the title from the command line') do |title|
+    options[:title] = title
+  end
+
+  opts.on('-h', '--help', 'Prints this help') do
+    puts opts
+    exit
+  end
+end.parse!
+
+Til::Core.run options: options

data/lib/til-rb.rb

@@ -1,2 +1,3 @@
 require 'til/core'
+require 'til/readme_updater'
 require 'til/version'

data/lib/til/core.rb

@@ -1,10 +1,14 @@
 require 'octokit'
 require 'tempfile'
+require 'readline'
 
 module Til
   class Core
 
-    def self.run
+    GH_TOKEN_ENV_VAR_NAME = 'TIL_RB_GITHUB_TOKEN'
+    GH_REPO_ENV_VAR_NAME = 'TIL_RB_GITHUB_REPO'
+
+    def self.run(options: {})
       # Exit if `fzf` is not available
       # Optionally print a spinner
       # Grab the list of existing categories
@@ -17,17 +21,18 @@ module Til
       # Create the new file
       # Create a new commit
       # Output a link to the file and the link to edit it
-      til = new
+      til = new(options: options)
       til.run
     end
 
-    def initialize(kernel: Kernel, process: Process, env: ENV, github_client: nil, stderr: $stderr)
+    def initialize(options: {}, kernel: Kernel, process: Process, env: ENV, github_client: nil, stderr: $stderr)
+      @options = options
       @kernel = kernel
       @process = process
       @env = env
       @stderr = stderr
       @github_client = github_client
-      @repo_name = 'pjambet/til'
+      @repo_name = nil
       @new_category = false
     end
 
@@ -37,7 +42,10 @@ module Til
         check_environment_variables
         existing_categories = fetch_existing_categories
         selected_category = prompt_fzf(existing_categories)
-        prepopulate_tempfile(selected_category)
+        if @new_category
+          selected_category = prompt_for_new_category
+        end
+        prepopulate_tempfile(selected_category, @options[:title])
         open_editor
         til_content = read_file
         commit_new_til(selected_category, til_content)
@@ -54,17 +62,25 @@ module Til
     end
 
     def check_environment_variables
-      if @env['GH_TOKEN'].nil? || @env['GH_TOKEN'] == ''
-        raise 'The GH_TOKEN (with the public_repo or repo scope) environment variable is required'
+      if @env[GH_TOKEN_ENV_VAR_NAME].nil? || @env[GH_TOKEN_ENV_VAR_NAME] == ''
+        if @env['GH_TOKEN'].nil? || @env['GH_TOKEN'] == ''
+          raise "The #{GH_TOKEN_ENV_VAR_NAME} (with the public_repo or repo scope) environment variable is required"
+        else
+          @stderr.puts "Using GH_TOKEN is deprecated, use #{GH_TOKEN_ENV_VAR_NAME} instead"
+        end
       end
 
-      if (@env['VISUAL'].nil? || @env['VISUAL'] == '') && (@env['EDITOR'].nil? || @env['EDITOR'] == '')
-        raise 'The VISUAL or EDITOR environment variables are required'
+      if @env[GH_REPO_ENV_VAR_NAME].nil? || @env[GH_REPO_ENV_VAR_NAME] == ''
+        if @env['GH_REPO'].nil? || @env['GH_REPO'] == ''
+          raise "The #{GH_REPO_ENV_VAR_NAME} environment variable is required"
+        else
+          @stderr.puts "Using GH_REPO is deprecated, use #{GH_REPO_ENV_VAR_NAME} instead"
+        end
       end
     end
 
     def fetch_existing_categories
-      existing_categories = github_client.contents(@repo_name, path: '').filter do |c|
+      existing_categories = github_client.contents(repo_name, path: '').filter do |c|
         c['type'] == 'dir'
       end
 
@@ -76,7 +92,11 @@ module Til
     end
 
     def github_client
-      @github_client ||= Octokit::Client.new(access_token: @env['GH_TOKEN'])
+      @github_client ||= Octokit::Client.new(access_token: @env[GH_TOKEN_ENV_VAR_NAME] || @env['GH_TOKEN'])
+    end
+
+    def repo_name
+      @repo_name ||= (@env[GH_REPO_ENV_VAR_NAME] || @env['GH_REPO'])
     end
 
     def prompt_fzf(categories)
@@ -99,6 +119,10 @@ module Til
       throw :exit
     end
 
+    def prompt_for_new_category
+      Readline.readline("New category > ").downcase
+    end
+
     def prepopulate_tempfile(selected_category, title = 'Title Placeholder')
       @tempfile = Tempfile.new('til.md')
       @tempfile.write("# #{title}")
@@ -108,7 +132,7 @@ module Til
     end
 
     def open_editor
-      editor = ENV['VISUAL'] || ENV['EDITOR']
+      editor = ENV['VISUAL'] || ENV['EDITOR'] || 'vi'
       system(*editor.split, @tempfile.path)
     end
 
@@ -118,22 +142,26 @@ module Til
       content
     end
 
+    def new_filename(commit_title)
+      today = Time.now.strftime '%Y-%m-%d'
+      name = CGI.escape(commit_title.split.map(&:downcase).join('-'))
+      "#{today}_#{name}.md"
+    end
+
     def commit_new_til(category, content)
       commit_title = content.lines[0].chomp
       if commit_title.start_with?('#')
         commit_title = commit_title[1..].strip
       end
-      today = Time.now.strftime '%Y-%m-%d'
-      name = commit_title.split.map(&:downcase).join('-')
-      filename = "#{today}_#{name}.md"
+      filename = new_filename(commit_title)
 
-      ref = github_client.ref @repo_name, 'heads/master'
-      commit = github_client.commit @repo_name, ref.object.sha
-      tree = github_client.tree @repo_name, commit.commit.tree.sha, recursive: true
-      readme = github_client.readme @repo_name
+      ref = github_client.ref repo_name, 'heads/master'
+      commit = github_client.commit repo_name, ref.object.sha
+      tree = github_client.tree repo_name, commit.commit.tree.sha, recursive: true
+      readme = github_client.readme repo_name
       readme_content = Base64.decode64 readme.content
 
-      blob = github_client.create_blob @repo_name, content
+      blob = github_client.create_blob repo_name, content
       blobs = tree.tree.filter { |object|
         object[:type] == 'blob' && object[:path] != 'README.md'
       }.map { |object|
@@ -141,42 +169,26 @@ module Til
       }
 
       updated_readme_content = update_readme_content(category, commit_title, filename, readme_content)
-      new_readme_blob = github_client.create_blob @repo_name, updated_readme_content
+      new_readme_blob = github_client.create_blob repo_name, updated_readme_content
       blobs << { path: 'README.md', mode: '100644', type: 'blob', sha: new_readme_blob }
 
       blobs << { path: "#{category}/#{filename}", mode: '100644', type: 'blob', sha: blob }
 
-      tree = github_client.create_tree @repo_name, blobs
-      commit = github_client.create_commit @repo_name, commit_title, tree.sha, ref.object.sha
-      github_client.update_ref @repo_name, 'heads/master', commit.sha
+      tree = github_client.create_tree repo_name, blobs
+      commit = github_client.create_commit repo_name, commit_title, tree.sha, ref.object.sha
+      github_client.update_ref repo_name, 'heads/master', commit.sha
 
-      puts "You can see your new TIL at : https://github.com/pjambet/til/blob/master/#{category}/#{filename}"
-      puts "You can edit your new TIL at : https://github.com/pjambet/til/edit/master/#{category}/#{filename}"
+      puts "You can see your new TIL at : https://github.com/#{repo_name}/blob/master/#{category}/#{filename}"
+      puts "You can edit your new TIL at : https://github.com/#{repo_name}/edit/master/#{category}/#{filename}"
     end
 
     def update_readme_content(category, commit_title, filename, readme_content)
-      beginning = readme_content.index('### Categories') + '### Categories'.length
-      eend = readme_content.index('---', readme_content.index('---') + 1) - 1
-
-      # [["[Git](#git)", "Git", "git"], ["[Qux](#qux)", "Qux", "qux"]]
-      categories = readme_content[beginning..eend].scan(/(\[(\w+)\]\(#(\w+)\))/)
+      updater = Til::ReadmeUpdater.new(readme_content)
 
       if @new_category
+        updater.add_item_for_new_category(category, commit_title, filename)
       else
-        existing_cat = categories.find { |c| c[2] == category }
-
-        loc_in_page = readme_content.index("### #{existing_cat[1]}")
-        next_cat_location = readme_content.index('###', loc_in_page + 1)
-
-        new_line = "- [#{commit_title}](#{category}/#{filename})"
-        new_readme_content = ''
-        if next_cat_location
-          breakpoint = next_cat_location - 2
-          new_readme_content = readme_content[0..breakpoint] + new_line + readme_content[breakpoint..]
-        else
-          new_readme_content = readme_content + new_line + '\n'
-        end
-        new_readme_content
+        updater.add_item_for_existing_category(category, commit_title, filename)
       end
     end
 

data/lib/til/readme_updater.rb

@@ -0,0 +1,85 @@
+module Til
+  class ReadmeUpdater
+
+    def initialize(initial_content)
+      @initial_content = initial_content
+    end
+
+    def add_item_for_existing_category(category, item_title, filename)
+      beginning = @initial_content.index('### Categories') + '### Categories'.length
+      eend = @initial_content.index('---', @initial_content.index('---') + 1) - 1
+
+      # [["[Git](#git)", "Git", "git"], ["[Qux](#qux)", "Qux", "qux"]]
+      categories = @initial_content[beginning..eend].scan(/(\[(\w+)\]\(#(\w+)\))/)
+
+      existing_cat = categories.find { |c| c[2] == category }
+
+      loc_in_page = @initial_content.index("### #{existing_cat[1]}")
+      next_cat_location = @initial_content.index('###', loc_in_page + 1)
+
+      new_line = "- [#{item_title}](#{category}/#{filename})"
+      new_readme_content = ''
+      if next_cat_location
+        breakpoint = next_cat_location - 2
+        new_readme_content = @initial_content[0..breakpoint] + new_line + @initial_content[breakpoint..]
+      else
+        new_readme_content = @initial_content + new_line + "\n"
+      end
+      new_readme_content
+    end
+
+    def add_item_for_new_category(category, item_title, filename)
+      # TODO: We'll need some form of validation on the category name
+      beginning = @initial_content.index('### Categories') + '### Categories'.length
+      first_dashdashdash = @initial_content.index('---')
+      eend = @initial_content.index('---', first_dashdashdash + 1) - 1
+
+      # [["[Git](#git)", "Git", "git"], ["[Qux](#qux)", "Qux", "qux"]]
+      categories = @initial_content[beginning..eend].scan(/(\[(\w+)\]\(#(\w+)\))/)
+
+      insert_at = categories.bsearch_index do |category_triplet|
+        category_triplet[2] >= category
+      end
+
+      if insert_at.nil?
+        # It's the last category
+        insert_at = categories.length
+      end
+
+      categories.insert(insert_at, ["[#{category.capitalize}](\##{category})", category.capitalize, category])
+
+      new_categories_formatted = categories.map do |category|
+        "* #{category[0]}"
+      end.join("\n")
+
+      new_categories_formatted.prepend("### Categories\n\n")
+
+      category_sections_found = 0
+      current_search_index = eend + 1 + 3
+
+      while category_sections_found < insert_at
+        current_search_index = @initial_content.index('###', current_search_index + 1)
+        category_sections_found += 1
+      end
+
+      next_bound = @initial_content.index('###', current_search_index + 1)
+
+      new_line = "- [#{item_title}](#{category}/#{filename})"
+
+      if next_bound
+        new_readme_content = @initial_content[0..(first_dashdashdash + 2)] \
+                             + "\n\n#{new_categories_formatted}\n" \
+                             + @initial_content[eend..(next_bound - 2)] \
+                             + "\n### #{category.capitalize}\n\n#{new_line}\n\n" \
+                             + @initial_content[next_bound..]
+      else
+        new_readme_content = @initial_content[0..(first_dashdashdash + 2)] \
+                             + "\n\n#{new_categories_formatted}\n" \
+                             + @initial_content[eend..] \
+                             + "\n### #{category.capitalize}\n\n#{new_line}\n"
+      end
+
+      new_readme_content
+    end
+  end
+end

data/lib/til/version.rb

@@ -1,5 +1,5 @@
 module Til
 
-  VERSION = '0.0.2'
+  VERSION = '0.0.7'
 
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: til-rb
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.7
 platform: ruby
 authors:
 - Pierre Jambet
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.11.2
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.1
 description: til-rb helps you manage a repo of TILs similar to https://github.com/jbranchaud/til
 email: hello@pjam.me
 executables:
@@ -50,8 +64,9 @@ files:
 - bin/til
 - lib/til-rb.rb
 - lib/til/core.rb
+- lib/til/readme_updater.rb
 - lib/til/version.rb
-homepage: https://rubygems.org/gems/til-rb
+homepage: https://github.com/pjambet/til-rb/
 licenses:
 - MIT
 metadata: {}