From c729916f9dba44300361337847d1dd0b99265fd7 Mon Sep 17 00:00:00 2001 From: Bill Niblock Date: Sat, 6 May 2017 17:34:19 -0400 Subject: [PATCH] Start using Yard - Add yard to Gemfile - Configure .yardopts to pull in proper files - Update custom docs to include yard metadata --- .yardopts | 9 +++ README.md | 5 ++ docs/config_file.md | 5 ++ docs/config_file_example.md | 42 +++++++++++++ docs/config_file_example.yaml | 1 + docs/editor.md | 4 ++ lib/sapling.rb | 107 +++++++++++++++++----------------- 7 files changed, 121 insertions(+), 52 deletions(-) create mode 100644 .yardopts create mode 100644 docs/config_file_example.md diff --git a/.yardopts b/.yardopts new file mode 100644 index 0000000..6ccae4b --- /dev/null +++ b/.yardopts @@ -0,0 +1,9 @@ +--title "Sapling Documentation" +- +README.md +docs/config_file.md +docs/config_file_example.md +docs/editor.md +CONTRIBUTING.md +LICENSE +lib/**.*.rb diff --git a/README.md b/README.md index 7009c49..af8be4b 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,8 @@ + + # Sapling: A Dialogue Tree CLI Utility Sapling allows for easy creation and use of dialogue trees. diff --git a/docs/config_file.md b/docs/config_file.md index d0ad949..bc72f3a 100644 --- a/docs/config_file.md +++ b/docs/config_file.md @@ -1,3 +1,8 @@ + + # Configuration File Documentation The configuration file for `sapling` is a standard YAML file. The general diff --git a/docs/config_file_example.md b/docs/config_file_example.md new file mode 100644 index 0000000..8a9acdd --- /dev/null +++ b/docs/config_file_example.md @@ -0,0 +1,42 @@ + +# Example Dialogue Tree + --- + # The trunk is a general introduction to the tree. It shouldn't include any + # thematic details, rather a one-liner to let the user know what they're getting + # into. + - + trunk: "This is a general introduction to the dialogue tree." + + # Branches are the content of a dialogue tree. Each branch is numbered, and that + # number is used as the primary means of navigation. The text of a branch is the + # story provided to the user; the result of getting to the branch. The leaves + # (the section titled leaf) represent the options. Options are displayed in the + # order they appear. Within a leaf, the text is what the option says, and the + # branch is the branch number which this option will lead to. Leading to branch + # number 0 will immediately exit the program. + # + # You can have as many branches and leaves as you wish, though having too many + # leaves may lead to both display problems, and paralyzing indecision. + - + branch: + number: 1 + text: "The first branch. Displayed first, by default." + leaf: + - + text: "The first option for this branch. It leads to branch 2" + branch: 2 + - + text: "The second branch. It immediately exits the program." + branch: 0 + + # A terminal branch is a branch which has no leaves. This represents an ending. + # Once a user hits a terminal branch, the program will display the branch text, + # and then redirect the user to branch 0, to exit. + - + branch: + number: 2 + text: "This is a terminal branch. After displaying this text, + the program will exit." diff --git a/docs/config_file_example.yaml b/docs/config_file_example.yaml index 03a1ce2..1a6551e 100644 --- a/docs/config_file_example.yaml +++ b/docs/config_file_example.yaml @@ -1,3 +1,4 @@ +# @title Example YAML File --- # The trunk is a general introduction to the tree. It shouldn't include any # thematic details, rather a one-liner to let the user know what they're getting diff --git a/docs/editor.md b/docs/editor.md index 29fe5d9..5b4106e 100644 --- a/docs/editor.md +++ b/docs/editor.md @@ -1,3 +1,7 @@ + # Sapling Editor Sapling provides an editor for creating and modifying dialogue trees. The editor diff --git a/lib/sapling.rb b/lib/sapling.rb index fdb28ca..a7348dc 100644 --- a/lib/sapling.rb +++ b/lib/sapling.rb @@ -9,7 +9,7 @@ module Gardner # Parse the branch # # @param tree [Array] The dialogue tree - # @return branches [Array] The array of options on the branch. + # @return [Array] The array of options on the branch. def self.prune_branches(tree) branches = { 0 => { "desc" => "Thanks for using Sapling!" } } tree.each do |b| @@ -25,7 +25,7 @@ module Gardner # Parse the options # # @param leaves [Array] The option of leaf hashes - # @return options [Hash] A has of options + # @return [Hash] A has of options def self.prune_leaves(leaves) x = 1 options = {} @@ -45,7 +45,7 @@ module Gardner # The trunk is like the introduction to the tree. # # @param tree [Hash] The entire tree - # @return tree [Hash] The tree without the trunk + # @return [Hash] The tree without the trunk def self.prune_trunk(tree) trunk = tree.shift puts "Welcome to Sapling, a Dialogue Tree Utility.\n" @@ -61,7 +61,7 @@ module Gardner # The main method for Sapling. From here, the tree is grown. # # @param file [File] The dialogue tree file - # @return branches [Hash] The final, constructed data set + # @return [Hash] The final, constructed data set def self.grow(file) tree = YAML.load_file(file[0]) tree = Gardner.prune_trunk(tree) @@ -73,7 +73,7 @@ module Gardner # Verify that a file is a dialogue tree file. # # @param file [File] The provided file - # @return status [Boolean] True if the file is a tree; false otherwise + # @return [Boolean] True if the file is a tree; false otherwise def self.verify_tree(file) results = [] begin @@ -97,7 +97,10 @@ end # Dialogue is the module for traversing an existing tree. module Dialogue + # Spealer holds the functionality for viewing and going through a dialogue + # tree. class Speaker + # The file, which should be a dialogue tree YAML file. attr_accessor :file def initialize @@ -106,7 +109,6 @@ module Dialogue # Conversation handles navigating the tree, until the option to end is # reached. - # def conversation() tree = Gardner.grow(@file) @@ -123,7 +125,7 @@ module Dialogue # Talk displays a branch, the options, and prompts for a response # # @param branch [Hash] A branch data set - # @return response [Integer] The number of the next branch + # @return [Integer] The number of the next branch def talk(branch) # If there are no options on this branch, we assume it's a terminal # branch. Return 0, and end the program. @@ -165,56 +167,57 @@ module Planter end -# Parsing is the class for option parsing, and the gateway to the program -class Parsing +# Sapling is the main module for the program. From here, the rest of the world +# starts building. +module Sapling - # Option parsing, and gateway to either reading and traversing a tree, or - # editing/creating a tree. - # - # @params file [String] The location of the file to read, or write. - def talk(options) - opt_parser = OptionParser.new do |opt| - opt.banner = "Usage: sapling -t FILE\n" \ - "Usage: sapling -e [FILE]" + # CLI is the class for option parsing, and the gateway to the program + class CLI - opt.on_tail("-h", "--help", "Show this menu") do - puts opt + # Option parsing, and gateway to either reading and traversing a tree, or + # editing/creating a tree. + def talk(options) + opt_parser = OptionParser.new do |opt| + opt.banner = "Usage: sapling -t FILE\n" \ + "Usage: sapling -e [FILE]" + + opt.on_tail("-h", "--help", "Show this menu") do + puts opt + exit + end + + opt.on("-t", "--talk", + "Begin traversing the provided dialogue tree") do + + if ARGV.empty? + puts opt_parser + exit + end + + unless Gardner.verify_tree(ARGV[0]) + puts "\n#{opt}\n" + exit + end + + speaker = Dialogue::Speaker.new + speaker.file = ARGV + speaker.conversation + end + + opt.on("-e", "--edit", + "Create or edit a dialogue tree") do + puts "We gonna make a tree!" + end + + end + opt_parser.parse!(options) + + if ARGV.empty? + puts opt_parser exit end - - opt.on("-t", "--talk", - "Begin traversing the provided dialogue tree") do - - if ARGV.empty? - puts opt_parser - exit - end - - unless Gardner.verify_tree(ARGV[0]) - puts "\n#{opt}\n" - exit - end - - speaker = Dialogue::Speaker.new - speaker.file = ARGV - speaker.conversation - end - - opt.on("-e", "--edit", - "Create or edit a dialogue tree") do - puts "We gonna make a tree!" - end - end - opt_parser.parse!(options) - - if ARGV.empty? - puts opt_parser - exit - end - end - end -Parsing.new.talk(ARGV) +Sapling::CLI.new.talk(ARGV)