general 1.5.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ae2513790cf50098833adabdd311b9bbecc9409d
-  data.tar.gz: a120cf500bc65f1853c240749ecf2f5a048b144c
+  metadata.gz: 8cd60835b374d4c4eae5d1a8b0c38eaea4032189
+  data.tar.gz: a37a61c98244f3927208539dcf5da0994ceabc35
 SHA512:
-  metadata.gz: 651d42923d42e35fdb6e8ddf4fae1080f668c24bbffd85b6abd70f4bd9f6f7e91862437266625d447c9edebb6ca93b80091eacc910db66ed13e5993468c828e1
-  data.tar.gz: a283344e7695397591087313ab9f29f54c92bd50653333e49a1467e5744ef8384bda3076aca2ab04ba714e17550dd7e246085d497a5530b110035e167d7fe48d
+  metadata.gz: ef5ce9c1ed0d2f1e02418b46e54c2ddea1af940ca7d461f846b423aa19eaa064c2dbb16393c1982caf7293cffdeee635562678472cdef14f38b67bf18ac02bd4
+  data.tar.gz: 1850598692f1c631661f912fc86e30a300d1883c23fc575474a817b2ca6e9905f96c43314959c1961d2709d5a3f6690761e2dfecc935e9e5e5a411055234a00c

data/README.md

@@ -1,13 +1,28 @@
 # General
 
-## Overview
+	Hello, I am @(name: gordon ramsay -> capitalize all) and I like @(food: cat food)!
 
 General is a simple templating system in ruby that allows you to create templates from both pure strings and files (with the extension .general), as well as create new strings and files with these created objects.
 
+## Table of Contents
+
+- [General Templates](#general-templates)
+	- [Basic Templates](#basic-templates)
+	- [Array Templates](#array-templates)
+	- [Placeholder Operations](#placeholder-operations)
+		- [To-Array Operations](#to-array-operations)
+- [General Time Format](#general-time-format)
+- [General IO](#general-io)
+	- [PrePartials](#prepartials)
+		- [Including Other Templates](#including-other-templates)
+		- [Extending Templates](#extending-templates)
+
 ## General Templates
 
 ### Basic Templates
 
+	"Hello, I am @(name: Gordon Ramsay) and I like @(food: cat food)!"
+
 A general template consists of regular text along with placeholders, which are defined as follows: `@(-name-)`. You can also specify default text as well like so: `@(-name-: -default text-)`.
 
 Here's an exmple of a general template text: `"Hello, I am @(name: Gordon Ramsay) and I like @(food: cat food)!"`
@@ -45,23 +60,13 @@ array = template.apply_all [{name: "Joe", food: "Joe Schmoes"}, {name: "Jane", f
 #   - Hello, I am Denny and I like Denny's Fennies
 ```
 
-### Placeholder Operations
-
-You can also specify operations to be performed on values passed to placeholders, akin to AngularJS's filters. For example: `@(name -> capitalize)` will capitalize whatever name is inputted before applying it to the text.
-
-The current placeholder operations are:
-
-| Operation  |                       Description                       |
-|:-----------|:--------------------------------------------------------|
-| capitalize | Capitalizes the first letter of each word in a string   |
-| uppercase  | Makes every letter in a string uppercase                |
-| lowercase  | Makes every letter in a string lowercase                |
-| dollars    | Formats an integer money amount (in cents) to dollars   |
-| time       | Formats an integer time (in seconds) to HH:MM:SS format |
-
 ### Array Templates
 
-You can also make array templates within templates, which will format each value in an array of data according to a general template
+	@[people]
+		Hello, @(name)! How's the @(pet)?
+	@[\n]
+
+Array templates will format each value in an array of data according to a general template
 
 A general array template is as follows: `@[-name-] -general template for each value- @[]`. You can also specify the delimeter, which will be appended to the end of each element. The delimeter should be added in the end tag, like so: `@[-name-] -general template for each value- @[-delimeter-]`. If no delimeter is given, the default is a space. The start and end tags are invariant with atleast 1 whitespace or newline. So you can also define the template like such: 
 
@@ -99,18 +104,82 @@ string = template.apply crew: [
 #		Michael Caine: Alfred Pennyworth"
 ```
 
+### Placeholder Operations
+
+	@(name -> capitalize all)
+
+You can also specify operations to be performed on values passed to placeholders, akin to AngularJS's filters. For example: `@(name -> capitalize)` will capitalize whatever name is inputted before applying it to the text. Placeholder operations also have arguments, which change behaviour. `@(name -> capitalize first)` will capitalize the first word of name, whereas `@(name -> capitalize all)` will capitalize all words in the name.
+
+- capitalize: capitalizes the string
+	- Argument 1:
+		- 'first': only first word is capitalized
+		- 'all': all words are capitalized
+		- default: 'first'
+- uppercase: converts a string to uppercase
+- lowercase: converts a string to lowercase
+- money: converts an integer to a monetary amount in the given format
+	- Argument 1:
+		- 'USD': United States Dollar
+		- 'EUR': European Euro
+		- default: 'USD'
+- time: converts an integer to a formatted time in the given time format
+	- Argument 1:
+		- Time format to set to
+		- default: '@I:@MM:@SS @A'
+
+#### To-Array Operations
+
+	@[groceries -> split]
+		I need to get some @#!
+	@[\n].
+
+Certain operations can convert data values to arrays to be used by an array template. These can be applied to array placeholders as follows `@[text -> split] -general- @[].` These return pure data values, and they can be accessed by a special placeholder `@#` which applies the entire data value as is.
+
+```ruby
+template = General::GTemplate.new "@[text -> split] -> @# @[\n]"
+string = template.apply text: "Good Afternoon World
+I am Chef Gordon Ramsay"
+
+# string now equals
+# "-> Good Afternoon World
+# -> I am Chef Gordon Ramsay"
+```
+
+- split: splits a string based on a given delimeter
+	- Argument 1:
+		- The delimeter regex to split the string by
+		- default: \r?\n
+- splitwords: splits a string at a given number of words
+	- Argument 1:
+		- The words at which to split the string
+		- default: 10
+
+## General Time Format
+
+General offers a separate special template called a GTimeFormat used for formatting times. The GTimeFormat syntax is also used by the time operation. 
+
+Time format placeholders are written as an @ followed by one or more characters of the same letter: `@LL...` (except for `@A`) The letter indicates the part of time information to format and the number of letters indicates the number of zeros.
+
+| Letter |       Description       |
+|:-------|:------------------------|
+| @H...  | Hour (0 to 23)          |
+| @I...  | Time interval (1 to 12) |
+| @M...  | Minutes (0 to 59)       |
+| @S...  | Seconds (0 to 59)       |
+| @A     | AM/PM                   |
+
 ## General IO
 
-You can also write to files using io GIO, a general template capable of writing to files. You can create a GIO like a GTemplate:
+You can also write to files using GIO, a general template capable of writing to files. You can create a GIO like a GTemplate:
 
 ```ruby
 gio = General::GIO.new "Hello, I am @(name: Gordon Ramsay) and I like @(food: cat food)!"
 ```
 
-You can also load a GIO from a file. For example, here's how you create a template file from the file "example.txt.general"
+You can also load a GIO from a file. For example, here's how you create a template file from the file "example.general"
 
 ```ruby
-gio = General::GFile.load "example.txt.general"
+gio = General::GFile.load "example.general"
 ```
 
 To write to a file, simply call the write method, pass in the file and the data to apply (like in GTemplate#apply):
@@ -128,8 +197,85 @@ gio.write "example.txt", name: "Joe", food: "Joe's Schmoes"
 To get the original source filename of the GIO, just call `source`
 
 ```ruby
-gio.source # == "example.txt.general"
+gio.source # == "example.general"
 ```
 
+### PrePartials
+
+	@@extend basic_layout
+	@@include header
+
+	<p>I am a subtemplate! My name is @(name -> capitalize all)</p>
+
+PrePartials are parsed before the general template is parsed, and perform file template manipulation like including or extending another template.
+
+#### Including Other Templates
+
+File to include
+
+	@(title)
+	@(author)
+	@(subject)
+	@(date)
+
+Including file
+
+	@@include file
+
+	@(content)
+
+Resulting File
+
+	@(title)
+	@(author)
+	@(subject)
+	@(date)
+
+	@(content)
+
+To include another template file in your file, you use `@@include [name of template]` (excluding the suffix). This will read the corresponding template file and append the content in place of the `@@include`.
+
+NOTE: `@@include` requires a new line or carriage return to be parsed (it takes up one entire line). It also appends a newline at the end of the included template.
+
+#### Extending Templates
+
+File to Extend
+	
+	<!doctype html>
+	<html>
+	<title>@(title -> capitalize all)</title>
+	<body>
+	@@yield
+	</body>
+	</html>
+
+Extending File
+
+	@@extend file
+
+	<h1>@(name)'s Profile!</h1>
+	<p>Favorite Color: @(color)</p>
+	<p>Favorite Sport: @(sport)</p>
+
+Resulting File
+
+	<!doctype html>
+	<html>
+	<title>@(title -> capitalize all)</title>
+	<body>
+	<h1>@(name)'s Profile!</h1>
+	<p>Favorite Color: @(color)</p>
+	<p>Favorite Sport: @(sport)</p>
+	</body>
+	</html>
+
+Extending a file wraps the contents of the file around the current template. This is good when many templates will share a single common layout. Extend prepartials are as follows `@@extend [name of template]` (also excluding extension). The `@@extend` must be defined at the beginning of the template, and there can be only one `@@extend` in any template.
+
+The extending file should define a `@@yield` where the file will be extended from. This is by default at the end of the file. Note that if `@@yield` is defined in a template, the template is considered a meta-template and cannot be parsed. Also, like extend, only one `@@yield` statement can be defined in a single file.
+
+## Notes
+
+Regex and matching have now been officially depricated, and will be removed in General 2.1.0.
+
 -------------------------------------------------------------------------------------------------------------------------------------
 Anshul Kharbanda

data/Rakefile

@@ -44,9 +44,18 @@ namespace :git do
 		sh "git commit -m #{args[:message].inspect}"
 	end
 
+	desc "Ammend recent commit"
+	task :ammend, [:messave] do |task, args|
+		sh "git commit --ammend"
+	end
+
 	desc "Soft git reset"
-	task :reset do sh "git reset" end
+	task :reset do
+		sh "git reset"
+	end
 
 	desc "Hard git reset"
-	task :reset_hard do sh "git reset --hard HEAD" end
+	task :hardreset do
+		sh "git reset --hard HEAD"
+	end
 end

data/exp/expected/applied1.txt

@@ -0,0 +1 @@
+There once was a chef named Joe, and he loved eating Joe's Schmoes. He went to Kentucky.

data/exp/expected/applied2.txt

@@ -0,0 +1,3 @@
+There once was a chef named Joe, and he loved eating Joe's Schmoes. He went to Kentucky.
+
+Joe drove to the store to get some Joe's Schmoes.

data/exp/expected/applied3.txt

@@ -0,0 +1,9 @@
+General Super Layout
+
+Open
+
+There once was a chef named Joe, and he loved eating Joe's Schmoes. He went to Kentucky.
+
+Joe went to china to eat some crickets.
+
+Close

data/exp/expected/default1.txt

@@ -0,0 +1 @@
+There once was a chef named Gordon Ramsay, and he loved eating carrots. He went to Virginia.

data/exp/expected/default2.txt

@@ -0,0 +1,3 @@
+There once was a chef named Gordon Ramsay, and he loved eating carrots. He went to Virginia.
+
+Gordon Ramsay drove to the store to get some carrots.

data/exp/expected/default3.txt

@@ -0,0 +1,9 @@
+General Super Layout
+
+Open
+
+There once was a chef named Gordon Ramsay, and he loved eating carrots. He went to Virginia.
+
+Gordon Ramsay went to china to eat some crickets.
+
+Close

data/exp/out/sample1.txt

@@ -0,0 +1 @@
+There once was a chef named Joe, and he loved eating Joe's Schmoes. He went to Kentucky.

data/exp/out/sample2.txt

@@ -0,0 +1,3 @@
+There once was a chef named Joe, and he loved eating Joe's Schmoes. He went to Kentucky.
+
+Joe drove to the store to get some Joe's Schmoes.

data/exp/out/sample3.txt

@@ -0,0 +1,9 @@
+General Super Layout
+
+Open
+
+There once was a chef named Joe, and he loved eating Joe's Schmoes. He went to Kentucky.
+
+Joe went to china to eat some crickets.
+
+Close

data/exp/templates/sample0.general

@@ -0,0 +1,7 @@
+General Super Layout
+
+Open
+
+@@yield
+
+Close

data/exp/templates/sample1.general

@@ -0,0 +1 @@
+There once was a chef named @(name: gordon ramsay -> capitalize all), and he loved eating @(food: carrots). He went to @(place -> capitalize).

data/exp/templates/sample2.general

@@ -0,0 +1,3 @@
+@@include sample1
+
+@(name -> capitalize all) drove to the store to get some @(food).

data/exp/templates/sample3.general

@@ -0,0 +1,4 @@
+@@extend sample0
+@@include sample1
+
+@(name -> capitalize all) went to china to eat some @(exotic_food: crickets).

data/exp/templates/sampleE0.general

@@ -0,0 +1,7 @@
+This should not work
+
+@@yield
+
+Because it has two yields!
+
+@@yield

data/exp/templates/sampleE1.general

@@ -0,0 +1,3 @@
+@@extend sampleE0
+
+WOA! HOW DID THIS HAPPEN!

data/exp/templates/sampleE2.general

@@ -0,0 +1,3 @@
+This one has the extend in the wrong place!
+
+@@extend sample0

data/exp/templates/sampleE3.general

@@ -0,0 +1,7 @@
+@@extend sample0
+
+And this one has TWO Extends!
+
+@@extend sampleE0
+
+What is haaaapening????

data/lib/general.rb

@@ -14,6 +14,6 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-require_relative "template/gtemplate"
-require_relative "template/gtimeformat"
-require_relative "template/gio"
+require_relative "gtemplates/gtemplate"
+require_relative "gtemplates/gtimeformat"
+require_relative "gtemplates/gio"

data/lib/gerror.rb

@@ -0,0 +1,33 @@
+# General is a templating system in ruby
+# Copyright (C) 2016  Anshul Kharbanda
+# 
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+# General is a templating system in ruby
+#
+# Author: Anshul Kharbanda
+# Created: 3 - 4 - 2016
+module General
+	# Base class for errors in General
+	#
+	# Author:  Anshul Kharbanda
+	# Created: 1 - 21 - 2017
+	class GError < StandardError; end
+
+	# A General Operation Error
+	#
+	# Author:  Anshul Kharbanda
+	# Created: 1 - 21 - 2017
+	class GOperationError < GError; end
+end

data/lib/goperations.rb

@@ -14,7 +14,8 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-require_relative "templates/gtimeformat"
+require_relative "gtemplates/gtimeformat"
+require_relative "gerror"
 
 # General is a templating system in ruby
 #
@@ -35,6 +36,25 @@ module General
 		# The default time format
 		DEFAULT_TIME = "@I:@MM:@SS @A"
 
+		private
+
+		# Asserts that the given argument for the given operation exists and is of the given types
+		#
+		# Parameter: operation - the name of the operation
+		# Parameter: argument  - the argument being checked
+		# Parameter: types     - the allowed types for the argument
+		#
+		# Raises: GOperationError if assertion fails
+		def self.assert operation, argument, *types
+			raise GOperationError.new "Requied argument not given for operation #{operation}" if argument.nil?
+			unless types.any? { |type| argument.is_a? type }
+				raise GOperationError.new "Argument #{argument} for operation #{operation} " \
+				"must be of type(s): #{types.collect(&:to_s).join(", ")}. Got #{argument.class.name}"
+			end
+		end
+
+		public
+
 		#-----------------------------------STRING OPERATIONS------------------------------------
 
 		# Capitalizes every word in the string
@@ -42,12 +62,13 @@ module General
 		# Parameter: string - the string being capitalized
 		#
 		# Return: the capitalized string
-		def self.capitalize string, what="first"
-			assert_type string, String
+		def self.capitalize string=nil, what='first'
+			assert 'capitalize', string, String
+
 			case what
-			when "all" then string.split(' ').collect(&:capitalize).join(' ')
-			when "first" then string.capitalize
-			else raise TypeError.new "Undefined second argument for operation capitalize: #{what}"
+			when 'all' then string.split(' ').collect(&:capitalize).join(' ')
+			when 'first' then string.capitalize
+			else raise GOperationError.new "Undefined second argument for operation capitalize: #{what}"
 			end
 		end
 
@@ -56,9 +77,9 @@ module General
 		# Parameter: string - the string being uppercased
 		#
 		# Return: the uppercased string
-		def self.uppercase(string)
-			assert_type string, String
-			string.upcase
+		def self.uppercase string=nil
+			assert 'uppercase', string, String
+			return string.upcase
 		end
 
 		# Converts every letter in the string to lowercase
@@ -66,9 +87,9 @@ module General
 		# Parameter: string - the string being lowercased
 		#
 		# Return: the lowercased string
-		def self.lowercase(string)
-			assert_type string, String
-			string.downcase
+		def self.lowercase string=nil
+			assert 'lowercase', string, String
+			return string.downcase
 		end
 
 		#-----------------------------------INTEGER OPERATIONS------------------------------------
@@ -79,12 +100,13 @@ module General
 		# Parameter: type    - the type of money (defaults to USD)
 		#
 		# Return: the formatted money amount
-		def self.money integer, type="USD"
-			assert_type integer, Integer
+		def self.money integer=nil, type="USD"
+			assert 'money', integer, Integer
+
 			if MONEY_TYPES[type]
-				(integer < 0 ? "-" : "") + MONEY_TYPES[type] + (integer * 0.01).abs.to_s
+				return (integer < 0 ? "-" : "") + MONEY_TYPES[type] + (integer * 0.01).abs.to_s
 			else
-				raise TypeError.new("Money type: #{type} is not supported!")
+				raise GOperationError.new "Money type: #{type} is not supported!"
 			end
 		end
 
@@ -94,23 +116,69 @@ module General
 		# Parameter: format  - the format being used (defaults to DEFAULT_TIME)
 		#
 		# Return: the time formatted with the given formatter
-		def self.time integer, format=DEFAULT_TIME
-			assert_type integer, Integer
-			General::GTimeFormat.new(format).apply(integer)
+		def self.time integer=nil, format=DEFAULT_TIME
+			assert 'time', integer, Integer
+			return General::GTimeFormat.new(format).apply(integer)
 		end
 
-		private
+		#---------------------------------TO ARRAY OPERATIONS-----------------------------------
+
+		# Splits the string by the given delimeter (or by newline if no delimeter is given)
+		#
+		# Parameter: string    - the string to split
+		# Parameter: delimeter - the delimeter to split by (defaults to newline)
+		#
+		# Return: the array containing hashes representing the split string chunks
+		def self.split string=nil, delimeter="\r?\n"
+			assert 'split', string, String
+			return string.split(Regexp.new(delimeter))
+		end
 
-		# Raises TypeError if the given value is not one of the given types
+		# Splits a sequence by a set number of words (defaults to 10)
 		#
-		# Parameter: value - the value to check
-		# Parameter: types - the types to check for
+		# Parameter: string - the string to split
+		# Parameter: words  - the number of words to split by (defaults to 10)
 		#
-		# Raises: TypeError - if the given value is not one of the given types
-		def self.assert_type value, *types
-			unless types.any? {|type| value.is_a? type}
-				raise TypeError.new "Unexpected value type #{value.class.name}. Expected #{types.collect(&:name).join(",")}"
+		# Return: an array containing hashes representing the chunks of the string split by words
+		def self.splitwords string=nil, words=10
+			assert 'splitwords', string, String
+
+			# Convert words to integer
+			words = words.to_i
+
+			# Regex to match words
+			matcher = /\G[\w\',\.\?!\(\)\-\:\;\"\"]+\s*/
+
+			# Buffers
+			to_return = []
+			buffer    = ""
+
+			# Initialize loop
+			matched = matcher.match string
+			index   = 0
+
+			# While matched data exists
+			while matched
+				# Push line to array and reset if number of words is passed
+				if index % words == 0
+					to_return << buffer.sub(/\s+$/, "")
+					buffer = ""
+				end
+
+				# Append word to buffer
+				buffer += matched.to_s
+
+				# Trim word from string
+				string = string[matched.end(0)..-1]
+
+				# Iterate
+				matched = matcher.match string
+				index += 1
 			end
+
+			# Push final line to array and return
+			to_return << buffer
+			return to_return[1..-1] # Getting rid of the first blank line
 		end
 	end
 end