Merge branch 'master' into mockResp

README.rst

@@ -72,6 +72,13 @@ or
 
     python setup.py install
 
+
+New to howdoi ? 
+----------------
+::
+
+    howdoi howdoi
+
 Usage
 -----
 

howdoi/howdoi.py

@@ -100,6 +100,8 @@ CACHE_DIR = appdirs.user_cache_dir('howdoi')
 CACHE_ENTRY_MAX = 128
 
 HTML_CACHE_PATH = 'cache_html'
+SUPPORTED_HELP_QUERIES = ['use howdoi', 'howdoi', 'run howdoi',
+                          'do howdoi', 'howdoi howdoi', 'howdoi use howdoi']
 
 if os.getenv('HOWDOI_DISABLE_CACHE'):
     cache = NullCache()  # works like an always empty cache
@@ -341,6 +343,10 @@ def _get_links_with_cache(query):
     return question_links
 
 
+def build_splitter(splitter_character='=', spliter_length=80):
+    return '\n' + splitter_character * spliter_length + '\n\n'
+
+
 def _get_instructions(args):
     question_links = _get_links_with_cache(args['query'])
     if not question_links:
@@ -351,8 +357,7 @@ def _get_instructions(args):
 
     answers = []
     initial_position = args['pos']
-    spliter_length = 80
-    answer_spliter = '\n' + '=' * spliter_length + '\n\n'
+    answer_spliter = build_splitter('=', 80)
 
     for answer_number in range(args['num_answers']):
         current_position = answer_number + initial_position
@@ -382,6 +387,28 @@ def _clear_cache():
     return cache.clear()
 
 
+def _is_help_query(query: str):
+    return any([query.lower() == help_query for help_query in SUPPORTED_HELP_QUERIES])
+
+
+def _get_help_instructions():
+    instruction_splitter = build_splitter(' ', 60)
+    query = 'print hello world in python'
+    instructions = [
+        'Here are a few popular howdoi commands ',
+        '>>> howdoi {} (default query)',
+        '>>> howdoi {} -a (read entire answer)',
+        '>>> howdoi {} -n [number] (retrieve n number of answers)',
+        '>>> howdoi {} -l (display only a link to where the answer is from',
+        '>>> howdoi {} -c (Add colors to the output)',
+        '>>> howdoi {} -e (Specify the search engine you want to use e.g google,bing)'
+    ]
+
+    instructions = map(lambda s: s.format(query), instructions)
+
+    return instruction_splitter.join(instructions)
+
+
 def howdoi(raw_query):
     args = raw_query
     if type(raw_query) is str:  # you can pass either a raw or a parsed query
@@ -391,6 +418,9 @@ def howdoi(raw_query):
     args['query'] = ' '.join(args['query']).replace('?', '')
     cache_key = str(args)
 
+    if _is_help_query(args['query']):
+        return _get_help_instructions() + '\n'
+
     res = cache.get(cache_key)
     if res:
         return res
@@ -407,24 +437,15 @@ def howdoi(raw_query):
 
 
 def get_parser():
-    parser = argparse.ArgumentParser(
-        description='instant coding answers via the command line')
-    parser.add_argument('query', metavar='QUERY', type=str, nargs='*',
-                        help='the question to answer')
-    parser.add_argument(
-        '-p', '--pos', help='select answer in specified position (default: 1)', default=1, type=int)
-    parser.add_argument('-a', '--all', help='display the full text of the answer',
-                        action='store_true')
-    parser.add_argument('-l', '--link', help='display only the answer link',
-                        action='store_true')
-    parser.add_argument('-c', '--color', help='enable colorized output',
-                        action='store_true')
-    parser.add_argument('-n', '--num-answers',
-                        help='number of answers to return', default=1, type=int)
-    parser.add_argument('-C', '--clear-cache', help='clear the cache',
-                        action='store_true')
-    parser.add_argument('-v', '--version', help='displays the current version of howdoi',
-                        action='store_true')
+    parser = argparse.ArgumentParser(description='instant coding answers via the command line')
+    parser.add_argument('query', metavar='QUERY', type=str, nargs='*', help='the question to answer')
+    parser.add_argument('-p', '--pos', help='select answer in specified position (default: 1)', default=1, type=int)
+    parser.add_argument('-a', '--all', help='display the full text of the answer', action='store_true')
+    parser.add_argument('-l', '--link', help='display only the answer link', action='store_true')
+    parser.add_argument('-c', '--color', help='enable colorized output', action='store_true')
+    parser.add_argument('-n', '--num-answers', help='number of answers to return', default=1, type=int)
+    parser.add_argument('-C', '--clear-cache', help='clear the cache', action='store_true')
+    parser.add_argument('-v', '--version', help='displays the current version of howdoi', action='store_true')
     parser.add_argument('-e', '--engine', help='change search engine for this query only (google, bing, duckduckgo)',
                         dest='search_engine', nargs="?", default='google')
     return parser

test_howdoi.py

@@ -42,6 +42,7 @@ class HowdoiTestCase(unittest.TestCase):
                         'convert mp4 to animated gif',
                         'create tar archive',
                         'cat']
+        self.help_queries = howdoi.SUPPORTED_HELP_QUERIES
         self.pt_queries = ['abrir arquivo em python',
                            'enviar email em django',
                            'hello world em c']
@@ -194,6 +195,30 @@ class HowdoiTestCase(unittest.TestCase):
         actual_output = howdoi._get_questions(links)
         self.assertSequenceEqual(actual_output, expected_output)
 
+    def test_help_queries(self):
+        help_queries = self.help_queries
+
+        for query in help_queries:
+            output = self.call_howdoi(query)
+            self.assertTrue(output)
+            self.assertIn('few popular howdoi commands', output)
+            self.assertIn('retrieve n number of answers', output)
+            self.assertIn(
+                'Specify the search engine you want to use e.g google,bing',
+                output
+            )
+
+    def test_help_queries_are_properly_validated(self):
+        help_queries = self.help_queries
+        for query in help_queries:
+            is_valid_help_query = howdoi._is_help_query(query)
+            self.assertTrue(is_valid_help_query)
+        bad_help_queries = [self.queries[0],
+                            self.bad_queries[0], 'use how do i']
+
+        for query in bad_help_queries:
+            self.assertFalse(howdoi._is_help_query(query))
+
 
 class HowdoiTestCaseEnvProxies(unittest.TestCase):