Skip to content
This repository

Update docs about YAML #2630

Merged
merged 3 commits into from over 1 year ago

2 participants

Jack Kuan Thomas S Hatch
Jack Kuan

Also, I think it's not true that YAML only allows ASCII which is told in the page...

Thomas S Hatch thatch45 merged commit f8e9513 into from
Thomas S Hatch thatch45 closed this
Thomas S Hatch
Owner

Thanks @kjkuan, you have been hitting things very hard lately!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Showing 3 unique commits by 1 author.

Nov 18, 2012
Jack Kuan Update docs about troubleshooting YAML. a284732
Jack Kuan Merge branch 'develop' of github.com:saltstack/salt into develop af93e5f
Jack Kuan Fix a case when a single shorthand state is declared without arguments.
Also, now automatically adds the name argument, if one is not provided,
for states declared under a dot-prefixed state id.
190f4bd
This page is out of date. Refresh to see the latest.
46  doc/topics/troubleshooting/yaml_idiosyncrasies.rst
Source Rendered
@@ -16,7 +16,11 @@ Spaces vs Tabs
16 16
 
17 17
 `YAML uses spaces`_, period. Do not use tabs in your SLS files! If strange
18 18
 errors are coming up in rendering SLS files, make sure to check that
19  
-no tabs have crept in! In vi / vim, you can check with ``:se spell``.
  19
+no tabs have crept in! In Vim, after enabling search highlighting
  20
+with: ``:set hlsearch``,  you can check with the following key sequence in
  21
+normal mode(you can hit `ESC` twice to be sure): ``/``, `Ctrl-v`, `Tab`, then
  22
+hit `Enter`. Also, you can convert tabs to 2 spaces by these commands in Vim:
  23
+``:set tabstop=2 expandtab`` and then ``:retab``.
20 24
 
21 25
 .. _`YAML uses spaces`: http://yaml.org/spec/1.1/#id871998
22 26
 
@@ -149,14 +153,33 @@ ALSO DOES NOT WORK:
149 153
 
150 154
     fred:
151 155
       user.present
152  
-      ssh.present:
  156
+      ssh_auth.present:
153 157
         - name: AAAAB3NzaC...
154  
-        - enc: dsa
  158
+        - user: fred
  159
+        - enc: ssh-dss
  160
+        - require:
  161
+          - user: fred
155 162
 
156  
-So, to make these work they would need to be defined the "old way", or with
157  
-multiple "full decs"
  163
+The correct way is to define them like this:
158 164
 
159  
-WORKS:
  165
+.. code-block:: yaml
  166
+
  167
+    vim:
  168
+      pkg.installed: []
  169
+      user.present: []
  170
+
  171
+    fred:
  172
+      user.present: []
  173
+      ssh_auth.present:
  174
+        - name: AAAAB3NzaC...
  175
+        - user: fred
  176
+        - enc: ssh-dss
  177
+        - require:
  178
+          - user: fred
  179
+
  180
+
  181
+Alternatively,  they can be defined the "old way",  or with multiple
  182
+"full decs":
160 183
 
161 184
 .. code-block:: yaml
162 185
 
@@ -169,9 +192,13 @@ WORKS:
169 192
     fred:
170 193
       user:
171 194
         - present
172  
-      ssh.present:
  195
+      ssh_auth:
  196
+        - present
173 197
         - name: AAAAB3NzaC...
174  
-        - enc: dsa
  198
+        - user: fred
  199
+        - enc: ssh-dss
  200
+        - require:
  201
+          - user: fred
175 202
 
176 203
 YAML support only plain ASCII
177 204
 =============================
@@ -206,6 +233,7 @@ Python can also be used to discover the Unicode number for a character:
206 233
 
207 234
 This shell command can find wrong characters in your SLS files:
208 235
 
209  
-.. code-block: shell
  236
+.. code-block:: bash
  237
+
210 238
     find . -name '*.sls'  -exec  grep --color='auto' -P -n '[^\x00-\x7F]' \{} \;
211 239
 
42  salt/renderers/stateconf.py
@@ -70,9 +70,22 @@
70 70
     files.
71 71
 
72 72
     For example, in the `salt://some/file.sls`, a state id such as ``.sls_params``
73  
-    will be turned into ``some.file::sls_params``.
  73
+    will be turned into ``some.file::sls_params``. Example::
74 74
 
75  
-    Moreover, the leading dot trick can be used with extending state ids as well,
  75
+        .vim:
  76
+          package.installed
  77
+
  78
+    Above will be translated into::
  79
+
  80
+        some.file::vim:
  81
+          package.installed:
  82
+            - name: vim
  83
+    
  84
+    Notice how that if a state under a dot-prefixed state id has no 'name'
  85
+    argument then one will be added automatically by using the state id with
  86
+    the leading dot stripped off.
  87
+
  88
+    The leading dot trick can be used with extending state ids as well,
76 89
     so you can include relatively and extend relatively. For example, when
77 90
     extending a state in `salt://some/other_file.sls`, eg,::
78 91
 
@@ -294,6 +307,7 @@ def process_sls_data(data, context=None, extract=False):
294 307
         # wrong during the preprocessing.
295 308
         data = copy.deepcopy(high)
296 309
         try:
  310
+            rewrite_single_shorthand_state_decl(data)
297 311
             rewrite_sls_includes_excludes(data, sls)
298 312
 
299 313
             if not extract and IMPLICIT_REQUIRE:
@@ -371,6 +385,22 @@ def has_names_decls(data):
371 385
         for _ in nvlist(args, ['names']):
372 386
             return sid
373 387
 
  388
+def rewrite_single_shorthand_state_decl(data):
  389
+    '''
  390
+    Rewrite all state declarations that look like this::
  391
+
  392
+      state_id_decl:
  393
+        state.func
  394
+
  395
+    into::
  396
+
  397
+      state_id_decl:
  398
+        state.func: []
  399
+    '''
  400
+    for sid, states in data.items():
  401
+        if isinstance(states, basestring):
  402
+            data[sid] = {states: []}
  403
+
374 404
 
375 405
 def _parent_sls(sls):
376 406
     i = sls.rfind('.')
@@ -477,6 +507,14 @@ def rename_state_ids(data, sls, is_extend=False):
477 507
                     'Can\'t rename state id({0}) into {1} because the later '
478 508
                     'already exists!'.format(sid, newsid)
479 509
                 )
  510
+            # add a '- name: sid' to those states without '- name'.
  511
+            for args in data[sid].itervalues():
  512
+                for arg in args:
  513
+                    if isinstance(arg, dict) and iter(arg).next() == 'name':
  514
+                        break
  515
+                else: # then no '- name: ...' is defined in the state args
  516
+                    # add the sid without the leading dot as the name.
  517
+                    args.insert(0, dict(name=sid[1:]))
480 518
             data[newsid] = data[sid]
481 519
             del data[sid]
482 520
 
44  tests/unit/stateconf_test.py
@@ -67,6 +67,40 @@ def test_sls_dir(self):
67 67
                          'echo sls_dir=path/to')
68 68
 
69 69
 
  70
+    def test_states_declared_with_shorthand_no_args(self):
  71
+        result = render_sls('''
  72
+test:
  73
+  cmd.run:
  74
+    - name: echo testing
  75
+    - cwd: /
  76
+test1:
  77
+  pkg.installed
  78
+test2:
  79
+  user.present
  80
+'''     )
  81
+        self.assertTrue(len(result), 3)
  82
+        for args in (result['test1']['pkg.installed'],
  83
+                     result['test2']['user.present']  ):
  84
+            self.assertTrue(isinstance(args, list))
  85
+            self.assertEqual(len(args), 0)
  86
+        self.assertEqual(result['test']['cmd.run'][0]['name'], 'echo testing')
  87
+
  88
+
  89
+    def test_adding_state_name_arg_for_dot_state_id(self):
  90
+        result = render_sls('''
  91
+.test:
  92
+  pkg.installed:
  93
+    - cwd: /
  94
+.test2:
  95
+  pkg.installed:
  96
+    - name: vim
  97
+''', sls='test')
  98
+        self.assertEqual(
  99
+                result['test::test']['pkg.installed'][0]['name'], 'test')
  100
+        self.assertEqual(
  101
+                result['test::test2']['pkg.installed'][0]['name'], 'vim')
  102
+
  103
+
70 104
     def test_state_prefix(self):
71 105
         result = render_sls('''
72 106
 .test:
@@ -153,7 +187,9 @@ def test_goal_state_generation(self):
153 187
 ''', sls='test.goalstate', argline='yaml . jinja')
154 188
         self.assertTrue(len(result), len('ABCDE')+1)
155 189
 
156  
-        reqs = result['test.goalstate::goal']['stateconf.set'][0]['require']
  190
+        reqs = result['test.goalstate::goal']['stateconf.set'][1]['require']
  191
+        # note: arg 0 is the name arg.
  192
+
157 193
         self.assertEqual(set([i.itervalues().next() for i in reqs]),
158 194
                          set('ABCDE'))
159 195
 
@@ -207,7 +243,9 @@ def test_implicit_require_with_goal_state(self):
207 243
         self.assertEqual(G_req[2]['cmd'], 'F')
208 244
 
209 245
         goal_args = result['test::goal']['stateconf.set']
210  
-        self.assertEqual(len(goal_args), 1)
  246
+        # Note: arg 0 is the auto-added name arg.
  247
+
  248
+        self.assertEqual(len(goal_args), 2)
211 249
         self.assertEqual(
212  
-                [i.itervalues().next() for i in goal_args[0]['require']],
  250
+                [i.itervalues().next() for i in goal_args[1]['require']],
213 251
                 list('ABCDEFG'))
Commit_comment_tip

Tip: You can add notes to lines in a file. Hover to the left of a line to make a note

Something went wrong with that request. Please try again.