rundoc 0.0.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 7935527c5d717e2c4bdc0883a285dd3c7f834f65
-  data.tar.gz: ffc9bf341d82df737a5dc3ba4bb557160ae049b9
+SHA256:
+  metadata.gz: ed87bdf4593dcd65e6823a9ef5231802b0282aed932c119022cfc44d2ec6f9d8
+  data.tar.gz: 0d7a80aab3b225049978eb30ca301f817203a564aa9787dcd0026a89b61c101d
 SHA512:
-  metadata.gz: e4839a376fc7911464bfd37ec2a64cc824963a52bef72d1e9e4876c07c8e1f5d6d1d99bab48243ef1c769cb98dabf186624dfe4ecf5a411480a6a748fd0293ab
-  data.tar.gz: 6cd4c38c55413efe85e174b561f39e99bc5788d21e2f63e93cef0c709563609a3864f704cb05c8c04b139d999ef789addeda7105b0b71c8f524890cc4aad2a4d
+  metadata.gz: ff4a68baac0e70330af729e752dc96e01c95e1da4ffe0e4850d8fca619e026adbaea940fed31982d41bcc41308ffdb7c3625145c2209ea0db7ec22b714738377
+  data.tar.gz: '09e9a757c31ea81c31b1e1d1c70da5241f2b756c39a2f6701e0d4b9f2a108647d21fb6d40edd31417b5136f3eb72f802c03020b7af9d42677d8f6efd96e3bf4d'

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+rvm:
+  - 2.4
+
+sudo: false
+
+script: bundle exec rake test
+

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 1.0.0
+
+- Now using a propper PEG parser (parslet)

data/Gemfile

@@ -1,3 +1,4 @@
 source "http://rubygems.org"
+gem 'm'
 
 gemspec

data/README.md

@@ -1,6 +1,6 @@
 # RunDOC
 
-![](https://www.dropbox.com/s/u354td51brynr4h/Screenshot%202017-05-09%2009.36.33.png?dl=1)
+![](https://www.dropbox.com/s/u354td51brynr4h/Screenshot%202017-05-09%2009.36.33.png?raw=1)
 
 ## What
 
@@ -55,10 +55,22 @@ Run the `rundoc build` command on any markdown file
 $ rundoc build --path runDOC.md
 ```
 
-Note: This command will create and manipulate directories in the working directory of your source markdown file. Best practice is to have your source markdown file in it's own empty directory.
+Note: This command will create and manipulate directories in the working directory of your source markdown file. Best practice is to have your source markdown file in its own empty directory.
 
 This will generate a project folder with your project in it, and a markdown README.md with the parsed output of the markdown docs, and a copy of the source.
 
+## Quick docs
+
+- [$]()
+- [fail.$]()
+- [file.write]()
+- [file.append]()
+- [file.remove]()
+- [background.start]()
+- [background.stop]()
+- [background.log.read]()
+- [background.log.clear]()
+
 ## Write it:
 
 Rundoc uses github flavored markdown. This means you write like normal but in your code sections
@@ -69,7 +81,7 @@ All runDOC commands are prefixed with three colons `:::` and are inclosed in a c
 command such as `$` which is an alias for `bash` commands like this:
 
     ```
-    :::> $ git init .
+    :::>- $ git init .
     ```
 
 Nothing before the three colons matters. The space between the colons
@@ -80,7 +92,7 @@ can add a minus symbol `-` to the end to prevent it from being
 rendered.
 
     ```
-    :::- $ git init .
+    :::-- $ git init .
     ```
 
 > Note: If all commands inside of a code block are hidden, the entire codeblock will not be rendered.
@@ -107,9 +119,9 @@ That's the syntax, let's look at different runDOC commands
 An arrow `>` is shorthand for "render this" and a dash `-` is shorthand for skip this section. The posions two positions are command first and result second. You can skip a trailing `-`.
 
 
-- `:::>`  (yes command, not result)
+- `:::>-` (yes command, not result)
 - `:::>>` (yes command, yes result)
-- `:::-`  (not command, not result)
+- `:::--` (not command, not result)
 - `:::->` (not command, yes result)
 
 ## Shell Commands
@@ -179,10 +191,12 @@ Current Commands:
 - `file.append`
 - `file.remove`
 
+If the exact filename is not known you can use a [file glob (\*)](https://github.com/schneems/rundoc/pull/6).
+
 Use the `file.write` keyword followed by a filename, on the next line(s) put the contents of the file
 
     ```
-    :::> file.write config/routes.rb
+    :::>- file.write config/routes.rb
 
     Example::Application.routes.draw do
       root        :to => "pages#index"
@@ -196,7 +210,7 @@ Use the `file.write` keyword followed by a filename, on the next line(s) put the
 If you wanted to change `users` to `products` you could write to the same file again.
 
     ```
-    :::> file.write config/routes.rb
+    :::>- file.write config/routes.rb
     Example::Application.routes.draw do
       root        :to => "pages#index"
 
@@ -256,13 +270,47 @@ Anything after the pipe `|` will generate a new command with the output of the p
 
 This command is currently hacked together, and needs a refactor. Use it, but if something does not behave as you would expected open an issue and explain it.
 
+## Background
+
+Sometimes you want to start a long lived process like a server in the background. In that case, the `background` namespace has your, well, back.
+
+To start a process, pass in the command as the first arg, and give it a name (so it can be referenced later):
+
+```
+:::>> background.start("rails server", name: "server")
+```
+
+You can make the background process wait until it receives a certain string in the logs. For instance to make sure that the server is fully booted:
+
+```
+:::>> background.start("rails server", name: "server", wait: "Listening on")
+```
+
+You can stop the process by referencing the name:
+
+```
+:::-- background.stop(name: "server")
+```
+
+You can also get the log contents:
+
+
+```
+:::>> background.log.read(name: "server")
+```
+
+You can also truncate the logs:
+
+```
+:::>> background.log.clear(name: "server")
+```
 
 ## Configure
 
 You can configure your docs in your docs use the `runDOC` command
 
     ```
-    :::- rundoc
+    :::-- rundoc
     ```
 
 Note: Make sure you run this as a hidden command (with `-`).
@@ -273,7 +321,7 @@ This will eval any code you put under that line (in Ruby). If you want to run so
 
 
     ```
-    :::- rundoc
+    :::-- rundoc
     Rundoc.configure do |config|
       config.after_build do
         puts "you could push to github here"
@@ -289,7 +337,7 @@ This will eval any code you put under that line (in Ruby). If you want to run so
 By default your app builds in a `tmp` directory. If any failures occur the results will remain in `tmp`. On a successful build the contents are copied over to `project`. If you are generating a new rails project in your code `$ rails new myapp`. Then the finished directory would be in `project/myapp`. If you don't like the `./project` prefix you could tell runDOC to output contents in `./myapp` instead.
 
     ```
-    :::- rundoc
+    :::-- rundoc
     Rundoc.configure do |config|
       config.project_root = "myapp"
     end
@@ -302,7 +350,7 @@ This will also be the root directory that the `after_build` is executed in.
 Sometimes sensitive info like usernames, email addresses, or passwords may be introduced to the output readme. Let's say that your email address was `schneems@example.com` you could filter this out of your final document and replace it with `developer@example.com` instead like this:
 
     ```
-    :::- rundoc
+    :::-- rundoc
     Rundoc.configure do |config|
       config.filter_sensitive("schneems@exmaple.com" => "developer@example.com")
     end
@@ -323,13 +371,13 @@ This is a section for brainstorming. If it's here it's not guaranteed to get wor
 
 
     ```
-    :::> background.start(command: "rails server")
+    :::>- background.start(command: "rails server")
     ```
 
     ```
     :::>> background.read("rails server")
-    :::> | $ head -n 23
-    :::> background.clear
+    :::>- | $ head -n 23
+    :::>- background.clear
     ```
 
 

data/bin/rundoc

@@ -84,6 +84,14 @@ class RundocCLI < Thor
     Dir.chdir(project_dir) do
       Rundoc.run_after_build
     end
+
+  ensure
+    Rundoc::CodeCommand::Background::ProcessSpawn.tasks.each do |name, task|
+      next unless task.alive?
+
+      puts "Warning background task is still running, cleaning up: name: #{name}"
+      task.stop
+    end
   end
 end
 

data/lib/rundoc.rb

@@ -7,9 +7,21 @@ module Rundoc
 
   def code_command_from_keyword(keyword, args)
     klass      = code_command(keyword.to_sym) || Rundoc::CodeCommand::NoSuchCommand
-    cc         = klass.new(args)
+    original_args = args.dup
+    if args.is_a?(Array) && args.last.is_a?(Hash)
+      kwargs = args.pop
+      cc = klass.new(*args, **kwargs)
+    elsif args.is_a?(Hash)
+      cc = klass.new(**args)
+    else
+      cc = klass.new(*args)
+    end
+
+    cc.original_args = original_args
     cc.keyword = keyword
     cc
+  rescue ArgumentError => e
+    raise ArgumentError, "Wrong method signature for #{keyword} with arguments: #{original_args.inspect}, error:\n #{e.message}"
   end
 
   def parser_options
@@ -74,3 +86,4 @@ end
 require 'rundoc/parser'
 require 'rundoc/code_section'
 require 'rundoc/code_command'
+require 'rundoc/peg_parser'

data/lib/rundoc/code_command.rb

@@ -1,10 +1,15 @@
 module Rundoc
+  # Generic CodeCommand class to be inherited
+  #
   class CodeCommand
-    attr_accessor :render_result, :render_command, :command, :contents, :keyword
+    attr_accessor :render_result, :render_command,
+                  :command, :contents, :keyword,
+                  :original_args
+
     alias :render_result? :render_result
     alias :render_command? :render_command
 
-    def initialize(arg)
+    def initialize(*args)
     end
 
     def hidden?
@@ -21,16 +26,25 @@ module Rundoc
     end
     alias :<< :push
 
-    # executes command to build project
+    # Executes command to build project
+    # Is expected to return the result of the command
     def call(env = {})
       raise "not implemented"
     end
+
+    # the output of the command, i.e. `$ cat foo.txt`
+    def to_md(env = {})
+      raise "not implemented"
+    end
   end
 end
 
+
 require 'rundoc/code_command/bash'
 require 'rundoc/code_command/pipe'
 require 'rundoc/code_command/write'
 require 'rundoc/code_command/repl'
 require 'rundoc/code_command/rundoc_command'
-require 'rundoc/code_command/no_such_command'
+require 'rundoc/code_command/no_such_command'
+require 'rundoc/code_command/raw'
+require 'rundoc/code_command/background'

data/lib/rundoc/code_command/background.rb

@@ -0,0 +1,9 @@
+class Rundoc::CodeCommand::Background
+end
+
+require 'rundoc/code_command/background/process_spawn'
+require 'rundoc/code_command/background/start'
+require 'rundoc/code_command/background/stop'
+require 'rundoc/code_command/background/wait'
+require 'rundoc/code_command/background/log/clear'
+require 'rundoc/code_command/background/log/read'

data/lib/rundoc/code_command/background/log/clear.rb

@@ -0,0 +1,17 @@
+class Rundoc::CodeCommand::Background::Log
+  class Clear < Rundoc::CodeCommand
+    def initialize(name: )
+      @spawn = Rundoc::CodeCommand::Background::ProcessSpawn.find(name)
+    end
+
+    def to_md(env = {})
+      ""
+    end
+
+    def call(env = {})
+      @spawn.log.truncate(0)
+      ""
+    end
+  end
+end
+Rundoc.register_code_command(:"background.log.clear", Rundoc::CodeCommand::Background::Log::Clear)

data/lib/rundoc/code_command/background/log/read.rb

@@ -0,0 +1,16 @@
+class Rundoc::CodeCommand::Background::Log
+  class Read < Rundoc::CodeCommand
+    def initialize(name: )
+      @spawn = Rundoc::CodeCommand::Background::ProcessSpawn.find(name)
+    end
+
+    def to_md(env = {})
+      ""
+    end
+
+    def call(env = {})
+      @spawn.log.read
+    end
+  end
+end
+Rundoc.register_code_command(:"background.log.read", Rundoc::CodeCommand::Background::Log::Read)

data/lib/rundoc/code_command/background/process_spawn.rb

@@ -0,0 +1,70 @@
+require 'shellwords'
+require 'timeout'
+
+class Rundoc::CodeCommand::Background
+  class ProcessSpawn
+    def self.tasks
+      @tasks
+    end
+
+    @tasks = {}
+    def self.add(name, value)
+      raise "Task named #{name.inspect} is already started, choose a different name" if @tasks[name]
+      @tasks[name] = value
+    end
+
+    def self.find(name)
+      raise "Could not find task with name #{name.inspect}, known task names: #{@tasks.keys.inspect}" unless @tasks[name]
+      @tasks[name]
+    end
+
+    attr_reader :log, :pid
+
+    def initialize(command , timeout: 5, log: Tempfile.new("log"), out: "2>&1")
+      @command = command
+      @timeout_value = timeout
+      @log           = log
+
+      @log = Pathname.new(@log)
+      @log.dirname.mkpath
+
+      @command = "/usr/bin/env bash -c #{@command.shellescape} >> #{@log} #{out}"
+      @pid = nil
+    end
+
+    def wait(wait_value = nil, timeout_value = @timeout_value)
+      call
+      return unless wait_value
+
+      Timeout.timeout(Integer(timeout_value)) do
+        until @log.read.match(wait_value)
+          sleep 0.01
+        end
+      end
+    rescue Timeout::Error
+      raise "Timeout waiting for #{@command.inspect} to find a match using #{ wait_value.inspect } in \n'#{ log.read }'"
+      false
+    end
+
+    def alive?
+      return false unless @pid
+      Process.kill(0, @pid)
+    rescue Errno::ESRCH, Errno::EPERM
+      false
+    end
+
+    def stop
+      return unless alive?
+      Process.kill('TERM', @pid)
+      Process.wait(@pid)
+    end
+
+    def check_alive!
+      raise "#{@original_command} has exited unexpectedly: #{@log.read}" unless alive?
+    end
+
+    private def call
+      @pid ||= Process.spawn(@command)
+    end
+  end
+end

data/lib/rundoc/code_command/background/start.rb

@@ -0,0 +1,36 @@
+require 'tempfile'
+
+class Rundoc::CodeCommand::Background
+  class Start < Rundoc::CodeCommand
+    def initialize(command, name: , wait: nil, timeout: 5, log: Tempfile.new("log"), out: "2>&1", allow_fail: false)
+      @command = command
+      @name    = name
+      @wait    = wait
+      @allow_fail = allow_fail
+
+      @spawn = ProcessSpawn.new(
+        @command,
+        timeout: timeout,
+        log:     log,
+        out:     out
+      )
+      ProcessSpawn.add(@name, @spawn)
+    end
+
+    def to_md(env = {})
+      return "$ #{@command}"
+    end
+
+    def call(env = {})
+      @spawn.wait(@wait)
+      @spawn.check_alive! unless @allow_fail
+      @spawn.log.read
+    end
+
+    def alive?
+      !!@spawn.alive?
+    end
+  end
+end
+
+Rundoc.register_code_command(:"background.start", Rundoc::CodeCommand::Background::Start)