README

shell

http://godoc.org/bitbucket.org/creachadair/shell

The shell package implements basic shell command-line splitting.

Expand ▾ Collapse ▴

Documentation

Overview

    Package shell supports splitting and joining of shell command strings.

    The Split function divides a string into whitespace-separated fields, respecting single and double quotation marks as defined by the Shell Command Language section of IEEE Std 1003.1 2013. The Quote function quotes characters that would otherwise be subject to shell evaluation, and the Join function concatenates quoted strings with spaces between them.

    The relationship between Split and Join is that given

    fields, ok := Split(Join(ss))
    

    the following relationship will hold:

    fields == ss && ok
    

    Index

    Examples

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    func Join

    func Join(ss []string) string

      Join quotes each element of ss with Quote and concatenates the resulting strings separated by spaces.

      func Quote

      func Quote(s string) string

        Quote returns a copy of s in which shell metacharacters are quoted to protect them from evaluation.

        func Split

        func Split(s string) ([]string, bool)

          Split partitions s into tokens divided on space, tab, and newline characters using a *Scanner. Leading and trailing whitespace are ignored.

          The Boolean flag reports whether the final token is "valid", meaning there were no unclosed quotations in the string.

          Types

          type Scanner

          type Scanner struct {
          	// contains filtered or unexported fields
          }

            A Scanner partitions input from a reader into tokens divided on space, tab, and newline characters. Single and double quotation marks are handled as described in http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02.

            Example
            Output:
            
            51 6 43 true EOF
            

            func NewScanner

            func NewScanner(r io.Reader) *Scanner

              NewScanner returns a Scanner that reads input from r.

              func (*Scanner) Complete

              func (s *Scanner) Complete() bool

                Complete reports whether the current token is complete, meaning that it is unquoted or its quotes were balanced.

                func (*Scanner) Each

                func (s *Scanner) Each(f func(tok string) bool) error

                  Each calls f for each token in the scanner until the input is exhausted, f returns false, or an error occurs.

                  Example
                  Output:
                  
                  a b
                  c d
                  e f's g
                  stop
                  

                  func (*Scanner) Err

                  func (s *Scanner) Err() error

                    Err returns the error, if any, that resulted from the most recent action.

                    func (*Scanner) Next

                    func (s *Scanner) Next() bool

                      Next advances the scanner and reports whether there are any further tokens to be consumed.

                      func (*Scanner) Rest

                      func (s *Scanner) Rest() io.Reader

                        Rest returns an io.Reader for the remainder of the unconsumed input in s. After calling this method, Next will always return false. The remainder does not include the text of the current token at the time Rest is called.

                        Example
                        Output:
                        
                        found marker; all the remaining stuff
                        

                        func (*Scanner) Split

                        func (s *Scanner) Split() []string

                          Split returns the remaining tokens in s, not including the current token if there is one. Any tokens already consumed are still returned, even if there is an error.

                          Example
                          Output:
                          
                          cmd
                          -flag=t
                          ** Args: foo, bar, baz
                          

                          func (*Scanner) Text

                          func (s *Scanner) Text() string

                            Text returns the text of the current token, or "" if there is none.

                            Source Files