margin 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb9dc60bfae6e3c83db3a65db9f6acc5190f134f3ad7cf950814d822b0cd089e
-  data.tar.gz: 754b9388aaf8f10472ad9866f5a5e133cbb33437d7ab562906b38705cb3f9e1c
+  metadata.gz: 233a6e36f3ef6ab23c049f53a2dfa1d2835102324ccb0c95d4db8d9075b9a064
+  data.tar.gz: 7ed177ebb4ae5298a16f02e3ad89c7c6a2659636dc93d268536b5314b5d00dfb
 SHA512:
-  metadata.gz: b551f8c060c5f2bc07cfee1dc4578d7ecac235a6332042575ae5a64e995ecc50ce070852f6b62f86a17b4f98ee76e09d2a784a6307975146c6f6333dcb76c639
-  data.tar.gz: 202ab73b884e08667e06e552447113170ce98f3cda2de6dfff3f5b4df453ee673ab09137714ca8455169a375239a7691914a84b2d06729387ceda0af1f32b9ef
+  metadata.gz: 642f0084057a8cbc72553cb7b4c68480bb3d947d82b6be3a6b69c20a10552171b023be0014b4c7e5cf27948343b359749b70f28aade5b8af9182b47ed52439d1
+  data.tar.gz: 86121dc2787e55b910f4924c4d808bfa4cdffc050972969b2ee1d376fdf0ed6d38c46245e2e0d2db5eae86ca240cd233a977343ef878611663bb9ccb8259eab6

data/.gitignore

@@ -6,3 +6,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+*.gem

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    margin (0.1.0)
+    margin (0.2.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,12 +1,46 @@
-# Margin
+# MarginRB
+
+This is a Ruby parser for Alex Gamburg's "Margin" markup language.
+
+See https://margin.love/ for the documentation,
+and https://github.com/gamburg/margin for Alex's implementation.
+
+This should be considered an early Alpha, as many details in the
+spec are still being worked out.
+
+## Divergence from Alex's Implementation
+
+To eliminate some ambiguities in the spec and keep the parser
+simple, this implementation refines the specification for Margin
+as follows:
+
+1. Every valid item must end in a newline, which means the document itself
+   must end in a newline if there is an item on the last line.
+2. Items can be one of two types, "item" or "task." To represent this I added
+   a 'type' field on the Item's JSON representation. This is mostly informational
+   and avoids users of the parsed data needing to do additional checks
+   to figure out if an item is a task or not.
+3. Items which are tasks have a boolean `done` field indicating whether they are done.
+4. The `value` field on each item is cleaned of any leading or trailing decoration,
+   including whitespace. Thus, the `value` field of a Task does not include the leading
+   "checkbox" annotation.
+5. Annotations are represented as objects with a required `value` and an optional `key`.
+   In Alex's implementation the key and value of what he calls an "index"
+   (an annotation with a colon in it) are not machine parsed.
+6. If the `value` of an annotation is strictly numeric, it is parsed into a number,
+   not a string.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/margin`. To experiment with that code, run `bin/console` for an interactive prompt.
+## Installation
 
-TODO: Delete this and the text above, and describe your gem
+Margin requires Ruby >= 2.6.x.
 
-## Installation
+To use it directly:
+
+```sh
+$ gem install margin
+```
 
-Add this line to your application's Gemfile:
+In an application, add this line to your application's Gemfile:
 
 ```ruby
 gem 'margin'
@@ -14,15 +48,22 @@ gem 'margin'
 
 And then execute:
 
-    $ bundle install
-
-Or install it yourself as:
-
-    $ gem install margin
+```sh
+$ bundle install
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+Right this minute there's not much you can do with it except load it into
+a repl and poke it. As an example, supposing you have a file `example.margin`
+in your working directory, you can then run `bin/console` and play with it in
+IRB like so:
+
+```ruby
+d = Margin::Document.from_margin(File.read('example.margin'))
+d.root #=> returns a Margin::Item for the root
+d.to_json #=> returns a JSON representation of the parsed tree
+```
 
 ## Development
 
@@ -30,10 +71,15 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
-## Contributing
+## Development Plans
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/margin.
+I'm not sure! I saw Alex's ShowHN introducing Margin to the world and thought it looked like a fun parser to crank out. I thought it would take a couple hours... a couple hours turned out to be more like 8, haha :D.
+
+I'm having fun poking at this for now and discussing the spec on the main Margin repo. I'll probably add a CLI that will make this more useful. After that, I'm not sure. At that point it's sort of done?
+
+## Contributing
 
+Feedback, bug reports, and pull requests are welcome on GitHub at https://github.com/burlesona/margin.
 
 ## License
 

data/lib/margin/document.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'margin/parser'
+
+module Margin
+  class Document
+    attr_reader :root
+
+    def initialize(input="", format: :margin)
+      @root = Item.root
+      case format
+      when :margin then parse_margin!(input)
+      when :json then parse_json!(input)
+      else raise ArgumentError, "Allowed formats: :margin, :json"
+      end
+    end
+
+    def to_margin
+      ""
+    end
+
+    def to_json(pretty: false)
+      root.to_json(pretty: pretty)
+    end
+
+    private
+
+    def parse_margin!(input)
+      @root = Parser.parse(input)
+    end
+
+    def parse_json!(input)
+    end
+
+    class << self
+      def from_margin(input)
+        new(input, format: :margin)
+      end
+
+      def from_json(input)
+        new(input, format: :json)
+      end
+    end
+  end
+end

data/lib/margin/item.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Margin
+  class Item
+    attr_accessor :raw_data,
+                  :type,
+                  :value,
+                  :done,
+                  :annotations,
+                  :children
+
+    def initialize(raw_data: "", type: :item, done: false, value: "", annotations: [], children: [])
+      @raw_data = raw_data
+      @type = type
+      @done = done
+      @value = value
+      @annotations = annotations
+      @children = children
+    end
+
+    def task?
+      type == :task
+    end
+
+    def done?
+      done
+    end
+
+    def root?
+      value == "root"
+    end
+
+    def as_json
+      h = {}
+      h[:raw_data] = raw_data
+      h[:type] = type
+      h[:value] = value
+      h[:done] = done if type == :task
+      h[:annotations] = annotations
+      h[:children] = children.map(&:as_json)
+      h
+    end
+
+    def to_json(pretty: false)
+      pretty ? JSON.pretty_generate(as_json) : JSON.generate(as_json)
+    end
+
+    class << self
+      def root
+        new raw_data: "root", value: "root"
+      end
+
+      def from_line(line)
+        new raw_data: line.raw_data,
+            type: line.type,
+            value: line.value,
+            done: line.done,
+            annotations: line.annotations
+      end
+    end
+  end
+end

data/lib/margin/parser.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require 'strscan'
+require 'margin/item'
+
+module Margin
+
+  # Notes:
+  # - The parser requires a trailing newline at the end of the last item.
+  # - Per the spec: leading and trailing dashes, colons, asterisks,
+  #   chevrons, underscores and whitespaces, as well as blank lines, are ignored.
+  module Parser
+
+    IGNORED_CHARACTERS = /[\ \-\*:><_]/
+    LINE_DECORATION = /#{IGNORED_CHARACTERS}*/
+    EMPTY_LINE = /^#{IGNORED_CHARACTERS}*\n/
+    TASK_START = /^\[.\]\ /
+    ANNOTATION_ONLY = /^\[.*\]$/
+
+
+    module LineMethods
+      module_function
+      # Get the inner value by scanning past all leading and trailing line decorations.
+      def strip_line(string)
+        s = StringScanner.new(string)
+        raw_inner = ""
+        s.skip LINE_DECORATION
+        raw_inner += s.getch until s.match? (/#{LINE_DECORATION}$/)
+        raw_inner
+      end
+
+      # Detect the offset of a raw line
+      def detect_offset(string)
+        s = StringScanner.new(string)
+        s.match? (/\s*/)
+      end
+
+      # Detect if this matches the criteria for a task,
+      # Return the status and rest of string if yes,
+      # otherwise return false.
+      def detect_task(string)
+        return false unless string.match? TASK_START
+        done = string[1] != " "
+        rest = string.sub(TASK_START,"")
+        [done, rest]
+      end
+
+      def detect_annotation_only(string)
+        string.match? ANNOTATION_ONLY
+      end
+
+      def extract_annotations(string)
+        value = ""
+        current_annotation = ""
+        annotations = []
+        s = StringScanner.new(string)
+        in_annotation = false
+        until s.eos?
+          c = s.getch
+          case
+          when c == "["
+            in_annotation = true
+          when c == "]"
+            in_annotation = false
+            annotations << structure_annotation(current_annotation)
+            current_annotation = ""
+          when in_annotation
+            current_annotation += c
+          else
+            value += c
+          end
+        end
+        value = value.strip
+        value = nil if value.length == 0
+        [value, annotations]
+      end
+
+      def structure_annotation(string)
+        first, last = string.split(":",2)
+        if last
+          { key: first.strip, value: extract_annotation_value(last) }
+        else
+          { value: extract_annotation_value(first) }
+        end
+      end
+
+      # Check if a value is really numeric, return the clean value
+      def extract_annotation_value(string)
+        string = string.strip
+        case
+        when i = Integer(string, exception: false) then i
+        when f = Float(string, exception: false) then f
+        else string
+        end
+      end
+    end
+
+
+    class Line
+      include LineMethods
+
+      attr_reader :raw_data,
+                  :offset,
+                  :type,
+                  :done,
+                  :value,
+                  :annotations
+
+      def initialize(raw_data)
+        @raw_data = raw_data
+        @offset = detect_offset(raw_data)
+        @annotations = { notes: [], indexes: {} }
+        parse!
+      end
+
+      private
+
+      def parse!
+        raw_inner = strip_line(raw_data)
+        
+        if detect_annotation_only(raw_inner)
+          @type = :annotation
+        elsif result = detect_task(raw_inner)
+          @type = :task
+          @done, raw_inner = result
+        else
+          @type = :item
+        end
+
+        @value, @annotations = extract_annotations(raw_inner)
+      end
+    end
+
+
+    module_function
+
+    def parse(text)
+      s = StringScanner.new(text)
+      lines = []
+      until s.eos?
+        raw = s.scan_until(/\n/)&.chomp
+        break if raw.nil? # probably should handle this with a custom error
+        lines << Line.new(raw) unless raw.match? (/^#{IGNORED_CHARACTERS}*$/)
+      end
+      parse_items Item.root, lines
+    end
+
+    def parse_items(parent, lines)
+      return parent if !lines.any?
+      while this_line = lines.shift do
+        this_item = nil
+
+        # handle this line
+        case this_line.type
+        when :item, :task
+          this_item = Item.from_line(this_line)
+          parent.children << this_item
+        when :annotation
+          parent.annotations += this_line.annotations
+        else
+          raise TypeError, "Unknown line type: `#{this_line.type}`"
+        end
+        
+        break if this_item.nil?
+        break if lines.empty?
+        
+        # now look ahead to decide what to do next
+        next_line = lines.first
+        parse_items(this_item, lines) if next_line.offset > this_line.offset
+        break if next_line.offset < this_line.offset
+      end
+      parent
+    end
+  end
+end

data/lib/margin/version.rb

@@ -1,3 +1,3 @@
 module Margin
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/margin.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.description   = "Converts margin-formatted text into Ruby data (or the inverse), and can also import and export compatible JSON."
   spec.homepage      = "https://aburleson.com"
   spec.license       = "MIT"
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.6.0")
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/burlesona/margin-rb"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: margin
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Andrew Burleson
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-05-11 00:00:00.000000000 Z
+date: 2020-05-13 00:00:00.000000000 Z
 dependencies: []
 description: Converts margin-formatted text into Ruby data (or the inverse), and can
   also import and export compatible JSON.
@@ -29,6 +29,9 @@ files:
 - bin/console
 - bin/setup
 - lib/margin.rb
+- lib/margin/document.rb
+- lib/margin/item.rb
+- lib/margin/parser.rb
 - lib/margin/version.rb
 - margin.gemspec
 homepage: https://aburleson.com
@@ -46,7 +49,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: 2.6.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="