all repos — h3rald @ e719859cd0d453d6ee8b23b00714a87194072a83

The sources of https://h3rald.com

content/glyph/book/extending/validators.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 
<!DOCTYPE html> 
<html lang="en"> 
	<head> 
		<title>Using Validators &ndash; Glyph Documentation</title> 



		<meta charset="utf-8" /> 
		<meta name="author" content="Fabio Cevasco" /> 
		<meta name="copyright" content="Fabio Cevasco" /> 
		<meta name="robots" content="all, follow" /> 
		<meta name="Revisit-After" content="2 Days" /> 
		<meta name="language" content="en" /> 
		<meta name="target_country" content="en-us" /> 
		<meta name="country" content="United States" /> 
		<meta name="description" content="H3RALD - Fabio Cevasco's Web Site" /> 

		<meta name="keywords" content="h3rald, fabio cevasco, glyph" /> 
		<link rel="shortcut icon" href="/favicon.png" type="image/png" /> 
		<meta content="44.388041;9.073248" name="ICBM" /> 


		<link rel="stylesheet" type="text/css" href="/styles/html5reset.css" /> 
		<link rel="stylesheet" type="text/css" href="/styles/style.css" /> 

		<!--[if lte IE 8]>
		<script src="/js/html5.js" type="text/javascript"></script>
		<![endif]--> 
	</head> 
	<body> 
		<!--[if lte IE 6]>
		<div id="ie-warning">
			This site is not compatible with Internet Explorer 6 or lower. You should consider using a more modern browser for a better &ndash; and <em>safer</em> &ndash; web experience. [<a href="http://browsehappy.com/browsers/">Read More &raquo;</a>]
		</div>
		<![endif]--> 

		<section id="container"> 

			<header class="page"> 
				<nav class="home-link"> 
					<a href="/"> 
						<img src="/images/h3rald_small.png" alt="H3RALD" class="default"/> 
						<![if !IE]> 
						<img src="/images/h3rald_hover_small.png" alt="H3RALD" class="hover"/> 
						<![endif]> 
					</a> 
				</nav> 

				<nav class="section"> 
					/<a href="/glyph/" rel="archives">GLYPH</a> 
				</nav> 

			</header> 
			<article class="page"> 
				<header> 
					<hgroup> 
					<h1>Using Validators</h1> 
					<h2>Glyph Documentation</h2>
					</hgroup> 
				</header> 
				<section id="body-text" class="hyphenate glyph-book"> 

							<nav><a href="/glyph/book/extending/placeholders.html">Using Placeholders &larr;</a><a href="/glyph/book/index.html">Contents</a><a href="/glyph/book/extending/interpreting.html">&rarr; Interpreting Glyph Code</a></nav>
								<p>If you need to make sure that a macro is used properly, consider using <a href="http://yardoc.org/docs/h3rald-glyph/Glyph/Macro/Validators">validators</a>. These methods can be used anywhere within the macro code to check whether certain conditions are met or not. Some default validators are provided to check the number of parameters of a macro, and they are actually used in some system macros.</p>
	<p>If you want to create your own validators, you can call the generic <code>validate</code> method which takes the message to display in case of error, a Hash of options and a block containing the validation to perform.</p>
	<aside class="box">
<div class="box-title">Validating macro placement</div>
<p>You can, of course, create your own validators to check whether a macro is used directly within another. While this may seem a good idea to enforce constraints into the way documents are created, it has one major drawback: if you define a macro with such validation, you&#8217;re effectively limiting its usage, so for example you won&#8217;t be able to use within snippets or other custom macros.</p>
<p>Suppose, for example, that the <a href="/glyph/book/macros/macros_block.html#m_box"><code>box</code></a> macro is only allowed directly under a <code>section</code> macro. This means that, for example:</p>
<ul>
	<li>the macro cannot be used within <code>chapter</code> or <code>appendix</code> macros.</li>
	<li>the macro cannot be used in snippets</li>
</ul>
<p>Even if you consider all the possibilities within the scope of the default macros provided with Glyph, this could still make the <code>box</code> macro unusable within custom macros.</p>
<p>For the specific cases where a macro does not make sense unless is within another (e.g. the <a href="/glyph/book/macros/macros_core.html#m_eq"><code>eq</code></a> macro), a <code>within</code> validator is used. Note though, that this validator only checks that the macro is used within another, but it is not necessarily its child.</p>

</aside>
							<nav><a href="/glyph/book/extending/placeholders.html">Using Placeholders &larr;</a><a href="/glyph/book/index.html">Contents</a><a href="/glyph/book/extending/interpreting.html">&rarr; Interpreting Glyph Code</a></nav>
				</section> 
			</article> 


			<footer> 
				<section class="ads"> 
					<script type="text/javascript"><!--
						google_ad_client = "pub-2871497824158668";
						/* 728x90, created 9/10/10 */
						google_ad_slot = "3963343166";
						google_ad_width = 728;
						google_ad_height = 90;
						//-->
					</script> 
					<script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"> 
					</script> 
				</section> 
				<section> 
					<nav> 
						<a href="/about/">ABOUT</a>|<a href="/contact/">CONTACT</a> 
					</nav> 
					<p>H3RALD Web Site v8.1 &mdash; &copy; 2010 &mdash; <em>Fabio Cevasco</em></p> 
				</section> 
			</footer> 
		</section><!-- #container end --> 
		<script src="http://www.google.com/jsapi?key=ABQIAAAAr6RY1Z6dchG_sX9WDLSy3xRlq2n1sm52B5HDRR5tm6o8XM18FhR56xHNNH6CsX86uN5VoTrglpyOyQ" type="text/javascript"></script> 
		<!-- <script src="/js/jquery.js" type="text/javascript"></script> --> 
		<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script> 
		<script src="/js/jquery-timeago.js" type="text/javascript"></script> 
		<script src="/js/jquery-easing.js" type="text/javascript"></script> 
		<script src="/js/jquery-fancybox.js" type="text/javascript"></script> 
		<script src="/js/jquery-toc.js" type="text/javascript"></script> 
		<script src="/js/date.js" type="text/javascript"></script> 
		<script src="/js/feeds.js" type="text/javascript"></script> 
		<script src="/js/search.js" type="text/javascript"></script> 
		<script src="/js/hyphenator.js" type="text/javascript"></script> 
		<script src="/js/init.js" type="text/javascript"></script> 
		<!-- Start Google Analytics --> 
		<script type="text/javascript"> 
			var _gaq = _gaq || [];
			_gaq.push(['_setAccount', 'UA-18587377-1']);
			_gaq.push(['_trackPageview']);

			(function() {
			var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
			ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
			var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
			})();
		</script> 
		<!-- End Google Analytics --> 
		<!-- Start of StatCounter Code --> 
		<script type="text/javascript"> 
			var sc_project=6193656; 
			var sc_invisible=1; 
			var sc_security="57f7ee2a"; 
		</script> 
		<script type="text/javascript" src="http://www.statcounter.com/counter/counter_xhtml.js"></script> 
		<!-- End of StatCounter Code --> 
	</body> 
</html>