mysh 0.2.7 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bceb539dd8a9fe46587018141691e37cbb6b71fa
-  data.tar.gz: cb7f62b68e30efe7589670f14a3bbeab072aca64
+  metadata.gz: e859f5e9fd3f2d6d4e88de719444088195e2d1e0
+  data.tar.gz: e2eb0dacb82603274b4511a7b6f72f366230649e
 SHA512:
-  metadata.gz: af00b483a5f61b429b70dbd843660e17c6176b10b2172abb749b1ca4432299954e2ac818b6b99c3a0158874e17ee038f9203e0b5db888174c27c1629f3d9c843
-  data.tar.gz: 2707296e56b968dc1495e1ba11e476ed6aa5463561bded59eda61de83dfb022aa006dced3ab7665216cb2ac0ace3fa90ae886c882ba303604b52d6bc07abc1d7
+  metadata.gz: 09493f5a93d52dbe8812cbf01c7cf3418fb0f2c627935f258b86b4819ee874ce986453eb5a43c98b67da911fc95ee39062dde4795c1d2fe4db86b394702c21cf
+  data.tar.gz: abde27a389011b5175a46579c5878a4e514a6906d178893df5623f9df4cbbbecf1b496e3acf315ca0bf661d1299c6b89683075863437ad81d458ee84b174c7ef

data/README.md

@@ -8,26 +8,23 @@ Inspired by the excellent article "Writing a Shell in 25 Lines of Ruby Code"
 I thought it would be fun to experiment with that concept and see if it could
 be taken further.
 
-Many years ago, a popular shell program was modeled after
-the 'C' programming language. It went by the name csh for C-shell (by the C
-shore :-) Instead of 'C', my shell would be based on Ruby (were you shocked?)!
-The obvious name rsh for Ruby-shell was already in use by the Remote-shell. So,
-given the limited scope of this effort, and not wanting to do a lot of typing
-all the time, I chose the name mysh for MY-SHell.
+Many years ago, a popular shell program was modeled after the 'C' programming
+language. It went by the name csh for C-shell (by the C shore :-) Instead of
+'C', my shell would be based on Ruby (were you shocked?)! The obvious name rsh
+for Ruby-shell was already in use by the Remote-shell. So, given the limited
+scope of this effort, and not wanting to do a lot of typing all the time, I
+chose the name mysh for MY-SHell.
 
 Since that name was available, it would seem that no one had yet written a
 shell program at this level of narcissism.
 
 The mysh is available as both a stand-alone CLI program and for use as a
-command shell within Ruby applications and (eventually) Rails web sites.
+command shell within Ruby applications and (maybe? eventually? someday?) Rails
+web sites.
 
 See the original article at:
 (http://www.blackbytes.info/2016/07/writing-a-shell-in-ruby/)
 
-By the way. The briefest look at the code will reveal that mysh has grown to be
-way more than 25 lines long. As Thomas Edison once said: 1% inspiration, 99%
-perspiration. Enjoy!
-
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -46,33 +43,304 @@ Or install it yourself as:
 
 ## Usage
 
-The mysh gem includes a simple executable called mysh. Command entry is a
-typical cli. For more information, see the mini_readline gem at
-( https://github.com/PeterCamilleri/mini_readline )
+The mysh gem includes a simple executable called mysh. The template for running
+the mysh is:
+
+```
+mysh <args>
+```
+
+Where args are currently a work in progress and not available at this time.
 
-When running mysh, the user is presented with a command prompt:
+When mysh is run, the user is presented with a command prompt:
 
 ```
 $ mysh
+/cygdrive/c/Sites/mysh
 mysh>
+
+```
+Now the user (that's you) may enter commands that hopefully increase the level
+of awesome coolness in the known universe. Entropy does not take vacations so
+hop to it! :-)
+
+###REPL
+
+Now for a little more detail. The mysh program is built around a design pattern
+called REPL. This stands for Read Eval Print and Loop and is used in may
+utilities like irb, pry and the rails console. To better use mysh, it is good
+to understand each of these four operating steps.
+
+####READ
+
+The first step is just to get input from the user. For interactive sessions
+this is done using the mini_readline gem. The user is prompted and input is
+obtained. There is a twist here. Just what constitutes a unit of input?
+Normally an input is one line entered by the user. Like this:
+
+```
+mysh> ls *.rb
+```
+In mysh, the user is able to chain together multiple lines and have them
+treated as a single input. So for the following scenario:
 ```
+mysh>line one\
+mysh\line two\
+mysh\line three
+```
+The input string will be:
+```
+"line one\nline two\nline three\n"
+```
+Note that while the prompt is user configurable, it will always end with '>'
+for the initial line and '\\' for subsequent lines.
+
+For more information about the mini_readline gem please see
+https://github.com/PeterCamilleri/mini_readline or
+https://rubygems.org/gems/mini_readline
+
+####EVAL
+
+Once input has been obtained from the user, that input is then evaluated. This
+evaluation has two phases: pre-processing and processing.
+
+#####Input Preprocessing
+
+During pre-processing, the input is scanned for macro-like substitutions that
+have been placed into the input. There are three steps to this phase:
+
+1. Replacing mysh variables with their values. This process is recursive in
+that these variables also undergo the full pre-processing treatment before
+being inserted into the user command.
+2. Replacing embedded ruby "handlebars" with the results of their execution.
+3. Replacing '\\{' and '\\}' with '{' and '}' respectively.
+
+#####Command Processing
+
+Once input has been obtained and massaged adequately, it's time to actually
+do some work. In mysh there is a hierarchy of four types of commands. These
+command types serve as a simple command path for determining what action is to
+be taken for the input. The four types are:
+
+1. Quick Commands - These commands are recognized by having a signature first
+character in the input. These signature characters are:
+  * ! to access the mysh command history buffer. For more information see
+  Command History below.
+  * $ to access or update mysh variables. For more information see Shell
+  Variables below.
+  * = to evaluate an expression of Ruby code. For more information see Ruby
+  Expressions below.
+  * ? to access the mysh help subsystem. For more information see Shell Help
+  below.
+  * @ to get information about the system, its environment, and the ruby
+  installation. For more information see Shell Info below.
+
+2. Internal Commands - These commands are recognized by having the first word
+in the input match a word stored in an internal hash of command actions. For
+more information see Interanl Commands below.
+3. External Ruby Commands - These commands are recognized by having the first
+word in the input have the extension (*.rb) of a ruby source file. For more
+information see External Ruby Commands below.
+4. External Commands - Any command not matching any of the above is sent to the
+system shell for execution. For more information see External Commands below.
+
+Notes:
+* The recursive pre-processing steps have checks on them to detect loops and
+other forms of bad behavior before they do nasty things like blow up the stack.
+* The mysh variables are also used to control many aspects of the mysh and are
+covered in their own section below.
+* The embedded ruby "handlebars" also get their own section below.
+
+####PRINT
+
+Once the command is run, some results are expected most of the time. For Ruby
+expressions, this is handled by the pretty print gem. The 'pp' function is
+given the value returned by the expression just evaluated. For other types
+of command, the command itself generates any required output.
+
+To assist in the creation of well formatted output, the mysh environment
+provides a number of "helper" methods in the Array and String classes. These
+are:
+
+* String#decorate - given a string with a file path/name value, express that
+string in a manner compatible with the current operating environment.
+* Array#format_mysh_columns - take an array and convert it to a string with nice
+regular columns.
+* Array#puts_mysh_columns - as above, but print the string.
+* Array#format_mysh_bullets - take an array and convert it to a string with nice
+bullet points. The appearance of each point depends on its structure. See below:
+* Array#puts_mysh_bullets - as above, but print the string.
+
+This must all be confusing. Some examples may help:
+
+```
+mysh>=puts "lib/mysh/expression/lineage.rb".decorate
+lib\mysh\expression\lineage.rb
+
+mysh>=(1..100).to_a.puts_mysh_columns
+1 5 9  13 17 21 25 29 33 37 41 45 49 53 57 61 65 69 73 77 81 85 89 93 97
+2 6 10 14 18 22 26 30 34 38 42 46 50 54 58 62 66 70 74 78 82 86 90 94 98
+3 7 11 15 19 23 27 31 35 39 43 47 51 55 59 63 67 71 75 79 83 87 91 95 99
+4 8 12 16 20 24 28 32 36 40 44 48 52 56 60 64 68 72 76 80 84 88 92 96 100
+
+mysh>=["foo", "bar "*30, "some "*25, "stuff"].puts_mysh_bullets
+* foo
+* bar bar bar bar bar bar bar bar bar bar bar bar bar bar bar bar bar bar bar
+  bar bar bar bar bar bar bar bar bar bar bar
+* some some some some some some some some some some some some some some some
+  some some some some some some some some some some
+* stuff
+
+mysh>=[["foo", "bar "*20], ["sna", "foo young "*10 ] ].puts_mysh_bullets
+foo bar bar bar bar bar bar bar bar bar bar bar bar bar bar bar bar bar bar
+    bar bar
+sna foo young foo young foo young foo young foo young foo young foo young foo
+    young foo young foo young
+
+mysh>=[["foo", 1,2,3]].puts_mysh_bullets
+foo 1
+    2
+    3
+
+mysh>=[[(1..100).to_a]].puts_mysh_bullets
+* 1 5 9  13 17 21 25 29 33 37 41 45 49 53 57 61 65 69 73 77 81 85 89 93 97
+  2 6 10 14 18 22 26 30 34 38 42 46 50 54 58 62 66 70 74 78 82 86 90 94 98
+  3 7 11 15 19 23 27 31 35 39 43 47 51 55 59 63 67 71 75 79 83 87 91 95 99
+  4 8 12 16 20 24 28 32 36 40 44 48 52 56 60 64 68 72 76 80 84 88 92 96 100
+
+mysh>=[["foo", (1..100).to_a], ["baz", "yes"]].puts_mysh_bullets
+foo 1 5 9  13 17 21 25 29 33 37 41 45 49 53 57 61 65 69 73 77 81 85 89 93 97
+    2 6 10 14 18 22 26 30 34 38 42 46 50 54 58 62 66 70 74 78 82 86 90 94 98
+    3 7 11 15 19 23 27 31 35 39 43 47 51 55 59 63 67 71 75 79 83 87 91 95 99
+    4 8 12 16 20 24 28 32 36 40 44 48 52 56 60 64 68 72 76 80 84 88 92 96 100
+baz yes
+
+```
+
+
+####LOOP
+
+The processing of input continues (looping) until it doesn't. This occurs when
+a command to stop looping is entered or the mini_readline gem signals
+end-of-input condition. The commands that do this are:
+
+* exit - exit the current mysh level.
+* quit - terminate the mysh program.
+
+Work-in-progress - mysh only has one level at this time so these two commands
+do exactly the same thing... for now!
+
+An end-of-input condition is signaled by the user by entering Ctrl-z (in
+windows) or Alt-z (in Linux/Mac). See the mini_readline gem (link above) for
+more information on the keyboard mappings used by mysh.
+
+### Handlebars
+
+In mysh, it is possible to embed snippets of ruby into text files, in shell
+variables or on the command line through the use of handlebars. Handlebars
+look like this:
+
+    {{ code goes here  }}
+
+Lets see a simple example of putting the result of a calculation into the
+command line:
+
+    mysh>echo {{ (1..10).map {|i| i.to_s}.join(" ") }}  > foo.txt
+    mysh>type foo.txt
+    1 2 3 4 5 6 7 8 9 10
+
+Handlebars work by evaluating the ruby code within the {{  }} sequence in
+the appropriate execution environment. For the command line, this is the same
+environment used for the '=' quick execution command. For example:
 
-Then start entering some commands! This prompt can be used to execute four
-sorts of commands:
+    mysh>=a="A very long string indeed!"
+    "A very long string indeed!"
+    mysh>echo {{ a }}
+    A very long string indeed!
 
-* Ruby expressions, which are preceded by the equal (=) sign.
-* Internal commands that are processed directly by mysh
-* External ruby source files that are passed on to the Ruby interpreter.
-* External commands that are passed on to the standard command shell.
+The value returned by expression is coverted to a string (if needed) and then
+inserted in place of the handlebar expression. There are, however, times when
+it is not desired to insert anything in the place of the code snippet. For
+those cases, simply end the expression with a '#' character. For example:
 
-#### Ruby expressions:
+    mysh>echo {{ "not embedded" #}}{{ "embedded" }}
+    embedded
+
+Finally, it may be that it is desired to embed braces into a text file or
+the command line. In that case precede the brace with a backslash character
+like: \{  or \}
+
+### Command History
+
+The history (or !) command is used to allow the user greater control over the
+history of commands that have been entered. The action taken by the history
+command is controlled by an optional parameter.
+
+If the longer form, show is used, a space is required before the parameter. If
+the quick form, ! is used, the space is optional.
+
+Quick Form | Long Form    |  Command Description
+-----------|--------------|--------------------------------
+!          | history      | Display the entire history buffer.
+!5         | history 5    | Retrieve history entry 5 and present this to the user as the next command.
+!clear     | history clear| Clear the command history.
+
+### Shell Variables
+
+In mysh, variables are kept that control the behavior of the shell. This simple
+command is used to set, delete, and display these variables. The basic method
+for setting a variable is:
+
+    $name=value
+
+Where:
+* name is a word matching the regex: /[a-z][a-z0-9_]*/. Lower case only.
+* value is a string, with embedded variables and handlebars.
+
+To erase the value of a variable, use:
+
+    $name=
+
+To display the name/value of a variable, use:
+
+    $name
+
+To display all variable names/values use:
+
+    $
+
+As an escapement, the string $$ maps to a single $.
+
+Some variables that are used in mysh are:
+
+Variable    | Description
+------------|--------------------------------------------
+$d          | The current date.
+$date_fmt   | The format for the date: "%Y-%m-%d"
+$debug      | Does the shell display additional debugging info (true/false)
+$h          | The home folder's path
+$post_prompt| The prompt used when a line is continued with a trailing \\ character.
+$pre_prompt | A prompt string displayed before the actual command prompt. Delete the pre_prompt variable to disable pre-prompting.
+$prompt     | The user prompt.
+$t          | The current time.
+$time_fmt   | The format for the time: "%H:%M"
+$u          | The current user.
+$w          | The current working directory's path.
+
+
+
+### Ruby Expressions:
+
+In mysh, ruby code may be executed at any time from command prompt. This allows
+the mysh command line to serve as a programming, debugging and super-calculator
+environment. Just a few reminders:
 
 * Any line beginning with an equals "=" sign will be evaluated as a Ruby
-  expression. This allows the mysh command line to serve as a programming,
-  debugging and super-calculator environment.
+  expression.
 * Expressions ending with a backslash character "\" are continued on the next
-  line. The prompt changes to "mysh\" to indicate that this is going on.
-* The results are displayed using the pretty-print facility.
+  line. The prompt changes to end with a "\" character to indicate that this is
+  going on.
+* The results of the expression are displayed using the pretty-print facility.
 * Auto-complete always places any file names in quotes so they can be used
   as string parameters.
 
@@ -95,14 +363,11 @@ mysh>=a.lineage
 mysh>=reset
 
 mysh>=a
-NameError: undefined local variable or method `a' for #<#<Class:0x1c57a10>:0x1c57938>
+NameError: undefined local variable or method `a' for exec_host:#<Class:0x1ba8720>
 mysh>=result
 
 mysh>
 ```
-
-
-
 The Ruby expression execution environment has direct access to many advanced
 Math functions. For example, to compute the cosine of 3.141592653589793 use:
 ```
@@ -144,72 +409,128 @@ tanh(x)    |Float |The hyperbolic tangent of x (in radians).
 E          |Float |The value e (2.718281828459045)
 PI         |Float |The value &#960; (3.141592653589793)
 
-#### Internal mysh commands:
-
-Internal commands are recognized by name and are executed by mysh directly.
+### Shell Help
 
-The following set of commands are supported:
-
-```
-!<index>        Display the mysh command history, or if an index is specified,
-                retrieve the command with that index value.
-?<topic>        Display help information for mysh with an optional topic.
-@<item>         Display information about a part of mysh. See ?@ for more.
-cd <dir>        Change directory to the optional <dir> parameter and then
-                display the current working directory.
-exit            Exit mysh.
-gls <-l> <mask> Display the loaded ruby gems. See ?gls for more.
-help <topic>    Display help information for mysh with an optional topic.
-history <index> Display the mysh command history, or if an index is specified,
-                retrieve the command with that index value.
-pwd             Display the current working directory.
-quit            Exit mysh.
-show <item>     Display information about a part of mysh. See ?@ for more.
-type            Display a text file with optional embedded handlebars.
-vls <mask>      Display the loaded modules, matching the optional mask, that
-                have version info.
-```
-Of note is the command "help help" or "??" which provides a list of all
-available help topics.
+The help (or ?) command is used to get either general help about mysh or an
+optional specified topic. If the longer form, help is used, a space is required
+before the topic. If the quick form, ? is used, the space is optional. Of note
+is the command "help help" or "??" which provides a list of all available help
+topics. These are:
+
+Topic      | Description
+-----------|----------------------------------------------------
+           | General help on mysh.
+!          | Help on the history command.
+$          | Help on mysh variables.
+=          | Help on ruby expressions.
+?          | This help on the help command.
+@          | Help on the show command.
+env        | Help on the show env command.
+gls        | Help on gls internal mysh command.
+help       | This help on the help command.
+history    | Help on the history command.
+kbd        | Help on mysh keyboard mapping.
+math       | Help on math functions.
+quick      | Help on quick commands.
+ruby       | Help on the show ruby command.
+show       | Help on the show command.
+{{         | Help on mysh handlebars.
+
+
+### Shell Info
+
+The show (or @) command is used to inspect various aspects of the mysh
+environment specified by the item parameter. If the longer form, show is used,
+a space is required before the topic. If the quick form, @ is used, the space
+is optional. Currently, mysh supports two areas on inquiry: the environment and
+ruby:
+
+##### Environment (@env)
+
+This command displays useful information about the current operating
+environment.
+
+Topic    | Description
+---------|----------------------------------------------------
+user     | The current user name.
+home     | The current home directory.
+name     | The path/name of the mysh program currently executing.
+shell    | The path/name of the system command shell.
+host     | The name of the host computer.
+os       | The current operating system.
+platform | The operating platform detected by the low-level terminal gem.
+java     | Is the current platform powered by Java?
+term     | What terminal is defined by the system, if one is defined.
+disp     | What display is defined by the system, if one is defined.
+edit     | What editor is defined by the system, if one is defined.
+path     | An easy-to-read, formatted version of the current search path.
+
+
+##### Ruby (@ruby)
+
+This command displays useful information about the currently running ruby
+language system.
+
+Topic       | Description
+------------|----------------------------------------------------
+location    | The path/name of the current ruby interpreter.
+description | A comprehensive summary of the version and other such data.
+version     | The version of ruby.
+patch       | Its patch level.
+revision    | Its revision level.
+date        | The date of its release.
+platform    | The target platform.
+copyright   | The legal ownership of the software.
+engine      | The internal engine in the software.
+host        | A summary of the host operating environment.
+host cpu    | A (crude) approximation of the installed cpu.
+host os     | The current operating system.
+host vendor | The current environment vendor/genre.
+$:          | An easy-to-read, formatted version of $: or the ruby search path.
+
+
+### Internal Shell Commands:
+
+Internal commands are recognized by name and are executed by mysh directly. The
+complete list of internal commands is given in the default help command ("?").
+Some commands, not already covered in other sections include:
+
+Command        | Description
+---------------|----------------------------------------------------
+cd {dir}       | Change directory to the optional dir parameter and then display the current working directory.
+exit           | Exit mysh.
+gls {-l} {mask}| Display the loaded ruby gems. Use optional -l for a more details and a mask to limit output.
+history {index}| Display the mysh command history, or if an index is specified, retrieve the command with that index value.
+pwd            | Display the current working directory.
+quit           | Exit mysh.
+type           | Display a text file with optional embedded handlebars.
+vls {mask}     | Display the loaded modules, matching the optional mask, that have version info.
+
+### External Ruby Commands
+
+Any command that ends with a ".rb" extension will be sent as the target of the
+ruby interpreter. So for example, let's run the test.rb file located in the
+samples folder:
 
 ```
-Help: mysh help command summary:
-
-The help (or ?) command is used to get either general help about mysh or an
-optional specified topic.
-
-If the longer form, help is used, a space is required before the topic. If the
-quick form, ? is used, the space is optional.
-
-The available help topics are:
-
-        General help on mysh.
-!       This help on the history command.
-=       Help on ruby expressions.
-?       This help on the help command.
-@       Help on the show command.
-env     Help on the show env command.
-gls     Help on gls internal mysh command.
-help    This help on the help command.
-history This help on the history command.
-kbd     Help on mysh keyboard mapping.
-math    Help on math functions.
-quick   Help on quick commands.
-ruby    Help on the show ruby command.
-show    Help on the show command.
-{{      Help on mysh handlebars.
+mysh>$debug = on
+mysh>samples/test.rb 1 2 $d $t
+=> samples/test.rb 1 2 2016-12-21 13:43
+=> C:/RailsInstaller/Ruby2.1.0/bin/ruby.exe samples/test.rb 1 2 2016-12-21 13:43
+Running sample file.
+args = ["1", "2", "2016-12-21", "13:43"]
+mysh>
 ```
 
-#### External commands:
+### External Commands:
 
 All other commands are executed by the system using the standard shell or
-the appropriate ruby interpreter.
+the appropriate ruby interpreter. In effect, the system method is the action of
+last resort for mysh commands.
 
 Notes:
 * If an internal command has the same name as an external command, adding a
   leading space will force the use of the external command.
-* If the command has a '.rb' extension, it is executed by the appropriate ruby
-  interpreter. The interpreter used is the one specified by RbConfig.ruby
 
 ## Embedding mysh in an application.
 
@@ -218,7 +539,7 @@ The mysh can also be used from within a Ruby application:
 ```ruby
 require "mysh"
 
-#Some stuff omitted.
+#Some application stuff omitted.
 
 Mysh.run
 ```
@@ -245,7 +566,6 @@ module Mysh
     def call(args)
     end
 
-
   end
 
   desc = "A succinct description of what this command does."