mysh 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7927b9f18a9a450e85b27f329ef62a9cc4dc212b
-  data.tar.gz: d058babe1aadabcb1b63bb5eaa9af689f2674ab5
+  metadata.gz: d3adff2eeba99442ae70d9eea972c624906238a1
+  data.tar.gz: 828447d5721f3a973e20ef96d6ad7aa6a82dcbc3
 SHA512:
-  metadata.gz: 40c991266f6c8b9185d2c635ba496cd3c6ba593744efa299cd088767f03f3be63400b05fafc1a6db31567e447a7fa21fddc9144476b564b85b0eaea7a6902398
-  data.tar.gz: 96f671dec8eaba3798c5bd807c54ae681c588f69c9b530cda545af70e3c9fff8f0f5481018d3d065cefa7ec9ef26ce89be26c0de9702ea94525baba8dd91fa37
+  metadata.gz: ea9d214229c39f0185346032bdcd06b27df9cd241df796b8b427543f593995c4e76706af3f3012625ce335cbf6bb794e9b142aed11f353558505fe19f2822d2c
+  data.tar.gz: 5c30d99b23cb66088fa77a2e71ddf24304d03f118a67f7f1e58a2ec33a0e8b36cd9e2bdb1aeb840d5237a2e7e1a7c05d9f8179bb4c8ceb58ed13fea349a433ba

data/README.md

@@ -25,6 +25,10 @@ web sites.
 See the original article at:
 (http://www.blackbytes.info/2016/07/writing-a-shell-in-ruby/)
 
+Oh, and one other little thing. A survey of the mysh reveals that it currently
+contains 2291 lines of code. It seems that there has been some growth beyond
+the 25 lines in the original article.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -52,21 +56,21 @@ mysh <options>
 
 Where the available options are:
 
-Option               | Short Form  | Description
----------------------|-------------|---------------------------
---debug              | -d          | Turn on mysh debugging.
---no-debug           | -nd         | Turn off mysh debugging.
---help               | -? -h       | Display mysh usage info and exit.
---init filename      | -i filename | Initialize mysh by loading the specified file.
---no-init            | -ni         | Do not load a file to initialize mysh.
---load filename      | -l filename | Load the specified file into the mysh.
---post-prompt "str"  | -pp "str"   | Set the mysh line continuation prompt to "str".
---no-post-prompt     | -npp        | Turn off mysh line continuation prompting.
---pre-prompt "str"   | -pr "str"   | Set the mysh pre prompt to "str".
---no-pre-prompt      | -npr        | Turn off mysh pre prompting.
---prompt "str"       | -p "str"    | Set the mysh prompt to "str".
---no-prompt          | -np         | Turn off mysh prompting.
---quit               |             | Quit out of the mysh program.
+Option               | Short Form(s)| Description             | Default
+---------------------|--------------|-------------------------|-----------
+--debug              | -d           | Turn on mysh debugging. | false
+--no-debug           | -nd          | Turn off mysh debugging.
+--help               | -? -h        | Display mysh usage info and exit.
+--init filename      | -i filename  | Initialize mysh by loading the specified file. | ~/mysh_init.mysh
+--no-init            | -ni          | Do not load a file to initialize mysh.
+--load filename      | -l filename  | Load the specified file into the mysh.
+--post-prompt "str"  | -pp "str"    | Set the mysh line continuation prompt to "str". | $prompt
+--no-post-prompt     | -npp         | Turn off mysh line continuation prompting.
+--pre-prompt "str"   | -pr "str"    | Set the mysh pre prompt to "str". | $w
+--no-pre-prompt      | -npr         | Turn off mysh pre prompting.
+--prompt "str"       | -p "str"     | Set the mysh prompt to "str". | mysh
+--no-prompt          | -np          | Turn off mysh prompting.
+--quit               |              | Quit out of the mysh program.
 
 <br>When mysh is run, the user is presented with a command prompt:
 
@@ -90,17 +94,26 @@ and acclimated to its environment. The boot/initialization  process of mysh is
 somewhat modeled after (well if I'm honest, more like inspired by) that of the
 famous bash shell. On startup:
 
-1. Process pre-boot options. Some command line options are processed early.
-These are --help, -h, -?, --init, -i, --no-init, -ni, and --quit. See above
-for details on these.
-2. Try to load and execute the mysh init file. There are two possible files
-for this role. They are the ~/mysh_init.mysh and ~/mysh_init.rb files. If
-both files should be present, the .mysh file is processed and the .rb is
-ignored. NOTE: If an init file should be specified with the --init (-i)
-option, or disabled with the --no-init (-ni) option, this step is skipped.
-3. The rest of the command line options are processed at this time. Again,
-see above for details.
-
+1. Option values are initialized to their initial, default values.
+2. Process pre-boot command line options: Some command line options are
+processed early. These are --help, -h, -?, --init, -i, --no-init, and -ni.
+See Usage above for details on these.
+3. Try to load and execute the mysh_init file. There are three possible files
+for this role. They are ~/mysh_init.mysh, ~/mysh_init.rb, and ~/mysh_init.txt.
+In priority, ".mysh" > ".rb" > ".txt". <br>NOTE: If an init file should be
+specified with the --init option, or disabled with the --no-init option, this
+step is skipped.
+4. The rest of the command line options are processed at this time. Again,
+see Usage above for details.
+
+It should be noted that in the event of a conflict in settings during the boot
+process, the last command/option encountered shall prevail. For example if the
+~/mysh_init.mysh contains the line:
+```
+$debug = on
+```
+and the command line has the -nd option, then debug mode will be disabled
+because the -nd command line option is processed after the mysh_init file.
 
 ###REPL
 
@@ -110,6 +123,10 @@ 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.
 
+For more information on REPLs please see:
+(https://en.wikipedia.org/wiki/Read-eval-print_loop) and
+(https://repl.it/languages/ruby)
+
 ####READ
 
 The first step is just to get input from the user. For interactive sessions
@@ -175,7 +192,6 @@ character in the input. These signature characters are:
   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 Internal Commands below.
@@ -333,8 +349,8 @@ 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.
+* name is a word matching the regex: /[a-z][a-z0-9_]*/. Note: lower case only.
+* value is some text, with optional embedded variables and handlebars.
 
 To erase the value of a variable, use:
 
@@ -490,6 +506,8 @@ environment.
 
 Topic    | Description
 ---------|----------------------------------------------------
+version  | The version of mysh in use.
+init file| The init file in use or &#60;none found&#62; or &#60;none&#62;.
 user     | The current user name.
 home     | The current home directory.
 name     | The path/name of the mysh program currently executing.
@@ -546,9 +564,11 @@ say <stuff>    | Display the text in the command arguments.
 type file      | Display a text file with support for optional embedded handlebars and mysh variables.
 vls {mask}     | Display the loaded modules, matching the optional mask, that have version info.
 
-Note that the load command applied to a mysh script file acts exactly the same
-as if the script file were executed directly from the command line. As a
-result of this:
+Notes:
+1. The notation {x} means that x is optional.
+2. The load command applied to a mysh script file acts exactly the same
+   as if the script file were executed directly from the command line. As a
+   result of this:
 
 ```
 myfile.mysh
@@ -622,28 +642,51 @@ located at:
 A survey of the contents of that folder will reveal the nature of these files.
 
 New internal commands may also be added in code via the the add_action method
-of the InternalCommand class of the Mysh module. The code to do this would look
-something like this:
+of the Action class of the Mysh module. There are two ways to do this:
+
+* The command may be created as an instance of the Action class with a command
+name, description and a block that contains the action to be performed by this
+command. This block takes one parameter, an input wrapper (see About Command
+Arguments below for details). This approach is best when the command is simple
+enough to fit into a single lambda block of code. Like this template:
 
 ```ruby
 module Mysh
-  class NewCommand < Action
+  command_name = 'new <item>'
+  desc = "A succinct description of what this command does."
+  action = lambda do |input|
+    #Action packed stuff goes here!
+  end
+
+  COMMANDS.add_action(Action.new(command_name, desc, &action))
+end
+```
 
+
+* The command may be created as an instance of a sub-class of the Action class.
+In this case, only a name and description are needed as the sub-class should
+contain all the needed code. The action method is the process_command and this
+takes one parameter, an input wrapper (see About Command Arguments below for
+details). This approach is required when the command action needs to be spread
+across multiple methods. Like this template:
+
+```ruby
+module Mysh
+  class NewCommand < Action
     #This method is called when the command is executed.
-    def call(args)
+    def process_command(input)
+      #Even more action packed stuff goes here!
     end
-
   end
 
   desc = "A succinct description of what this command does."
   command_name = 'new <item>'
   COMMANDS.add_action(NewCommand.new(command_name, desc))
-
 end
 ```
 
-Where:
-* command_name is the name of the command with optional argument descriptions
+##### Command names:
+The name of the command is a string with optional argument descriptions
 separated with spaces. The command is the first word of this string. For
 example a command_name of:
 
@@ -653,22 +696,90 @@ example a command_name of:
 
 will create a command called "new" with a title of "new &#60;item&#62;"
 
-* command_description is a string or an array of strings that describe the
-command. This serves as the descriptive help for the command. The help display
-code handles matters like word wrap automatically.
+##### Command descriptions:
+A string or an array of strings that describe the command. This serves as the
+descriptive help for the command. The help display code handles matters like
+word wrap automatically.
+
+##### About Command Arguments
+
+The process_command method take one parameter that is an instance of the
+InputWrapper class. This class provides several ways to access the parts of the
+command line. These are:
+
+Method        | Description
+--------------|----------------
+raw           | The raw, unprocessed command line text.
+cooked        | The command line with variables and handlebars expanded.
+raw_command   | The command portion of the raw text.
+quick_command | The quick command of the raw text.
+raw_body      | The raw text after the command.
+quick_body    | The raw text after the quick command.
+cooked_body   | The cooked text after the command.
+parsed        | The command and parameters parsed into an array of strings.
+args          | The parameters parsed into an array of strings.
+
+Note: commands are not normally "cooked". Should this be required
+use the following code snippet:
+
+```ruby
+input.raw.preprocess
+```
+
+##### Some Useful Helper Methods
+
+Within the mysh environment, there exists a number of methods designed to make
+life easier in adding new commands or in load ruby files or embedded into
+handlebars. Some of these more noteworthy methods are listed below:
+
+###### MNV[:name]
+Retrieve the mysh variable "$name"
 
-#### About command args
+###### MNV[:name]="value"
+Set/Update the mysh variable "$name". Note that the value is always a string,
+even for things like "true" and "false". If the value is an empty string, the
+variable is deleted.
 
-The call method take one parameter called args. The args parameter is an array
-of zero or more arguments that were entered with the command.
+###### mysh "string"
+Execute the string as a mysh command.
 
-So if a command is given
+###### Mysh.parse_args("string")
+Parse the string into an array of arguments.
 
-    command abc "this is a string" 23 --launch --all
+###### Mysh.input.readline(parms)
+Get a line of input from the console. See the mini_readline gem for info
+on the optional parms.
 
-the args array will contain:
+###### "string".preprocess(context=mysh_default_context)
+Process the string for embedded variables and handlebars. By default,
+any embedded ruby  is evaluated in the mysh global expression binding. However,
+another BindingWrapper instance may be passed to access an alternative binding.
 
-    ["abc", "this is a string", "23", "--launch", "--all"]
+###### "string".decorate
+Given a string with a file spec, decorate that string so that it is more
+pleasing to the local environment. This is a great boon to writing effortless
+portable code.
+
+#### Adding Help Topics
+
+In mysh, help topics are generally implemented as text files often augmented
+with embedded mysh variables and ruby code. It it noteworthy however that they
+can also be mysh script or ruby code files. The management of these help files
+is located in the file:
+```
+mysh/lib/mysh/internal/actions/help/sub_help.rb
+```
+In this file, you can locate a variable called "help". This is an array of
+arrays where each line describes a help topic. Within each line is a further
+array of three strings. Respectively these are:
+1. The name of the help item.
+2. A brief description of the help topic. This line is used in the help on help
+(??) topic.
+3. The name of the file, **with its extension**, that contains the actual help
+information.
+
+To add a new help topic, simply add the new help file to the help folder and
+and a corresponding line entry to to the help variable.
 
 ## Contributing
 
@@ -676,7 +787,7 @@ All participation is welcomed. There are two fabulous plans to choose from:
 
 #### Plan A
 
-1. Fork it ( https://github.com/PeterCamilleri/mysh/fork )
+1. Fork it (https://github.com/PeterCamilleri/mysh/fork)
 2. Switch to the development branch ('git branch development')
 3. Create your feature branch ('git checkout -b my-new-feature')
 4. Commit your changes ('git commit -am "Add some feature"')

data/lib/mysh.rb

@@ -7,11 +7,13 @@ require 'in_array'
 
 require_relative 'mysh/exceptions'
 require_relative 'mysh/binding_wrapper'
+require_relative 'mysh/input_wrapper'
 require_relative 'mysh/user_input'
-require_relative 'mysh/quick'
 require_relative 'mysh/expression'
 require_relative 'mysh/internal'
-require_relative 'mysh/external_ruby'
+require_relative 'mysh/quick'
+require_relative 'mysh/external'
+require_relative 'mysh/system'
 require_relative 'mysh/handlebars'
 require_relative 'mysh/shell_variables'
 require_relative 'mysh/pre_processor'

data/lib/mysh/{external_ruby.rb → external.rb}

@@ -1,20 +1,20 @@
 # coding: utf-8
 
-#* mysh/external_ruby.rb -- Support for executing Ruby files with the ruby interpreter.
+#* mysh/external.rb -- Support for executing external files.
 module Mysh
 
-  #Try to execute as a Ruby program.
+  #Try to execute an external file.
   #<br>Endemic Code Smells
   #* :reek:TooManyStatements
-  def self.try_execute_external_ruby(str)
-    args = parse_args(str.chomp)
+  def self.try_execute_external(input)
+    args = input.parsed
     file_name = args.shift
 
     if (file_name)
       ext = File.extname(file_name)
 
       if ext == '.rb'
-        new_command = "#{RbConfig.ruby} #{str}"
+        new_command = "#{RbConfig.ruby} #{input.cooked}"
         puts "=> #{new_command}"  if MNV[:debug]
         system(new_command)
         :ruby_exec
@@ -22,8 +22,7 @@ module Mysh
         Mysh.process_file(file_name)
         :mysh_script
       elsif ext == '.txt'
-        exec_host = BindingWrapper.new(binding)
-        show_handlebar_file(file_name, exec_host)
+        show_handlebar_file(file_name, BindingWrapper.new(binding))
         :internal
       end
     end

data/lib/mysh/handlebars.rb

@@ -8,7 +8,7 @@ class Object
   #Show a file with embedded ruby handlebars.
   #<br>Note:
   #The message receiver is the evaluation host for the handlebar code.
-  def show_handlebar_file(name, evaluator)
+  def show_handlebar_file(name, evaluator = $mysh_exec_host)
     puts eval_handlebar_file(name, evaluator)
   end
 

data/lib/mysh/init.rb

@@ -9,18 +9,23 @@ module Mysh
   #Perform init phase processing.
   def self.mysh_load_init
 
-    unless $mysh_init_file || !(home = ENV['HOME'])
-      name_mysh = home + '/mysh_init.mysh'
-      name_rb = home + '/mysh_init.rb'
-
-      if File.file?(name_mysh)
-        process_file($mysh_init_file = name_mysh)
-      elsif File.file?(name_rb)
-        load ($mysh_init_file = name_rb)
+    unless $mysh_init_file
+
+      if (home = ENV['HOME'])
+        names = [home + '/mysh_init.mysh',
+                 home + '/mysh_init.rb',
+                 home + '/mysh_init.txt']
+
+        $mysh_init_file = names.detect {|name| File.file?(name)}
+      end
+
+      if $mysh_init_file
+        mysh "load #{$mysh_init_file.decorate}"
+      else
+        $mysh_init_file = '<none found>'
       end
     end
 
-    $mysh_init_file = '<none found>' unless $mysh_init_file
   end
 
 end

data/lib/mysh/input_wrapper.rb

@@ -0,0 +1,67 @@
+# coding: utf-8
+
+#* mysh/internal/input_wrapper.rb -- An action compatible wrapper for a input.
+module Mysh
+
+  #* mysh/internal/input_wrapper.rb -- An action compatible wrapper for a input.
+  class InputWrapper
+
+    #Build an input wrapper.
+    def initialize(raw)
+      @raw = raw.chomp
+      @raw_command = @raw_body = nil
+    end
+
+    #Access the raw text.
+    attr_reader :raw
+
+    #Get the first raw character.
+    def quick_command
+      @raw[0] || ""
+    end
+
+    #Get the balance of the raw string.
+    def quick_body
+      @raw[1..-1] || ""
+    end
+
+    #Get the command word if it exists.
+    def raw_command
+      @raw_command ||= @raw.split[0] || ""
+    end
+
+    #Get the parameter text.
+    def raw_body
+      @raw_body ||= @raw[(raw_command.length)..-1]
+    end
+
+    #Get the preprocessed argument text.
+    def cooked_body
+      raw_body.preprocess
+    end
+
+    #Access the massaged text.
+    def cooked
+      raw_command + cooked_body
+    end
+
+    #Get the parsed arguments
+    def args
+      Mysh.parse_args(cooked_body)
+    end
+
+    #Get the parsed command line.
+    def parsed
+      [raw_command] + args
+    end
+
+    #Set up input for a quick style command.
+    def quick
+      @raw_command = quick_command
+      @raw_body    = quick_body
+      self
+    end
+
+  end
+
+end